NAS 정식 배포 완료 상태를 SSOT에 반영

docs/ops/deployment-pipeline.md

@@ -61,10 +61,38 @@ NAS 배포는 Forgejo에서 직접 pull하는 방식으로 전환하고, cloudfl
 - Forgejo master == 로컬 master (배포 무결성)
 - NAS: `docker compose ps` healthy, `/api/health` ok·db/engine true
 
-## 5. 남은 구성 작업 (TODO)
+## 5. 실증된 배포 절차 (2026-09-01 1차 실배포 완료, SHA `dce85620`)
 
-- [ ] Forgejo master를 기준으로 NAS 자동배포 스크립트/후크 구성 (또는 NAS에서 git pull)
-- [ ] `origin`(github) private 유지하나 Forgejo가 SSOT임을 문서·SSOT 대시보드에 반영
-- [ ] cloudflare tunnel 제거 (서빙용만 유지)
+NAS 호스트에는 git이 없으므로 git 컨테이너로 Forgejo에서 clone한다.
+
+```sh
+# NAS에서 (ssh yunchan@192.168.0.38)
+cd /volume1/docker/vignette-prod
+# 0) 백업: pg_dump custom + env.nas 사본 + 구 이미지 SHA 기록
+docker exec vignette-prod-db-1 pg_dump -U vignette_owner -d vignette -Fc > backups/pre-deploy-<sha>-<ts>.dump
+cp private/env.nas private/env.nas.before-deploy-<sha>
+# 1) Forgejo master clone (git 컨테이너) + HEAD 검증
+docker run --rm -v $PWD:/work alpine/git clone --depth 1 --branch master \
+  http://192.168.0.38:3000/yunchan/vignette.git /work/src-<sha>
+# 2) 이미지 빌드 (API 컨텍스트는 저장소 루트)
+cd src-<sha> && docker build -f apps/api/Dockerfile -t vignette-nas-api:<sha> .
+docker build --build-arg VITE_API_BASE=/api -t vignette-nas-web:<sha> apps/web
+# 3) 새 마이그레이션은 psql로 온라인 적용(initdb 스크립트는 재실행되지 않음),
+#    구 API가 의존하는 제약을 바꾸는 마이그레이션은 stop api 후 적용
+# 4) private/env.nas의 VIGNETTE_NAS_API_IMAGE/WEB_IMAGE를 새 이미지 ID로 교체
+docker compose -f docker-compose.nas.yml --env-file private/env.nas config --quiet
+docker compose -f docker-compose.nas.yml --env-file private/env.nas up -d
+# 5) readiness: public health ok·db/engine true, OpenAPI 200, /auth/me 401, 데이터 집계 전후 동일
+```
+
+공개 웹(Cloudflare Pages)은 별도 배포한다: `apps/web`에서 `npm run build` →
+`node ../../scripts/preserve-assets.mjs`(이전 세대 자산 보존) →
+`npx wrangler pages deploy dist --project-name vignette --branch main`.
+
+## 6. 남은 구성 작업 (TODO)
+
+- [ ] Forgejo master 기준 NAS 자동배포 후크(수동 절차는 §5로 실증 완료)
+- [x] Forgejo가 SSOT임을 문서에 반영, github은 private 미러 유지
+- [ ] cloudflare tunnel 제거 검토 — 현재 api-vignette 서빙이 NAS 호스트 상주 cloudflared 터널 경유라 제거 시 대체 ingress 필요(소유자 결정)
 - [ ] 배포 시 NAS 접근 자격(SSH 키/배포 계정)을 `.env.deploy`/시크릿으로 관리
 ```