ai-customer-service/docs/SHARED_PREPROD_ACCESS_HANDOFF_CHECKLIST.md

共享预生产入口交接清单

状态：待共享预生产环境提供方回填
最近更新：2026-05-06
适用项目：projects/ai-customer-service
目标：确保“真实共享预生产 Gate B 复跑”和“真实共享预生产/灰度环境 Gate C 回滚演练”具备可执行入口，而不是停留在口头说明

---

1. 这份清单解决什么问题

当前项目已经具备：

1. 代码级门禁通过
2. 本地/容器化 Gate B 通过
3. 本地/容器化 Gate C 回滚演练通过

当前仍然缺失的是：

1. 真实共享预生产环境 Gate B 复跑入口
2. 真实共享预生产/灰度环境 Gate C 回滚演练入口

这里的“入口”不是一个 URL，也不是一句“环境已经有了”，而是：

从当前执行机器出发，能真实操作共享预生产环境的运维通道。

必须能够支持：

1. 启动/重启服务
2. 查看日志
3. 访问 health probe
4. 访问真实 PostgreSQL
5. 获取真实环境变量来源
6. 在该环境执行 Gate B 验证
7. 在该环境执行 Gate C 回滚演练
8. 留下可复核证据

---

2. 合格入口类型

满足以下任一类型即可：

2.1 SSH 主机入口

提供：

• 主机地址
• 用户名
• 登录方式
• 项目目录
• 启动/重启命令
• 日志路径
• 服务访问地址

适用场景：

• systemd 服务
• 直接运行二进制
• Docker / Podman 单机部署

2.2 Kubernetes 入口

提供：

• kubectl 可用
• kubeconfig 或 context
• namespace
• deployment / service 名称
• 查看日志权限
• rollout / undo 权限

适用场景：

• Kubernetes Deployment
• StatefulSet
• 多副本灰度切换

2.3 CI/CD 或发布平台入口

提供：

• 预生产部署流水线入口
• 环境变量/Secret 查看或确认方式
• 服务日志查看入口
• 重启/回滚入口
• 部署版本与提交号映射

适用场景：

• GitOps
• 平台托管部署
• 云上控制台发布

---

3. 不算合格入口的情况

以下情况都不够：

1. 只有共享预生产 URL
2. 只有数据库只读账号
3. 只有监控只读面板
4. 只有截图、文档或口头说明
5. 只能“看状态”，不能“重启/回滚/留痕”

原因很直接：

Gate B / Gate C 都要求可操作性，不只是可观察性。

---

4. 入口必须满足的规范要求

4.1 部署对象明确

必须明确服务部署对象：

• systemd service 名称
• Docker / Podman 容器名称
• Kubernetes deployment / rollout 对象

不能只说“服务在那台机器上”，必须能回答：

1. 由谁启动
2. 怎么重启
3. 怎么回滚
4. 日志在哪

4.2 环境变量来源明确

必须明确共享预生产如何注入这些变量：

• AI_CS_RUNTIME_ENV
• AI_CS_ADDR
• AI_CS_POSTGRES_ENABLED
• AI_CS_POSTGRES_DSN
• AI_CS_POSTGRES_MIGRATION_DIR
• AI_CS_WEBHOOK_SECRET
• AI_CS_WEBHOOK_TIMESTAMP_HEADER
• AI_CS_WEBHOOK_SIGNATURE_HEADER
• AI_CS_WEBHOOK_MAX_SKEW_SECONDS

基线文档：

• CONFIG_CONTRACT_BASELINE.md

必须至少能回答：

1. 变量值从哪里来
2. 谁负责维护
3. 如何在不泄露明文 secret 的前提下确认其已正确注入

4.3 数据库必须是共享预生产真实库

不能使用：

• 本地测试库
• 临时容器库
• 开发库

必须使用共享预生产 PostgreSQL，才能证明：

1. migration 基线真实可用
2. ticket 入库真实可用
3. audit 入库真实可用
4. dedup 入库真实可用

4.4 必须具备最小操作权限

