docs/07_troubleshooting.md

07. 트러블슈팅

이 문서는 개발 중 자주 만날 수 있는 문제와 확인 방법을 정리합니다.

Docker가 실행되지 않을 때

증상

docker compose up --build 실행 시 Docker daemon 관련 오류가 발생합니다.

확인할 것

Docker Desktop이 실행 중인지 확인합니다.

docker info

해결 방향

• Docker Desktop을 실행한다.
• Docker가 완전히 시작된 뒤 다시 명령을 실행한다.
• 기존 컨테이너가 꼬였으면 docker compose down 후 다시 실행한다.

Streamlit 앱에 접속되지 않을 때

증상

http://localhost:8501에 접속해도 화면이 열리지 않습니다.

확인할 것

컨테이너가 실행 중인지 확인합니다.

docker compose ps

로그를 확인합니다.

docker compose logs cert-study-app

해결 방향

• 앱 컨테이너가 종료되었는지 확인한다.
• 8501 포트를 다른 프로그램이 사용 중인지 확인한다.
• 필요하면 http://127.0.0.1:8501로도 접속해 본다.

로컬 가상환경의 streamlit 실행 파일이 예전 경로를 가리킬 수 있습니다. 이 경우 아래처럼 Python 모듈 방식으로 실행합니다.

python -m streamlit run streamlit_app.py

PostgreSQL 연결 오류

증상

앱 실행 중 데이터베이스 연결 오류가 발생합니다.

확인할 것

PostgreSQL 컨테이너 상태를 확인합니다.

docker compose ps postgres

로그를 확인합니다.

docker compose logs postgres

해결 방향

• postgres 컨테이너가 healthy 상태인지 확인한다.
• DATABASE_URL이 Docker Compose 설정과 일치하는지 확인한다.
• 로컬에서 직접 실행할 때는 host가 postgres가 아니라 localhost여야 할 수 있다.

SQLite fallback 관련 혼동

증상

PostgreSQL을 쓰려고 했는데 SQLite 파일이 생기거나, 반대로 SQLite fallback이 되지 않습니다.

설명

현재 프로젝트는 PostgreSQL 사용을 기본으로 합니다. SQLite는 개발 중 임시 fallback 용도입니다.

해결 방향

PostgreSQL을 사용할 때:

DATABASE_URL=postgresql+pg8000://cert_study:cert_study@postgres:5432/cert_study

SQLite fallback을 꼭 허용해야 할 때:

CERT_STUDY_DB_FALLBACK=1

운영 또는 배포 환경에서는 PostgreSQL을 기준으로 맞추는 것이 좋습니다.

attempt to write a readonly database 오류가 날 때

기존 SQLite 파일 권한 때문에 seed 갱신이 실패할 수 있습니다.

빠르게 화면만 확인하려면 새 임시 DB를 지정합니다.

DATABASE_URL=sqlite:////tmp/cert-study-local-check.db \
  python -m streamlit run streamlit_app.py

기존 DB를 계속 쓰려면 data/questions.db 파일 권한과 소유자를 확인합니다.

Airflow 화면에 접속되지 않을 때

증상

http://localhost:8080에 접속해도 Airflow 화면이 열리지 않습니다.

확인할 것

docker compose ps airflow-webserver airflow-scheduler

docker compose logs airflow-webserver

해결 방향

• airflow-init이 먼저 실행되었는지 확인한다.
• 8080 포트를 다른 프로그램이 사용 중인지 확인한다.
• Airflow DB 마이그레이션 오류가 있는지 로그를 확인한다.

PDF 처리 작업이 멈춘 것처럼 보일 때

증상

PDF 업로드 후 처리 현황이 오래 바뀌지 않습니다.

확인할 것

• Airflow DAG가 실행 중인지 확인한다.
• ingestion_jobs의 stage, message, current, total 값이 바뀌는지 확인한다.
• Airflow 로그에서 실패 단계가 있는지 확인한다.

해결 방향

• 큰 PDF는 파싱 시간이 오래 걸릴 수 있다.
• LLM 또는 이미지 분석을 켜면 더 느려질 수 있다.
• 실패한 경우 해당 작업의 오류 메시지를 먼저 확인한다.

문제 파싱 결과가 이상할 때

증상

문제 본문이 잘리거나, 보기가 빠지거나, 정답이 비어 있습니다.

확인할 것

• 품질 리포트가 생성되었는지 확인한다.
• quality_score, quality_status, quality_issues 값을 확인한다.
• 원본 PDF 텍스트 추출이 가능한 PDF인지 확인한다.

해결 방향

• 파싱 규칙을 개선한다.
• OCR이 필요한 PDF인지 확인한다.
• 문제 번호 패턴과 보기 패턴을 더 명확히 처리한다.
• 모든 문제를 LLM으로 처리하기보다, 실패 가능성이 높은 문제만 보정하는 방향이 좋다.

공통 지문이 보이지 않을 때

증상

케이스 스터디 문제인데 공통 지문 보기가 나타나지 않습니다.

