From 9065479e872795f9da43c48ad816b2bc9f80dece Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 31 Jul 2026 04:06:09 +0000 Subject: [PATCH] =?UTF-8?q?docs(ops):=20complete=20N3=20stabilize=20?= =?UTF-8?q?=E2=80=94=20backup,=20tester=20guide,=20smoke=20results?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Record invite/metrics/dashboard/draft(no_key) checks, pg_dump restore rehearsal, and tester-facing guide for msn.iykyka.com. Co-authored-by: okuma --- README.md | 8 +++---- docs/deploy-checklist.md | 19 ++++++++------- docs/ops-backup.md | 28 ++++++++++++++++++++++ docs/tester-guide.md | 48 ++++++++++++++++++++++++++++++++++++++ scripts/backup-postgres.sh | 17 ++++++++++++++ 5 files changed, 107 insertions(+), 13 deletions(-) create mode 100644 docs/ops-backup.md create mode 100644 docs/tester-guide.md create mode 100755 scripts/backup-postgres.sh diff --git a/README.md b/README.md index 85b65db..54e4bf8 100644 --- a/README.md +++ b/README.md @@ -30,10 +30,10 @@ ## 현재 단계 -- Phase 1 **A~C** + **N2 Docker 컷오버 완료** — 라이브: [`https://msn.iykyka.com`](https://msn.iykyka.com) -- **다음:** [`docs/deploy-checklist.md`](./docs/deploy-checklist.md) N3 안정화 → N4 FCM/Android QA -- **맨 마지막:** N5 / D — 사람 PoC #1/#3·Q3 인터뷰 (`docs/roadmap.md` §3). §3 기본값 추측 금지 -- 테스터 데모 초대: **`DEMO-YKAVU`** +- Phase 1 **A~C** + **N2 컷오버 + N3 안정화 완료** — 라이브: [`https://msn.iykyka.com`](https://msn.iykyka.com) +- 테스터 안내: [`docs/tester-guide.md`](./docs/tester-guide.md) · 데모 코드 **`DEMO-YKAVU`** +- **다음:** 서버 `GEMINI_API_KEY` 주입(실초안) 및/또는 N4 FCM·Android QA +- **맨 마지막:** N5 / D — 사람 PoC (`docs/roadmap.md` §3). §3 기본값 추측 금지 - 프로토타입 공유 URL은 [`docs/prototype.md`](./docs/prototype.md)의 `SHARE_URL`에 Master가 기입 ## 로컬 실행 (요약) diff --git a/docs/deploy-checklist.md b/docs/deploy-checklist.md index 43fc520..3748c77 100644 --- a/docs/deploy-checklist.md +++ b/docs/deploy-checklist.md @@ -29,7 +29,7 @@ Phase 1 **A~C** 이후 실행 트랙. 작업 단위를 하나씩 처리한다. ### NOW - 앱 코드는 클로즈드 베타 직전 수준 -- 프로덕션 Docker **이미지·compose 준비 완료**. `msn.iykyka.com` **컷오버는 SSH/Portainer 자격 대기** +- **`https://msn.iykyka.com` 라이브 + N3 안정화 완료**. Gemini 키 미설정(`no_key`). 다음: N4 또는 키 주입 - 실 FCM · Android UI 수동 QA · 사람 PoC 실행은 남음 ### NEXT 순서 @@ -128,12 +128,12 @@ N2-A 전체 확정. 다음 구현 트랙은 **N1 스모크 → N2-B (Dockerfile/ | ID | 작업 | Status | 완료 조건 | |----|------|--------|-----------| -| **N3-1** | 헬스/로그 | todo | OOM·CORS·502 없음 | -| **N3-2** | 초대 발급 리허설 | todo | `docs/invite-ops.md` 절차 1회 | -| **N3-3** | admin metrics | todo | `/admin/metrics`·`/admin/dashboard` 토큰 조회 | -| **N3-4** | Gemini | todo | draft 1회 실호출 또는 mock 정책 명시 | -| **N3-5** | 백업 리허설 | todo | Postgres 덤프/복구 1회 (`pg_dump` 등) | -| **N3-6** | 테스터 안내 | todo | URL + 초대(`DEMO-YKAVU` 또는 개인 코드) + 주의사항 | +| **N3-1** | 헬스/로그 | **done** (2026-07-31) | 전 컨테이너 healthy. 공개 `/health` OK. 최근 로그에 OOM/502 없음 | +| **N3-2** | 초대 발급 리허설 | **done** (2026-07-31) | `POST /invites` note=`N3-rehearsal` 발급·`GET /invites` 목록 확인 | +| **N3-3** | admin metrics | **done** (2026-07-31) | Bearer로 `/admin/metrics`·`/admin/dashboard` 200 | +| **N3-4** | Gemini | **done** (정책) | draft → `status=no_key` (서버 `GEMINI_API_KEY` 비어 있음). 키 넣으면 실호출로 전환 | +| **N3-5** | 백업 리허설 | **done** (2026-07-31) | `pg_dump` gzip → restore test DB → drop. [`ops-backup.md`](./ops-backup.md) | +| **N3-6** | 테스터 안내 | **done** (2026-07-31) | [`tester-guide.md`](./tester-guide.md) | --- @@ -192,7 +192,8 @@ N1~N4(배포·품질에 필요한 최소분) 이후에만 착수. `roadmap.md` P 1. ~~N2-A1~A6 결정 체크~~ **done** 2. ~~N1 스모크~~ **done** (E2E 16/16 + DEMO API 경로; 브라우저 UI 탭은 테스터) 3. ~~N2-B1~B7 이미지·compose~~ **done** (파일 랜딩·이미지 빌드) -4. **N2-B8~B12** Portainer/SSH 컷오버 ← **blocked (자격 필요)** — [`deploy-portainer.md`](./deploy-portainer.md) -5. **N3-6** 테스터 안내 +4. ~~N2-B8~B12 컷오버~~ **done** (`msn.iykyka.com` 라이브) +5. ~~N3 배포 안정화~~ **done** — 다음: **N4 FCM/Android QA** 또는 서버에 `GEMINI_API_KEY` 주입 + 완료 시 본 표의 Status를 `done`으로 바꾸고, [`roadmap.md`](./roadmap.md) §4/§5의 대응 `[~]`/`[ ]`도 같이 갱신한다. diff --git a/docs/ops-backup.md b/docs/ops-backup.md new file mode 100644 index 0000000..f3a13c6 --- /dev/null +++ b/docs/ops-backup.md @@ -0,0 +1,28 @@ +# Postgres 백업·복구 (N3-5) + +서버 path: `~/project/ykavu` +덤프 위치: `~/backups/ykavu/ykavu-YYYYMMDDThhmmssZ.sql.gz` + +## 백업 + +```bash +cd ~/project/ykavu +./scripts/backup-postgres.sh +# 또는 +docker compose exec -T postgres pg_dump -U ykavu ykavu | gzip > ~/backups/ykavu/ykavu-$(date -u +%Y%m%dT%H%M%SZ).sql.gz +``` + +리허설(2026-07-31): 덤프 → `ykavu_restore_test` DB로 복구 → `\dt` 11테이블 · users count 확인 → 테스트 DB 삭제 OK. + +## 복구 (주의: 운영 DB 덮어쓰기) + +```bash +cd ~/project/ykavu +# 1) 서비스 중지 권장 +docker compose stop core-backend web +# 2) 기존 DB 드롭/재생성 또는 새 DB로 검증 후 전환 +gunzip -c ~/backups/ykavu/ykavu-XXXX.sql.gz | docker compose exec -T postgres psql -U ykavu -d ykavu +docker compose start core-backend web +``` + +권장: 먼저 별도 DB(`ykavu_restore_test`)에 복구해 검증한 뒤 컷오버. diff --git a/docs/tester-guide.md b/docs/tester-guide.md new file mode 100644 index 0000000..f3e877a --- /dev/null +++ b/docs/tester-guide.md @@ -0,0 +1,48 @@ +# 와카뷰 테스터 안내 (N3-6) + +## 접속 + +- 웹: **https://msn.iykyka.com** +- 공용 데모 초대 코드: **`DEMO-YKAVU`** +- 표시 이름 예시: `테스터` (원하는 이름으로 변경 가능) + +같은 코드를 여러 명이 쓸 수 있습니다 (`ALLOW_DEMO_INVITE=1`). + +## 권장 플로우 (5분) + +1. 가입 — 초대 코드 `DEMO-YKAVU` 입력 +2. 말투 샘플 온보딩 — 몇 줄 적거나 스킵 +3. 연락처에 상대 유저 등록 → 대화 시작 +4. 메시지 전송 · 분신 초안(L1) 한 번 시도 +5. (선택) 자율성 L0~L2 / 거부권 / 사후알림 함 확인 + +## 알아둘 점 + +- **초안(AI)**: 서버에 `GEMINI_API_KEY`가 없으면 초안이 `no_key`로 나오고, 예시 문구만 채워질 수 있습니다. 키가 들어가면 실제 Gemini 초안이 나옵니다. +- 푸시(FCM)는 아직 플레이스홀더 단계일 수 있습니다. +- 문제/스크린샷은 Master에게 전달해 주세요. +- 민감 정보·실명 대화는 베타 특성상 최소화해 주세요. + +## 개인 초대 (운영자) + +공용 코드 대신 1회용 코드가 필요하면: + +```bash +curl -sS -X POST https://msn.iykyka.com/invites \ + -H "Authorization: Bearer $ADMIN_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"note":"테스터-이름","expires_in_days":14}' +``` + +절차 상세: [`invite-ops.md`](./invite-ops.md) + +## 장애 시 운영자 체크 + +```bash +cd ~/project/ykavu +docker compose ps +curl -sS https://msn.iykyka.com/health +docker compose logs --tail=100 core-backend ai-service web +``` + +백업: `./scripts/backup-postgres.sh` (호스트에서) diff --git a/scripts/backup-postgres.sh b/scripts/backup-postgres.sh new file mode 100755 index 0000000..c8cd211 --- /dev/null +++ b/scripts/backup-postgres.sh @@ -0,0 +1,17 @@ +#!/usr/bin/env bash +# Run on the deploy host from the compose project directory (e.g. ~/project/ykavu). +# Creates gzipped pg_dump under ~/backups/ykavu and prunes older than keep-count. +set -euo pipefail + +KEEP="${BACKUP_KEEP:-10}" +ROOT="$(cd "$(dirname "$0")/.." && pwd)" +cd "$ROOT" +OUT_DIR="${BACKUP_DIR:-$HOME/backups/ykavu}" +mkdir -p "$OUT_DIR" +STAMP="$(date -u +%Y%m%dT%H%M%SZ)" +DUMP="$OUT_DIR/ykavu-$STAMP.sql.gz" + +docker compose exec -T postgres pg_dump -U "${POSTGRES_USER:-ykavu}" "${POSTGRES_DB:-ykavu}" | gzip >"$DUMP" +ls -lh "$DUMP" +ls -1t "$OUT_DIR"/ykavu-*.sql.gz | tail -n +"$((KEEP + 1))" | xargs -r rm -f +echo "OK $DUMP"