baa-conductor

commit

e4e3f32

parent

7d4f292

author

im_wower

date

2026-03-22 11:49:32 +0800 CST

Simplify deployment target to mini single-node

 1@@ -4,6 +4,16 @@
 2 
 3 本文档是新 conductor 系统的实施基线。
 4 
 5+## 0.1 当前有效部署决策
 6+
 7+从 `2026-03-22` 起，当前有效目标已经简化为：
 8+
 9+- 只保留 `mini` 作为唯一中控
10+- 只保留 `mini` 的自启动、控制面、运行态检查与公网入口
11+- 不再继续推进 `mac` 备主、planned failover、emergency failover、switchback
12+
13+下面保留的主备/failover 内容，视为历史设计记录，不再是当前执行目标。
14+
15 它的细节深度是按“多个 Codex worker 读完就能并行开工”来写的。
16 
17 本文档定义了：
18@@ -11,7 +21,7 @@
19 - 系统目标
20 - 拓扑结构
21 - 域名与转发布局
22-- `mini` 与 `mac` 的主备切换行为
23+- 历史上的 `mini` / `mac` 主备切换行为
24 - Cloudflare D1 控制平面设计
25 - task 与 step 模型
26 - `planner`、`conductor`、`worker` 的职责边界
27@@ -27,9 +37,9 @@
28 
29 构建一个稳定的 AI 执行系统，具备以下特征：
30 
31-- `mini` 是主 conductor。
32-- `mac` 是备用 conductor。
33-- 两台机器都可以运行 Codex worker。
34+- `mini` 是唯一长期运行的 conductor。
35+- `mini` 承担自启动、控制面、本地状态面和浏览器控制集成。
36+- 如需额外开发机或临时 worker，视为辅助资源，不再纳入主备设计目标。
37 - 人类只使用一个可见的 Claude `control` 对话。
38 - 自动化使用一个隐藏的 Claude `dispatch` 通道。
39 - task 真相存储在共享数据库中。

 1@@ -2,13 +2,13 @@
 2 
 3 `baa-conductor` 是新的 AI 执行编排仓库。
 4 
 5-它的目标不是提供单个 AI 会话，而是提供一套可以让 `mini` 主控、`mac` 备主、多个 Codex worker 并行工作的稳定基础设施。
 6+它的目标不是提供单个 AI 会话，而是提供一套以 `mini` 为唯一中控、带自启动和浏览器控制面的稳定执行基础设施。
 7 
 8 当前仓库状态：
 9 
10 - 设计文档已落在 [`DESIGN.md`](./DESIGN.md)
11 - 代码目录骨架已建立
12-- 具体功能大多仍为占位实现
13+- 当前推荐部署模式已经收口为 `mini` 单节点
14 - 并行任务文档已放在 [`coordination/`](./coordination/)
15 
16 ## 先读什么
17@@ -57,6 +57,8 @@ docs/
18 
19 ## 当前约定
20 
21+- 当前只保留 `mini` 的 conductor / status-api / 自启动路径
22+- 不再继续推进 `mac` 备主与主备切换
23 - 一个任务一个分支
24 - 一个任务一个 worktree
25 - 一个任务一个任务卡

 1@@ -55,7 +55,7 @@
 2 ## 下一步建议
 3 
 4 - 当前没有活动开发任务。
 5-- 后续以运维、观察和零散修复为主。
 6+- 后续以 `mini` 单节点运维、观察和零散修复为主。
 7 
 8 ## 需要整合者关注的点
 9 