入口必须允许执行以下动作：

1. 启动或重启当前版本
2. 查看最近日志
3. 访问 /actuator/health/live
4. 访问 /actuator/health/ready
5. 读取当前部署版本/镜像/tag/commit
6. 执行回滚动作
7. 验证回滚后主链恢复

4.5 必须可留痕

至少保留以下证据：

1. summary.txt
2. 服务日志路径
3. 部署版本 / 提交号
4. 健康检查结果
5. Gate B / Gate C 执行命令
6. 回滚前后版本信息
7. 必要时数据库验证摘要

---

5. Gate B 所需最小入口要求

如果当前只想完成“真实共享预生产 Gate B 复跑”，入口最少要具备：

1. 共享预生产服务启动权限
2. 共享预生产 PostgreSQL 可连
3. 真实 AI_CS_* 环境变量可确认
4. 服务地址可访问
5. 日志可读

执行入口：

• scripts/verify_preprod_gate_b.sh

对应证据模板：

• PREPROD_VERIFICATION_RECORD.md

---

6. Gate C 所需额外入口要求

如果要完成“真实共享预生产/灰度环境 Gate C 回滚演练”，除 Gate B 外还必须额外明确：

1. 坏发布怎么制造
   • 错误配置
   • 错误 DSN
   • 错误 Secret
   • 错误镜像/tag
2. 回滚对象是谁
   • systemd service
   • container
   • deployment
3. 标准回滚动作是什么
   • systemctl restart ...
   • docker/podman restart ...
   • kubectl rollout undo ...
4. 恢复完成如何判定
   • live / ready 恢复
   • signed webhook 重新返回 200
   • ticket / audit / dedup 重新恢复写入

执行入口：

• scripts/verify_gate_c_rollback.sh

对应证据模板：

• ROLLBACK_DRILL_RECORD.md

---

7. 共享预生产入口交接模板

请环境提供方至少按下面模板回填：

共享预生产入口类型：
- SSH / Kubernetes / CI-CD

如果是 SSH：
- 主机地址：
- 用户名：
- 登录方式：
- 项目目录：
- 服务启动命令：
- 服务重启命令：
- 服务停止命令：
- 日志路径：
- 服务访问地址：
- 环境变量来源文件或注入方式：

如果是 Kubernetes：
- kubeconfig/context：
- namespace：
- deployment 名称：
- service 名称：
- ingress / 访问地址：
- 查看日志命令：
- 重启命令：
- 回滚命令：
- Secret / ConfigMap 名称：

如果是 CI/CD：
- 平台名称：
- 流水线入口：
- 发布目标环境名称：
- 当前部署版本查看方式：
- 日志查看入口：
- 回滚入口：

数据库：
- 是否为共享预生产 PostgreSQL：
- DSN 获取方式：
- migration 目录所在位置：

Gate B 执行责任人：
- 负责人：
- 计划时间：

Gate C 回滚演练责任人：
- 负责人：
- 计划时间：

证据归档位置：
- summary.txt：
- service.log：
- 版本信息：
- 回滚记录：

---

8. 当前项目的真实阻断

截至 2026-05-06，当前执行机器上已确认：

1. 没有 kubectl
2. 没有 ~/.kube/config
3. 没有共享预生产专用 AI_CS_* 环境
4. 仓库内没有共享预生产部署清单

因此当前阻断不是：

• Gate B/Gate C 脚本缺失
• 本地演练能力缺失
• 门禁文档缺失

而是：

真实共享预生产环境运维入口未交接。

---

9. 当前结论

当前可以准确表达为：

1. 代码级门禁：通过
2. 本地/容器化 Gate B：通过
3. 本地/容器化 Gate C 回滚演练：通过
4. 真实共享预生产 Gate B：待共享预生产入口交接后执行
5. 真实共享预生产/灰度环境 Gate C：待共享预生产入口交接后执行

没有入口，不应宣称“真实共享预生产已验证”；有入口后，才可以继续执行真实 Gate B / Gate C。