Hermes WebUI「Agent Bridge is not reachable: connect ENOENT」排障与修复
|
140
|
0
|
未分类

1316 字
|
7 分钟

Hermes WebUI「Agent Bridge is not reachable: connect ENOENT」排障与修复文档

整理：EverNight｜环境：Alibaba Cloud Linux 8 + hermes-web-ui v0.6.43+ + Hermes Agent v0.19.0
适用：Hermes Studio WebUI（npm 包 hermes-web-ui）部署在 systemd –user 服务的场景

1. 故障现象

在 WebUI 新建会话发送消息，前端直接返回：

Error: Agent Bridge is not reachable: connect ENOENT configured endpoint
  • 网关状态显示正常（GET /health 200），配置、会话列表都能读；
  • 只有聊天执行挂了。

ENOENT 是关键线索：Node 端在连接一个不存在的 Unix Socket 文件。

2. 架构链路（搞清楚哪一环断了）

浏览器
  │  Socket.IO /chat-run
  ▼
hermes-web-ui (Node/Koa, :8648)
  │  agent-bridge client（Node 进程内）
  ▼  默认 ipc:///tmp/hermes-agent-bridge.sock
hermes_bridge.py（Python bridge broker，由 WebUI 启动）
  │  按 profile 拉起 WorkerProcess
  ▼  --agent-root 定位 run_agent.py
run_agent.py → Hermes Agent runtime（读 ~/.hermes profile）
  • Linux/macOS 默认 broker 端点：ipc:///tmp/hermes-agent-bridge.sock
  • Windows 默认：tcp://127.0.0.1:18765
  • Linux 也可强制 TCP：HERMES_AGENT_BRIDGE_WORKER_TRANSPORT=tcp

socket 文件不存在 = broker 根本没起来或起一半退了。 我们的 case 是后者。

3. 排查步骤（按顺序执行，每步都有明确判据）

3.1 看 socket 和进程

ls -l /tmp/hermes-agent-bridge.sock
ps -eo pid,ppid,args | grep -Ei 'hermes_bridge|bridge' | grep -v grep

判据：socket 不存在 + 没有 hermes_bridge.py 进程 → broker 没起来，继续往下。

3.2 看 WebUI 服务日志

# journalctl --user 在本机读不到条目时，直接看文件日志：
tail -60 /root/.hermes-web-ui/logs/server.log | grep -Ei 'bridge|bootstrap'
tail -40 /root/.hermes-web-ui/logs/bridge.log

典型实锤日志：

[agent-bridge] starting: /usr/bin/python3.11 .../hermes_bridge.py --endpoint ipc:///tmp/hermes-agent-bridge.sock --hermes-home /root/.hermes
[agent-bridge] exited code=1 signal=null
[bootstrap] agent bridge failed to start

随后 bridge.log 里全是重试：connect ENOENT /tmp/hermes-agent-bridge.sock。

3.3 手动跑同一条命令，拿 Python 侧 traceback

用测试 socket避免干扰，25 秒超时自动退出：

cd /usr/local/lib/node_modules/hermes-web-ui/dist/server/agent-bridge/python
timeout 25 /usr/bin/python3.11 hermes_bridge.py \
  --endpoint ipc:///tmp/bridge-test.sock --hermes-home /root/.hermes 2>&1 | head -40
rm -f /tmp/bridge-test.sock

真实报错：

RuntimeError: hermes-agent run_agent.py not found. Pass --agent-root or set HERMES_AGENT_ROOT.
Tried: /root/.hermes/hermes-agent, /root/.local, /root, ...

3.4 确认 run_agent.py 真实位置

python3.11 -c "import hermes_cli, os; print(os.path.dirname(hermes_cli.__file__))"
# → /root/.local/lib/python3.11/site-packages/hermes_cli
ls /root/.local/lib/python3.11/site-packages/run_agent.py   # 存在

4. 根因

