KO Troubleshooting

문제 해결

아래 순서는 데이터를 지우거나 운영 데이터베이스를 직접 바꾸지 않고 원인을 좁히는 방법입니다.

증상	먼저 확인할 것	안전한 다음 조치
설치 직후 페이지가 열리지 않음	`docker compose ps -a`, 앱 로그, 포트 충돌	`AUTH_SECRET`과 포트 설정을 확인한 뒤 앱 로그를 검토합니다.
`/api/health`는 되지만 `/api/ready`가 실패	Postgres와 migrate 상태	데이터베이스 로그와 `migrate` 종료 상태를 확인합니다.
receive check에 이벤트가 보이지 않음	token, shim 자격 증명, 서버 공개 URL	Settings의 설치 명령을 다시 확인하고 shim 수동 수집 후 receive check를 다시 실행합니다.
사용량이 일부 빠짐	shim 버전, 로컬 세션 파일, 수집 주기	shim을 업데이트하고 `toard-shim collect`로 수동 수집을 실행합니다.
비용이 `$0`으로 보임	가격 동기화 상태와 모델 가격	관리 화면에서 가격 동기화 상태를 확인하고 수동 동기화를 실행합니다.
shim 업데이트 실패	네트워크, 릴리스 접근, 로컬 권한	`toard-shim version`과 `toard-shim update` 출력을 확인하고 릴리스 접근 경로를 점검합니다.
본문 수집이 비활성임	서버 KEK와 사용자의 수집 정책	KEK 설정과 `CONTENT_COLLECTION_DEFAULT` 또는 사용자 선택 상태를 확인합니다.

다음 정보를 모아 issue 또는 지원 채널에 전달하면 원인 분리에 도움이 됩니다.

token, 비밀번호, KEK, 데이터베이스 접속 문자열은 공유하지 마세요.