photo-live/docs/plans/2026-09-21-P5-准备件.md

# P5 准备件 实施计划（无凭证前置批）

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 在不依赖任何真实凭证/服务器权限的前提下，完成 P5 的全部可预制件：双地域生产镜像与编排、1Panel 部署说明、迁移与发布流程、监控告警配置、CDN 接入清单、压测框架、部署演练与回滚手册，以及 P5 正式实施计划草案。凭证到位后 P5 实施只需填 env + 执行。

**依赖基线:** tag `p4b`（22188ce）。所有产物只依赖代码库现状，不触碰真实云资源。

---

## Task 1: 生产镜像与编排

- [ ] `services/api/Dockerfile`（多阶段：pnpm build → node dist，双入口 cn/ov 同镜像不同 CMD；含 prisma generate 阶段）；`services/worker/Dockerfile`、`services/sync/Dockerfile`（或单通用镜像多角色 CMD——决策：单镜像 `photo-live-server`，CMD 区分 api-cn/api-ov/worker/sync，减少 1Panel 维护面）；`apps/viewer`、`apps/admin` 构建产物 + `infra/deploy/nginx.conf`（静态 + /v1 反代 + embed/v1 长缓存 + gzip）→ `photo-live-web` 镜像（VIEWER/ADMIN 两份 env 注入入口脚本区分）
- [ ] `infra/deploy/docker-compose.cn.yml`（api-cn/worker/sync/web-cn + 复用 1Panel 既有 MySQL/Redis 连接，不内建数据库）、`docker-compose-ov.yml`（api-ov/web-ov + sync-receiver 内嵌于 api-ov？——按 P2 架构 sync 是独立进程双向：cn 侧跑 sender+reconciler+stat-receiver，ov 侧只需 api-ov 内嵌 inbox；核对现状后如实编排）；healthcheck、重启策略、日志 json-file 轮转上限
- [ ] `.env.production.example-cn` / `-ov`（全量变量清单含注释：DB/Redis 连 1Panel 容器名、S3 真实 OSS 段、SYNC_INTERNAL_KEY 强随机提醒、域名、CORS、上传/窗口/轮询参数——对齐 D10/D11 建议值）
- [ ] `infra/deploy/README-1Panel.md`：镜像导入（1Panel 容器-镜像-Compose 编排步骤）、MySQL 建库授权 SQL、迁移执行（`docker run --rm photo-live-server npx prisma migrate deploy` 两地域两 schema）、OpenResty 反代与证书、首次 bootstrap/演练顺序
- [ ] 构建验证：本地 `docker build` 两个镜像成功 + compose config 校验通过（不起真容器）
- [ ] Commit `build(deploy): production images, compose stacks and 1panel guide`

## Task 2: 发布/迁移/回滚运行手册

- [ ] `infra/deploy/RUNBOOK.md`：发布前检查单（备份、水位、镜像 tag）；发布步骤（迁移→服务滚动→冒烟：健康/登录/上传/公开读四点）；回滚步骤（旧镜像 tag + 迁移向前兼容原则、outbox/inbox/水位保留）；紧急停用通道（ov emergency 端点调用样例含 HMAC 签名生成命令）；故障速查（同步积压/计数差异/CDN 缓存三种典型）
- [ ] `scripts/prod-smoke.sh`（对指定环境跑四点冒烟：health/登录/小图上传全链/公开读——复用本地 e2e 逻辑的最小 curl/node 版）
- [ ] Commit `docs(deploy): runbook with smoke script and emergency channel`

## Task 3: 监控告警 + CDN 接入清单 + 压测框架

- [ ] `infra/deploy/monitoring.md`：指标清单落地方式（1Panel 应用监控 + pino 结构化日志字段表 + 关键日志检索语句：同步失败/上传失败/计数差异）；告警项表（错误率/队列积压/同步水位延迟/磁盘容量——1Panel 告警或云监控分工建议）；日志保留策略
- [ ] `infra/deploy/cdn-checklist.md`：阿里云全球 CDN 接入步骤核对单（OSS 回源私有授权、URL 鉴权 A/B 型选型建议、缓存键规则：variants 长缓存+签名 URL 短缓存、失效/预热 API 调用样例、隐藏照片失效窗口验证步骤、冷缓存测试点建议——全部"待凭证执行"标注）
- [ ] `loadtest/`（k6 脚本：L1 场景 相册1000照片×100观众×3上传 / L2 10000×1000×10——读路径分页/大图/点赞/浏览上报四类 scenario + 阈值占位；README 说明运行方式与 D05 确认后填目标）
- [ ] Commit `test(loadtest),docs: monitoring, cdn checklist and k6 framework`

## Task 4: P5 正式实施计划草案 + 准备件评审 + 总纲注记

- [ ] `docs/plans/2026-09-21-P5-真实环境接入.md` 草案（待凭证到位后评审转正）：任务分解 = G1 补跑（OSS 冒烟脚本已备）→ 国内单地域真库真 OSS 起栈 → ov 真机部署 + 首次快照 → CDN + 域名 → 用户源真实对接（G4/D08）→ 跨地域演练（断网重放/紧急停用/统计对账）→ 压测 D05 → G2 真机关口 → G6 试运行 → 发布交接；每任务标注"所需用户输入"
- [ ] 准备件统一评审（一个 reviewer 过全部产物：镜像/编排/runbook/监控/CDN/压测/P5 草案）
- [ ] 总纲 P5 行注记"准备件完成 2026-09-21，实装待 G5 凭证"；`git tag p5-prep`
- [ ] Commit `docs: p5 preparation complete and implementation draft`

---

## 执行注意

- 一切产物均不包含真实密钥；.env.production.example 用占位符 + 强提醒。
- 镜像构建走仓库根 `pnpm build` 产物路径，不重复发明构建；版本 = git short sha + date。
- compose 与 1Panel：优先「1Panel 编排 = 我们的 compose 文件」路径（1Panel 支持 compose 模板），README 双路径说明。
- 压测脚本只写框架与场景，不预设结论（D05 未定）。