markdown

Hermes Agent + Hermes WebUI 部署记录（本机路径版）

部署目录：
/root/data/docker_data/hermes-agent

WebUI目录：
/root/data/docker_data/hermes-agent/hermes-webui

1. Hermes Agent（Telegram）对接

1.1 准备 Bot Token

  • 在 Telegram 里联系 @BotFather
  • 创建 bot：/newbot
  • 获取 token（注意保密，不要在聊天中明文发送）

1.2 配置环境变量

编辑：
~/.hermes/.env

添加：
TELEGRAM_BOT_TOKEN=你的新token

1.3 启用 Telegram 平台

编辑：
~/.hermes/config.yaml

确保包含：

messaging:
  telegram:
    enabled: true

1.4 启动 Gateway

在 Hermes Agent 项目目录执行：

source venv/bin/activate
python -m gateway.run

说明：

  • gateway.run 是前台阻塞进程
  • 可用后台方式运行（如 systemd/nohup/tmux）

1.5 验证连通

  • 在 Telegram 打开 bot，先 /start
  • 发送任意消息
  • 服务端日志应看到对应 chat_id 的消息事件

2. Hermes WebUI 部署

2.1 克隆项目

cd /root/data/docker_data/hermes-agent
git clone https://github.com/nesquena/hermes-webui.git
cd hermes-webui

2.2 启动（监听公网）

./start.sh --host 0.0.0.0 8787 --no-browser

参数说明：

  • --host 0.0.0.0：允许外部访问
  • 8787：端口
  • --no-browser：服务器环境不自动拉起浏览器

2.3 检查监听

ss -lntp | grep 8787

期望看到：
0.0.0.0:8787

2.4 本机验证

curl -I http://127.0.0.1:8787

2.5 公网访问

浏览器访问：
http://<公网IP>:8787

如果不通，检查：

  1. 系统防火墙（ufw/firewalld）
  2. 云安全组（入站 TCP/8787）
  3. 服务是否实际监听 0.0.0.0

3. 认证密码说明（重要）

现象：重装 webui 后仍要求旧密码，且旧密码可登录。
原因：认证状态保存在 ~/.hermes 持久化目录，不在代码目录里。

3.1 重置 WebUI 认证状态（清空）

pkill -f 'hermes-webui/server.py' || true
rm -rf /root/.hermes/webui
cd /root/data/docker_data/hermes-agent/hermes-webui
./start.sh --host 0.0.0.0 8787 --no-browser

4. 常见问题与排查

4.1 报错：Internal server error

应先看日志：

tail -f /root/.hermes/webui/bootstrap-8787.log

4.2 曾出现错误：找不到静态首页

典型错误：
FileNotFoundError: /root/hermes-webui/static/index.html

含义：

  • 进程读取了旧路径 /root/hermes-webui
  • 但实际部署目录是 /root/data/docker_data/hermes-agent/hermes-webui
  • 路径不一致会导致 500

处理：

  • 停掉全部旧进程
  • 只从正确目录启动
  • 用 ps -ef 确认 server.py 路径

命令：

pkill -f 'hermes-webui/server.py' || true
pkill -f 'bootstrap.py' || true
cd /root/data/docker_data/hermes-agent/hermes-webui
./start.sh --host 0.0.0.0 8787 --no-browser
ps -ef | grep -i 'hermes-webui/server.py' | grep -v grep

5. 建议的长期运行方式（systemd）

创建服务文件：
/etc/systemd/system/hermes-webui.service

示例：

[Unit]
Description=Hermes WebUI
After=network.target

[Service]
Type=simple
WorkingDirectory=/root/data/docker_data/hermes-agent/hermes-webui
ExecStart=/root/data/docker_data/hermes-agent/hermes-webui/start.sh --host 0.0.0.0 8787 --no-browser
Restart=always
RestartSec=2
User=root
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=multi-user.target

启用：

