photo-live/docs/plans/2026-09-21-P5-真实环境接入.md

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（发布交接完成）。