vignette/docs/ops/deployment-pipeline.md
Yun Chan 8d6201e19e 장식 배경 WebP 반영·NAS web 갱신 결과를 기록하고 게이트 수치를 바로잡는다
Pages 0e90049c와 NAS web(sha256:8ec81318…)에 14061d25를 반영한 영수증을
남긴다. 글꼴 변경 뒤 미실행이던 레이아웃 E2E 결과(layout-visual-gate 15/15,
session-layout 10/10, auth-visual 1/1)를 기록하고, AGENTS.md와 검증 가이드의
옛 수치(7/7·8/8)를 실제 테스트 수에 맞춘다.
2026-10-26 05:56:27 +09:00

211 lines
27 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 배포 파이프라인 (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-<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) 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 </dev/null &
echo $! > 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`/시크릿으로 관리