im_wower
·
2026-03-26
node-verification.md
1# node verification
2
3当前只检查 `mini`，正式运行面同时认识：
4
5- `conductor` `http://100.71.210.78:4317`
6- `codexd` `http://127.0.0.1:4319`
7- `status-api` `http://100.71.210.78:4318`，是显式 opt-in 的本地只读观察面，默认读取 `http://100.71.210.78:4317/v1/system/state`
8
9其中 `codexd` 的正式产品面仍是 `status / sessions / turn / events`，但 on-node 运维探针只要求 `/healthz` 和 `/v1/codexd/status`。会话级端到端链路单独由仓库 smoke 覆盖。
10
11## 1. 推荐入口：统一 mini verify wrapper
12
13```bash
14./scripts/runtime/verify-mini.sh \
15 --repo-dir /Users/george/code/baa-conductor \
16 --install-dir /Users/george/Library/LaunchAgents \
17 --shared-token-file /Users/george/.config/baa-conductor/shared-token.txt \
18 --local-api-base http://100.71.210.78:4317 \
19 --local-api-allowed-hosts 100.71.210.78 \
20 --codexd-api-base http://127.0.0.1:4319 \
21 --expected-rolez leader \
22 --check-loaded
23```
24
25这条入口会顺序执行：
26
27- `check-launchd.sh`
28- `check-node.sh --skip-static-check`
29
30说明：
31
32- 默认服务集合是 `conductor`、`codexd`
33- `status-api` 仍是显式 opt-in；如果已经安装，再额外加 `--service status-api`
34- 需要覆盖 `status-api` 地址时，再补 `--status-api-base http://100.71.210.78:4318 --status-api-host 100.71.210.78`
35- 如需从仓库根调用，可以用 `pnpm verify:mini --check-loaded`
36- 会话级链路 smoke 仍然单独执行，不并入这条 wrapper
37
38## 2. 底层静态检查
39
40```bash
41npx --yes pnpm -r build
42./scripts/runtime/check-launchd.sh \
43 --repo-dir /Users/george/code/baa-conductor \
44 --node mini \
45 --service conductor \
46 --service codexd \
47 --install-dir /Users/george/Library/LaunchAgents \
48 --shared-token-file /Users/george/.config/baa-conductor/shared-token.txt \
49 --local-api-base http://100.71.210.78:4317 \
50 --local-api-allowed-hosts 100.71.210.78 \
51 --codexd-local-api-base http://127.0.0.1:4319
52```
53
54说明：
55
56- 默认 mini 静态检查不需要显式传 `--public-api-base`；只有 `conductor` 的 upstream/public API base 不是 `https://conductor.makefile.so` 时才需要覆盖
57- `status-api` 的有效默认真相源仍然是 `--local-api-base http://100.71.210.78:4317`
58- `check-launchd.sh` 现在会优先校验 `conductor` 安装副本里的 `BAA_CONDUCTOR_PUBLIC_API_BASE`，同时接受只带 legacy `BAA_CONTROL_API_BASE` 的旧安装副本；其他服务要求这两个变量都不存在
59- `check-launchd.sh` 现在也会校验 `conductor` 安装副本里的 `BAA_CODEXD_LOCAL_API_BASE`
60- `check-launchd.sh` 现在会校验 `codexd` 的监听地址、事件流路径、日志目录、状态目录和 `app-server` child 配置
61- 如果 `status-api` 已显式安装，再额外加 `--service status-api --status-api-host 100.71.210.78`
62- 这些静态检查不包含 run/exec 路线
63
64## 3. 底层运行态检查
65
66```bash
67./scripts/runtime/check-node.sh \
68 --repo-dir /Users/george/code/baa-conductor \
69 --node mini \
70 --service conductor \
71 --service codexd \
72 --install-dir /Users/george/Library/LaunchAgents \
73 --local-api-base http://100.71.210.78:4317 \
74 --local-api-allowed-hosts 100.71.210.78 \
75 --codexd-api-base http://127.0.0.1:4319 \
76 --expected-rolez leader \
77 --check-loaded
78```
79
80`check-node.sh` 当前会验证：
81
82- `launchctl print` 是否成功
83- 进程命令行是否匹配
84- `logs/launchd/*.log` 是否存在
85- `conductor` 是否监听 `4317` 并返回 `/healthz`、`/readyz`、`/rolez`、`/v1/codex`
86- `codexd` 是否监听 `4319` 并返回 `/healthz`、`/v1/codexd/status`
87- 如果显式纳入 `--service status-api`，再验证 `status-api` 是否监听 `4318` 并返回 `/healthz`、`/v1/status`
88- 如果显式纳入 `--service status-api`，再验证 `status-api /v1/status` 是否能跟随同机 `conductor` 的 `/v1/system/state`
89- 不要求探测 run/exec 路线
90
91## 4. 会话链路 smoke
92
93```bash
94./scripts/runtime/codexd-e2e-smoke.sh
95```
96
97这条 smoke 会起一组临时 `codexd` + `conductor` 进程，并验证：
98
99- `codexd status`
100- `GET /v1/codex`
101- session create/read
102- turn create/read
103- `logs/codexd/**` 和 `state/codexd/**` 落盘
104
105## 5. 手工探针
106
107主路径：
108
109```bash
110curl -fsSL https://conductor.makefile.so/healthz
111curl -fsSL https://conductor.makefile.so/readyz
112curl -fsSL https://conductor.makefile.so/rolez
113curl -fsSL https://conductor.makefile.so/v1/runtime
114```
115
116on-node：
117
118```bash
119curl -fsSL http://100.71.210.78:4317/healthz
120curl -fsSL http://100.71.210.78:4317/v1/runtime
121curl -fsSL http://100.71.210.78:4317/v1/codex
122curl -fsSL http://127.0.0.1:4319/healthz
123curl -fsSL http://127.0.0.1:4319/v1/codexd/status
124curl -fsSL http://100.71.210.78:4318/v1/status
125```
126
127会话链路回归不要直接手工拼 `run/exec` 探针，统一跑 `./scripts/runtime/codexd-e2e-smoke.sh`。
128
129## 6. 常见失败点
130
131- `conductor /rolez` 不是 `leader`
132- `codexd` 没有监听 `127.0.0.1:4319`
133- `codexd /v1/codexd/status` 没有返回 `app-server` 运行信息
134- `conductor /v1/codex` 没有正确代理到 `codexd`
135- `conductor.makefile.so` 没有正确回源到 `100.71.210.78:4317`
136- `launchctl print` 失败
137- `logs/launchd/*.log` 没有新内容