Hermes 部署全记录

结论先行

在国内服务器部署 Hermes Agent（Nous Research 的开源 AI Agent 框架），最大的门槛不是 Python 依赖、不是配置项有多复杂，而是 GitHub 根本连不上。git clone 会在 60% 进度时被 GFW 中断，curl tarball 下到一半被 reset，连 hermes update 内置命令也因为 repo 过大直接超时。

最终花了一整天时间，绕过了五六个坑，才把 Hermes 跑起来并顺利打开 WebUI。这篇把踩过的坑和修复方法都记下来，希望对同样在国内服务器上折腾的朋友有帮助。

背景

我之前在本地 Windows 上跑 Hermes 用得挺好，但想把它部署到云服务器上 7×24 运行。七牛云一台 Linux 服务器，系统 Ubuntu，准备在上面安装 Hermes。

目标很明确：服务器端运行 Hermes Agent，本地浏览器通过 WebUI 远程管理。

第一阶段：GitHub 被墙，下载寸步难行

❌ 踩坑 1：hermes update 超时

服务器上已经有旧版 Hermes，执行 hermes update：

hermes update
# ...
# The update command timed out (known issue with large repos)

Hermes 内置的更新命令因为仓库过大（~60MB）被网络掐断。它尝试 fallback 到 git fetch --depth=1，同样失败。

❌ 踩坑 2：直接 git clone 中途断开

git clone --depth=1 https://github.com/NousResearch/hermes-agent.git
# remote: Enumerating objects: 6977, done.
# error: RPC failed; curl 92 HTTP/2 stream cancelled
# fatal: early EOF

HTTP/2 流被重置，经典 GFW 行为。

❌ 踩坑 3：curl tarball 也被中断

curl -L -o hermes.tar.gz https://ghproxy.net/.../main.tar.gz
# 下载到 4.6MB 后 HTTP/2 INTERNAL_ERROR

ghproxy.net 这个镜像本身连接也不稳定。

✅ 正解：wget + gh-proxy.com（带杠的）

wget -O /tmp/hermes-agent.tar.gz \
  --tries=10 --timeout=30 \
  https://gh-proxy.com/https://github.com/NousResearch/hermes-agent/archive/refs/heads/main.tar.gz

两个关键点：

• 用 gh-proxy.com 而不是 ghproxy.net（前者更稳定）
• 用 wget 而不是 curl（wget 的重试机制更可靠）

61MB 的 tarball，5 秒下完，速度 12MB/s。

第二阶段：手动安装的依赖问题

✅ 解压到 FHS 目录

mkdir -p /usr/local/lib/hermes-agent
tar xzf /tmp/hermes-agent.tar.gz \
  -C /usr/local/lib/hermes-agent --strip-components=1

⚠️ 踩坑 4：uv 的 --system 安装被拒

Hermes 安装脚本会用 uv 管理 Python 环境。直接 uv pip install --system -e . 报错：

error: The interpreter at ... is externally managed

正解：创建虚拟环境

cd /usr/local/lib/hermes-agent
uv venv --python 3.11
source .venv/bin/activate
uv pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

注意加 -i https://pypi.tuna.tsinghua.edu.cn/simple 用清华 PyPI 镜像，否则 pip 下载依赖也会被墙堵住。

第三阶段：Dashboard 登录页 Internal Server Error

配置用户名密码登录后，打开浏览器访问，直接白屏 + Internal Server Error。

错误日志定位到：

NotImplementedError: BasicAuthProvider is password-only;
there is no OAuth redirect flow.
The login page POSTs to /auth/password-login instead.

🔍 根因

Hermes main 分支的 routes.py 中，/auth/login 路由统一调用 p.start_login()——这是为 OAuth 提供商（GitHub/Google）设计的重定向方法。但用户名密码认证（BasicAuthProvider）不走 OAuth，它直接在 /auth/password-login 页面提交表单。BasicAuthProvider 的 start_login() 方法写死了 raise NotImplementedError。

路由代码没有提前区分 provider 类型，一刀切调了错误的方法。

✅ 修复：加一个类型判断

在 hermes_cli/dashboard_auth/routes.py 第197行前插入：

if type(p).__name__ == 'BasicAuthProvider':
    return RedirectResponse(url='/auth/password-login', status_code=302)

这个判断很简单——检测到是 BasicAuthProvider 时，直接重定向到密码登录页，不调用 OAuth 方法。

第四阶段：外网访问——SSH 隧道方案

⚠️ 踩坑 5：安全组/SELinux 全关，还是连不上

服务器上 iptables 策略是 ACCEPT，ufw inactive，端口监听在 0.0.0.0:9119，本地 curl 127.0.0.1:9119 正常返回，但外网就是打不开。

查了一圈发现七牛云的外层安全组没有放行 9119 端口。但更关键的是——SSH 端口不是默认的 22，云厂商封了 22 但开放了一个自定义端口。

✅ 最终方案：SSH 隧道转发

# 在本地 Windows 上执行
ssh -N -L 9119:127.0.0.1:9119 -p 10315 root@服务器IP

浏览器访问 http://127.0.0.1:9119 即可——像访问本地服务一样访问远程 Hermes Dashboard。

为了方便，写了个 bat 批处理放桌面，每次双击就能建隧道。 加了 -o ServerAliveInterval=30 心跳保活，关掉浏览器也不会断连。

第五阶段：配置凭证池

把本地的 API provider 加到服务器的凭证池中：

python3 -c "
import yaml
cfg = yaml.safe_load(open('/root/.hermes/config.yaml'))
cfg.setdefault('custom_providers', []).append({
    'name': 'qnaigc',
    'base_url': 'https://api.qnaigc.com/v1',
    'key_env': 'QNAIGC_API_KEY',
    'model': 'deepseek/deepseek-v4-flash',
})
yaml.dump(cfg, open('/root/.hermes/config.yaml', 'w'),
          default_flow_style=False, allow_unicode=True)
"

然后设为默认模型，重启生效。

踩坑汇总

总结

Hermes Agent 本身是一个优秀的 AI Agent 框架，在国内服务器部署它的真正挑战不在软件配置，而在网络环境。从代码下载、依赖安装到 WebUI 访问，每一层都跟网络较劲。

几个经验：

1. 国内下载 GitHub 代码：优先用 gh-proxy.com 做镜像代理，用 wget 而不是 curl
2. Python 依赖：清华 PyPI 镜像比任何代理都可靠
3. FHS 安装：uv venv + source .venv/bin/activate 比 --system 稳定
4. 外网访问：SSH 隧道比暴露端口安全且可靠
5. 遇到 NotImplementedError：先看是不是 main 分支的代码不完善，这类 Bug 通常很快修复

最后，在目前中国 AI 全球发展背景下，能跑在自家服务器上的开源 AI 工具越来越有价值——国内开发者需要的就是这种不依赖海外 API、数据在本地的自主可控方案。