baa-conductor

T-027-node-verification.md

 1---
 2task_id: T-027
 3title: launchd 节点验证与 On-Node 检查
 4status: done
 5branch: feat/T-027-node-verification
 6repo: /Users/george/code/baa-conductor
 7base_ref: main@6505a31
 8depends_on:
 9  - T-019
10  - T-020
11  - T-021
12write_scope:
13  - docs/runtime/**
14  - scripts/runtime/**
15updated_at: 2026-03-22T02:16:15+0800
16---
17
18# T-027 launchd 节点验证与 On-Node 检查
19
20## 目标
21
22把当前 launchd/bootstrap 脚本推进到“有更贴近真实节点的 on-node 检查和验证流程”的程度。
23
24## 本任务包含
25
26- 在 `scripts/runtime/**` 下补 on-node 检查脚本
27- 在 `docs/runtime/**` 下补 mini / mac 节点验证步骤
28- 覆盖本地端口、`healthz/readyz/rolez`、status-api 宿主进程、日志路径等检查点
29
30## 本任务不包含
31
32- 修改 app 业务代码
33- 真实加载 launchd 服务
34- 修改 Nginx / DNS
35
36## 建议起始文件
37
38- `docs/runtime/launchd.md`
39- `docs/runtime/README.md`
40- `scripts/runtime/check-launchd.sh`
41
42## 交付物
43
44- 更接近真实节点操作的验证脚本
45- 明确的 mini / mac 验证清单
46
47## 验收
48
49- 如果新增 shell 脚本：`bash -n scripts/runtime/*.sh`
50- `git diff --check`
51- 文档里明确 mini 与 mac 的 on-node 检查顺序
52
53## 更新要求
54
55完成时更新 frontmatter 的：
56
57- `status`
58- `base_ref`
59- `updated_at`
60
61并补充下面这些内容：
62
63## files_changed
64
65- `coordination/tasks/T-027-node-verification.md`
66- `docs/runtime/README.md`
67- `docs/runtime/launchd.md`
68- `docs/runtime/node-verification.md`
69- `scripts/runtime/common.sh`
70- `scripts/runtime/check-node.sh`
71
72## commands_run
73
74- `npx --yes pnpm install`
75- `bash -n scripts/runtime/*.sh`
76- `git diff --check`
77- `scripts/runtime/check-node.sh --help`
78- `scripts/runtime/check-node.sh --repo-dir <tmp_repo> --node mini --service conductor --service status-api --skip-static-check --local-api-base http://127.0.0.1:4417 --status-api-base http://127.0.0.1:4418 --expected-rolez leader`
79
80## result
81
82- 新增 `scripts/runtime/check-node.sh`，把节点验证推进到运行态层：覆盖 runtime 静态校验复用、本地端口、conductor `/healthz` `/readyz` `/rolez`、status-api 宿主进程与 `/healthz` `/v1/status` `/v1/status/ui`、以及 launchd 日志文件存在性。
83- `scripts/runtime/common.sh` 补了 status-api 默认地址、on-node 默认服务集合和进程匹配辅助逻辑，避免节点约定散落在多个脚本里。
84- `docs/runtime/README.md`、`docs/runtime/launchd.md`、`docs/runtime/node-verification.md` 明确了 mini/mac 的静态检查顺序、on-node 检查顺序，以及 steady-state 下 `mini=leader`、`mac=standby` 的 `rolez` 预期。
85
86## risks
87
88- 没有在真实 `mini` / `mac` 节点上执行 `--check-loaded`，因此 `launchctl print gui/...` / `launchctl print system/...` 只完成了脚本级接线，没有做实机验证。
89- `status-api /v1/status` 目前按返回体中包含 `"ok": true` 做断言；如果后续响应格式改成不同 JSON 序列化风格，脚本可能需要同步微调。
90
91## next_handoff
92
93- 在真实 `mini` 与 `mac` 节点上各跑一次 `scripts/runtime/check-node.sh --check-loaded ...`，确认 launchd 域、日志文件、端口和探针都与文档一致。
94- 如果某个节点不常驻 `status-api`，在落地时显式使用 `--service conductor`，并确认运维文档是否需要额外区分“仅 conductor 节点”和“conductor + status-api 节点”。