baa-conductor

T-022-ops-automation.md

  1---
  2task_id: T-022
  3title: Nginx 与 Cloudflare DNS 自动化
  4status: done
  5branch: feat/T-022-ops-automation
  6repo: /Users/george/code/baa-conductor
  7base_ref: main@458d7cf
  8depends_on:
  9  - T-008
 10write_scope:
 11  - ops/nginx/**
 12  - docs/ops/**
 13  - scripts/ops/**
 14updated_at: 2026-03-22
 15---
 16
 17# T-022 Nginx 与 Cloudflare DNS 自动化
 18
 19## 目标
 20
 21把当前的 Nginx 配置和 Cloudflare DNS 管理推进到“有脚本辅助同步和部署”的程度，减少手工改记录、手工改配置的步骤。
 22
 23## 本任务包含
 24
 25- 在 `scripts/ops/**` 下补 Cloudflare DNS 管理脚本
 26- 把当前公网域名与内网 Tailscale `100.x` 的关系写成可执行模板
 27- 补 Nginx 部署/校验辅助脚本或分发模板
 28- 收口 `docs/ops/**` 中的操作步骤
 29
 30## 本任务不包含
 31
 32- 实际修改线上 DNS 记录
 33- 实际重载线上 Nginx
 34- 修改 control-api-worker、conductor-daemon、status-api 代码
 35
 36## 建议起始文件
 37
 38- `ops/nginx/baa-conductor.conf`
 39- `ops/nginx/includes/*.conf`
 40- `docs/ops/README.md`
 41- `scripts/ops/`
 42
 43## 交付物
 44
 45- DNS 辅助脚本
 46- Nginx 校验/部署辅助脚本或模板
 47- 对应运维文档收口
 48
 49## 验收
 50
 51- 如果新增 shell 脚本：`bash -n scripts/ops/*.sh`
 52- `git diff --check`
 53- 文档与脚本中的域名 / Tailscale `100.x` 方案一致
 54
 55## 更新要求
 56
 57完成时更新 frontmatter 的：
 58
 59- `status`
 60- `base_ref`
 61- `updated_at`
 62
 63并补充下面这些内容：
 64
 65## files_changed
 66
 67- `coordination/tasks/T-022-ops-automation.md`
 68- `docs/ops/README.md`
 69- `ops/nginx/templates/baa-conductor.conf.template`
 70- `ops/nginx/templates/includes/direct-node-auth.conf.template`
 71- `scripts/ops/baa-conductor.env.example`
 72- `scripts/ops/cloudflare-dns-plan.mjs`
 73- `scripts/ops/cloudflare-dns-plan.sh`
 74- `scripts/ops/lib/ops-config.mjs`
 75- `scripts/ops/nginx-sync-plan.mjs`
 76- `scripts/ops/nginx-sync-plan.sh`
 77
 78## commands_run
 79
 80- `git worktree add /Users/george/code/baa-conductor-T022 -b feat/T-022-ops-automation 458d7cf`
 81- `npx --yes pnpm install`
 82- `chmod +x scripts/ops/*.sh scripts/ops/*.mjs`
 83- `bash -n scripts/ops/*.sh`
 84- `node --check scripts/ops/cloudflare-dns-plan.mjs`
 85- `node --check scripts/ops/nginx-sync-plan.mjs`
 86- `node --check scripts/ops/lib/ops-config.mjs`
 87- `scripts/ops/cloudflare-dns-plan.sh --env scripts/ops/baa-conductor.env.example`
 88- `scripts/ops/nginx-sync-plan.sh --env scripts/ops/baa-conductor.env.example --check-repo --bundle-dir .tmp/ops/baa-conductor-nginx`
 89- `git diff --check`
 90- `git commit -m "feat(ops): add nginx and cloudflare dns automation helpers"`
 91- `git push -u origin feat/T-022-ops-automation`
 92
 93## result
 94
 95- 新增 `scripts/ops/baa-conductor.env.example`，把公网域名、VPS 公网 IP、Tailscale `100.x` 回源和 Nginx 安装路径收口到一份可执行 inventory 模板
 96- 新增 `scripts/ops/cloudflare-dns-plan.{mjs,sh}`，可渲染目标 DNS 记录、可选用 Cloudflare GET API 对比现网，并输出预览用的 `curl` shell 脚本，但默认不写线上 DNS
 97- 新增 `scripts/ops/nginx-sync-plan.{mjs,sh}` 与 `ops/nginx/templates/**`，可按 inventory 渲染 Nginx 配置、检查仓库默认配置是否漂移，并打出包含 `deploy-on-vps.sh` 的部署 bundle
 98- `docs/ops/README.md` 已改为 inventory 驱动的运维流程说明，覆盖 DNS 计划、Nginx bundle、VPS 分发、证书与验证步骤
 99
100## risks
101
102- 本次没有连接真实 Cloudflare zone；`--fetch-current` 和预览 shell 仍需在填入真实 Zone ID / token 后做一次人工核对
103- 本次没有在真实 VPS 上执行 `deploy-on-vps.sh`、`nginx -t` 或 `systemctl reload nginx`；证书路径、权限和 systemd 服务名仍需线上确认
104- 真实 inventory 预计放在仓库外，若运维人员绕开 inventory 手工改 Nginx 或 DNS，模板与线上状态仍可能漂移
105
106## next_handoff
107
108- 在仓库外复制并填写 `scripts/ops/baa-conductor.env.example`，补上真实 VPS 公网 IP、Cloudflare Zone ID 与证书路径
109- 导出 `CLOUDFLARE_API_TOKEN` 后运行 `scripts/ops/cloudflare-dns-plan.sh --fetch-current --emit-shell ...`，审阅差异和预览脚本
110- 运行 `scripts/ops/nginx-sync-plan.sh --env <real-env> --bundle-dir <dir>`，把 bundle 分发到 VPS，先执行 `sudo ./deploy-on-vps.sh`，确认 `nginx -t` 后再显式执行 `sudo ./deploy-on-vps.sh --reload`
111
112开始时建议直接把 `status` 改为 `in_progress`。
113
114做完并推送后：
115
116- 如果等待整合，改为 `review`
117- 如果确认结束，改为 `done`