❓ 어드민 자주 묻는 질문 (FAQ) 및 트러블슈팅

본 문서는 블로그 설치, 배포, 운영 단계에서 발생할 수 있는 주요 트러블슈팅 해결 방안과 새 버전 업그레이드 가이드를 제공합니다.

🗄️ Q1. 최신 버전으로 안전하게 업그레이드(Upgrade)하거나 데이터를 복원하는 방법을 알려주세요.

블로그 데이터베이스의 정합성을 지키고 예기치 못한 빌드 크래시를 방지하기 위해 아래의 안전한 업그레이드 절차를 준수하는 것을 강력히 권장합니다.

1. 안전한 새 버전 업그레이드 검증 절차 (권장)

기존 DB와의 스키마 불일치나 템플릿 변경에 따른 충돌을 예방하기 위해, 즉시 본 서버에 배포하는 대신 테스트 환경에서 선검증을 거치십시오. (Git 미사용자 포함)

1. 설정 백업 보존:
   • 기존 개발 폴더 안의 wrangler.backup.json 및 .dev.vars 파일을 안전한 임시 폴더에 복사해 둡니다.
   • ※ .dev.vars 파일은 중요 인증 정보(비밀번호, OAuth 등)를 담고 있으나 보안상 Git 관리 대상에서 제외(.gitignore)되어 있으므로, 코드를 새로 가져오거나 초기화할 때 유실되기 쉽습니다. 반드시 백업을 받아두어야 합니다.
2. 기존 운영 데이터 백업:
   • 현재 가동 중인 블로그 어드민의 콘텐츠 백업 메뉴에서 전체 포스트 및 설정 백업 파일을 다운로드해 둡니다.
3. 격리된 폴더에 새 버전 클론/다운로드:
   • 기존 폴더를 덮어쓰지 말고, 완전히 새로운 디렉토리에 최신 릴리스 소스코드를 내려받거나 클론합니다.
4. 임시 테스트 서버 배포:
   • 새 폴더로 이동해 의존성을 설치(npm install)하고 임시 테스트용 데이터베이스를 생성하여 테스트 배포를 수행합니다.
5. 백업 복원 테스트:
   • 새로 임시 배포된 테스트 어드민에 접속하여, 2단계에서 다운로드했던 백업 파일을 로드해 데이터가 유실 없이 잘 나타나고 에러가 없는지 꼼꼼하게 검증합니다.
6. 본 서버 정식 업데이트 적용:
   • 테스트 서버에서 모든 기능이 정상 작동함을 확인한 뒤에만, 기존 가동 폴더로 돌아와 코드를 갱신(git pull 또는 소스 덮어쓰기)하고 개별 앱 배포 명령어(npm run deploy:blog, npm run deploy:admin)를 실행하여 정식 업그레이드를 마칩니다.

2. 데이터 유실 시 최후의 복구 수단

• npm run restore 명령어 사용:
  • 만약 인프라 설정이나 데이터가 심각하게 훼손되어 원천 복구가 필요한 경우에만, 백업해 두었던 wrangler.backup.json 파일을 기반으로 전체 인프라를 복구 재구성하는 최후의 데이터 복구 수단으로 실행하십시오.

📂 Q2. R2, Supabase, ImageKit 이미지 저장소 변경 시 입력해야 할 필수 키는 무엇인가요?

각 외부 이미지 저장소 사용 시 누락 없이 입력해야 하는 필수 환경변수 및 세팅 체크리스트입니다.

📊 Q3. 대시보드 통계 그래프가 데모 데이터로만 표시됩니다.

• 원인: 구글 애널리틱스 4(GA4) API 환경변수가 입력되지 않았거나 비정상적인 경우, 오류 방지를 위해 임시 데모 데이터가 대체 표시됩니다.
• 설정 방법: Cloudflare Pages 설정에 아래 환경변수를 입력하고 다시 배포합니다.
  • GA4_PROPERTY_ID: 구글 애널리틱스 속성 ID
  • GA4_CLIENT_EMAIL: 구글 클라우드 서비스 계정 이메일
  • GA4_PRIVATE_KEY: 구글 서비스 계정 비공개 키
