Hermes WebUI 部署指南

给你的 Hermes Agent 装上一个漂亮的 Web 界面，支持浏览器和手机访问。跟 CLI 功能基本对等。不需要额外模型，直接用你现有的 Hermes 配置。

---

一、hermes-webui 文件下载

项目地址：https://github.com/nesquena/hermes-webui

# 有外网
git clone https://github.com/nesquena/hermes-webui.git

# 没外网——先在有网的机器上下载 zip，再传到服务器
# 下载链接：https://codeload.github.com/nesquena/hermes-webui/zip/refs/heads/master
unzip hermes-webui-master.zip
cd hermes-webui-master

二、hermes-webui 安装

依赖极轻——核心只需 PyYAML。WebUI 会自动复用 Hermes Agent 的 venv。

# 方法一：用 Hermes 自带的 venv（推荐）
source ~/hermes-agent/hermes-agent/venv/bin/activate
pip install pyyaml

# 方法二：如果系统没有 pip，用 Hermes venv 里的 pip
~/hermes-agent/hermes-agent/venv/bin/pip install pyyaml

# 方法三：如果没有 Hermes venv，用系统包管理器
# sudo apt install python3-yaml python3-pip

项目结构：

hermes-webui/
├── server.py          # 入口
├── bootstrap.py       # 启动引导
├── ctl.sh             # 进程管理脚本（项目自带，不用改）
├── start.sh           # 快速启动
├── api/               # 后端 API
├── static/            # 前端页面
├── requirements.txt   # pyyaml
└── .env.example       # 环境变量模板

三、启动hermes-webui

1. 后台守护进程（推荐）

HERMES_WEBUI_AGENT_DIR=~/hermes-agent/hermes-agent ./ctl.sh start

验证：

./ctl.sh status

输出示例：

● hermes-webui — running
  PID:     961538
  Uptime:  00:15
  Bound:   0.0.0.0:8787
  Log:     /home/peturn/.hermes/webui.log
  Health:  ok (0 sessions, 0 active streams)

管理命令：

命令	作用
./ctl.sh start	启动
./ctl.sh stop	停止
./ctl.sh restart	重启
./ctl.sh status	状态
./ctl.sh logs	查看日志

2. 设置界面为中文字体

• 登录后：点击左下角齿轮图标进入设置 –》 找到 Language / 语言 –》 选择 简体中文 –》拉到最下面，点击保存设置按钮。
• 也可以在登录页先选好语言再登录。

3. 配置局域网可访问

WebUI 默认只绑定 127.0.0.1（仅本机）。要让局域网内其他设备也能访问：

1. 创建 .env 文件

项目目录下创建 .env，ctl.sh 和 start.sh 启动时自动加载这个文件，不需要改任何脚本。

cat > .env << 'EOF'
HERMES_WEBUI_HOST=0.0.0.0
HERMES_WEBUI_AGENT_DIR=/home/peturn/hermes-agent/hermes-agent
HERMES_WEBUI_PASSWORD=你的密码
EOF

变量	说明	默认值
HERMES_WEBUI_HOST	0.0.0.0 = 所有网卡	127.0.0.1
HERMES_WEBUI_PORT	端口	8787
HERMES_WEBUI_AGENT_DIR	Hermes Agent 路径	自动发现
HERMES_WEBUI_PASSWORD	登录密码（必设！）	无

2. 处理 Docker 网络干扰（关键！）

服务器有 Docker 时，多出的 docker0 网卡会导致外部连接"响应超时"——数据包能到 8787，回复却走了 docker0 路由回不去。

sudo iptables -I INPUT -p tcp --dport 8787 -j ACCEPT

重启后失效。持久化方案：

sudo apt install iptables-persistent
sudo iptables-save > /etc/iptables/rules.v4

3. 重启

./ctl.sh restart

4. 验证

# 本机
curl http://127.0.0.1:8787/health

# 另一台机器（把IP换成你服务器的实际IP）
curl http://192.168.1.104:8787/health

5. 访问

浏览器打开 http://<服务器IP>:8787，输入密码。

安全：绑定 0.0.0.0 不设密码 = 局域网任何人都能操控你的 Agent。务必设密码。

---

四、常见问题

1. 启动显示 agent dir NOT FOUND？
   → 设 HERMES_WEBUI_AGENT_DIR 指向包含 run_agent.py 的目录。
2. 局域网访问"响应时间过长"？
   → 检查是否有 Docker 网卡，加 iptables 放行规则。
3. 改密码？
   → 改 .env 里的 HERMES_WEBUI_PASSWORD 重启，或登录后在 Settings 页面改。
4. 系统没有 pip？
   → 用 Hermes venv 里的 ~/hermes-agent/hermes-agent/venv/bin/pip，或用系统包管理器安装 python3-pip。