baa-conductor

T-018-control-api-deploy.md

  1---
  2task_id: T-018
  3title: Cloudflare Worker 与 D1 部署配置
  4status: done
  5branch: feat/T-018-control-api-deploy
  6repo: /Users/george/code/baa-conductor
  7base_ref: main@458d7cf
  8depends_on:
  9  - T-014
 10write_scope:
 11  - apps/control-api-worker/**
 12  - ops/cloudflare/**
 13updated_at: 2026-03-22
 14---
 15
 16# T-018 Cloudflare Worker 与 D1 部署配置
 17
 18## 目标
 19
 20把 `control-api-worker` 从“可构建的 Worker 代码”推进到“具备明确 Cloudflare Worker / D1 绑定配置、可部署模板和最小运维说明”的程度。
 21
 22## 本任务包含
 23
 24- 为 `apps/control-api-worker` 补部署配置文件，例如 `wrangler.jsonc`
 25- 明确 D1 binding、环境变量和 Worker 入口约定
 26- 在 `ops/cloudflare/**` 下补部署示例、变量模板或辅助脚本
 27- 把当前 runtime 代码与部署配置对齐，保证入口和 bindings 命名一致
 28
 29## 本任务不包含
 30
 31- 实际上线部署到 Cloudflare
 32- 修改 `packages/db/**`
 33- 修改 `packages/auth/**`
 34- 修改 conductor 或 status-api 代码
 35
 36## 建议起始文件
 37
 38- `apps/control-api-worker/src/index.ts`
 39- `apps/control-api-worker/src/contracts.ts`
 40- `apps/control-api-worker/package.json`
 41- `ops/cloudflare/`
 42
 43## 交付物
 44
 45- 可提交到仓库的 Worker / D1 配置骨架
 46- 清晰的 binding 与 secret 约定
 47- 最小部署说明或辅助脚本
 48
 49## 验收
 50
 51- `npx --yes pnpm --filter @baa-conductor/control-api-worker typecheck`
 52- `npx --yes pnpm --filter @baa-conductor/control-api-worker build`
 53- Worker 配置文件与代码里的 env/binding 名称一致
 54
 55## 更新要求
 56
 57完成时更新 frontmatter 的：
 58
 59- `status`
 60- `base_ref`
 61- `updated_at`
 62
 63并补充下面这些内容：
 64
 65## files_changed
 66
 67- `apps/control-api-worker/.dev.vars.example`
 68- `apps/control-api-worker/.gitignore`
 69- `apps/control-api-worker/package.json`
 70- `apps/control-api-worker/src/contracts.ts`
 71- `apps/control-api-worker/src/handlers.ts`
 72- `apps/control-api-worker/src/runtime.ts`
 73- `apps/control-api-worker/wrangler.jsonc`
 74- `ops/cloudflare/README.md`
 75- `ops/cloudflare/apply-control-api-d1-migrations.sh`
 76- `ops/cloudflare/control-api-worker.secrets.example.env`
 77- `ops/cloudflare/deploy-control-api-worker.sh`
 78- `coordination/tasks/T-018-control-api-deploy.md`
 79
 80## commands_run
 81
 82- `git worktree add /Users/george/code/baa-conductor-T018 -b feat/T-018-control-api-deploy 458d7cf`
 83- `npx --yes pnpm install`
 84- `bash -n ops/cloudflare/deploy-control-api-worker.sh ops/cloudflare/apply-control-api-d1-migrations.sh`
 85- `npx --yes pnpm --filter @baa-conductor/control-api-worker typecheck`
 86- `npx --yes pnpm --filter @baa-conductor/control-api-worker build`
 87
 88## result
 89
 90- 为 `control-api-worker` 增加了可提交的 `wrangler.jsonc`，固定了 Worker 名称、入口 `dist/index.js`、自定义域 `control-api.makefile.so`、D1 binding `CONTROL_DB` 和最小运行时变量。
 91- 在 `contracts.ts` / `runtime.ts` / `handlers.ts` 中把 D1 binding 与 token/env 名称抽成常量并接入运行时，减少代码和部署配置之间的漂移。
 92- 在 `ops/cloudflare/` 下补了最小运维材料：部署说明、secret 模板、远端 D1 migration 脚本、构建后部署脚本；同时在包脚本中暴露了 Cloudflare 相关入口。
 93
 94## risks
 95
 96- `apps/control-api-worker/wrangler.jsonc` 中的 `database_id` 与 `preview_database_id` 仍是占位值；实际部署前必须替换为真实 D1 UUID。
 97- 本任务只提供 secret 模板和 `wrangler secret put` 约定，真实 secret 仍需在目标 Cloudflare 账号中手动注入。
 98- 未执行真实 Cloudflare deploy / D1 远端 migration，因此自定义域、账号权限和线上资源绑定仍需落地验证。
 99
100## next_handoff
101
102- 先填写 `wrangler.jsonc` 的真实 D1 UUID，再执行 `./ops/cloudflare/apply-control-api-d1-migrations.sh`。
103- 按 `ops/cloudflare/control-api-worker.secrets.example.env` 的键名把生产 secret 写入 Cloudflare Worker。
104- 完成后执行 `./ops/cloudflare/deploy-control-api-worker.sh`，并验证 `https://control-api.makefile.so` 是否能正常返回 Worker 响应。
105
106开始时建议直接把 `status` 改为 `in_progress`。
107
108做完并推送后：
109
110- 如果等待整合，改为 `review`
111- 如果确认结束，改为 `done`