Hermes WebUI 部署与运维标准手册 (v3.5)
本手册整合了多次部署复盘经验，旨在为 WSL2 环境下的 Hermes WebUI 提供一套从零开始的、物理级的清空与重建标准。
一、 部署环境参数基准
- 宿主机操作系统：Windows 11 (经由 WSL2 虚拟化运行 Ubuntu)
- 网络路由拓扑：Mirrored (镜像模式)
- 作用：强制 WSL 内核端口与 Windows 宿主机的 localhost 进行物理级映射，消除 NAT 转换障碍。
- 架构组成：
- 底层驱动：Hermes Agent (Nous Research 官方主线)
- 应用层组件：nesquena/hermes-webui (纯 Python 后端驱动)
二、 第一阶段：物理级全盘清算
在进行任何重建之前，必须彻底抹除旧环境的残留，以防止模型连接快照”劫持”新配置。
# 1. 强制释放 8787 端口并终止所有相关进程
fuser -k 8787/tcp
pkill -f hermes
# 2. 物理级删除代码目录及私有数据库缓存
rm -rf ~/hermes-webui
rm -rf ~/.hermes/webui
rm ~/.hermes/state.db
# 3. 清理旧的启动别名并刷新系统配置
sed -i '/alias run-web/d' ~/.bashrc
source ~/.bashrc三、 第二阶段：标准化环境重建
废弃官方 bootstrap.py 引导脚本，采用手动构建虚拟环境的方式，以确保依赖链的完整性。
# 1. 获取纯净前端源码
git clone https://github.com/nesquena/hermes-webui.git ~/hermes-webui
cd ~/hermes-webui
# 2. 构建隔离运行舱 (venv)
python3 -m venv venv
source venv/bin/activate
# 3. 强化安装核心依赖库
pip install --upgrade pip
pip install openai anthropic loguru python-dotenv requests websockets pyyaml fire fal_client firecrawl
# 4. 退出虚拟环境
deactivate四、 第三阶段：权限熔断与启动固化
通过环境变量注入法，解决 .env 文件读取不到的问题，并实现一键启动。
# 1. 写入凭证并实施权限熔断（禁止非属主用户访问）
echo "HERMES_WEBUI_PASSWORD=[WebUI密码] > .env
chmod 600 .env
# 2. 注入启动口令 (Alias) 到系统档案
# 注意：此步将密码直接锁死在启动流程中
echo 'alias run-web="export HERMES_WEBUI_PASSWORD=[WebUI密码] && cd ~/hermes-webui && source venv/bin/activate && python3 server.py"' >> ~/.bashrc
# 3. 立即激活设置
source ~/.bashrc五、 故障树分析与异常处置
| 报错现象 | 逻辑归因 | 终极对策 |
|---|---|---|
| No password set 警告 | 程序未能在当前目录下识别到 .env 文件。 | 确保使用整合版中的 alias 启动，通过 export 强制定义密码。 |
| ModuleNotFoundError | WebUI 虚拟环境缺少 Agent 运行所需的库（如 openai）。 | 进入 WebUI 目录激活 venv，重新执行本文档第三阶段的 pip install。 |
| Invalid editable requirement | 指向 Agent 的物理路径错误（通常漏掉了路径中的隐藏点 .）。 | 检查路径，确保指向 /home/用户名/.hermes/hermes-agent。 |
| 无法访问 localhost:8787 | 端口进程未驻留或 WSL2 镜像模式映射断链。 | 1. 核查终端是否有启动回显；2. 在 Windows PowerShell 执行 wsl —shutdown 后重启。 |
| timeout 15 或长时间转圈 | 外部 API 响应过慢或 WSL 网络阻塞。 | 点击停止按钮，引导 Agent 切换到 “Web Search” 模式手动提取信息。 |
六、 进阶运维与架构策略
1. 核心资产灾备判定
当触发硬件更换或系统重装时，需转移的核心资产仅限以下范围：
- /home/用户名/.hermes/ (全目录)：包含全部对话快照 (state.db)、技能树、用户画像及 API 密钥。
- /home/用户名/hermes-webui/.env：包含 WebUI 的验证口令。
- 注：除上述文件外，其余代码文件均建议通过 Git 重新克隆以保持纯净。
2. 技能触发的”唯一性”原则
为确保 Agent 运行精准，避免日常口语干扰：
- 避坑：不要使用”分析”、“查一下”等模糊词。
- 策略：采用 [动作动词] + [特定对象] 结构（例如：“进行财务分析”）。
3. 权限管理
更新代码或迁移目录后，若提示权限不足，请执行：
chown -R $(whoami):$(whoami) ~/.hermes