接口总览与认证

daemon 起来之后监听一个端口（缺省 127.0.0.1:8420，由 rha.toml 的 [api].listen 决定）。面板、rha 命令行、MCP、你自己写的脚本，全都走它。

本区四页的接口清单与字段表全部由代码生成，跟着二进制走，不会与实现分叉。

拿 token

除了 /healthz，所有接口都要 rha.toml 里 [api].token 那个值：

export RHA_TOKEN=你的token
curl -s -H "Authorization: Bearer $RHA_TOKEN" http://127.0.0.1:8420/api/entities | jq .

token 至少 16 个字符，空着 daemon 直接起不来。这是刻意的：一个没有 token 的监听端口，等于把家里所有设备的开关放在网上。

这是这套接口最容易配错的地方，也是安全设计的核心：

组	认什么	包含
读组	Bearer 或面板会话 cookie	实体、设备、历史，以及给实体写值
写组	只认 Bearer	规则增删改、reload、面板上传

面板页面在浏览器里跑，它拿不到 token（token 在服务端配置里）。所以第一次带 token 访问 /d/ 时，服务端发一张会话 cookie，之后面板靠这张 cookie 调读组接口。

一张泄漏的 cookie 是能开关设备的 —— /api/entities/{id}/set 就在读组里，因为面板必须能按开关。这是有意的取舍，不是漏洞。但它改不了自动化规则、触发不了 reload、传不了面板：那些是写组，cookie 在那边一律 401。

除了 /healthz 与 /metrics，所有接口都返回同一个信封：

{ "ok": true, "data": [], "error": null }

失败时 ok 是 false、data 是 null、error 是一句人话原因：

{ "ok": false, "data": null, "error": "entity fan.nope not found" }

先看 HTTP 状态码判断是哪一类问题，再看 error 看具体是哪一条。

后面三页每条接口都列了它自己可能返回的错误码。401 不逐条重复列 —— 它对所有非匿名接口都成立。

GET/healthz

认证：匿名 —— 不需要 token

全站唯一的匿名端点 —— 它一个字节的信息都不泄漏, 所以不要 token。返回纯文本 ok, 不带信封。给 systemd、容器编排、监控探针用。

纯文本，不带 {ok, data, error} 信封。

GET/metrics

认证：Bearer token

默认不存在。 要在 rha.toml 里写 [api] metrics = true 并重启进程(reload 不管用)。关着时返回 404, 带对 token 也是 404 —— 那条路由压根没注册。

返回 Prometheus 展示格式的纯文本, 不带信封。只认 Bearer, 不认面板 cookie: 指标里带着实体名与设备名, 那是「这户人家有哪些设备」的完整清单。

纯文本，不带 {ok, data, error} 信封。

指标有哪些、怎么用它排查问题，见出了问题怎么查。