# P5 真实环境接入 实施计划

> **状态：草案——待 G5 凭证到位后评审转正。** 本草案由 P5-prep（2026-09-21，
> tag `p5-prep`）产出：全部准备件（镜像/编排/RUNBOOK/监控/CDN 清单/压测框架）
> 已就位，凭证到位后按序执行并按实际环境修正本计划再转正。
>
> **For agentic workers:** 转正后按任务序推进，每任务完成即提交并回填勾选。
> 准备件索引：`infra/deploy/README-1Panel.md`（部署）、`infra/deploy/RUNBOOK.md`
>（发布/回滚/紧急通道）、`infra/deploy/monitoring.md`（监控告警）、
> `infra/deploy/cdn-checklist.md`（CDN）、`loadtest/`（压测）、
> `scripts/prod-smoke.sh`（四点冒烟）。

**Goal:** 双地域真实环境（真 OSS / 真 MySQL / 真域名 / 真 CDN / 真用户源）接入、
演练、压测与试运行，直至发布交接（对齐总纲 P5 与项目计划 7.3 发布门槛）。

**出口门:** 全量 A 回归 + 容量报告 + G5/G6 闭环；A24/A25/A28 真实级证据落档。

---

## 0. 关键架构现状（从代码核实，P5 决策的出发点）

- **sync 只跑 cn 侧**，双库直连（cn 库取 outbox + **ov 库跨境公网 3306** 直读
  副本计数 / 直读写 `outbox_stat_events`）+ 双 API 调用（content-batches /
  reconcile / digest / bootstrap / stat-snapshots，HMAC 签名）。ov 侧 inbox 与
  emergency 内嵌 api-ov。→ 跨境 3306 暴露是 **T6 决策点**（见 T6 三选项）。
- **图片一律 OSS presigned GET 直链**（SigV4，TTL 900s，variants 内容寻址键）。
  → CDN 图片加速存在双层签名冲突，三选一决策见 T5 / cdn-checklist §0。
- ov 公开读不依赖 cn（A25 数据面），但 sync 依赖「cn→ov API 可达 + ov 库可达」
  双通道；紧急停用通道（emergency）独立于同步链路，依赖 ov API 存活。

## 1. 任务序

> 每任务：**产出** / **依赖用户输入** / **关口**。勾选在转正后执行时回填。

### T1 G1 OSS 冒烟（凭证）

- [ ] 用真实 OSS 凭证（cn-hangzhou 外网 endpoint + 私有桶）跑本地/国内栈
      `scripts/prod-smoke.sh`，覆盖 G1 清单：presign PUT/head 核验/禁止覆盖
      （staging→originals 受控复制）/跨域/现有桶生命周期规则对项目前缀的影响
      （总纲 §6 G1 行）。
- 产出：G1 冒烟记录（补总纲 G1「跳过并登记」的闭环）+ `.env.production-cn`
      OSS 段定稿。
- 依赖用户输入：OSS AccessKey/Secret、桶名、endpoint（G5）。
- 关口：**G1**（OSS 适配器定稿；若现签 PUT 与真实 OSS 行为有差异，回到
  `packages/storage` 修正后再继续）。

### T2 国内真库起栈（compose + migrate + seed-admin + prod-smoke）

- [ ] 按 `README-1Panel.md` §1-§7 cn 段执行：MySQL 建库授权（**先
      `SELECT VERSION();` 登记——低于 8.0.30 则校对回退 `utf8mb4_bin` 并重跑
      token 大小写语义验收，D12 注意项）→ Redis → 镜像导入 →
      `migrate-deploy cn` → `seed-admin` → compose up → `prod-smoke.sh
      <cnBase> <任意> <账号> <密码> --skip-ov`。
- 产出：cn 栈运行 + 单地域冒烟 PASS 记录；env 文件归位（不入 git）。
- 依赖用户输入：cn 服务器 1Panel 访问权、MySQL/Redis 容器名、admin 初始密码。
- 关口：无（G1 建议先行；镜像通道 D13 未定则走 tar 导入路径）。

### T3 ov 部署 + 首次 bootstrap 快照 + 对账

