部署 runbook

从零把 CoreOTT 实例部署到客户自己的 Cloudflare 账号，并完成验收。

source=manual · owner=biz-dev · lastVerified=2026-11-07 · version=1.0

本文面向客户运维：拿到平台交付的部署包后，在自己的 Cloudflare 账号完成首次部署。平台侧的控制台/订单流程见 BIZCON 文档；本文只讲实例侧执行步骤。

前置条件

一个 Cloudflare 账号，且账号下已创建 D1 数据库与 R2 桶（平台交付单会给出名称）。
一个已接入 Cloudflare 的域名（例如 video.example.com）。
API Token：至少具备 Workers Scripts、D1、R2 的编辑权限；不要使用 Global API Key。
本机：Node.js 22+、pnpm、Git（或解压后的部署包）。

1. 准备配置

cd coreott-instance
cp deploy.env.example deploy.env

编辑 deploy.env，至少确认：

OTT_DOMAIN=video.example.com
OTT_D1_DATABASE_ID=<平台交付单里的 D1 id>
OTT_R2_BUCKET=<平台交付单里的 R2 桶名>

密钥不要写进 deploy.env：

export CLOUDFLARE_API_TOKEN=...      # 执行者环境变量，不落文件
export CLOUDFLARE_ACCOUNT_ID=...

2. 零副作用检查

./deploy.sh <env> plan

plan 只读，不创建/修改任何资源。必须五项全部通过：

配置占位符已替换；
CF 凭据有效；
PAYLOAD_SECRET 已准备；
运行时 secrets 数量正确；
待应用 migration 列表符合预期。

任何一项失败都不要继续；按提示修复后重跑 plan。

3. 首次部署（Worker 还不存在时）

./deploy.sh <env> migrate
./deploy.sh <env> build
./deploy.sh <env> deploy
./deploy.sh <env> secret     # 首次部署才需要；写入 PAYLOAD_SECRET
./deploy.sh <env> verify

顺序不能颠倒：deploy 不会自动迁移，secret 需要 Worker 已存在。

4. 验收

verify 必须全部通过（HTTP + 渲染标记 + 定价/内容配置面 + 管理端登录 + /api/health）。另外人工确认：

首页、定价页、登录页可打开；
管理端 /admin 只在 CRM 域名可访问；
/api/health 的 migrationCount 与 latestMigration 符合交付单；
记录本次 Version ID（部署输出最后一行），写入交付记录。

5. 失败处理

失败点	处理
`plan` 五项检查失败	按输出修复配置/凭据；不要进入 deploy
`migrate` 失败	看具体 migration；先备份 D1，再修复后重跑
`deploy` 失败	代码未上线；看 wrangler 输出，修复后重跑
`verify` 失败	按「回滚 runbook」回到上一版本，再排查

6. 安全与留痕

不把 Token、PAYLOAD_SECRET、数据库导出提交到 Git 或工单。
每次部署记录：时间、执行人、Version ID、migrationCount、verify 结果。
生产与 staging 使用不同的 CF 账号/Token；不要复用。