怎么跑起来
那个从没打开的端口
绑非回环地址不是一个单独加就生效的参数。在没配任何认证方式的情况下用 <code>--host 0.0.0.0</code> 启动,服务直接拒绝绑定,把原因打出来,然后以 0 退出,端口上一个监听都没有。要命的是那个退出码:只看退出状态的启动脚本会记下「成功」。绑回环则正常启动并打出 ready 行——那才是唯一可信的信号。
讲「把服务对外开放」的文章几乎都从同一句话开始:绑 0.0.0.0,前面套认证。我们只试了前半句,预期是一个警告加一个打开的端口。实际发生的更像是另一个故事,对写自动化的人来说也更糟。
命令到底做了什么
$ timeout 15 hermes serve --host 0.0.0.0 --port 9123
Refusing to bind dashboard to 0.0.0.0 — the auth gate engages on non-loopback binds
(0.0.0.0), but no auth providers are registered.
Configure an auth provider before exposing the dashboard:
• Password: set dashboard.basic_auth.username + password_hash in config.yaml
(hash with: python -c "from plugins.dashboard_auth.basic import hash_password; print(hash_password('your-password'))")
• OAuth: run `hermes dashboard register` (Nous Portal) or install a DashboardAuthProvider plugin.
There is no unauthenticated public-dashboard option. For local-only use, bind 127.0.0.1
and leave dashboard.public_url unset; a configured external public URL requires auth
even when a local reverse proxy reaches a loopback backend.
它拒绝了,而且把原因说得一清二楚。这部分是好的设计。这篇文章要说的是其余的行为。
要命的是退出码
$ timeout 12 hermes serve --host 0.0.0.0 --port 9123 >/tmp/a.log 2>&1; echo "退出码=$?"
退出码=0
$ ss -tlnp | grep 9123
9123 无监听
零。端口上什么都没有。在大数人的心智模型里,这两行不该同时出现;而这个组合正是丢掉一个小时的开始:带 Restart=on-failure 的守护进程看到「成功」就不再重试;检查 $? 的部署脚本打印「已启动」继续往下走;三十秒后的健康检查说端口不通,而本该被读到的那十行说明早就滚过去了。
如果这一页只带走一条运维经验,就带走这一对:以 0 退出的启动命令,不代表启动成功;最便宜的校验是 socket,不是状态码。
为什么拒绝才是对的默认
绑非回环地址的那一刻,本机工具就变成「任何能路由过来的人都能连」;而它背后那个东西能在你的机器上执行命令。绝大多数「暴露后被拿下」的事件都不高级:一个没有认证的 agent 后端挂在公网地址上,等于一个多绕几步的远程 shell。
所以这道闸门不是要绕过的麻烦,它就是设计本身:没有认证提供方,就没有非回环绑定。满足它的两种方式就印在那段话里——把密码哈希写进配置,或走 dashboard 的 OAuth 注册流程。两者都是一次性的,而且都严格优于那个「悄悄把端口打开」的参数。
绑回环会启动,而且会说
对照组,同一个二进制、同一个端口:
$ ( hermes serve --host 127.0.0.1 --port 9123 >/tmp/b.log 2>&1 & ); sleep 7
$ ss -tlnp | grep 9123
LISTEN 0 2048 127.0.0.1:9123 0.0.0.0:* users:(("hermes",pid=628,fd=14))
$ head -2 /tmp/b.log
HERMES_BACKEND_READY port=9123
Hermes backend listening on 127.0.0.1:9123
两条互相独立的确认,而且都不是退出码:一条点名端口的 ready 行,和一个属于该进程号的监听 socket。只有其中一条不算验证——ready 行可能在后面出问题之前就打出来,而监听 socket 可能属于上一次尝试留下的陈旧进程。
陈旧进程这点值得变成习惯:ss 会显示 pid,拿它跟你刚启动的进程比,别默认那个端口是你的。
反向代理这条「捷径」也关着
最像样的变通是:后端留在回环,前面放个代理,闸门就永远不触发。那段说明预判了这一点——一旦配置了外部公开 URL,即使本机的反向代理能打到回环后端,也要求认证。也就是说,决定因素不是「我绑在哪块网卡上」,而是「这个服务是不是要能被外面访问」;配置说了是,认证要求就跟着来。
这个取舍是对的。代理负责终止 TLS、改写头,但它不知道打电话的是谁,也没法让 agent 小心一点。如果部署本来就是本地的,就绑回环、把公开 URL 留空——工具压根不碰认证这摊事,因为外面根本到不了。
怎么知道它真的有效
针对「被拒绝」这种情况,三条检查本来能立刻发现问题:
- 端口以你要的地址存在:
ss -tlnp | grep 9123返回带你自己 pid 的LISTEN行。 - 日志里有那个端口的 ready 行——如果日志里是 “Refusing to bind”,就地停下配认证,不要重试。
- 打这个端口有回应:
curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:9123/api/status给出状态码,而不是空响应。
针对「已暴露」的情况再加第四条:换一台机器,端口能连通,并且不带凭据的请求被拒绝。一个不问凭据就应答的端口不是成功,它正好是这套机制要防的那个失败。
怎么回滚
被拒绝的那次什么都没改,这很容易核,也值得核一下:
md5sum ~/.hermes/config.yaml # 被拒绝绑定前后哈希一致
对于真的生效了的改动,顺序很重要:先停进程,确认端口空出来,再从你动手前复制的那份恢复配置。如果加了密码哈希,删掉 basic_auth 段会回到「没有认证提供方、只绑回环」的状态——用那个密码建立的会话也随之消失。如果是收掉暴露,先改回绑定地址,再改客户端配置,因为客户端指向一个死地址的样子,跟后端坏了一模一样。
我们没验的部分
配好密码哈希后真的绑公网网卡、OAuth 注册全流程、以及在回环后端前面套 TLS 终止。我们验的是「拒绝」这条路径与回环这条路径,同一台机器、各跑一次,两次都查了 socket——活下来的那个结论是关于退出码的,不是关于参数的。
相关档案
常见问题
为什么会拒绝绑 0.0.0.0?
因为认证闸门在非回环绑定时就会生效,而当时没有注册任何认证方式。服务自己说明了它没有「不认证的公开选项」,并告诉你先配密码或 OAuth 再来暴露。
它报错了吗?
打了一段清楚的说明,然后以退出码 0 结束。所以这件事值得写下来:只看退出状态的脚本或守护进程会把这次记录成成功,而 ss 会告诉你端口上什么都没有。
绑回环、前面套反向代理,能绕开闸门吗?
如果配置了对外公开 URL,绕不开。说明里写得很明确:一旦配置了外部公开 URL,即使本机的反向代理能打到回环后端,也要求认证——代理这条路不是绕过认证的方法。
它要我造的密码怎么生成?
它把命令也打出来了:用 dashboard_auth 的辅助函数把密码哈希化,再把用户名和哈希写进配置。明文不会被保存,你手里留下的只有哈希。
怎么可靠地判断它起来了?
两个信号同时成立:进程打出带端口号的 ready 行,并且端口以你要求的地址出现在监听列表里。退出码是 0 对此什么也证明不了。
来源
本文最后一次核验:2026-11-19 · 拒绝的原文、退出码、空端口与可用的回环监听,都是 2026-11-19 在这台机器上观测到的;配置文件的哈希在被拒绝的那次启动前后完全一致。