Hermes Web UI 部署踩坑实践

Apr 29, 2026

本文详细记录 Hermes Web UI v0.5.5 的完整部署过程，包括所有踩坑点和生产环境最佳实践。

📋 目录

1. 前置环境准备
2. 安装 Hermes Web UI
3. 核心配置
4. Systemd 服务配置（生产必备）
5. 启动与验证
6. 常见问题排障
7. 核心要点总结
8. 经验教训

---

前置环境准备

1.1 环境要求

组件	版本要求	本文环境
Node.js	>= 18.x	v24.15.0
Hermes Agent	>= 3.x	已安装
Hermes Gateway	已运行	端口 8642
操作系统	Linux/macOS	Debian 12

1.2 验证基础环境

# 验证 Node.js
node --version
npm --version

# 验证 Hermes CLI
which hermes
hermes --version

# 验证 Gateway 运行状态
hermes gateway status
curl http://127.0.0.1:8642/health

预期输出：

{"status": "ok", "platform": "hermes-agent"}

---

安装 Hermes Web UI

2.1 npm 全局安装

# 安装指定版本（推荐）
npm install -g hermes-web-ui@0.5.5

# 或安装最新版
npm install -g hermes-web-ui

# 验证安装
hermes-web-ui -v

安装路径：

• 全局包: ~/.nvm/versions/node/v24.15.0/lib/node_modules/hermes-web-ui/
• 可执行文件: ~/.nvm/versions/node/v24.15.0/bin/hermes-web-ui

2.2 目录结构说明

hermes-web-ui/
├── bin/              # CLI 入口
├── dist/
│   ├── client/       # 前端静态文件 (Vue 3)
│   ├── server/       # BFF 后端 (Koa)
│   └── data/         # 数据目录
├── node_modules/     # 依赖
├── package.json
├── LICENSE
└── README.md

---

核心配置

3.1 config.yaml 配置（最关键）

⚠️ 90% 的部署失败都是因为缺少这个配置！

编辑 ~/.hermes/config.yaml，添加 api_server 配置块：

# ~/.hermes/config.yaml

# ... 其他已有配置 ...

# ============================================
# Hermes Web UI 必需的 API 服务器配置
# ============================================
api_server:
  enabled: true            # 必须启用
  port: 8642              # 与 Gateway 端口一致
  bind_host: 127.0.0.1    # 建议绑定本地回环
  key: "123456"           # API 密钥，自定义

# ... 其他已有配置 ...

3.2 .env 配置

编辑 ~/.hermes/.env，确保 API 密钥一致：

# ~/.hermes/.env

# API 服务器密钥（必须与 config.yaml 中 api_server.key 一致）
API_SERVER_KEY=123456

# ... 其他配置 ...

3.3 配置原理

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   浏览器 :8648  │────▶│  BFF 服务 :8648 │────▶│ Gateway :8642   │
│                 │     │  (hermes-web-ui)│     │  (Hermes Agent) │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                               │                         │
                        API 密钥认证               API 密钥认证

关键：两边的 API 密钥必须完全一致，否则会出现 401 认证失败。

---

Systemd 服务配置（生产必备）

4.1 为什么需要 Systemd？

使用 hermes-web-ui start 启动的问题：

• ❌ 后台进程不稳定，可能意外退出
• ❌ 服务器重启后不会自动启动
• ❌ 没有崩溃自动重启机制
• ✅ 使用 Systemd 解决所有问题

4.2 创建 Systemd 服务文件

创建 ~/.config/systemd/user/hermes-web-ui.service：

[Unit]
Description=Hermes Web UI - Web Dashboard for Hermes Agent
After=network.target hermes-gateway.service
StartLimitIntervalSec=600
StartLimitBurst=5

[Service]
Type=simple
ExecStart=/root/.nvm/versions/node/v24.15.0/bin/node /root/.nvm/versions/node/v24.15.0/lib/node_modules/hermes-web-ui/dist/server/index.js
WorkingDirectory=/root/.hermes-web-ui
Environment="PATH=/root/.nvm/versions/node/v24.15.0/bin:/root/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
Environment="HERMES_HOME=/root/.hermes"
Environment="NODE_ENV=production"
Restart=on-failure
RestartSec=10
KillMode=mixed
KillSignal=SIGTERM
TimeoutStopSec=30
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target

重要说明：

1. ExecStart 路径需要根据实际 Node.js 安装位置调整
2. After=hermes-gateway.service 确保 Gateway 先启动
3. Restart=on-failure 崩溃后 10 秒自动重启
4. 使用用户级 systemd，不需要 root 权限

4.3 启用并启动服务

# 重新加载 systemd 配置
systemctl --user daemon-reload

# 启用开机自启并立即启动
systemctl --user enable --now hermes-web-ui.service

# 验证运行状态
systemctl --user status hermes-web-ui.service

4.4 常用管理命令

# 查看状态
systemctl --user status hermes-web-ui

# 查看日志
journalctl --user -u hermes-web-ui -f

# 重启服务
systemctl --user restart hermes-web-ui

# 停止服务
systemctl --user stop hermes-web-ui

# 禁用自启
systemctl --user disable hermes-web-ui

---

启动与验证

5.1 服务启动后自动执行的流程

Web UI 启动时会自动完成以下初始化：

1. ✅ Gateway Manager 初始化
2. ✅ 数据存储初始化 (SQLite)
3. ✅ Hermes 会话自动同步（从 ~/.hermes/state.db）
4. ✅ CORS + 路由注册
5. ✅ 认证 Token 自动生成
6. ✅ Terminal WebSocket 建立
7. ✅ Session 清理任务启动