systemctl daemon-reload
systemctl enable --now hermes-webui
systemctl status hermes-webui --no-pager -l

6. 安全建议

不建议长期直接暴露 :8787 到公网。
建议：

  1. Nginx 反向代理到 127.0.0.1:8787
  2. 配置 HTTPS（Let’s Encrypt）
  3. 增加 Basic Auth / IP 白名单 / Cloudflare Tunnel

7. 本次部署关键路径汇总

  • Hermes 工作目录：/root/data/docker_data/hermes-agent
  • WebUI 目录：/root/data/docker_data/hermes-agent/hermes-webui
  • WebUI 日志：/root/.hermes/webui/bootstrap-8787.log
  • Hermes 配置：~/.hermes/config.yaml
  • Hermes 环境变量：~/.hermes/.env

Hermes 卸载教程（按当前这台机器实际情况整理）

当前机器上的 Hermes 相关路径

  • Hermes 主命令：
    • /root/.local/bin/hermes
  • Hermes 数据目录：
    • /root/.hermes
  • WebUI 项目目录：
    • /root/data/docker_data/hermes-agent/hermes-webui
  • 自定义启动脚本：
    • /root/.local/bin/hermes-webui-start
  • ~/.zshrc 中新增过的 alias：
    • alias hermes-webui-start="/root/.local/bin/hermes-webui-start"

当前已确认状态

  • 当前 8787 端口上还有 WebUI 在运行
  • 当前没有 cron 定时任务
  • 当前 profile 只有 default

一、只卸载 Hermes 程序，保留配置和数据

适合：

  • 以后可能还会重装
  • 想保留历史会话、配置、API key、skills、memory

步骤 1：先停掉 WebUI / Hermes 相关进程

pkill -f '/root/data/docker_data/hermes-agent/hermes-webui/server.py' || true
pkill -f '/root/.local/bin/hermes chat' || true
pkill -f 'bootstrap.py' || true

步骤 2：执行官方卸载

交互式：

hermes uninstall

不想手动确认：

hermes uninstall --yes

说明：

  • 这一步通常会卸载 Hermes 程序本体
  • 尽量保留 ~/.hermes 数据，便于以后恢复

步骤 3：检查命令是否还存在

command -v hermes || true

如果没有输出，说明主命令已卸掉。

步骤 4：确认数据是否仍保留

du -sh /root/.hermes 2>/dev/null || true

如果还有输出，说明你的配置/历史大概率还在。

二、彻底卸载 Hermes（推荐保存这一版）

适合：

  • 以后不打算继续用
  • 想把程序、配置、会话、memory、skills、WebUI、启动脚本都删干净

1）先备份重要内容（强烈推荐）

全量备份示例

mkdir -p /root/hermes-backup
cp -a /root/.hermes /root/hermes-backup/.hermes.backup
cp -a /root/data/docker_data/hermes-agent/hermes-webui /root/hermes-backup/hermes-webui.backup 2>/dev/null || true
cp -a /root/.zshrc /root/hermes-backup/.zshrc.backup

如果只备份最关键内容，至少备份这些

  • /root/.hermes/config.yaml
  • /root/.hermes/.env
  • /root/.hermes/auth.json
  • /root/.hermes/memories/
  • /root/.hermes/skills/
  • /root/.hermes/sessions/

2）停掉所有 Hermes / WebUI 相关进程

pkill -f '/root/data/docker_data/hermes-agent/hermes-webui/server.py' || true
pkill -f '/root/.local/bin/hermes chat' || true
pkill -f 'bootstrap.py' || true
pkill -f '/root/.local/bin/hermes' || true

再检查一次

ps -ef | grep -Ei 'hermes|bootstrap.py|server.py' | grep -v grep || true
ss -ltnp | grep 8787 || true

如果没有输出，说明相关进程已经停掉。

3）执行 Hermes 官方全量卸载

交互式：

hermes uninstall --full

不想交互确认：

hermes uninstall --full --yes