- [ ] ov 侧同 T2（`migrate-deploy ov` + compose-ov up）→ cn 侧 sync 起栈：
      先**临时**用「安全组/防火墙白名单 cn 服务器出口 IP + 3306」打通（T6
      定案长期方案后切换），观察 sync 三循环日志（`outbox batch pushed` /
      reconcile / `stat snapshots returned`）→ 首次全量当前态重放与 digest
      比对自动完成（reconciler 语义：sinceVersion=0 清扫 + 不一致触发
      bootstrap）→ `prod-smoke.sh` 全四点（含 ov 公开读端到端）。
- 产出：双地域端到端冒烟 PASS + 首次 bootstrap/对账记录（sync 日志与水位
      快照留档，口径同 RUNBOOK §1）。
- 依赖用户输入：ov 服务器 1Panel 访问权、规格/地域登记（D09）、ov MySQL
      出口白名单操作权。
- 关口：跨地域同步端到端首次打通（失败排查入口 = RUNBOOK §5.1）。

### T4 域名 / OpenResty / 证书

- [ ] 1Panel 网站 + 反代 + HTTPS（README-1Panel §5）：cn viewer/admin 域名 →
      127.0.0.1:8088；ov → 127.0.0.1:8089；强制 HTTPS；WS（/v1/realtime）
      Upgrade 头透传核对；`CORS_ORIGINS` 两栈回填真实域名；trust proxy 处理
      登记（interactions 限速以 req.ip 为键，反代后需按部署确认——likes/
      visits controller 文件头既有登记项）。
- 产出：两地域域名 HTTPS 可用 + 冒烟重跑 PASS。
- 依赖用户输入：域名与 DNS 解析权、证书（1Panel 申请或已有）。
- 关口：无（CDN 前置）。

### T5 CDN 按 checklist 接入（含图片加速三选一决策）

- [ ] 按 `infra/deploy/cdn-checklist.md` 执行（全步骤待凭证）：Zone 1 viewer
      域名加速（缓存规则/HTML no-cache/WS 绕行）→ 冷缓存多地域测试点记录
      （checklist §6 表）→ **图片加速三选一定案**（推荐 c 起步：presigned
      直链不变、CDN 仅 viewer 静态；图片流量数据到位后评估 b=CDN 鉴权+私有桶
      回源授权改造）→ 若定案 b：失效/预热样例入 RUNBOOK、隐藏照片失效窗口
      实测登记。
- 产出：CDN 接入记录 + 冷缓存时延表 + 三选一决策登记（A25「图片经全球 CDN」
      的达成时点随决策明确——c 起步期间为 presigned 直读，A25 部分满足需在
      验收记录如实标注）。
- 依赖用户输入：CDN 账号/权限、（若 b）图片域名解析权（G5）。
- 关口：**G5**（CDN 权限项闭环）。

### T6 跨境 MySQL 连通方案定案（SSL / 隧道 / 白名单）

- [ ] 三选项评估定案并实施：
      ① **白名单 + MySQL 原生 SSL**（起步推荐）：ov 安全组仅放行 cn 出口 IP，
      ov MySQL 账户 `REQUIRE SSL`，连接串追加 SSL 参数——改动最小（env 层），
      暴露面 = 单 IP 单端口 + TLS。
      ② **隧道**（frp/wireguard/stunnel）：3306 不出公网，运维面 +1 组件
      （可用 1Panel 计划任务守护），适合安全要求更高的形态。
      ③ **HTTP 化 sync 接口走 ov API**（消除跨境 3306，备选改造）：ov API
      增设两个 internal 端点（副本计数 digest 查询 + outbox_stat_events
      拉取/确认，均挂既有 InternalSyncGuard HMAC 域），reconciler 与
      stat-return 的直连查询改 HTTP。**改造量评估**：契约 +2 operation、
      api-ov +2 端点、sync 两模块数据源重写、集成测试补跨境断连用例——
      约数个代理工作日量级，收益是数据库面零跨境暴露、通道收敛到已签名
      API；代价是 API 面扩大与分页语义复杂化。建议作为 P6 演进备案，
      P5 用 ① 起步。
- 产出：定案记录 + 实施与验证（sync 日志连续无 `P1001`/超时；断网重放演练
      见 T8）。
- 依赖用户输入：安全策略口径（能否接受单 IP 白名单 + TLS）。
- 关口：P5 决策项登记（与 T5 三选一同表）。

### T7 G4 用户源真实对接（D08）

- [ ] 按 P4a 验收记录的替换点：`UserSourcePort` provider 换真实接口（D08
      契约：稳定 ID/字段/鉴权/停启用语义），fixtures 重跑（改名/停用/分页
      中断/空响应/增量）+ 真实测试账号一轮手动同步验证；管理页「用户同步
      状态」页观测一轮完整调度。
