docs(storage): Storage PR-1 — read-only inventory + 정책 문서

Storage Backbone NAS 트랙의 첫 PR. plan v6 명시대로 read-only inventory PR — 운영 변경 / mount 변경 / file_path 갱신 / asset 이동 모두 0건. 문서만. 산출물: - docs/storage_layout.md 영구 정책 문서 (정책 / 마운트 매트릭스 / NFS 옵션 baseline) - reports/storage_inventory_2026-05-11.md 측정 결과 snapshot 핵심 인사이트: 1. NAS binary layer 는 이미 잘 분리되어 있음 — PKM/extracted_images/ study_question_images 모두 이미 NAS. 추가 이관 PR-3/4 작업량 거의 없음. 2. 현 GPU NFS mount = plan v6 권고안 baseline 과 정확히 같음 (soft, vers=4.1, timeo=10, retrans=3) — PR-2 는 mount 옵션 변경 아닌 애플리케이션 layer (정규화 wrapper / 장애 처리 / uid 매핑) 에 집중. 3. fastapi 만 NAS rw, worker 는 ro — 원본 안전 분리 OK. 4. Postgres pgdata = 1.1GB (DB 본체 이관 안 함, plan 결정 = GPU 잔류). 5. PR-4 도입 시 extracted_emails/ 신규 디렉토리 추가 예정 (Storage PR-5 합류). 실측 명령: SSH 100.111.160.84 → df/mount/du/docker volume ls/docker run -v ... alpine du. 모두 read-only. 운영 영향 0.
2026-05-11 07:23:28 +09:00
parent 8ca27eb573
commit 768fc36746
2 changed files with 257 additions and 0 deletions
@@ -0,0 +1,115 @@
+# Storage Inventory — 2026-05-11
+
+**Storage PR-1 read-only inventory 실측 결과**.
+**측정 명령**: GPU 서버 (100.111.160.84) SSH `df` / `mount` / `du` / `docker volume ls` / `docker run -v ... alpine du`. **read-only**, 운영 변경 없음.
+**참조**: `docs/storage_layout.md` (영구 문서) + plan `~/.claude/plans/beszel-tingly-sloth.md` v6.
+
+## 1. 디스크 사용 요약
+
+### GPU 서버 (Ubuntu, RTX 4070 Ti Super)
+```
+Filesystem                              Size  Used Avail Use% Mounted on
+/dev/mapper/ubuntu--vg-ubuntu--lv       936G  182G  715G  21% /
+192.168.1.227:/volume4/Document_Server  3.5T  401G  3.1T  12% /mnt/nas/Document_Server (NFS)
+192.168.1.227:/volume4/Comic            3.5T  401G  3.1T  12% /mnt/comic (NFS, Document Server 외)
+192.168.1.227:/volume1/Video            (별 volume)
+```
+
+### NAS NFS 옵션 (이미 plan v6 권고안 baseline)
+```
+nfs4 rw,relatime,vers=4.1,rsize=1048576,wsize=1048576,
+soft,proto=tcp,timeo=10,retrans=3,_netdev
+```
+
+## 2. NAS volume 안 Document Server 디렉토리 (`du -sh`)
+
+| 경로 | 크기 |
+|---|---|
+| `/mnt/nas/Document_Server/PKM/` | **38GB** |
+| `/mnt/nas/Document_Server/PKM/Knowledge/` | 31GB |
+| `/mnt/nas/Document_Server/PKM/References/` | 5.5GB |
+| `/mnt/nas/Document_Server/PKM/Inbox/` | 1.5GB |
+| `/mnt/nas/Document_Server/PKM/Videos/` | 116KB |
+| `/mnt/nas/Document_Server/PKM/Recordings/` | 20KB |
+| `/mnt/nas/Document_Server/PKM/Archive/` | 0 |
+| `/mnt/nas/Document_Server/PKM/.preview/` | (6 entry, 소량) |
+| `/mnt/nas/Document_Server/Main/` | **14GB** (의미 확인 필요) |
+| `/mnt/nas/Document_Server/extracted_images/` | 1.2MB |
+| `/mnt/nas/Document_Server/study_question_images/` | 12MB |
+| `/mnt/nas/Document_Server/프로그래밍 전 참고 자료/` | 56KB |
+
+**합계** ≈ 52GB (NAS volume 401GB used 중 일부)
+
+## 3. GPU 서버 local Docker volume (`docker run -v ... alpine du -sh /data`)
+
+| Volume | 크기 |
+|---|---|
+| `hyungi_document_server_pgdata` | 1.1GB (postgres container 안 `du -sh /var/lib/postgresql/data`) |
+| `hyungi_document_server_ollama_data` | **11.9GB** |
+| `hyungi_document_server_stt_models` | 3.0GB |
+| `hyungi_document_server_reranker_cache` | 2.1GB |
+| `hyungi_document_server_ocr_models` | 1.4GB |
+| `hyungi_document_server_marker_models` | 4KB (HF cache 다른 위치로 추정) |
+| `hyungi_document_server_caddy_data` | (작음, 미측정) |
+
+**GPU local 합계** ≈ 19.5GB (시스템 rootfs 182GB used 중 일부, 나머지는 OS/Docker image/홈/별 작업)
+
+## 4. 컨테이너 마운트 매트릭스 (`docker-compose.yml` 추출)
+
+```
+postgres:
+  - pgdata:/var/lib/postgresql/data
+  - ./migrations:/docker-entrypoint-initdb.d (init scripts, 실제 사용 X)
+
+kordoc-service / ocr-service / marker-service / stt-service:
+  - ${NAS_NFS_PATH}:/documents  (ro)
+  - {worker}_models:/root/.cache OR /models  (rw)
+
+fastapi:
+  - ${NAS_NFS_PATH}:/documents  (rw)  ← NAS 쓰기 권한 단일 책임
+  - ./config.yaml ./domain_policy.yaml ./scripts ./logs ./migrations
+
+ai-gateway: ollama_data
+reranker: reranker_cache
+caddy: ./Caddyfile + caddy_data
+```
+
+## 5. 이관 후보 분류
+
+### 확정 NAS (이미 잘 분리됨, 추가 작업 X)
+- `PKM/*` (38GB) — 사용자 컨텐츠 원본
+- `extracted_images/` — Markdown Phase 1B.5
+- `study_question_images/` — 가스기사 PR-8
+- `Main/` (14GB) — 의미 확인 필요지만 이미 NAS
+
+### 확정 GPU local (latency 민감 / AI 인접)
+- Postgres pgdata (1.1GB)
+- AI 모델 cache (ollama / STT / reranker / OCR / marker) ≈ 18.5GB
+- 로그 / Caddy data
+
+### 회색 → 검토 후 결정 (Storage PR-2 영역)
+- `PKM/.preview/` (LibreOffice PDF 변환 cache) — 현재 NAS, 재생성 가능 → GPU local 로 옮길지 검토. *단 가치 작음, 후순위*.
+- `Main/` 14GB 의 실제 내용 확인 — Document Server 가 사용하는지, 별 트랙인지.
+
+### PR-4 도입 시 신규 디렉토리
+- `extracted_emails/{event_id}/` — MailPlus forward ingest 첨부 (Storage PR-5 / events PR-4 합류)
+
+## 6. 핵심 인사이트
+
+1. **NAS 의 binary layer 는 이미 잘 구성**. Storage 백본 트랙의 큰 부분이 *이미 진행됨*. 추가 PR-3/4 의 작업량 = 거의 없음 (PR-5 만 events PR-4 와 합류).
+2. **NFS mount 옵션 = plan v6 권고안 baseline 과 정확히 같음** (`soft,timeo=10,retrans=3,vers=4.1`). Storage PR-2 는 mount 옵션 변경 아닌 *애플리케이션 layer* (정규화 wrapper / 장애 처리 / uid 매핑 / 시뮬 gate) 에 집중.
+3. **Postgres data dir 1.1GB 매우 작음**. DB 본체 이관 자체는 기술적으로 SSD 480GB NAS 에 1000+ 배 여유. 단 plan 결정 = GPU 잔류 (CPU/RAM 우위, 라운드 9). 본 inventory 는 그 결정을 *변경하지 않음*.
+4. **GPU rootfs 21% 사용 (715GB 여유)** — AI 모델 캐시 늘어도 1–2년 여유. 단기 storage 압박 없음.
+5. **fastapi 만 NAS rw**, 다른 worker 는 ro → 원본 안전 보장. 좋은 분리.
+
+## 7. 후속 작업 (Storage PR-1 외)
+
+- **Storage PR-2** (별 PR): 정규화 wrapper / uid·gid 매핑 / NAS 장애 시뮬 gate (test mount 부터) / fastapi 쓰기 경로 fsync+rename 패턴 점검
+- **Storage PR-5** (events PR-4 합류): `extracted_emails/{event_id}/` 표준 + 첨부 저장 패턴
+- **Main/ 14GB 의미 확인** (1회성 chore, 본 PR 범위 외): 사용 안 하는 legacy 면 archive 검토
+
+## 8. 본 PR 산출물 (커밋 대상)
+
+- `docs/storage_layout.md` (영구 정책 문서)
+- `reports/storage_inventory_2026-05-11.md` (본 파일, 측정 결과 snapshot)
+- **코드 / 운영 / mount / fstab / DB / file_path 변경 0건** (read-only inventory PR)