빈 볼륨 첫 기동 시 postgres 가 migrations/*.sql 을 psql autocommit 으로 실행해
스키마는 만들되 schema_migrations 스탬프를 안 남김 → fastapi init_db 가 documents
존재로 'fresh' 오판해 baseline 로드를 건너뛰고 001 부터 재replay → CREATE TABLE
users(IF NOT EXISTS 없음) 충돌 → DR/신규환경 부팅 크래시.
fresh-boot 을 init_db 의 baseline + migration runner 단일 경로로 일원화.
기존 prod 볼륨은 비어있지 않아 init scripts 미발동 = 무영향. 관련 docs 정정.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
호스트 30GB 빠듯(여유 <1GB·스왑 full)에서 mineru VLM 스파이크가 글로벌 OOM 유발 시 커널이
가해자 대신 postgres(prod DB)/fastapi(앱+스케줄러 SPOF)를 reap 하던 비대칭 제거. tier-0 = -900(보호),
mineru = 16g cap(steady ~12GB)로 봉쇄. mineru 는 docker update 로 live 선적용.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
mineru-service profile-gate 해제(상시 기동) + fastapi depends_on 추가 +
MARKER_ENDPOINT 을 mineru-service:3301 로 flip. marker-service 는 롤백 대비
Phase 2 까지 잔존(depends_on 유지, 호출만 안 됨 → idle-unload). 동일 /convert 계약.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
rerank_service.py 가 후보를 MAX_RERANK_INPUT=200 까지 청크 없이 한 번에 TEI 로 POST → TEI 한도 64 초과(85) 시 HTTPError → RRF silent fallback(리랭크 누락=검색 품질 저하, 48h 4회). MAX_BATCH_TOKENS=16384 가 VRAM 상한이라 client batch entries 한도만 256(MAX_RERANK_INPUT 200 커버)으로 상향, reranker 만 재생성. 검증: 85-text rerank HTTP 200, batch 에러 0.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
DS compose 의 ollama 서비스가 standalone ~/ollama 컨테이너와 host 127.0.0.1:11434 를
다퉈, 정기 재부팅 후 `docker compose up` 이 'port already allocated' 로 abort →
caddy·frontend 미기동 = 웹 outage(2026-06-08 internal error). standalone 이 이미
hyungi_document_server_default 망 + 동일 ollama_data 볼륨(external) 부착으로 fastapi
`ollama:11434` 임베딩을 서빙하므로 DS 서비스는 100% 잉여 → 제거(서비스+ai-gateway
depends_on). ollama_data 볼륨 def 는 standalone external 참조용으로 보존. 임베딩 무영향.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1B/1C 단계에서 host .env 변수가 fastapi 컨테이너에 주입되지 않은 누락.
voice-memo 동일 패턴으로 environment 블록에 명시 + default false.
PR-Notebook-Client-1 에서 username swap (laptop-worker-bot → notebook-client-bot)
시 env override 로 적용 가능.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
D9 Track B revised (2026-05-08):
1) STT owner GPU 정식 복귀:
- docker-compose.yml: stt-service profiles:[legacy] 제거 → 상시 활성
- fastapi STT_ENDPOINT = http://stt-service:3300 (compose 내부 DNS)
- 정책: Mac mini = Gemma 26B 전용 우선이므로 STT/Whisper 는 호출량 무관
GPU 서버 소유. 이전 "Mac mini 이전본" 주석은 trace 오인 기반.
2) KGS Code 등 외부 학습 자료 추가 스캔 경로:
- ADDITIONAL_WATCH_TARGETS env (쉼표 구분, PKM 상대경로)
- app/core/config.py: additional_watch_targets list 설정 추가
- app/workers/file_watcher.py: 추가 watch path 처리
- app/workers/classify_worker.py: KGS Code 분류 분기 (가스기사 학습 자료)
- 모두 expected_category=library 처리 (md/pdf/docx 만)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- docker-compose.yml stt-service 를 profiles:[legacy] 로 이동. GPU 의
stt-service 는 더 이상 기동하지 않고, fastapi STT_ENDPOINT 가
Mac mini (기본 100.76.254.116:8804 Tailscale, MAC_MINI_HOST env 로
LAN IP 주입) 를 바라보도록 변경. 복원 필요 시
`docker compose --profile legacy up -d stt-service`.
- config.yaml: classifier 섹션을 gemma4:e4b-it-q8_0 으로 복원. 이전
B-0 커밋이 classifier 를 주석 처리했는데, 실제로는 classifier_service
가 쓰고 있어 gate 유효. exaone 은 이미 제거됐으니 모델만 gemma4 로
통일. classifier_service 의 hasattr 체크는 유지되어 fallback 안전.
D13 (STT 이전) drift 를 main 으로 승격. inventory 갱신은 B-3 마감
단계에서 3-tier + STT 경로 묶어서 일괄.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
배포 검증 중 발견: domain_policy.yaml 이 repo root 에 있지만 fastapi
컨테이너의 build context 는 ./app 이라 COPY 가 포함하지 못함. 결과
load_policy() 가 FileNotFoundError.
1. docker-compose.yml: config.yaml 과 동일 패턴으로 읽기전용 bind mount
- ./domain_policy.yaml:/app/domain_policy.yaml:ro
2. app/policy/loader.py: _resolve_path 에 4 개 후보 검색 추가 —
cwd / /app / /app/.. / <this>.parent.parent.parent 순으로 파일 존재
확인. 첫 매칭 반환. 로컬/컨테이너/다른 배포 환경 모두 호환.
CI: pytest tests/policy/ -q → 98 passed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- accept-suggestion: documents.updated_at != expected stale 검사 제거.
classify_worker 가 source_updated_at 을 pre-commit 값으로 저장하는데
SQLAlchemy onupdate 가 commit 에서 updated_at 을 bump → 항상 불일치 →
승인 영구 불가. payload 교체 검사 하나만으로 core race 는 막힘.
사용자 직접 편집 감지는 별도 user_updated_at 컬럼 도입 시 재논의.
- docker-compose.yml: postgres/kordoc/fastapi/frontend 포트 127.0.0.1
바인딩. GPU 서버 로컬에만 있던 drift 를 main 으로 승격. UFW-Docker
우회 컨텍스트에서 불필요한 LAN 노출 축소.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
stt:
- services/stt/server.py: lazy → eager preload in FastAPI lifespan.
STT_PRELOAD=0 으로 lazy 강제 가능 (개발/테스트). preload 실패해도
프로세스는 살아 있고 /ready false 로 남아 healthcheck 가 unhealthy 처리.
- docker-compose.yml: healthcheck /health → /ready. /health 는 단순
liveness 라 모델 미적재 상태도 healthy 로 잡혀 운영 신호 부적합.
queue ORM:
- app/models/queue.py: process_stage enum 에 'stt'/'thumbnail' 추가 +
create_type=False (migration 150/151 가 DB enum 확장 담당). 이게
없으면 stt_worker INSERT 시 SQLAlchemy 가 enum value 를 거부.
dashboard 강화 (§4 선제, §3 신규 stage 까지 자동 커버):
- app/api/dashboard.py: category_counts + library_pending_suggestions +
queue_lag (stage 별 pending/processing/failed + oldest_pending_age_sec).
- frontend/src/lib/stores/system.ts: QueueLag 타입 + DashboardSummary 확장.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
25MB 파일 크기 제한은 텍스트 PDF(18MB 성공)까지 차단하는 문제.
실제 원인은 이미지 스캔 PDF의 in-memory 파싱 시 메모리 폭발.
- extract_worker: 25MB 파일 크기 제한 삭제
- docker-compose: kordoc-service mem_limit 4g + memswap_limit 4g
- 텍스트 PDF → 크기 무관 정상 파싱
- 이미지 PDF → 4GiB 초과 시 Docker OOM-kill → 재시작 → 3회 실패 후 failed
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
기존 fastapi build context는 ./app이라 부모 디렉토리의 migrations/가
컨테이너에 들어가지 않아 init_db()의 _run_migrations가 디렉토리 부재로 스킵.
016까지는 postgres docker-entrypoint-initdb.d 마운트로 첫 init 시점에만
적용되었고, 이후 추가된 마이그레이션(101 등)이 자동 적용되지 못하는 문제.
./migrations:/app/migrations:ro 한 줄 마운트로 init_db()가 100+ 마이그레이션
추적 + 적용 가능. Phase 4 deploy 검증 중 발견.
TEI 1.5 첫 시도 시 'builder error: relative URL without a base' 에러로
BAAI/bge-reranker-v2-m3 metadata 다운로드 실패. TEI 1.5의 알려진 버그.
해결: TEI 1.7로 업그레이드 (sequence-classification reranker 모델 지원 개선).
- NAS fail-fast: 시작 시 /documents/PKM 존재 확인, NFS 미마운트 방지
- ollama/ai-gateway 포트를 127.0.0.1로 제한 (외부 무인증 접근 차단)
- deploy.md: Caddy HTTPS 자동발급 → 앞단 프록시 HTTPS 종료 구조 반영
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Mac mini nginx proxies to GPU server Caddy. localhost-only binding
blocked external connections.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Integrate ollama + ai-gateway into root docker-compose.yml
(NVIDIA GPU runtime, single compose for all services)
- Change NAS mount from SMB (NAS_SMB_PATH) to NFS (NAS_NFS_PATH)
Default: /mnt/nas/Document_Server (fstab registered on GPU server)
- Update config.yaml AI endpoints:
primary → Mac mini MLX via Tailscale (100.76.254.116:8800)
fallback/embedding/vision/rerank → ollama (same Docker network)
gateway → ai-gateway (same Docker network)
- Update credentials.env.example (remove GPU_SERVER_IP, add NFS path)
- Mark gpu-server/docker-compose.yml as deprecated
- Update CLAUDE.md network diagram and AI model config
- Update architecture.md, deploy.md, devlog.md for GPU server as main
- Caddyfile: auto_https off, HTTP only (TLS at upstream proxy)
- Caddy port: 127.0.0.1:8080:80 (localhost only)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Frontend SvelteKit build has dependency conflicts (Svelte 5 + Vite 8).
Phase 0 setup wizard is served by FastAPI/Jinja2, no frontend needed.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add users table to migration, User ORM model
- Implement JWT+TOTP auth API (login, refresh, me, change-password)
- Add first-run setup wizard with rate-limited admin creation,
TOTP QR enrollment (secret saved only after verification), and
NAS path verification — served as Jinja2 single-page HTML
- Add setup redirect middleware (bypasses /health, /docs, /openapi.json)
- Mount config.yaml, scripts, logs volumes in docker-compose
- Route API vs frontend traffic in Caddyfile
- Include admin seed script as CLI fallback
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
hyungi
hyungi