10@@ -63,6 +63,7 @@
11 - `ops/launchd/**` 已合入，当前主线已经产出 app 级 `dist/index.js`
12 - `apps/conductor-daemon/package.json` 与 `apps/status-api/package.json` 的构建脚本已在第三波整合时收口
13 - Firefox 插件代码现已收口到本仓库子目录 `plugins/baa-firefox/`
14+- 当前推荐部署模式已改成 `mini` 单节点，不再继续推进主备切换
15 
16 ## 后续汇总规则
17 

 1@@ -57,8 +57,8 @@
 2 建议重点关注：
 3 
 4 - live `status-api` 持续漂移问题
 5-- mini/mac runtime 路径 canonicalization
 6-- Cloudflare proxy 重新启用前的单独演练
 7+- `mini` runtime 路径 canonicalization
 8+- 把运维文档和脚本继续收口到 `mini` 单节点模式
 9 
10 ## 6. 已归档任务
11 

 1@@ -0,0 +1,34 @@
 2+# 0001 单节点 mini 决策
 3+
 4+## 状态
 5+
 6+已采纳。
 7+
 8+## 决策
 9+
10+当前项目不再继续推进 `mini + mac` 主备切换方案，统一收口为：
11+
12+- `mini` 是唯一长期运行的 conductor 节点
13+- `mini` 负责自启动、状态面、控制面和公网入口
14+- `mac` 不再承担 standby、failover、switchback 的职责
15+
16+## 原因
17+
18+- 当前项目后续会被其他项目替代，不值得继续为主备切换维护额外复杂度
19+- 现网主要剩余问题已经集中在 `mini` 自身的运行态收口，而不是多节点编排能力
20+- 主备切换文档、脚本和操作链条过长，继续维护的性价比低
21+
22+## 直接影响
23+
24+- 当前推荐运维模式改成 `mini` 单节点
25+- `mac` 相关的主备/failover/switchback 文档降级为历史参考
26+- 后续零散修复优先聚焦：
27+  - live `status-api` 漂移
28+  - `mini` runtime 路径 canonicalization
29+  - `mini` 单节点下的自启动与公网入口稳定性
30+
31+## 不做的事情
32+
33+- 不在这一轮强拆所有历史 failover 代码路径
34+- 不把所有旧文档全部重写成单节点版本
35+- 不再围绕 `mac` 设计新的 rehearsal、切换或兜底流程

1@@ -10,3 +10,6 @@
2 
3 当前阶段先保留目录与约定，不写具体决策内容。
4 
5+当前已经落地的决策：
6+
7+- [`0001-single-node-mini.md`](./0001-single-node-mini.md)

 1@@ -1,18 +1,30 @@
 2 # VPS、Nginx 与 Cloudflare DNS 运维
 3 
 4-本目录收口第四波公网入口的运维步骤。当前方案固定遵守这几个约束：
 5+本目录收口公网入口的运维步骤。
 6+
 7+## 当前推荐模式
 8+
 9+从现在开始，当前有效运维目标改成：