• 주의 사항: .dev.vars 파일에 GA4_PRIVATE_KEY를 작성할 때 개행 코드(\n) 형식이 깨지지 않도록 반드시 전체 키 문자열을 큰따옴표(")로 묶어 등록해야 합니다.

⚡ Q4. 최초 setup 배포 후 어드민 접속이 안 되거나 일부 데이터 동기화가 누락된 것 같습니다.

• 원인: 원클릭 셋업 단계에서 환경변수 설정 유도가 정상적으로 완료되었더라도, 예상치 못한 원격 통신 장애나 기타 시스템 에러로 인해 암호화 키 또는 비밀 환경변수(Secrets)들의 동기화가 일부 누락되거나 오염된 상태로 배포가 진행될 수 있습니다.
• 해결법: 각 앱의 .dev.vars 설정값 상태를 다시 한번 육안으로 점검한 후, 각 폴더로 이동해 수동으로 개별 배포 명령어인 npm run deploy:blog와 npm run deploy:admin을 각각 1회 실행해 주십시오. 로컬의 .dev.vars 파일에 들어있던 비밀 환경변수들이 정상적으로 덮어씌워지면서 오작동이 해결됩니다.

🔒 Q5. 어드민 페이지 접근 시 "Forbidden (IP Not Allowed)" 또는 403 에러가 뜹니다.

이 블로그의 보안 사양상 배포 스크립트 실행 과정에서 배포 PC의 공인 IP 주소를 자동으로 감지하여 접속 허용 IP(ALLOWED_IP)로 Pages Secret에 자동 주입합니다.

⚠️ 어드민 보안 권고 사항

• 어드민 계정 탈취 및 비인가 접속을 예방하기 위해, 외부 공공장소(카페, 도서관 등)나 신뢰성이 보장되지 않는 공용 PC에서의 어드민 접속 및 관리 작업은 보안상 강력히 제한할 것을 권장합니다.

💡 상황별 대처 요령

• 상황 A. 집이나 사무실에서 인터넷 공유기가 재부팅되어 IP가 바뀐 경우:
  • 기존 작업을 진행하던 집/사무실의 메인 개발 PC 터미널에서 npm run deploy:admin을 1회 실행해주면 변경된 공인 IP를 자동으로 재감지하여 배포가 갱신되면서 즉시 접속이 재개됩니다.
• 상황 B. 피치 못하게 외부 장소로 개발 환경을 옮겨 장기 포스팅해야 하는 경우:
  • 기존 배포 정보가 담긴 백업 설정 파일(wrangler.backup.json 등)을 가지고 새로운 장소의 PC에서 원클릭 셋업 명령어로 새로 빌드/배포를 실행해 접속 권한을 획득하는 방법이 가장 간단합니다.
  • ※ 주의: 외부 작업을 마친 후 다시 원래 집이나 사무실로 귀환하여 블로그를 관리할 때는, 반드시 기존 본래 개발 PC에서 npm run deploy:admin을 다시 실행하여 허용 IP 주소를 다시 원래 고정 IP로 복원 배포해주어야 정상 제어가 가능해집니다.

🔐 Q6. Better Auth(소셜 로그인 및 회원가입) 관련 오류나 로그인 무한 루프가 발생합니다.

• 원인: 인증 보안에 사용되는 환경변수 정보가 누락되었거나 비정상일 때 세션 검증이 실패하여 계속 로그인 루프에 빠지게 됩니다.
• 해결법:
  1. apps/blog/.dev.vars 파일을 열고 BETTER_AUTH_SECRET 키값에 최소 32자 이상의 안전한 무작위 비밀 문자열이 정상 입력되었는지 점검합니다.
  2. 비밀값을 올바르게 설정한 후 npm run deploy:blog를 실행해 주면 변경된 보안키가 원격 Pages Secret으로 동기화되어 인증 기능이 정상으로 돌아옵니다.