说明：

  • 这是 Hermes 官方的“全卸载”入口

4）手动删除这台机器上的残留文件

rm -rf /root/.hermes
rm -f /root/.local/bin/hermes
rm -f /root/.local/bin/hermes-webui-start
rm -rf /root/data/docker_data/hermes-agent/hermes-webui

说明

  • /root/.hermes
    • Hermes 配置、日志、会话、memory、skills、认证信息
  • /root/.local/bin/hermes
    • Hermes 命令入口
  • /root/.local/bin/hermes-webui-start
    • 自定义固定启动脚本
  • /root/data/docker_data/hermes-agent/hermes-webui
    • WebUI 项目目录

5）清理 ~/.zshrc 里的启动 alias

你需要删除这一行：

alias hermes-webui-start="/root/.local/bin/hermes-webui-start"

自动删除方式

python3 - <<'PY'
from pathlib import Path
p = Path('/root/.zshrc')
text = p.read_text() if p.exists() else ''
line = 'alias hermes-webui-start="/root/.local/bin/hermes-webui-start"'
new = '\n'.join([x for x in text.splitlines() if x.strip() != line]) + '\n'
p.write_text(new)
PY

刷新 shell

source ~/.zshrc

6）验证是否卸载干净

command -v hermes || true
test -e /root/.hermes && echo EXISTS || echo REMOVED
test -e /root/.local/bin/hermes && echo EXISTS || echo REMOVED
test -e /root/.local/bin/hermes-webui-start && echo EXISTS || echo REMOVED
test -e /root/data/docker_data/hermes-agent/hermes-webui && echo EXISTS || echo REMOVED
ss -ltnp | grep 8787 || true

理想结果

  • command -v hermes 没输出
  • /root/.hermes => REMOVED
  • /root/.local/bin/hermes => REMOVED
  • /root/.local/bin/hermes-webui-start => REMOVED
  • /root/data/docker_data/hermes-agent/hermes-webui => REMOVED
  • 8787 没有监听

三、最短“彻底卸载版”命令清单

如果以后只想看最短版，保存下面这段即可：

pkill -f '/root/data/docker_data/hermes-agent/hermes-webui/server.py' || true
pkill -f '/root/.local/bin/hermes chat' || true
pkill -f 'bootstrap.py' || true
pkill -f '/root/.local/bin/hermes' || true

hermes uninstall --full --yes || true

rm -rf /root/.hermes
rm -f /root/.local/bin/hermes
rm -f /root/.local/bin/hermes-webui-start
rm -rf /root/data/docker_data/hermes-agent/hermes-webui

python3 - <<'PY'
from pathlib import Path
p = Path('/root/.zshrc')
if p.exists():
    line = 'alias hermes-webui-start="/root/.local/bin/hermes-webui-start"'
    text = p.read_text()
    new = '\n'.join([x for x in text.splitlines() if x.strip() != line]).strip()
    p.write_text((new + '\n') if new else '')
PY

source ~/.zshrc 2>/dev/null || true

四、哪些东西一删就基本不可恢复

彻底卸载前请特别注意这些：

  • /root/.hermes/.env
    • 里面可能有 API key
  • /root/.hermes/auth.json
    • 里面可能有登录授权
  • /root/.hermes/sessions/
    • 历史会话
  • /root/.hermes/memories/
    • 持久记忆
  • /root/.hermes/skills/
    • 积累的 skills
  • /root/data/docker_data/hermes-agent/hermes-webui
    • WebUI 项目代码和本地改动

如果这些以后还有价值，先备份再删。

五、如果以后又想装回来

最简单通常是：

  • 重新执行官方安装脚本
  • 或恢复之前备份的目录

如果保留了 /root/.hermes 备份，很多配置都能直接恢复。

六、建议

如果只是暂时不用

建议走：

  • “只卸载程序，保留 ~/.hermes 数据”

如果是确定不用，而且想清干净

建议走：

  • “彻底卸载”