# 배포 파이프라인 (Deployment Pipeline) > 작성: 2026-08-31 · 2026-10-25 현행화 · 문서 소유: docs/ops > 상태: 2026-10-26 Forgejo `master` SHA `14061d25e9ed90b3c04d8867be78ae9208cb7f7a`(장식 배경 WebP, 글꼴 분할본 포함)를 Pages production `0e90049c`와 NAS web에 반영했다. NAS API는 2026-10-25 `7facf961` 그대로다. 공개 터널은 자동 재시작 compose 컨테이너다(§5.8~§5.10). ## 목표 아키텍처 (소유자 지시) ``` 이 PC(개발 워크스테이션) │ push (master) ▼ Forgejo git.chanpaca.net ────── 소스 SSOT (이관 완료 2026-08-31) │ ├─ 미러(백업) ── github.com (private 유지) [현행 origin] │ └─ 배포 ──▶ NAS Production (vignette-prod) │ docker-compose.nas.yml (SSOT-host=nas, runtime-class=production) │ Cloudflare tunnel은 소유자 지시에 따라 제거 대상이다. 다만 현재 NAS ingress가 이를 경유하므로, 대체 ingress의 보안·가용성·OAuth 경계를 검증하기 전에는 제거하지 않는다. ``` - 나는 이 PC를 **개발 전용**으로만 사용한다. 배포 대상은 반드시 **NAS Production**이다. - github.com은 **private**로 백업/미러만 유지한다 (제거 아님). - git 관리·배포 파이프라인은 **git.chanpaca.net (Forgejo)** 이 소유한다. ## 1. 저장소 (소스 SSOT) | 원격 | URL | 역할 | 상태 | |---|---|---|---| | `origin` | https://github.com/yunchan8804-blip/vignette.git | private 백업/미러 | 유지 | | `forgejo` | ssh://git@git.chanpaca.net:2222/yunchan/vignette.git | **소스 SSOT·배포** | ✅ 이관 완료 | - Forgejo 레포: `yunchan/vignette` (id 14, public, default master) - 2026-09-01 배포 당시 기준 커밋: `dce85620`. 현재 master/로컬 HEAD는 실행 전에 별도로 확인한다. - Forgejo 접근: SSH 키(`~/.ssh/id_ed25519`, Host `git.chanpaca.net` → `192.168.0.38:2222`) · API 토큰(`infra/.env.deploy`의 `FORGEJO_API_TOKEN`, gitignore) ## 2. 로컬 브랜치 규칙 - `master` = Forgejo `master`와 동기화 (배포 기준선) - 기능/scoped 브랜치 = 개발용, 검증 후 master로 합침 ## 3. NAS Production 배포 흐름 (수동 절차 실증, 자동화 구성 예정) ``` [Forgejo] 승인된 master 후보 SHA ▼ [NAS] git 컨테이너로 해당 SHA clone·검증 ▼ [NAS] 변경 범위·필요 migration 호환성 검토 → 이미지 빌드 → 필요한 서비스별 교체·readiness ▼ vignette-prod (api/web/engine/db/proxy) readiness·데이터 보존 검증 ▼ [Cloudflare] 현재 공개 서빙 경로 유지 (대체 ingress 검증 뒤 tunnel retirement) ``` NAS 호스트에는 git이 없으므로 git 컨테이너로 Forgejo에서 clone한다. 2026-09-01 수동 실배포는 이 흐름으로 `dce85620`을 검증했다. 자동배포 hook과 tunnel retirement는 별도 열린 게이트다. ## 4. 검증 게이트 (배포 전) - `apps/web`: `npm run typecheck`, `npm run build` - `apps/api`: 관련 test suite (전체 1104 passed / 1 skipped) - SSOT checker `scripts/check-dev-dashboard-ssot.py` - Forgejo master == 로컬 master (배포 무결성) - NAS: 후보 변경 파일 범위로 engine 영향부터 판정한다. engine 코드·공통 requirements·`apps/api/Dockerfile`가 바뀌지 않았다면 API와 같은 이미지 참조를 쓰더라도 engine을 재생성하지 않는다. - NAS: `docker compose ps` healthy, 공개 `/health`의 `db: true`·`engine: true`, 실제 인증 UI 확인 전에는 완료를 선언하지 않는다. 컨테이너 `Started`는 완료 증거가 아니다. ## 5. 실증된 배포 절차 (2026-09-01 1차 실배포 완료, SHA `dce85620`) 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--.dump cp private/env.nas private/env.nas.before-deploy- # 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- # 2) 이미지 빌드 (API 컨텍스트는 저장소 루트) cd src- && docker build -f apps/api/Dockerfile -t vignette-nas-api: . docker build --build-arg VITE_API_BASE=/api -t vignette-nas-web: apps/web # 3) migration이 필요하면 호환성을 먼저 검토하고 적절한 시점의 별도 게이트에서 적용한다. # initdb 스크립트는 재실행되지 않으며, 구 API가 의존하는 제약 변경은 stop api 뒤 적용할 수 있다. # 4) 후보 변경 범위로 교체 대상을 판정한다. # engine 코드·requirements·apps/api/Dockerfile 변경이 없으면 engine은 유지한다. # API만 바뀌면 API만, web만 바뀌면 web만 --no-deps로 재생성한다. # engine 변경이면 engine을 먼저 교체하고 healthy 및 engine readiness를 확인한 뒤 API를 교체한다. # compose의 --wait 지원 여부는 현장에서 확인되지 않았으므로 쉘 폴링으로 health를 확인한다. # 단일 API 교체에는 기동 공백이 있다. 무중단은 별도 blue/green 전환 게이트를 통과한 경우에만 주장한다. # 5) 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 --no-deps api web # engine 변경 시에는 위 API/Web 명령 전에 별도로 `up -d --no-deps engine`을 실행한다. # 6) API 교체 뒤 healthy, 공개 /health의 db/engine true, 실제 인증 UI, 데이터 집계 전후 동일을 확인한다. # rollback은 자동 실행하지 않는다. 사전 DB dump와 이전 이미지·환경 파일을 보존하고 소유자가 결정한다. ``` 공개 웹(Cloudflare Pages)은 별도 배포한다: `apps/web`에서 `npm run build` → `node ../../scripts/preserve-assets.mjs`(이전 세대 자산 보존) → `npx wrangler pages deploy dist --project-name vignette --branch main`. ## 5.1 2차 정식 실배포 완료 (2026-09-08, SHA `a0311c59`) - **Forgejo / GitHub master 동기화**: `a0311c59` (파이프라인 문서 포함 `d9bb5b36`). - **사전 백업**: - DB dump: `/volume1/docker/vignette-prod/backups/pre-deploy-a0311c59-.dump` (12MB, custom 포맷) - 환경변수: `private/env.nas.before-deploy-a0311c59` - **NAS Docker 빌드 및 배포**: - API 이미지: `vignette-nas-api:a0311c59` (`sha256:8b1ed23d1d24...`) - Web 이미지: `vignette-nas-web:a0311c59` (`sha256:5c34139d8b56...`) - `private/env.nas` 이미지 SHA 갱신 및 `docker compose up -d` - 컨테이너 전건 healthy: `vignette-prod-api-1`, `vignette-prod-engine-1`, `vignette-prod-db-1`, `vignette-prod-web-1`, `vignette-prod-private-proxy-1` - **Cloudflare Pages 배포**: - `apps/web`: `npm run build` 성공 - `node ../../scripts/preserve-assets.mjs` 실행 (174개 이전 세대 자산 보존) - `npx wrangler pages deploy dist --project-name vignette --branch main` 성공 (`https://vignette.chanpaca.net`, preview: `https://2df910db.vignette-b1q.pages.dev`) - **Live 폐루프 검증**: - `https://api-vignette.chanpaca.net/health` -> `status: ok`, `db: true`, `engine: true`, `openai: true` - `https://api-vignette.chanpaca.net/auth/me` -> `401 Unauthorized` (fail-closed 보장) - `https://vignette.chanpaca.net` -> `HTTP 200 OK` ## 5.2 서비스별 교체·기동 공백 관찰 (2026-09-09, SHA `1306c524`) - API와 engine을 동시에 재생성한 동안 사용자가 다운을 보고했다. 이는 단일 API 교체에도 기동 공백이 생길 수 있음을 드러낸 관찰이며, 영구 장애 원인으로 단정하지 않는다. - 이후 같은 버전에서 컨테이너 healthy, 공개 `200`, 학습자 회기 조회 정상과 DB 전체 집계 동일을 확인했다. 이 회복 관찰은 무중단 배포 증거가 아니다. - 다음 배포는 §5의 변경 범위 판정을 먼저 적용한다. engine 변경이 있으면 engine healthy·readiness 뒤 API를 교체하고, engine 변경이 없으면 API와 같은 이미지 참조만으로 engine을 재생성하지 않는다. ## 5.3 3차 정식 배포 완료 (2026-09-11, SHA `4b45d331`) - 관리자 AI 제공자 연결 기능(토큰 붙여넣기 연결, `app.admin_provider_credential`) 배포. - §5 절차 준수: DB dump(`pre-deploy-4b45d331-.dump`, 11.8MB) + `env.nas.before-deploy-4b45d331` 백업 뒤 클론·빌드. - 변경 범위 판정: engine 코드 변경 존재 → **engine 먼저 재생성, healthy 확인 뒤 api·web 교체**(§5.2 교훈 적용, 동시 재생성 회피). - 이미지: `vignette-nas-api:4b45d331`(sha256 c6b9201ec8ef), `vignette-nas-web:4b45d331`(sha256 d999ea74a8e4). env.nas 이미지 참조 갱신. - 기동 확인: api·engine `healthy`, `http://127.0.0.1:18080/health` 및 공개 `https://api-vignette.chanpaca.net/health` → `status: ok, db: true, engine: true`(engine_mode openai, ready OK). - 배포 후 관리자가 `/admin/ai` 제공자 연결 패널에서 claude·codex·agy·openrouter 토큰을 연결하면 실행 중인 engine 컨테이너에 즉시 push 적용된다(재배포 불필요). - 이후 수정(`e3a9fc71`, `cb4d4557`): 앱 DB 계정엔 스키마 CREATE 권한이 없어 런타임 DDL이 권한 거부로 실패 → 소유자로 테이블 선생성(DDL은 `05_runtime_auth.sql`에 정식 반영) + `to_regclass` 존재 검사 선행(r2), OAuth 로그인 버튼(claude·openrouter PKCE 코드 교환) 추가(r3). 교체는 각각 api만 `--no-deps`로 수행, engine은 코드 변경이 없어 유지했다. ## 5.4 UX 웹 배포와 NAS web 전용 교체 (2026-09-12 배포 시작 17:55:31 KST · NAS 교체/로컬 HTTP 확인 18:06 KST, SHA `e8b770e4d9023238bf210b412de75dcb98bfc08e`) - Forgejo `master` push는 완료했다. Pages preview `https://1b115047.vignette-b1q.pages.dev` 배포도 완료했다. - 공개 `https://vignette.chanpaca.net`은 HTTP 200이고 `/assets/index-BA_Q0J7Y.js`가 새 번들과 일치한다. 이전 세대 자산 175개를 보존했다. - 공개 로그인 390px·1440px 원본을 직접 시각 검수해 수용했다. 각 확인에서 overflow, page error, failed request는 0건이었고 공개 health는 `db: true`, `engine: true`다. - NAS는 **web만** `vignette-nas-web:e8b770e4` (`sha256:487e745aa08c113de4994d7d4770737539b1bc49494f5cbb802e6dc0f8c535f9`)로 교체했고 로컬 HTTP 확인은 exit 0이다. `.devlogs/deploy-20260912-nas-before.txt`와 `nas-after.txt` 첫 3줄 대조에서 API·engine·DB 컨테이너 ID와 이미지는 동일했다. - DB dump `backups/pre-deploy-e8b770e4-20260912.dump`(11,783,464 bytes)는 `pg_restore --list`를 통과했고 `private/env.nas.before-deploy-e8b770e4`를 보존했다. 공개 health도 다시 `status: ok`, `db: true`, `engine: true`를 확인했다. - 공개 Pages의 현재 JS/CSS asset 의존 그래프는 로컬 `dist`와 비교해 52/52 HTTP 200이며 SHA-256이 일치한다. NAS web은 `/api` 빌드의 `index-Ccefqm_F.js`·`index-B1latakI.css`를 쓰며, 이는 `nginx -t`와 로컬 HTTP exit 0으로 별도 검증했다. - 따라서 Pages와 NAS web 전용 배포 반영은 완료했다. 다만 운영 인증 세션 만료로 내부 UI는 401이라 검증하지 못했으므로, 이 절은 전체 운영 내부 화면 GREEN이나 전체 기능 출시 완료를 의미하지 않는다. 구조화 증거: [`ux-web-deploy-2026-09-12.json`](./evidence/ux-web-deploy-2026-09-12.json). ## 5.5 재기동 복구 — 호스트 상주 cloudflared 터널 (2026-09-18 실측·복구 완료) - **증상과 범위**: 2026-09-18 공개 `https://api-vignette.chanpaca.net/*` 전 경로가 HTTP 530(`error code 1033`)을 반환했다. 같은 시각 공개 웹 `https://vignette.chanpaca.net`은 200으로 정상이었고, NAS 내부 `http://127.0.0.1:18080/health`도 200(`status: ok, db: true, engine: true`)이었다. 즉 api·db·engine·web 컨테이너는 모두 정상이었고 장애 범위는 **터널 구간 단일**이었다. 외부에서 18080이 닫혀 있는 것은 `infra/docker-compose.nas.yml`의 api 서비스가 `127.0.0.1:18080:8000`으로 loopback 바인딩된 설계이며 이번 장애와 무관하다. - **원인**: NAS가 2026-09-18 03:44경(KST) 재부팅됐다(`uptime` 12시간 1분, `/proc/uptime` 43301초로 확인). 재부팅 직전까지 cloudflared는 **NAS 호스트 상주 프로세스**로 정상 동작 중이었다 — `private/cloudflared-host.log` 마지막 줄이 `2026-09-17T18:09:06Z INF Initiating graceful shutdown due to signal terminated`(UTC, KST 03:09:06)로, 크래시가 아니라 재부팅에 의한 SIGTERM 정상 종료였다. 문제는 재부팅 후 이 호스트 프로세스가 자동으로 재기동되지 않았다는 데 있다: `ps -ef`에 cloudflared 없음, `netstat -an | grep :7844` 0건, `private/cloudflared-host.pid`는 stale이었다. `/usr/local/etc/rc.d/`는 빈 디렉터리고 `/etc/rc.local`도 없어 부팅 시 자동 시작 등록 자체가 없다. Docker의 컨테이너 restart 정책은 컨테이너만 보호하며, 터널은 컨테이너가 아닌 **호스트 프로세스**라 그 보호 범위 밖이다. - **복구 절차 및 실행 결과**: NAS에서 [`scripts/nas-recover-prod.sh`](../../scripts/nas-recover-prod.sh)를 실행하거나 아래 명령을 직접 수행한다. sudo·docker 권한은 필요 없다. 2026-09-18 16:13 KST(NAS 로컬시각)에 이 명령으로 호스트 터널을 재기동해 PID 25806으로 가동했다. ```sh cd /volume1/docker/vignette-prod nohup ./bin/cloudflared tunnel --no-autoupdate --config private/cloudflared-host.yml run >> private/cloudflared-host.log 2>&1 private/cloudflared-host.pid ``` 복구 후 공개 `https://api-vignette.chanpaca.net/health` → 200(`status: ok, db: true, engine: true`), 공개 `https://api-vignette.chanpaca.net/auth/me` → 401 `{"detail":"not authenticated"}`, 응답 헤더 `access-control-allow-origin: https://vignette.chanpaca.net`·`access-control-allow-credentials: true`를 확인했다. - **완료 판정 기준**: 공개 `/health`가 200이며 `db: true`·`engine: true`이고, **동시에** 공개 `/auth/me`가 401 + CORS 헤더(`access-control-allow-origin`·`access-control-allow-credentials`) 정상이어야 한다. 둘 중 하나만 확인하고 복구로 판정하지 않는다. - **함정**: `yunchan` 계정은 `/var/run/docker.sock`(root:root 660)에 접근 권한이 없어 `docker`·`docker compose` 명령이 전부 `permission denied`다. `sudo`는 비밀번호를 요구한다. 따라서 compose 기반 복구 명령은 현재 SSH 계정으로 실행할 수 없다. - **오진 기록**: 이 절은 원래 "cloudflared가 compose의 `profiles: [public-cutover-gate]` 게이트라 `--profile` 없이 `up -d` 하면 터널이 빠져 530이 재발한다"고 진단했으나, 이는 **오진이었다.** 근거: (1) 호스트 로그가 재부팅 직전(KST 03:09:06)까지 정상 갱신되고 있어 애초에 compose 컨테이너가 아닌 호스트 프로세스가 떠 있었다. (2) 재부팅 후 관측은 호스트 프로세스 부재(`ps -ef`)와 터널 엣지(`:7844`)로 나가는 연결 0건이었지 compose 프로파일 문제의 증상이 아니었다. (3) 이 판단은 §6의 "현재 `api-vignette`는 NAS 호스트 상주 cloudflared 터널 경유다" 기술과도 모순됐다. 이력을 지우지 않고 오진이었음을 남긴다. - **앱 증상 연결**: `apps/web/src/lib/auth.tsx`의 `restoreCurrentUser`는 `GET /auth/me`를 3회 재시도(지연 0/400/1000ms, 각 5초 abort) 후 실패하면 `restoreState="failed"`가 되고, `apps/web/src/App.tsx:113-135`의 "서버 연결 진단" 화면이 뜬다. 401만 정상 로그아웃으로 처리되며 530을 포함한 나머지 실패는 모두 이 화면으로 떨어진다. - **해결(2026-10-25)**: 공개 터널을 restart `unless-stopped` compose 컨테이너로 전환해 재부팅 자동 기동을 도커에 맡겼다. 위 호스트 상주 복구 절차는 대체 경로로만 남는다(§5.9). ## 5.6 승인 릴리스 배포 완료 (2026-10-20, SHA `aeddaa6972cafabec8113745037533893db0ac34`) - Forgejo `master` push는 완료했고 Cloudflare Pages production `f2039a2e`를 `main` 브랜치에 배포했다. 공개 `https://vignette.chanpaca.net`에서 desktop/mobile 로그인 화면은 정상 렌더, page error·import 오류는 각각 0건, 무인증 `/auth/me`는 401이었다. 이 검증은 인증된 내부 화면 검증이 아니다. - Pages entry `/assets/index-BAtV-qxp.js`와 stylesheet `/assets/index-CNzKarrr.css`의 공개 SHA-256은 로컬 산출물과 일치했고 이전 세대 자산 179개를 보존했다. `pages.dev` 주소는 API CORS 비허용으로 재연결 화면을 보여 로그인 정상 판정 근거에서 제외했다. - 사전 검증은 API legacy 1263 passed·1 skipped·1 warning, engine gateway 82 passed·1 warning, harness 68 passed, API types/typecheck/build/SSOT checker 통과다. 처음 desktop/mobile focused 실행의 10개 실패는 API 미기동 환경 원인이었고, 스택 기동 뒤 desktop 9 passed·mobile 9 passed와 별도 `single-run` 15 passed를 재확인했다. - NAS API(`sha256:309ccd2d…`)와 web(`sha256:6ca536db…`)을 교체하고 migration 25를 트랜잭션으로 적용했다. admin-only DELETE policy `app.current_role_name() = 'admin'`를 실증했다. engine·DB 컨테이너 ID/이미지/volume source와 runtime compose는 그대로 보존했다. - DB dump 11,892,253 bytes와 TOC, uploads 93개·52,973 bytes·manifest SHA-256 `2e7f31a28d3d7f527f62092b3adfc96bf92f5cd35769a498d242b99cbeae43d2`를 보존했다. 118개 테이블의 전후 행 수가 모두 같고, 행 수가 달라지거나 줄어든 테이블은 각각 0개다. retention dry-run은 raw 90일·rollup 365일에서 `applied=false`, 삭제 0으로 끝났으며 실제 apply는 별도 소유자 승인 대상이다. - `nginx -t`, 공개 health 3회(200, `status=ok`, `db=true`, `engine=true`), 무인증 `/auth/me` 401의 정확한 CORS origin/credentials, auth config/OpenAPI 200, Google 로그인 시작 302을 확인했다. API 단일 교체 중 curl reset/empty reply가 있었고 이후 회복했으므로 무중단 배포를 주장하지 않는다. 인증된 운영 내부 UI, Jev 품질/실제 대사, 외부·임상 gate는 열린 상태다. 구조화 증거: [`release-2026-10-20.json`](./evidence/release-2026-10-20.json). ## 5.7 승인 릴리스 배포 완료 (2026-10-24, SHA `b0ff44a1d4d3aed19b1bb0e1bbd0aab327aef0ea`) - 범위는 API 계약 1파일(`supervision_research.py`)과 web(라우터 7·딥링크 보존·동기 갱신 복구)이라 API·web만 `--no-deps`로 교체했다. engine·DB·proxy·cloudflared와 compose는 그대로이며 migration은 없다. - 사전 단계: DB dump 11,899,558 bytes(SHA-256 `17811709…`)·`pg_restore -l` 1,809줄, uploads 93개·52,973 bytes manifest, 테이블 행 수, `env.nas` 사본을 `receipts/release-20261024-20261024T130800Z`에 남겼다. 소스는 git 컨테이너 clone 뒤 SHA를 대조했다. - 교체 뒤 nginx 설정 검사 통과, uploads manifest 동일, 행 수 차이는 `app.auth_session` 1건 증가뿐이다. 공개 health 3회 200·ok, 무인증 `/auth/me` 401과 CORS, Google 로그인 시작 302, Pages `42eef402`의 JS/CSS hash 일치와 desktop/mobile 렌더, 딥링크 `next` 보존을 확인했다. - 함정: NAS 원격 명령에서 `cat > 파일 && ... & echo`처럼 체인 전체를 백그라운드로 보내면 stdin이 끊겨 빈 스크립트가 실행된다. 업로드와 `setsid nohup` 실행을 별도 ssh 호출로 나눈다. NAS에는 `pgrep`이 없다. - API 재생성부터 healthy까지 68초였으므로 무중단은 주장하지 않는다. 구조화 증거: [`release-2026-10-24.json`](./evidence/release-2026-10-24.json). ## 5.8 운영 점검 결함 수정 반영 (2026-10-25, SHA `7facf961c5c48355e1c4a2e05e2688811f49b8db`) - 소유자 지시로 운영 전 기능을 점검했다. 소유자 관리자 계정(Google 로그인)으로 23개 경로 × desktop/mobile 46화면을 쓰기 차단 상태로 순회했고, 실제 상담 연습 1회(회기 시작, 2턴, 음성 합성, 종료, 리뷰)를 확인했다. - 발견·수정: (1) 감독·연구 생성 주기가 2026-09-09 근거 링크 변경 뒤 같은 제출 번호에 다른 내용이 들어가 매시 충돌했다(마지막 성공 2026-08-30). 제출 번호 지문이 저장 내용 전체를 덮게 했다. (2) NAS 볼륨 동기 쓰기가 4KB당 약 0.35초라 로그인 요청마다 `last_seen_at` 확정 쓰기 2회가 `/auth/me`를 1~4초로 늘렸고, 모바일에서 재연결 화면이 떴다. 갱신을 60초 간격으로 묶었다. (3) 운영 공급자 `openai`의 참조 단가가 없어 관리자 AI 비용이 9월부터 $0이었다. `gpt-5.6-terra` 공식 단가를 추가했다. (4) 음성 합성 502의 원인을 서버 기록에 남긴다. - 범위는 `apps/api` 4파일과 테스트라 API만 `--no-deps`로 교체했다. 사전 DB dump 12,062,700 bytes·`pg_restore -l` 1,809줄, uploads 93개 manifest, 120개 표 행 수, `env.nas` 사본을 `receipts/release-20261025-20261025T103250Z`에 남겼다. 교체 뒤 행 수 차이 0, uploads 동일, web·engine·DB 컨테이너와 compose 무변경이다. API 재생성부터 healthy까지 69초였으므로 무중단은 주장하지 않는다. - 반영 뒤 감독·연구 주기가 10:45:31Z에 새 주의 스냅샷과 새 링크 형식 공백 스냅샷을 저장했다. `/auth/me`는 NAS 내부 0.012~0.034초, 공개 0.58~0.89초다. 재순회 46화면에서 재연결 화면·page error·끊긴 요청은 0건이다. - 서버 정리: 재시작만 반복하던 `vignette-prod-cloudflared-1`(설정 권한 거부, 45,869회)과 2026-08 미리보기 `vignette-db-1`(45,664회)을 재시작 정책 `no`로 바꾸고 정지했다. 삭제하지 않았다. 공개 터널은 호스트 상주 cloudflared가 계속 맡는다. - 남은 위험: NAS 공유 호스트 과부하(부하 평균 13~17, 교체 공간 소진, 다른 프로젝트 소유 프로세스)와 재부팅 시 호스트 터널 자동 시작 부재. 구조화 증거: [`release-2026-10-25.json`](./evidence/release-2026-10-25.json). ## 5.9 소유자 결정 후속 조치 (2026-10-25, 글꼴 `5c5b66d0`·복구 스크립트 `8fc829fe`) - **터널 컨테이너 전환**: 2026-09 전환 실패 원인은 `cloudflared/config.yml` 640(컨테이너 계정 65532가 못 읽음)과 빈 비밀 볼륨 `vignette-prod-cloudflared-secrets-20260830`이었다. config를 644로(상위 폴더 750 유지), 인증 파일을 볼륨에 65532 소유 400으로 복사한 뒤 `--profile public-cutover-gate up -d --no-deps --force-recreate cloudflared`로 띄웠다. 연결 4개(icn06/icn07, quic)가 등록됐고, 호스트 상주 cloudflared를 끈 상태에서 공개 health 10/10 200을 확인했다. 지금 공개 터널은 컨테이너 단독이다. - **복구 스크립트**: NAS 계정의 `ps`에는 컨테이너 프로세스가 보이지 않아 기존 중복 판정이 컨테이너를 놓쳤다. [`scripts/nas-recover-prod.sh`](../../scripts/nas-recover-prod.sh)는 `docker inspect`로 컨테이너를 먼저 판정·기동하고 실패할 때만 호스트 상주 터널을 띄운다. 컨테이너를 멈추고 실행해 재기동과 `RECOVER_DONE`을 확인했다. NAS 재부팅 자체는 공유 호스트라 실증하지 않았다. - **글꼴**: 첫 접속 때 최우선으로 받던 `PretendardVariable.woff2`(2,057,688 bytes) preload를 없애고 공식 92분할본(unicode-range)을 자체 호스팅했다. 공개 `/login` 첫 접속 글꼴 전송은 8요청 209,456 bytes이고, 변경 전후 로컬 화면 그림은 SHA-256까지 같다. 옛 전체 글꼴 파일은 이전 세대 CSS가 참조해 남겼다. web만 바뀌어 Pages(`d4a089db`)만 반영했고 NAS web 이미지는 다음 릴리스 때 갱신한다. - **NAS 정리**: 다른 프로젝트의 9일째 비밀번호 입력 대기 `createdb`와 5일 20시간 대기 Forgejo CI 작업 컨테이너를 소유자 승인으로 정리했다. - **남은 것**: Cloudflare가 한국 요청을 LAX 거점으로 처리해 Pages 자산이 초당 60~250KB로 내려온다(소유자 결정: 지켜보기, 실제 사용자 진단 보고 0건). 글꼴 뒤 병목은 사이드바 배경 PNG(1,168,196 bytes, 어두운 판 1,761,725 bytes)다. 구조화 증거: [`release-2026-10-25.json`](./evidence/release-2026-10-25.json)의 `followup_owner_decisions`. ## 5.10 장식 배경 WebP 전환과 NAS web 갱신 (2026-10-26, SHA `14061d25e9ed90b3c04d8867be78ae9208cb7f7a`) - **변경**: 학습자 대시보드 장식 14개와 로그인·회기 배경 2개를 같은 이름의 WebP(품질 90, 투명도 무손실)로 바꿨다. 합계 8,504,051→968,652 bytes, 사이드바 배경 1,168,196→152,228 bytes다. 옛 PNG는 이전 세대 CSS 참조 때문에 남기고 공유 미리보기(og:image)는 PNG를 유지한다. - **로컬 검증**: `check:design-ssot`·typecheck·build 통과. `layout-visual-gate` 15 passed, `auth-visual` 1 passed, `session-layout` desktop+mobile `--workers=1` 10 passed. 10개 병렬 실행은 회기 시작 대기 시간 초과가 실행마다 다르게 나서(testing.md의 병렬 포화 함정) 기준에서 뺐다. 같은 화면을 WebP와 PNG로 그려 비교한 16쌍에서 배경 영역 차이는 평균 0.03/255 수준이다. - **Pages**: production `0e90049c`. 공개 JS/CSS SHA-256이 dist와 같고, 공개 CSS의 대상 PNG 참조는 0이다. 직전 세대 JS·CSS, 옛 PNG, 옛 전체 글꼴은 200으로 남았다. 2026-10-24 세대 entry는 보존 목록 밖이라 빠졌다. 공개 `/login` 첫 접속은 708,839 bytes(배경이 PNG였다면 약 2,319,786 bytes), page error 0이다. 경로는 여전히 LAX다. - **NAS web 전용 교체**: NAS에만 둔 스크립트 `/volume1/docker/vignette-prod/scripts/release-20261026-web.sh`(인자: 40자 SHA)로 Forgejo clone·SHA 대조 → `vignette-nas-web:14061d25`(`sha256:8ec81318…`) 빌드 → `env.nas` 사본 보존 뒤 pin → `up -d --no-deps web`. 재생성 46초, nginx 검사 통과, NAS CSS SHA-256이 Pages와 같다. api·engine·db·cloudflared 컨테이너와 compose 파일은 전후 동일하다. web 전용이라 DB dump는 하지 않았고, 공개 API는 api 컨테이너가 직접 받아 끊기지 않았다. - **남은 것**: Cloudflare LAX 경로 지켜보기(소유자 결정), 인증된 운영 화면 재순회로 화면당 시간 재측정(소유자 로그인 필요), NAS 재부팅 실증(공유 NAS). 구조화 증거: [`release-2026-10-26.json`](./evidence/release-2026-10-26.json). ## 6. 남은 구성 작업 (TODO) - [ ] Forgejo master 기준 NAS 자동배포 후크(수동 절차는 §5, §5.1로 실증 완료) - [x] Forgejo가 SSOT임을 문서에 반영, github은 private 미러 유지 - [ ] cloudflare tunnel 제거 또는 유지 결정 — 현재 `api-vignette`는 NAS 호스트 상주 cloudflared 터널 경유다. 대체 ingress의 보안·가용성·OAuth 경계가 검증되기 전에는 제거하지 않는다. - [ ] 배포 시 NAS 접근 자격(SSH 키/배포 계정)을 `.env.deploy`/시크릿으로 관리