5.2 验证运行状态

# 检查进程
ps aux | grep hermes-web-ui

# 检查端口监听
netstat -tlnp | grep 8648

# 测试页面访问
curl -s http://127.0.0.1:8648/ | head -10

5.3 获取访问 Token

# 方法 1：从日志获取
journalctl --user -u hermes-web-ui | grep "Auth enabled"

# 方法 2：从 token 文件获取
cat ~/.hermes-web-ui/.token

5.4 访问 Web UI

# 本地访问
http://localhost:8648/#/?token=你的token

# 局域网访问（替换为实际 IP）
http://192.168.1.100:8648/#/?token=你的token

---

常见问题排障

6.1 端口占用 (EADDRINUSE)

# 查找占用进程
lsof -i :8648

# 杀掉旧进程
kill -9 <PID>

# 重启服务
systemctl --user restart hermes-web-ui

6.2 401 Unauthorized

原因： API 密钥不匹配

解决： 检查两处配置是否完全一致：

# config.yaml 中的 key
grep -A5 "api_server:" ~/.hermes/config.yaml

# .env 中的 key
grep "API_SERVER_KEY" ~/.hermes/.env

6.3 spawn hermes ENOENT

原因： Node.js 进程的 PATH 中找不到 hermes 命令

解决： 在 systemd service 中正确设置 PATH 环境变量

Environment="PATH=/root/.nvm/versions/node/v24.15.0/bin:/root/.local/bin:..."

6.4 Gateway 连接失败 (ECONNRESET)

原因： Gateway 重启或未启动

解决：

# 确保 Gateway 运行
hermes gateway start

# 重启 Web UI
systemctl --user restart hermes-web-ui

---

核心要点总结

✅ 必做检查清单

1. ✅ 配置 api_server 块 - 这是最容易漏掉的步骤
2. ✅ API 密钥一致 - config.yaml 和 .env 必须相同
3. ✅ 先启动 Gateway - Web UI 依赖 Gateway 的 8642 端口
4. ✅ 配置 Systemd 服务 - 生产环境必备，确保稳定性
5. ✅ 启用 linger - 确保用户退出后服务仍运行

# 启用用户级服务 linger（服务器重启后自动启动）
loginctl enable-linger $USER

📊 最终部署架构

服务器开机
    ↓
systemd 用户管理器启动
    ↓
├─ hermes-gateway.service (端口 8642)
└─ hermes-web-ui.service (端口 8648)
    ↓
浏览器访问 → BFF 代理 → Hermes Gateway → AI 模型

📁 重要文件位置

文件	路径	说明
主配置	~/.hermes/config.yaml	含 api_server 配置
环境变量	~/.hermes/.env	含 API_SERVER_KEY
Systemd 服务	~/.config/systemd/user/hermes-web-ui.service	服务配置
数据目录	~/.hermes-web-ui/	SQLite DB、日志、Token
安装目录	~/.nvm/versions/node/v24.15.0/lib/node_modules/hermes-web-ui/	npm 包

---

经验教训

🔴 教训 1：不要忽视配置文档

• 问题： 很多人直接安装后启动，没有配置 api_server
• 结果： Web UI 看起来启动了，但所有功能都无法使用
• 解决： 仔细阅读 README，确保所有必需配置都已完成

🟠 教训 2：生产环境必须用进程管理器

• 问题： hermes-web-ui start 启动的后台进程不稳定
• 结果： 进程意外退出后服务不可用
• 解决： 配置 Systemd 服务，自动重启 + 开机自启

🟡 教训 3：依赖顺序很重要

• 问题： Web UI 启动时 Gateway 还没准备好
• 结果： 连接失败、会话同步异常
• 解决： Systemd 中配置 After=hermes-gateway.service

🟢 教训 4：端口冲突要主动处理

• 问题： 重复启动导致端口被旧进程占用
• 结果： 新进程启动失败
• 解决： 配置 Systemd 前先停止旧进程：hermes-web-ui stop

🔵 教训 5：环境变量是隐形坑

• 问题： Systemd 运行环境与交互式 Shell 环境不同
• 结果： spawn hermes ENOENT 找不到命令
• 解决： 在 Service 文件中显式设置完整的 PATH

---

完整命令速查

# ===== 安装 =====
npm install -g hermes-web-ui@0.5.5

# ===== 配置 =====
# 编辑 config.yaml 添加 api_server
# 编辑 .env 设置 API_SERVER_KEY

# ===== Systemd 服务 =====
vim ~/.config/systemd/user/hermes-web-ui.service
systemctl --user daemon-reload
systemctl --user enable --now hermes-web-ui
systemctl --user status hermes-web-ui
journalctl --user -u hermes-web-ui -f

# ===== 日常管理 =====
hermes-web-ui -v
hermes-web-ui status
hermes-web-ui stop    # 如果用了 systemd 就不用这个
hermes-web-ui update  # 更新版本

# ===== 验证 =====
curl http://127.0.0.1:8642/health
curl http://127.0.0.1:8648/
cat ~/.hermes-web-ui/.token

---

🎉 成功标志

看到以下输出，说明部署完全成功：

● hermes-web-ui.service - Hermes Web UI - Web Dashboard for Hermes Agent
     Loaded: loaded (...; enabled; vendor preset: enabled)
     Active: active (running)

以及：

• 浏览器可以正常打开 Web UI 界面
• 可以看到历史会话列表
• 可以创建新会话并正常对话
• 所有菜单项（平台配置、技能管理等）功能正常

---

部署完成！ Hermes Web UI 现已生产可用，享受你的 AI 助手吧！🚀