bridge 的 _find_agent_root() 自动发现列表不包含 pip site-packages 路径（只找 ~/.hermes/hermes-agent、~/.local、各类 hermes-agent 源码目录）。

而 pip --user 安装的 Hermes Agent，run_agent.py 在：

/root/.local/lib/python3.11/site-packages/run_agent.py

发现失败 → broker 启动即 exit 1 → socket 永远不生成 → Node 端 ping 报 ENOENT → 前端显示 "Agent Bridge is not reachable"。

5. 修复方法

方法一（推荐）：systemd 单元里显式指定

编辑 /root/.config/systemd/user/hermes-web-ui.service，[Service] 段加两行：

Environment=HERMES_AGENT_ROOT=/root/.local/lib/python3.11/site-packages
Environment=HERMES_AGENT_BRIDGE_PYTHON=/usr/bin/python3.11

注意：HERMES_AGENT_ROOT 指向的是 run_agent.py 所在的目录（site-packages 本身），不是 hermes_cli 子目录。
如果你的 python3.11 是源码编译装的，路径是 /usr/local/bin/python3.11，以 command -v python3.11 为准。

只重启 WebUI（不要动 hermes-gateway）：

systemctl --user daemon-reload
systemctl --user restart hermes-web-ui.service

方法二：非 systemd 启动时临时指定

HERMES_AGENT_ROOT=/root/.local/lib/python3.11/site-packages \
HERMES_AGENT_BRIDGE_PYTHON=/usr/bin/python3.11 \
hermes-web-ui restart

6. 验证清单

ls -l /tmp/hermes-agent-bridge.sock
# srwxr-xr-x ... /tmp/hermes-agent-bridge.sock   ← socket 已生成

ps -eo pid,ppid,args | grep hermes_bridge | grep -v grep
# python3.11 .../hermes_bridge.py --endpoint ipc://... --agent-root /root/.local/lib/python3.11/site-packages ...

tail -20 /root/.hermes-web-ui/logs/server.log | grep agent-bridge
# [agent-bridge] ready at ipc:///tmp/hermes-agent-bridge.sock   ← 就绪标志

tail -5 /root/.hermes-web-ui/logs/bridge.log
# "request":{"action":"ping"} ... "response":{"ok":true}        ← ping 通了

全部通过后回 WebUI 刷新页面再发消息。

7. 关联坑位（同环境可能一起遇到）

坑 现象 处理
node-pty 缺 prebuild 日志 Failed to load native module: pty.node ... prebuilds/linux-x64 只影响 Web 终端，聊天不受影响；修复：重装时设 npm_config_python=$(command -v python3.11) 让它编译，或把 build/Release/pty.node 复制到 node_modules/node-pty/prebuilds/linux-x64/
WebUI 重启默认杀 bridge restart/update 默认停止 broker 想保留 bridge 会话：HERMES_AGENT_BRIDGE_STOP_ON_SHUTDOWN=0
journalctl –user 无输出 No journal files were found 本机用户日志不落 journal，看 /root/.hermes-web-ui/logs/{server,bridge}.log
想用 TCP 替代 IPC 多实例/容器隔离场景 HERMES_AGENT_BRIDGE_ENDPOINT=tcp://127.0.0.1:18765 + HERMES_AGENT_BRIDGE_WORKER_TRANSPORT=tcp

8. 关键路径速查

内容 路径
WebUI 服务单元 /root/.config/systemd/user/hermes-web-ui.service
WebUI 日志 /root/.hermes-web-ui/logs/server.log、logs/bridge.log
bridge 脚本 /usr/local/lib/node_modules/hermes-web-ui/dist/server/agent-bridge/python/hermes_bridge.py
run_agent.py /root/.local/lib/python3.11/site-packages/run_agent.py
broker socket /tmp/hermes-agent-bridge.sock
Hermes 数据目录 /root/.hermes

文档结束。有新增坑位会继续补进技能 hermes-studio-webui-operations～喵^w^

上一篇
下一篇