baa-conductor

README.md

  1# VPS、Nginx 与 DNS 运维
  2
  3当前运维模型只保留一条 canonical 路径：
  4
  5- `conductor.makefile.so` 是唯一公网域名
  6- VPS Nginx 统一回源到 `mini` 的 `100.71.210.78:4317`
  7- `mini` 本地 `4317` 是唯一主接口
  8- `mini` 本地 `4318` 只作为显式 opt-in 的兼容观察层
  9
 10旧的 `control-api` 域名、Cloudflare Worker 和 D1 已退出当前运维口径；默认 runbook 只写 `conductor.makefile.so`。
 11
 12主备切换、直连 `mac` 的公网域名和历史切换 runbook 已从当前主线移除。
 13
 14仓库根验证入口说明见：
 15
 16- [`repo-verification.md`](./repo-verification.md): `pnpm lint` / `pnpm test` 的覆盖范围与边界
 17
 18## 当前 inventory
 19
 20使用一份最小 inventory：
 21
 22- [`scripts/ops/baa-conductor.env.example`](../../scripts/ops/baa-conductor.env.example)
 23
 24里面只需要维护：
 25
 26- Cloudflare zone
 27- VPS 公网 IP
 28- `conductor.makefile.so`
 29- `mini` 的 Tailscale `100.71.210.78:4317`
 30- 可选本地观察口 `100.71.210.78:4318`
 31- 证书与 Nginx 安装路径
 32
 33## 当前公网关系
 34
 35| 公网域名 | 目标 | 回源 |
 36| --- | --- | --- |
 37| `conductor.makefile.so` | VPS 公网 IP | `100.71.210.78:4317` |
 38
 39## HTTP 面说明
 40
 41默认只把一条主路径当真：
 42
 43| 面 | 地址 | 当前用途 | 推荐首个请求 |
 44| --- | --- | --- | --- |
 45| public primary | `https://conductor.makefile.so` | 唯一公网入口 | `GET /healthz` |
 46| local primary | `http://100.71.210.78:4317` | 真相源、on-node 调试 | `GET /healthz` |
 47| local status view | `http://100.71.210.78:4318` | 本地兼容状态包装层 | `GET /healthz` |
 48
 49最小排查顺序：
 50
 511. `curl https://conductor.makefile.so/healthz`
 522. `curl https://conductor.makefile.so/readyz`
 533. `curl https://conductor.makefile.so/rolez`
 544. `curl https://conductor.makefile.so/v1/runtime`
 555. 如需 on-node 状态观察，先看 `curl http://100.71.210.78:4317/v1/status`
 566. 只有在排查兼容层时，再看 `curl http://100.71.210.78:4318/v1/status`
 57
 58## 当前节点监听
 59
 60`mini`:
 61
 62```text
 63BAA_CONDUCTOR_LOCAL_API=http://100.71.210.78:4317
 64BAA_CONDUCTOR_LOCAL_API_ALLOWED_HOSTS=100.71.210.78
 65BAA_STATUS_API_HOST=100.71.210.78
 66```
 67
 68## DNS 计划
 69
 70### 1. 准备私有 inventory
 71
 72```bash
 73cp scripts/ops/baa-conductor.env.example ../baa-conductor.ops.env
 74$EDITOR ../baa-conductor.ops.env
 75export CLOUDFLARE_API_TOKEN=...your token...
 76```
 77
 78### 2. 只看目标记录
 79
 80```bash
 81scripts/ops/cloudflare-dns-plan.sh --env ../baa-conductor.ops.env
 82```
 83
 84### 3. 生成变更预览
 85
 86```bash
 87scripts/ops/cloudflare-dns-plan.sh \
 88  --env ../baa-conductor.ops.env \
 89  --fetch-current \
 90  --emit-shell .tmp/ops/cloudflare-dns-preview.sh \
 91  --output .tmp/ops/cloudflare-dns-plan.json
 92```
 93
 94脚本只生成计划，不会直接改线上 DNS。
 95
 96## Nginx 渲染与部署
 97
 98### 1. 渲染 bundle
 99
100```bash
101scripts/ops/nginx-sync-plan.sh \
102  --env ../baa-conductor.ops.env \
103  --bundle-dir .tmp/ops/baa-conductor-nginx
104```
105
106### 2. 校验仓库默认配置
107
108```bash
109scripts/ops/nginx-sync-plan.sh \
110  --env scripts/ops/baa-conductor.env.example \
111  --check-repo
112```
113
114### 3. 分发到 VPS
115
116```bash
117rsync -av .tmp/ops/baa-conductor-nginx/ root@YOUR_VPS:/tmp/baa-conductor-nginx/
118ssh root@YOUR_VPS 'cd /tmp/baa-conductor-nginx && sudo ./deploy-on-vps.sh'
119ssh root@YOUR_VPS 'cd /tmp/baa-conductor-nginx && sudo ./deploy-on-vps.sh --reload'
120```
121
122## 前置条件
123
1241. VPS 已安装 `nginx`
1252. VPS 能访问 `100.71.210.78:4317`
1263. `conductor.makefile.so` 已有 DNS 记录
1274. 证书路径与 inventory 一致
128
129## 当前收口结果
130
131- 浏览器、CLI、AI 和运维说明默认都只写 `conductor.makefile.so`
132- Cloudflare Worker / D1 不再出现在默认运维 runbook
133- `status-api` 只保留本地兼容观察层，不承担公网暴露职责，也不再是默认运维入口
134
135## 说明
136
137- 当前只维护 `conductor.makefile.so`
138- 不依赖 MagicDNS
139- 是否启用 Cloudflare proxy 由实际证书和 SSL mode 决定
140- 历史多节点资料只通过 tag `ha-failover-archive-2026-03-22` 回溯