10+
11+- 只保留 `mini` 作为唯一中控
12+- 只保留 `mini` 的自启动、探活、控制面与公网入口
13+- 不再继续推进 `mac` 备主、planned failover、emergency failover、switchback
14+
15+下面的主备/failover 文档保留为历史参考，不再作为当前执行目标。
16+
17+当前方案固定遵守这几个约束：
18 
19 - 公网只暴露 VPS 的 `80/tcp` 与 `443/tcp`
20-- `mini` / `mac` 回源固定走 Tailscale `100.x` 地址
21+- `mini` 回源固定走 Tailscale `100.x` 地址
22 - 不依赖 `*.ts.net` 的 MagicDNS 名称
23 - 仓库脚本默认只做 DNS 计划、Nginx 渲染和部署分发，不会直接改线上 DNS
24 - `deploy-on-vps.sh` 只有显式传 `--reload` 时才会重载 Nginx
25 
26 `control-api.makefile.so` 的 Worker 自定义域仍由 Cloudflare Worker / D1 相关任务管理，不在这里的脚本覆盖范围内。
27 
28-## Failover 与 Rehearsal
29+## 历史参考
30 
31-第四波把公网入口和节点运行时铺好后，第五波开始把“主备切换怎么练、怎么做”单独收口在这里：
32+下面这些主备切换文档只保留作历史记录：
33 
34 - [`failover-topology.md`](./failover-topology.md)
35 - [`planned-failover.md`](./planned-failover.md)
36@@ -25,14 +37,7 @@
37 - [`../../scripts/failover/rehearsal-check.sh`](../../scripts/failover/rehearsal-check.sh)
38 - [`../../scripts/failover/print-checklist.sh`](../../scripts/failover/print-checklist.sh)
39 
40-这些文档和脚本明确约束当前设计：
41-
42-- Cloudflare DNS 不参与 failover，公网记录仍固定指向 VPS
43-- `conductor.makefile.so` 的切换依赖 VPS Nginx 对 Tailscale `100.x` upstream 的连通性判断
44-- `launchd` 决定节点上的 conductor / status-api 是保持 loopback，还是显式切到节点自己的 Tailscale `100.x`
45-- Nginx 不知道谁持有 leader lease，所以“逻辑 leader 已切走”不等于“公网一定已切走”
46-
47-最新真实回归记录：
48+最新真实回归记录仍保留在：
49 
50 - [`real-stability-regression-2026-03-22.md`](./real-stability-regression-2026-03-22.md)
51 
52@@ -56,16 +61,15 @@
53 
54 | 公网域名 | Cloudflare DNS 目标 | VPS 上的 Nginx upstream | 内网实际回源 |
55 | --- | --- | --- | --- |
56-| `conductor.makefile.so` | VPS 公网 IP | `conductor_primary` | `mini 100.71.210.78:4317` 主，`mac 100.112.239.13:4317` 备 |
57+| `conductor.makefile.so` | VPS 公网 IP | `conductor_primary` | `mini 100.71.210.78:4317` |
58 | `mini-conductor.makefile.so` | VPS 公网 IP | `mini_conductor_direct` | `100.71.210.78:4317` |
59-| `mac-conductor.makefile.so` | VPS 公网 IP | `mac_conductor_direct` | `100.112.239.13:4317` |
60 
61 统一原则：
62 
63-- 三个公网 host 都解析到同一台 VPS
64+- 当前优先维护 `conductor.makefile.so` 和 `mini-conductor.makefile.so`
65 - 只有 VPS 对公网暴露 `80/443`
66 - `4317` 只允许 VPS 通过 Tailscale 或 WireGuard 访问
67-- `mini-conductor.makefile.so` 与 `mac-conductor.makefile.so` 默认保留 Basic Auth
68+- `mini-conductor.makefile.so` 默认保留 Basic Auth
69 
70 ## 节点监听配置
71 
72@@ -79,18 +83,10 @@ BAA_CONDUCTOR_LOCAL_API_ALLOWED_HOSTS=100.71.210.78
73 BAA_STATUS_API_HOST=100.71.210.78
74 ```
75 
76-`mac`:
77-
78-```text
79-BAA_CONDUCTOR_LOCAL_API=http://100.112.239.13:4317
80-BAA_CONDUCTOR_LOCAL_API_ALLOWED_HOSTS=100.112.239.13
81-BAA_STATUS_API_HOST=100.112.239.13
82-```
83-
84 运维边界：
85 
86-- VPS Nginx 继续只回源 conductor，也就是 `100.71.210.78:4317` 主、`100.112.239.13:4317` 备
87-- `status-api` 如需 Tailscale 直连，地址对应 `http://100.71.210.78:4318` / `http://100.112.239.13:4318`
88+- VPS Nginx 继续只回源 `mini` 的 conductor，也就是 `100.71.210.78:4317`
89+- `status-api` 如需 Tailscale 直连，地址对应 `http://100.71.210.78:4318`
90 - 当前实现不是双监听；切到 `100.x` 后，节点本地检查要同步改用 `check-node.sh --local-api-base ... --status-api-base ...`
91 
92 ## Cloudflare DNS 计划

 1@@ -1,6 +1,6 @@
 2 # runtime
 3 
 4-本目录定义 `mini` 与 `mac` 上的本地 runtime 约定：目录布局、环境变量，以及 `scripts/runtime/*.sh` 驱动的 `launchd` 安装方式。
 5+本目录定义当前推荐的 `mini` 单节点 runtime 约定：目录布局、环境变量，以及 `scripts/runtime/*.sh` 驱动的 `launchd` 安装方式。
 6 
 7 当前仓库已经把 app 级 `build` 从单纯 typecheck 推进到真实 emit。执行 `npx --yes pnpm -r build` 后，`apps/*/dist/index.js` 会生成，`ops/launchd/*.plist` 里的入口路径也因此固定下来。
 8 
 9@@ -10,20 +10,20 @@