- 产出：真实源对接记录 + mock/real 双 provider 共存状态登记。
- 依赖用户输入：D08 契约文档、测试凭据（G4）。
- 关口：**G4**。

### T8 跨地域故障演练（RUNBOOK 清单）

- [ ] 按项目计划 7.3 / RUNBOOK 执行并留痕：①断网重放（阻断 cn→ov 通道制造
      outbox 积压 → 恢复后自动排空，核对水位与幂等）②乱序/重复回传（对账
      循环 5min 补漏语义验证）③紧急停用通道实测（RUNBOOK §4 HMAC 样例调用
      ov emergency disable/enable 各一次）④统计对账（点赞/浏览 → stat
      snapshots 回传核对 cn 权威值）⑤回滚演练（RUNBOOK §3：旧 tag 回滚 +
      冒烟 + 水位比对）⑥CDN 故障切回直连（若 T5 已接入）。
- 产出：《P5 故障演练记录》（每项：操作/预期/实际/截图或日志粘贴）。
- 依赖用户输入：演练窗口（低峰）与 ov 操作权。
- 关口：全部演练项 PASS（A24 真实级证据）。

### T9 压测 D05（k6）

- [ ] D05 确认后：`loadtest/` 两脚本 thresholds 取消占位注释并填定案值 →
      种子数据（upload-burst 建册灌图，L1=1000 照片 / L2=10000）→ L1→L2
      阶梯执行（read-feed VUS=100/1000；upload-burst VUS=3/10）→ 容量报告
      （P95 对照项目计划 §6 候选指标；瓶颈定位与优化建议；真实尺寸图片
      吞吐另测——fixture 小图只压链路，README 注记）。
- 产出：《P5 容量报告》+ 必要的性能修复回归。
- 依赖用户输入：D05（数量并发与网络目标）定案。
- 关口：发布门槛输入之一（项目计划 7.3）。

### T10 G2 真机验证（用户执行）

- [ ] P3 验收记录的 G2 最小验证集在**真机 + 真实 OSS**组合下执行：真机装
      包登录 → 批量 100 张真实样本上传中锁屏 ≥15min + 切后台 + 断网恢复 →
      厂商后台清理/强杀重启恢复 → HEIC 真机样本 → expedited 配额与通知
      授权 UX。
- 产出：G2 执行留痕（用户反馈截图/日志）。
- 依赖用户输入：用户真机操作（双平台）；分发方式 D03（APK 直装起步可先跑
      Android）。
- 关口：**G2**（强制；未通过阻塞试运行）。

### T11 G6 试运行

- [ ] 真实活动彩排一轮（现场人员 + 观众实机使用）：监控告警阈值按实测校准
      （monitoring.md §4 建议值→实际值）、1Panel 数据库**备份与恢复演练**
      （备份恢复到临时库核对可用性）、嵌入组件真实宿主页接入验证。
- 产出：试运行记录 + 校准后的告警阈值表 + 备份恢复演练留痕。
- 依赖用户输入：真实活动（或等价彩排场景）、参与人员。
- 关口：**G6**。

### T12 发布交接

- [ ] 交接材料归档：RUNBOOK + monitoring + cdn-checklist 执行状态版、
      App 分发（D03 定案后执行；旧客户端兼容口径确认——服务端保持必要的
      旧客户端兼容）、账号/密钥移交清单（不入 git 的部分线下交接）、
      监控/备份/回滚三项演练留痕汇总（T8/T11 产出）。
- 产出：交接包 + P5 验收记录（A24/A25/A28 真实级 + 全量 A 回归 + 容量
      报告）+ tag `p5`。
- 依赖用户输入：D03 定案；交接对象确认。
- 关口：发布门槛（项目计划 7.3）。

## 2. 用户输入清单汇总（凭证到位 = 转正前置）

