Files
HomeAgent/docs/zh
JianFeeeee 5cc0f53df8 docs(runbook): 补 §6 部署单元清单,并纠正一次误判的记录
## 补齐漏掉的单元

`cmd/` 下共 7 个可构建入口,服务端只部署 3 个:

| 单元 | 入口 | 服务端部署 |
| --- | --- | --- |
| homed(内核) | `cmd/homed` | ✅ 本机 `/usr/local/bin/homed` |
| waiter / waitercli | `cmd/waiter` | ✅ 106、30 的 `/opt/waiter/waiter` |
| 站点 | `site/`、`site_build/` | ✅ 106 的 `sites/` |
| **GUI** | `cmd/gui` | ❌ **Electron 桌面应用,随客户端分发** |

**GUI 不在服务端部署**(已确认生产无 `*.service`、无进程)。它与 waiter
是两端:GUI 用 `devicebridge_dll.js` 走设备桥协议连服务端 waiter,
`a781f8e` 修的正是 GUI 侧 bind 判 ok 与登记状态暴露。
⇒ 排查 GUI 问题要看**用户机器上的客户端**,不是 `homeagent.service` 日志。

另记:核查"有没有进程"时 `ps -ef | grep -c "[e]lectron"` 会把**自己的
grep 命令行**算进去返回非 0(实测返回 2,实际 0)—— 要看列出的内容,别只看计数。

## 本机 waiter 与 106/30 不同步

本机也留了一份 `/usr/local/bin/waiter`,`v1.3.2-153-gff69127`(2026-09-25
构建),**早于** main 在 09-26 合入的那批修复(设备反复掉线、bind 判 ok、
服务端发现自动链接),因而缺它们。106/30 已是 `1.4.0`。
本机这份无进程无服务,不影响生产设备桥;更新方式已记入文档。

## 记一次误判:判定"是否已合入"要按内容查

我曾用 `git merge-base --is-ancestor ff69127 origin/main` 判定"这批提交
没进 main",并推断"存在一条未合入、只靠 reflog 撑着的 5 提交线"。**该结论是错的。**

真实情况:这批改动在 2026-09-26 以**新 hash** 重做并进入 main,五对逐字节一致
(diff 均为 0 行):`1acbd39`→`1e58af7`、`3d30482`→`5d278cf`、
`078517e`→`7f5bf16`、`aaafaac`→`94c74b2`、`ff69127`→`a781f8e`。

⇒ 只查**旧 hash 的祖先关系**会误判;同一改动被重做为新 hash 时
   `merge-base` 必然说不包含,而 `git merge-tree` 报的 13 个"冲突"
   正是同源改动做两遍的必然结果,**不能当冲突去解**。

顺带修正一处归因:106 此前长期无 `online` 日志的成因是
`94c74b2`(设备反复掉线/静默失联:ping 路径断连 + bind 结果无人处理),
2026-09-26 已进 main,今天部署的 `1.4.0` 包含它。
2026-09-27 23:10:49 +08:00
..