10 
11 - [`layout.md`](./layout.md): `runs/`、`worktrees/`、`logs/`、`tmp/` 与 `state/` 的初始化方式和生命周期
12 - [`environment.md`](./environment.md): `launchd` 下必须显式写入的环境变量，以及安装脚本如何覆盖默认值
13-- [`launchd.md`](./launchd.md): `mini` 与 `mac` 的脚本化安装步骤，以及 `LaunchAgents` / `LaunchDaemons` 的差异
14-- [`node-verification.md`](./node-verification.md): `mini` / `mac` 的 on-node 验证顺序、期望探针结果，以及日志/进程检查点
15+- [`launchd.md`](./launchd.md): `mini` 的脚本化安装步骤，以及 `LaunchAgents` / `LaunchDaemons` 的差异
16+- [`node-verification.md`](./node-verification.md): `mini` 节点的 on-node 验证顺序、期望探针结果，以及日志/进程检查点
17 
18 ## 统一约定
19 
20-- `mini` 是首选 leader，默认跑 `so.makefile.baa-conductor` 的 `primary` 配置。
21-- `mac` 使用同一组服务，但 conductor 默认角色是 `standby`。
22-- 两台机器都推荐把仓库放在 `/Users/george/code/baa-conductor`，这样 repo 内的 plist 源模板可以直接复用设计里的绝对路径。
23+- 当前只保留 `mini` 作为长期运行节点，默认跑 `so.makefile.baa-conductor`。
24+- `mac` 不再作为备主节点要求的一部分；相关说明只保留作历史参考。
25+- 推荐把运行中的仓库放在 `/Users/george/code/baa-conductor`，这样 repo 内的 plist 源模板可以直接复用设计里的绝对路径。
26 - repo 中的 plist 只作为源模板；真正加载的是 `scripts/runtime/install-launchd.sh` 复制并改写到 `~/Library/LaunchAgents/` 或 `/Library/LaunchDaemons/` 的副本。
27 
28 ## 最短路径
29 
30 1. 先按 [`layout.md`](./layout.md) 运行 `./scripts/runtime/bootstrap.sh` 初始化 runtime 根目录。
31-2. 再按 [`environment.md`](./environment.md) 准备共享变量和节点变量，特别是 `BAA_SHARED_TOKEN`。
32+2. 再按 [`environment.md`](./environment.md) 准备共享变量和 `mini` 节点变量，特别是 `BAA_SHARED_TOKEN`。
33 3. 按 [`launchd.md`](./launchd.md) 运行 `install-launchd.sh` 生成安装副本，先用 `check-launchd.sh` 做静态校验。
34 4. 在节点上已有实际进程后，再按 [`node-verification.md`](./node-verification.md) 运行 `check-node.sh` 做端口、探针、status-api 宿主进程与日志路径检查。
35 5. 每次准备执行 `check-launchd.sh` 的 dist 校验、`check-node.sh` 的进程检查，或真正 `launchctl bootstrap` 前，先在 repo 根目录执行一次 `npx --yes pnpm -r build`，确认目标 app 的 `dist/index.js` 已更新。