Hermes Agent + Hermes WebUI 部署以及卸载教程

# 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`

确保包含：
```yaml
messaging:
  telegram:
    enabled: true
```

### 1.4 启动 Gateway
在 Hermes Agent 项目目录执行：
```bash
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 克隆项目
```bash
cd /root/data/docker_data/hermes-agent
git clone https://github.com/nesquena/hermes-webui.git
cd hermes-webui
```

### 2.2 启动（监听公网）
```bash
./start.sh --host 0.0.0.0 8787 --no-browser
```

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

### 2.3 检查监听
```bash
ss -lntp | grep 8787
```

期望看到：
`0.0.0.0:8787`

### 2.4 本机验证
```bash
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 认证状态（清空）
```bash
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
应先看日志：
```bash
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 路径

命令：
```bash
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`

示例：
```ini
[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
```

启用：
```bash
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 相关进程

```bash
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：执行官方卸载

交互式：

```bash
hermes uninstall
```

不想手动确认：

```bash
hermes uninstall --yes
```

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

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

```bash
command -v hermes || true
```

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

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

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

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

---

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

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

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

### 全量备份示例

```bash
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 相关进程

```bash
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
```

### 再检查一次

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

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

---

## 3）执行 Hermes 官方全量卸载

交互式：

```bash
hermes uninstall --full
```

不想交互确认：

```bash
hermes uninstall --full --yes
```

说明：
- 这是 Hermes 官方的“全卸载”入口

---

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

```bash
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

你需要删除这一行：

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

### 自动删除方式

```bash
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

```bash
source ~/.zshrc
```

---

## 6）验证是否卸载干净

```bash
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 没有监听

---

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

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

```bash
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` 数据”

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

建议走：
- “彻底卸载”

---