| # | 输入 | 用于任务 | 状态 |
| --- | --- | --- | --- |
| 1 | OSS AccessKey/Secret + 私有桶名 + cn-hangzhou 外网 endpoint | T1 | 待 G5 |
| 2 | cn 服务器 1Panel 访问 + MySQL(8.0.30+ 版本登记)/Redis 容器名 + admin 初始密码 | T2 | 待 G5 |
| 3 | ov 服务器 1Panel 访问 + 规格/地域登记（D09）+ MySQL 版本登记 | T3 | 待 G5 |
| 4 | viewer（cn/ov）域名 + DNS 解析权 + 证书 | T4/T5 | 待 G5 |
| 5 | CDN 账号/权限（+ 若图片加速选 b：图片域名） | T5 | 待 G5 |
| 6 | 跨境安全策略口径（白名单+SSL 是否可接受） | T6 | 待定案 |
| 7 | D08 用户接口契约 + 测试凭据 | T7 | 待 G4 |
| 8 | D05 容量目标定案 | T9 | 待确认 |
| 9 | 真机验证执行（用户）+ D03 分发方式 | T10/T12 | 待用户/待确认 |
| 10 | 试运行真实活动 | T11 | 待 G6 |

### 决策状态速查（总纲 §5 摘要 + P5 增量）

| 决策 | 状态 | P5 落点 |
| --- | --- | --- |
| D03 分发方式 | 待确认 | T10/T12（Android APK 直装可先行） |
| D05 容量目标 | 待确认（按 L1/L2 阶梯准备） | T9（thresholds 占位待填） |
| D08 用户接口契约 | 待确认（mock 先行） | T7 |
| D09 海外规格/地域 | ECS 已就绪，规格待登记 | T3 |
| D10 缓存失效窗口/轮询/用量阈值 | 待确认（建议值运行中） | T5/T11 校准 |
| D11 跨境同步参数 | 初值已给（2s/5min/60s），P5 冻结 | T3/T8 实测冻结 |
| D12 MySQL 版本/字符集 | 已确认 8.0+；精确版本 P5 登记（8.0.30 门槛） | T2/T3 首步 |
| D13 镜像仓库/CI | 待确认；tar 导入路径兜底 | T2 起每任务 |
| **P5-CDN 图片加速三选一** | **建议 c 起步**（新增决策项） | T5 |
| **P5-跨境 MySQL 通道** | **建议白名单+SSL 起步**（新增决策项） | T6 |

## 3. 风险表

| 风险 | 影响 | 缓解 |
| --- | --- | --- |
| 跨境公网链路（3306 与 API 双通道时延/抖动/被墙） | sync 积压、对账风暴 | 退避封顶 60s + 对账幂等（已内建）；T6 定案通道；T8 断网演练验证；RUNBOOK §5.1 排查路径 |
| CDN 图片加速双层签名（presigned GET × CDN URL 鉴权） | 命中率崩塌或鉴权失效 | 三选一决策（推荐 c 起步零改动；b 改造走 storage 适配层）——cdn-checklist §0 |
| MySQL 版本 < 8.0.30（utf8mb4_0900_bin 不可用） | token/publicToken 大小写语义漂移 | T2/T3 首步 `SELECT VERSION()` 登记；回退 utf8mb4_bin + 重跑语义验收（README-1Panel §2） |
| 镜像仓库通道未定（D13） | 发布节奏慢、人工步骤多 | tar 导入路径已备（README-1Panel §1A）；ACR 可选随时切换 §1B |
| WS 经 CDN/反代透传（/v1/realtime） | 实时气泡断连 | T4/T5 显式核对 Upgrade 透传；CDN 层 WS 绕行（cdn-checklist §7） |
| trust proxy 未配置（互动限速按网关 IP 聚合） | 观众误限 429 | T4 登记 nginx.conf.template 与 likes/visits controller 既有 P5 项；压测 README 同注 |
| 真实 OSS 费用/限流（压测与试运行） | 成本超预期 / 429 | T9 压测前预算口径；桶生命周期核对（T1） |
| 双数据库容器与其他业务争用（1Panel 共存） | 资源/备份耦合 | 独立库独立账号 + 连接池上限（已设）；1Panel 备份计划纳入（T11 演练） |

## 4. 验收口径（P5 出口）

- A24（区域数据不共用跨境数据库：ov 面独立服务 + sync 桥接语义随 T6 定案
  登记）、A25（海外直读；「图片经全球 CDN」达成度随 T5 决策如实标注）、
  A28（目标地域冷缓存/原图下载/下线传播实测时延记录）。
- 全量 A 回归（P1-P4b 验收记录基线不降级）+ 《P5 容量报告》（T9）+ 故障
  演练记录（T8）+ 试运行记录（T11）。
- tag `p5`（发布交接完成）。