확인할 것

• questions_seed.json에 parent_stem이 들어 있는지 확인한다.
• 앱이 오래된 DB를 보고 있지 않은지 확인한다.
• seed refresh가 DB에 쓸 수 있는 상태인지 확인한다.

해결 방향

• Space 또는 로컬 앱을 재시작한다.
• 로컬에서는 임시 SQLite DB로 다시 실행해 seed 자체가 정상인지 확인한다.
• 기존 DB가 읽기 전용이면 권한을 수정하거나 새 DB를 사용한다.

Yes/No 문제가 객관식처럼 보일 때

증상

다음 각 진술에 대해 예/아니오를 선택하는 문제가 A/B/C 보기처럼 표시됩니다.

설명

Yes/No 진술형 문제는 일반 객관식과 다르게 진술별 예 / 아니오 입력 UI가 필요합니다.

확인할 것

• question_type이 Hotspot (True/False) 또는 유사한 값인지 확인한다.
• 정답이 Y,N,Y 또는 [{key, value}] 형태로 정규화되는지 확인한다.
• 1-A / 1-B / 2-A / 2-B 형식은 항목별 선택 UI로 표시되어야 한다.

확인 명령

문제 유형 alias와 정답 정규화 테스트를 먼저 실행한다.

python -m pytest tests/test_answer_normalizer.py tests/test_question_type_metadata_service.py

해결 방향

• 새 문제 유형 문자열이 추가되면 question_type_metadata_service.py의 alias에 먼저 등록한다.
• 채점이 이상하면 화면 코드보다 answer_normalizer.py에서 chosen과 answer가 같은 기준으로 정규화되는지 확인한다.
• Yes/No는 일반 객관식 A/B/C가 아니라 Y,N,Y처럼 행별 답안으로 비교하는 것이 기준이다.

모바일 화면이 복잡하게 보일 때

증상

휴대폰에서 메뉴가 너무 많거나, 답안 선택 영역이 작아 보입니다.

해결 방향

• 홈 화면은 문제풀이, 오답/복습, 개념 정리 같은 학습 기능을 먼저 보여준다.
• PDF 업로드, 처리 현황, AI 색인은 업로드/관리 영역으로 묶는다.
• 답안 선택 UI는 최소 44px 이상의 터치 영역을 유지한다.
• 문제 유형별로 radio, checkbox, selectbox, Yes/No matrix를 구분해서 사용한다.

Chroma 검색 결과가 이상할 때

증상

유사 문제가 잘 나오지 않거나, 검색 결과가 비어 있습니다.

확인할 것

• 문제가 Chroma에 색인되었는지 확인한다.
• 사용 중인 임베딩 모델이 색인할 때의 모델과 같은지 확인한다.
• chroma_db 디렉터리가 유지되고 있는지 확인한다.

해결 방향

• 같은 임베딩 모델로 다시 색인한다.
• 임베딩 모델별로 컬렉션을 분리한다.
• PostgreSQL에는 문제가 있는데 Chroma에만 없다면 색인 작업을 다시 실행한다.

AI 질문 기능에서 화면이 깨질 때 (2026-07-04 추가)

증상

문제 풀이 중 "질문하기" 버튼을 누르면 페이지 전체가 에러로 깨집니다.

원인과 확인

① 문제 색인(ChromaDB)이 비어 있을 때

한 번도 AI 색인을 실행하지 않은 상태에서 검색하면 n_results > n_documents 오류가 납니다.

② Ollama가 응답하지 않을 때

모델 미설치 또는 서버 중지 상태에서 스트리밍 오류가 납니다.

curl http://localhost:11434/api/tags

해결 방향

• AI 색인 메뉴에서 먼저 색인을 실행한다.
• Ollama 실행 상태와 모델 설치를 확인한다.
• 앱이 에러 메시지를 표시하면 화면에서 URL·모델명 힌트를 확인한다.

2026-07-04 수정: 이제 빈 컬렉션이거나 Ollama 오류가 나도 페이지가 깨지지 않고 에러 메시지만 표시됩니다.

Ollama 또는 LLM 관련 오류

증상

LLM 파싱, 설명 생성, 이미지 분석 단계에서 오류가 발생합니다.

확인할 것

ollama list

해결 방향

• 필요한 모델이 설치되어 있는지 확인한다.
• Docker 컨테이너에서 접근하는 OLLAMA_BASE_URL이 맞는지 확인한다.
• LLM을 끄고 규칙 기반 파싱만으로 먼저 실행해 본다.

Git에 올리면 안 되는 데이터

다음 데이터는 실행 중 생성되는 런타임 데이터이므로 보통 Git에 올리지 않습니다.

• 업로드 PDF
• 파싱 결과 JSON
• Chroma 인덱스
• PostgreSQL 데이터 볼륨
• Airflow 로그
• Airflow DB
• 개인 .env 파일

GitHub에는 코드와 문서, 설정 예시 중심으로 올리는 것이 좋습니다.