hermes - 💡(How to fix) Fix Hermes Web UI 修复经验：GatewayManager 补丁、进程 D 状态、数据库升级问题

Hermes Web UI 修复经验总结

综合多个问题的诊断、修复过程和最终方案

环境

• WSL2 Ubuntu + Windows
• Hermes Agent v0.14.0
• hermes-web-ui v0.6.0（从 v0.5.33 升级）
• Node.js v26.1.0
• systemd 管理

---

问题 1：进程卡 D 状态 / 端口不监听 / systemd 循环重启

现象：Web UI 和网关进程在 WSL 中进入 D 状态（不可中断睡眠），端口停止监听，systemd Restart=always 不断拉起新进程，形成死循环。

根因：三个因素叠加：

1. WSL2 通过 9P 协议访问 /mnt/d/（Windows 挂载点）文件系统时，进程容易卡 D 状态
2. systemd Restart=always 导致进程被 SIGTERM 后立即拉起，新旧进程冲突
3. Web UI 启动时自动调用 gatewayManager.startAll() 刷新网关进程（对应 GitHub Issue #27041）

解决：

1. 将 Web UI 从 Windows npm 路径（/mnt/d/Software/nodejs/...）复制到 WSL 本地文件系统（/opt/hermes-web-ui）
2. 禁用 systemd 服务（systemctl disable hermes-webui.service）
3. 用 tmux 管理进程生命周期
4. 启动时设置 HERMES_WEB_UI_MANAGED_GATEWAY=false 防止 Web UI 自动管理网关

---

问题 2：登录 400 — hasUsers: false

现象：POST /api/auth/login 返回 400 Bad Request，GET /api/auth/status 显示 hasUsers: false。

根因：Web UI 从 v0.5.33 升级到 v0.6.0 后新增用户认证系统，需要 users 表。但旧 SQLite 数据库没有该表，启动时的 iC() 初始化函数（Ol(Ql,KWI)）未能正确创建。

解决：手动创建表并插入管理员： `javascript const { DatabaseSync } = require('node:sqlite'); const { scryptSync, randomBytes } = require('node:crypto'); const db = new DatabaseSync('/root/.hermes-web-ui/hermes-web-ui.db');

db.exec('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, username TEXT NOT NULL UNIQUE, password_hash TEXT NOT NULL, role TEXT NOT NULL DEFAULT '+"'admin'"+', status TEXT NOT NULL DEFAULT '+"'active'"+', created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, last_login_at INTEGER)');

const salt = randomBytes(16).toString('hex'); const key = scryptSync('123456', salt, 64).toString('hex'); const pw = 'scrypt:' + salt + ':' + key; db.prepare("INSERT INTO users (username, password_hash, role, status, created_at, updated_at) VALUES ('admin', ?, 'super_admin', 'active', ?, ?)").run(pw, Date.now(), Date.now()); `

---

问题 3：Chat 报 "GatewayManager not initialized"

现象：登录成功，但发消息后报 Error: {"error":{"message":"GatewayManager not initialized"}}。

根因：v0.6.0 编译后的 dist 文件中 QpI 变量始终为 ull，从未被实例化。 V() 代理函数调用 wpI() 时 GB() 返回 null 抛出异常。

解决：在 dist 文件中直接替换： ash sed -i 's|var QpI=null;function GB(){return QpI}|var QpI={getUpstream:function(){return "http://127.0.0.1:8642"},getApiKey:function(){return "hermes123"}};function GB(){return QpI}|' dist/server/index.js

这是目前最简单的绕过方案。等待官方修复。

---

问题 4：AI 调用返回 "Invalid API key"

现象：网关代理 AI 请求时返回 Invalid API key。

根因：.env 文件损坏，API Key 丢失/变成乱码。同时 GATEWAY_ALLOW_ALL_USERS=true 缺失导致网关拒绝所有请求。

解决：从 uth.json 的 credential_pool 或 state-snapshots/ 历史备份中恢复 Key。

---

问题 5：Web UI 后台进程被 WSL 杀死

现象：无论用 ohup、&、setsid、disown，进程在父 shell 退出后都被杀死。

解决：用 tmux 管理： ash tmux new-session -d -s hermes 'node dist/server/index.js'

---

问题 6：飞书平台自动连接导致网关卡死

飞书（Feishu）凭证在 .env 中导致网关自动连接飞书 WebSocket，心跳/重连机制可能触发 D 状态。移除 FEISHU_APP_ID 和 FEISHU_APP_SECRET 后解决。 对应修复 PR：https://github.com/NousResearch/hermes-agent/pull/31665

---

已知上游 Bug

---

一键修复

完整的 PowerShell 修复脚本（包含所有修复步骤和自动启动）见附件或评论区。