SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

HarnessRouter自托管:统一Codex、Claude Code和Hermes API

了解HarnessRouter的Docker部署、loopback绑定、首次登录后必须修改的初始凭据,以及通过TLS安全访问统一代理API的方法。

HarnessRouter 会移除的内容

您可以在自己的服务器上自行托管 HarnessRouter Community Edition,在多个代理 harness 前统一提供一个 API。代理 harness 是一个通过循环驱动模型的命令行程序:它会保持会话、编辑文件、运行命令,并将进度流式传回请求执行任务的一方。Codex、Claude Code 和 Hermes 都承担这一职责,但它们各自有独立的安装方式、凭据格式,以及对会话的定义。HarnessRouter 将它们全部运行在一个容器中,并在前面提供统一的 HTTP 端点、统一的登录入口和统一的密钥存储。

这就是全部思路,但代价也必须明确说明。您需要在服务器上增加一个容器、一个登录入口、一个卷和一套升级流程,才能将多个组件整合为一个整体。如果您目前只运行一个 harness,直接安装该 harness 会比这种方案更简单。这种取舍将在本文最后一节说明,因此请在部署前阅读该节。

以下内容均基于镜像标签 0.5.5 检查,该镜像于 19 August 2026 拉取。项目大多数日期都会发布新标签,因此一个月后查看本文时,请核对您实际运行的标签,不要直接信任本文内容。本文于 8 November 2026 根据项目当前文档和源代码重新检查;当时 latest 指向 0.38.5,当前版本行为不同的位置会明确说明。命令来自项目仓库 github.com/HarnessRouter/harnessrouter。这些命令位于 README 的 0.5.5;现在,配置细节位于同一仓库的 docs/self-hosting-guide.md。

Unified Harness Protocol 的实际含义

HarnessRouter 实现了 Unified Harness Protocol(UHP)。该协议发布于 unifiedharnessprotocol.org。UHP 规定了产品如何在 harness 上启动任务、在任务运行期间跟踪任务、管理会话和文件,以及报告失败。该规范按日期进行版本管理。截至 19 August 2026,线上版本的日期为 2026-08-11。截至 8 November 2026,网站将 2026-10-19 列为当前版本,并且仍将其称为“足够稳定、可以据此构建,并通过版本管理确保能够安全变更”的草案标准。

请仔细理解这里的“开放标准”。同一家公司编写规范、实现参考实现,并维护用于判定兼容性的 conformance suite;项目治理规则还规定,除非这三者同步变更,否则任何变更都不能合并。截至 9 November 2026,协议主页将该测试套件描述为 110 项可运行检查,但 conformance 页面显示为 101 项,而 self-hosting 指南中记录的、日期为 4 September 2026 的参考运行结果显示通过了 64 项,因此公开发布的数量并不一致。项目变更日志显示,新增的 6 项分支检查日期为 4 November 2026。对于这样年轻的协议,这属于正常情况;Apache-2.0 许可证意味着您可以 fork 其中任何部分。这也意味着 UHP 还不是多供应商标准。请将其视为一个正在形成中的协议:它有用、仍在快速变化,并且您的代码应能够在无需重写的情况下停止使用它。

开始前的准备工作

您需要 Docker 和约 4 GB 可用磁盘空间。您还需要一个已付费模型提供商的 API 密钥。镜像拉取量约为 700 MB,其余磁盘空间用于 agent CLI 及其写入的工作区。镜像中不包含模型或试用密钥,因此在连接模型提供商之前,任务会失败。HarnessRouter 本身采用 Apache-2.0 许可证。agent CLI 仍受其各自的许可证和条款约束,仓库许可证不会取代这些许可证和条款。它们会在首次启动时获取,而不是随镜像一起发布。

使用一次 docker run 自托管 HarnessRouter

docker pull harnessrouter/harnessrouter
docker run -d --name harnessrouter \
  -p 127.0.0.1:3000:3000 \
  -v harnessrouter:/data \
  harnessrouter/harnessrouter

然后监控容器启动。首次启动较慢,日志会说明原因。

docker logs -f harnessrouter

运行期间,您会看到类似以下内容的行:

installing Claude Code (Anthropic's terms apply)…
installing Codex (Apache-2.0)…
installing Hermes (check its upstream license before use)…

等待 ready on :3000。当前指南测得的时间约为半分钟,计时从 docker run 返回命令提示符开始,而不是从该行出现时开始;如果 http://localhost:3000 在就绪行出现后没有立即响应,请等待几秒后重试。已安装的 CLI 会缓存在该卷中,因此后续启动通常会快得多。不过,之后添加的后端,或之前安装失败的后端,仍可能触发安装操作。

该下载会带来两个事实,而这两点在 VPS 上都很重要。第一,首次启动需要出站网络访问。该镜像并非自包含,因此位于出站流量过滤器之后、或没有外部路由的主机无法获取 agent CLI。0.5.5 和当前版本都会将安装失败视为非致命错误,并在日志中列出这些失败,因此请检查 backends available: 行中缺少哪些后端。第二,您正在根据第三方条款安装第三方软件。Claude Code 受 Anthropic 的条款约束,Hermes 则受其上游项目规定的条款约束,因此在商业使用前请分别检查这两者的条款。

-v harnessrouter:/data 会创建一个命名 Docker 卷。所有持久化数据都位于 /data 中:SQLite 数据库、存储的文件、密钥存储和 agent 工作区。删除该卷就等于删除整个实例,包括提供商密钥和所有对话记录。请在容器停止后备份,因为在 SQLite 数据库写入期间复制它,得到的文件可能无法打开。相同的先停止、再复制原则适用于主机上的所有有状态容器,但具体步骤因服务而异,因为 PhotoPrism 和 Immich 各自需要使用专用的备份命令。

docker stop harnessrouter
docker run --rm -v harnessrouter:/data -v "$PWD":/backup alpine \
  tar czf /backup/harnessrouter-data.tgz -C / data
docker start harnessrouter

Compose 变体,以及必须修改的行

仓库中提供了一个 Compose 文件。当前版本发布 "127.0.0.1:3000:3000",并将主机端口绑定到 loopback。如果您在公网服务器上使用旧文件,请修改 0.5.5 文件中的 "3000:3000" 那一行。

services:
  harnessrouter:
    image: harnessrouter/harnessrouter:0.5.5
    ports:
      - "127.0.0.1:3000:3000"
    env_file:
      - .env
    volumes:
      - harnessrouter-data:/data
    restart: unless-stopped

volumes:
  harnessrouter-data:

有一处不同于当前上游版本:这里使用固定的版本标签,而不是 latest。由于发布版本更新很快,固定版本很重要:截至 8 November 2026 检查时,Docker Hub 显示 0.38.4 和 0.38.5 都是在过去一天内推送的。Agent 运行时在运行过程中发生变化,会很难排查问题。请固定当前发布版本,不要直接复制本页中的 0.5.5;截至 9 November 2026,该值为 0.40.0。然后复制环境文件,限制其权限,并启动服务。

cp .env.example .env
chmod 600 .env
docker compose up -d
docker compose logs -f

.env 以明文保存您的 provider 密钥,因此 mode 600 是最低要求。如果您不熟悉 docker compose 子命令,请参阅 Docker Compose 命令速查表,其中介绍了日常使用的命令。

为何将端口发布到 127.0.0.1,而不是 0.0.0.0

-p 3000:3000 默认会将端口发布到主机的每个网络接口。-p 127.0.0.1:3000:3000 会将主机端口发布到回环接口。早于 28.0.0 的 Docker 版本允许同一 L2 网段中的主机访问发布到 localhost 的端口;如果显式启用直接路由,即使主机端口映射到回环接口,也可能暴露容器端口。容器默认在内部监听 3000,可通过 PORT 配置,因此应修改左侧的端口号以避免主机端口冲突。检查实际结果:

docker port harnessrouter
sudo ss -ltnp | grep 3000

ss 输出 127.0.0.1:3000 是正确的。0.0.0.0:3000 表示控制台绑定到所有 IPv4 接口;是否能从公网访问,仍取决于路由和过滤规则。对于此处的控制台,这比大多数自托管应用的情况更危险,因为控制台会创建执行环境、读取所有会话记录、运行代理,并为这些代理提供 shell 和工作区中的真实文件系统。它还保存了您连接时使用的服务提供商密钥。任何能够访问未受保护控制台的人,都可以读取您的工作、运行命令并消耗您的密钥。

ufw 拒绝规则无法解决这个问题。Docker 会先通过自己的规则转发已发布的容器流量,然后才到达由 ufw 管理的链。因此,sudo ufw status 显示某个端口被拒绝,并不能证明已发布端口确实被阻止。请从另一台机器进行测试,不要从 VPS 本机测试,否则测试没有意义。这与在端口 3080 上无头运行 dsh的原则相同:将服务绑定到回环接口,然后再明确决定如何访问它。

首先修改默认登录凭据

使用用户名 harnessrouter 和实例生成的初始密码登录 http://localhost:3000。使用以下命令读取初始密码:

docker exec harnessrouter cat /data/selfhost-initial-password

共享密码 harnessrouter 曾在 0.5.5 中有效;当前安装不接受该已公开的默认密码。

您可以在 Profile 页面中修改密码,也可以在启动时为脚本化部署设置密码。HR_AUTH_USER 和 HR_AUTH_PASSWORD 用于提供初始凭据;在 Profile 中保存的凭据优先级更高。

docker run -d --name harnessrouter \
  -p 127.0.0.1:3000:3000 \
  -v harnessrouter:/data \
  -e HR_AUTH_USER='you' \
  -e HR_AUTH_PASSWORD='the-password-you-chose' \
  harnessrouter/harnessrouter

本地 Console 登录不支持通过电子邮件重置密码。如果忘记密码,请删除卷中的身份验证文件并重启,然后使用您配置的 HR_AUTH_USER 和 HR_AUTH_PASSWORD 登录;如果未提供自定义凭据,则使用生成的初始密码。

docker stop harnessrouter
docker run --rm -v harnessrouter:/data alpine rm -f /data/selfhost-auth.json
docker start harnessrouter

HR_AUTH_DISABLED=1 会完全移除登录控制。自托管指南称,这种设置“只适用于其他人无法访问的机器”。具有公网 IP 地址的 VPS 不属于这种机器,因此除非您在笔记本电脑上运行此服务,否则请保持登录控制启用。

检查版本,因为旧版本没有认证门槛

这一点必须认真对待。0.1.x 和 0.2.0 发布时完全没有认证机制:任何能访问 3000 端口的人都可以直接进入控制台。0.3.0 是第一个支持登录的版本。本页上次记录这些旧标签可发布并可拉取的时间是 2026 年 10 月 12 日;截至 2026 年 11 月 8 日,未确认它们当前是否仍可用。

截至 2026 年 8 月 19 日,最新发布的标签是 0.5.5,发布日期为 2026 年 8 月 18 日。2026 年 11 月 8 日,latest 指向 0.38.5。先检查当前使用的版本,再与 Docker Hub 上的标签列表进行比较:

docker image ls harnessrouter/harnessrouter

低于 0.3.0 的版本应立即替换,不要安排到以后处理。仍使用共享默认密码的旧版本也必须更改密码;当前安装会生成初始密码,并要求您设置自己的密码。不要将本页中的版本号视为当前版本。它们只在所述日期有效,而且该项目发布新版本的速度很快。

连接提供商

未连接模型提供商时,不会运行任何内容。您可以在账户菜单的 Bring your own key 中添加提供商,也可以将其传递给环境中的 docker run。该值为 JSON,因此请在 shell 中加引号:

-e HR_SECRET_GLOBAL_HARNESS_CONN_ANTHROPIC='{"name":"anthropic","provider":"anthropic","api_key":"sk-ant-…"}'

.env.example 为每个提供商系列指定一个连接变量:HR_SECRET_GLOBAL_HARNESS_CONN_ANTHROPIC 用于 claude-code 后端,HR_SECRET_GLOBAL_HARNESS_CONN_OPENAI 用于 codex 后端,HR_SECRET_GLOBAL_HARNESS_CONN_GOOGLE 用于 gemini 后端,HR_SECRET_GLOBAL_HARNESS_CONN_CUSTOM 用于任何 OpenAI 兼容端点。聚合服务或您自己的推理服务器应配置在这里。对应的 HR_SECRET_GLOBAL_HARNESS_POLICY_CLAUDE、HR_SECRET_GLOBAL_HARNESS_POLICY_CODEX 和 HR_SECRET_GLOBAL_HARNESS_POLICY_HERMES 变量指定各后端默认使用的连接,每个后端还各有一个策略变量。HR_SECRET_KEY 是独立的配置项。当前版本会使用它加密存储的凭据;如果您未提供密钥,系统会在 /data/secret-key 中生成一个。请在重启和升级之间保留同一个密钥。若要将密钥与现有实例中的数据分开,请将 HR_SECRET_KEY 设置为该文件中的值,然后删除该文件。

HR_BACKENDS 选择要安装和加载的后端,如 HR_BACKENDS=claude,codex,hermes 所示。如果不设置,当前版本会安装一个包含 30 个后端的较长默认列表,其中包括 claude、codex、hermes、opencode、gemini、goose 等。缩短该列表可以节省磁盘空间并缩短首次启动时间。当前自托管指南建议“如果不会使用某个后端,就将其从 HR_BACKENDS 中省略”,指南中的精简示例是 HR_BACKENDS=opencode,其中完全省略了 Hermes。某个后端安装失败不会导致整体失败:其他后端仍可用。针对未安装后端的任务会被拒绝,并显示“not installed”;容器日志会指出安装失败的后端。0.5.5 README 曾记录一个已知问题:省略 hermes 会使容器立即以状态 1 退出,且不显示错误消息。但该标签的入口点已经修复了此问题;其中的注释描述的是之前的实现。如果您只需要 Hermes 这一套运行环境,在自己的 VPS 上运行 Hermes 代理是更精简的部署方式。

不使用控制台调用 API

控制台不是必需的。两者使用同一个 API,并遵循 Responses 风格的契约。先登录以获取会话 Cookie:

curl -c hr.cookies http://localhost:3000/api/selfhost/login \
  -H 'content-type: application/json' \
  -d '{"username":"harnessrouter","password":"your-password"}'

然后发送任务,在 metadata.harness_id 中指定 harness,并指定已连接的服务商实际提供的模型:

curl -s -b hr.cookies http://localhost:3000/api/harness/v1/responses \
  -H 'content-type: application/json' \
  -d '{"input":"Reply with exactly this and nothing else: it works.",
       "metadata":{"harness_id":"codex"},
       "model":"gpt-5.4-mini",
       "stream":false}'

如果返回的 JSON 对象包含输出块和令牌数,说明 harness 已运行。将 harness_id 从 codex 改为 claude-code,会将同一个请求发送到另一个 harness;这种切换正是此软件存在的全部原因。请注意,id 是 claude-code,即使后端名称是 HR_BACKENDS,策略变量是 claude。上面的自定义连接用于将 harness 指向您已经托管的 OpenAI 兼容端点,连接方式与 在 VPS 上运行自托管 DeepSeek harness 相同。

会话 Cookie 流程仍支持本地调试。对于产品后端,当前文档建议在 API Keys 中创建 HarnessRouter API key,并将其作为 Bearer 令牌发送,而不是维护 Console 会话。

从笔记本电脑访问它,而不公开端口

有两种方式,且都不会在 0.0.0.0 上直接开放端口。

SSH 隧道成本最低,服务器无需安装任何软件。它会将本机的一个端口转发到 VPS 的 loopback。

ssh -N -L 3000:127.0.0.1:3000 you@your-vps

保持该命令运行,然后在浏览器中打开 http://localhost:3000。如果 SSH 输出 bind: Address already in use,说明笔记本电脑上已有程序占用端口 3000。此时使用 -L 3100:127.0.0.1:3000 选择其他本地端口,然后访问 3100 端口。

终止 TLS 的反向代理适合需要让其他人访问的场景。代理负责保存 TLS(传输层安全)证书,并将请求转发到 loopback。自托管指南提供了以下 Caddy 配置:

console.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:3000 {
        flush_interval -1      # agent turns stream for minutes; never buffer them
    }
}

flush_interval -1 用于显式禁用 Caddy 的响应缓冲;即使不配置它,Caddy 也会立即刷新 text/event-stream 响应。Agent 会持续数分钟输出流式令牌。如果代理缓冲响应,就会一直保留这些令牌,直到本轮处理结束。因此控制台看起来像是卡住,随后一次性输出全部内容。Nginx 中的等效配置是 location 块内的 proxy_buffering off;。无论选择哪种代理,都应让 DNS 名称指向代理,并让容器监听 loopback。比较 Nginx、Caddy 和 Traefik 作为反向代理介绍了如何根据服务器选择合适的代理。

以专用用户运行,不要使用 root

Docker daemon 以 root 身份运行,加入 docker 组等同于获得 root 权限,因为组成员可以启动挂载主机文件系统的容器。因此,“将团队加入 docker 组”实际上会向持有您的 provider key 的主机授予 root 权限。

简单方案是:创建一个拥有 compose 文件和 .env 的服务账户,并将这些文件放在共享 home 目录之外。

sudo adduser --disabled-password --gecos "" harness
sudo install -d -o harness -g harness -m 750 /srv/harnessrouter

不要通过将 --user 添加到 docker run,或将 user: 添加到 compose 文件中来实现这一点。当前指南要求容器以 root 身份启动,而从 0.8.2 开始,容器拒绝以其他方式启动,日志中会有一行明确说明原因。

更严格的方案是使用 rootless Docker,让 daemon 本身以该非特权用户身份运行。它需要 uidmap 软件包来提供 newuidmap 和 newgidmap,还需要在 /etc/subuid 和 /etc/subgid 中为该用户分配至少 65536 个从属 UID。Ubuntu 软件源中包含 uidmap,但不包含 docker-ce-rootless-extras:后者来自 Docker 自己的 apt 软件源 download.docker.com,安装 Docker engine 时会添加该软件源。如果您不是从该软件源安装 engine,grep -rl download.docker.com /etc/apt/sources.list.d/ 不会输出任何内容,下面的安装命令也找不到该软件包。

sudo apt install -y uidmap docker-ce-rootless-extras
sudo loginctl enable-linger harness
sudo -iu harness
dockerd-rootless-setuptool.sh install
export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock
systemctl --user enable --now docker

loginctl enable-linger 会在用户注销后保持其 systemd 实例运行,并在启动时启动该实例。使用 docker info 确认结果;该命令会在 Security Options 下列出 rootless。rootless 模式无法在未进行额外配置的情况下绑定 1024 以下的端口,但这里不受影响,因为端口 3000 高于该范围。账户本身的设置方法请参阅在 VPS 上创建最小权限用户。

故障现象与排查结果

容器启动一秒后退出,日志为空。 docker ps -a显示Exited (1)。早期版本的 entrypoint 会在 HR_BACKENDS 缺少 hermes 时失败,但 0.5.5 已包含修复,尽管其 README 仍列出该问题。不要仅根据退出状态诊断此故障。在较新的标签中,读取 docker logs 的最后一行:从 0.8.2 开始,使用 --user 启动的容器会退出,并显示一行提示必须以 root 身份启动。

首次启动始终无法完成。 日志在 installing 行后停止,且从未出现 ready on :3000。检查服务器是否可以访问网络以获取 agent CLI,因为这些 CLI 不在镜像中。0.5.5 和当前版本都会容忍已完成的安装失败,在日志中列出失败的安装,并将其从 backends available: 行中排除。修复出站路由或代理设置,然后重新启动。

控制台可以加载,但每个任务都失败。 没有连接任何 provider。镜像中不包含预置模型,也没有免费层,因此新实例即使可以完成登录,仍无法运行任何任务。

通过代理访问时,控制台在回答过程中卡住。 回答结束后,输出会一次性显示。这是响应缓冲导致的。请在 Caddy 中设置 flush_interval -1,或在 Nginx 中设置 proxy_buffering off;。

隧道已建立,但笔记本电脑无法访问服务。 在服务器上运行 docker port harnessrouter。如果没有输出,说明容器未发布任何端口,请检查端口映射和网络模式。

值得运行吗?

如果您确实使用多个 harness,并且希望使用一个端点和一个凭据存储,而不是分别维护三个端点和三个凭据存储,那么值得运行。如果您要在其上构建产品,并希望将 harness 设置为配置值,而不是在代码中重写,也值得运行。这正是 UHP 提供的价值,但仍需注意前文提到的协议尚处于早期阶段。

如果您只使用一个 harness,则不值得运行。直接在服务器上安装该 CLI,涉及的组件更少,也不需要在您与它之间增加登录环节。如果您需要的是多个代理协作完成一个任务,而不是在多个 harness 前提供一个 API,那么它同样不是合适的架构。这属于另一类工具:对于这种模式,请参阅 Omnigent 等多代理 harness。无论选择哪种方式,部署规则都不变:绑定 loopback、修改密码、固定使用当前版本,并使用独立用户。

FAQ

发布 HarnessRouter 到端口 3000 是否安全?

不安全。控制台可以创建 harness、读取所有转录内容、运行具有 shell 和文件系统访问权限的代理,并持有您连接的服务商密钥,因此未受保护的控制台会暴露这些全部功能。使用 -p 127.0.0.1:3000:3000 让服务仅监听 loopback,再通过 SSH 隧道或终止 TLS 的反向代理访问。单独使用 ufw 拒绝规则并不足够:Docker 会在 ufw 管理的链处理之前转发已发布的容器流量。使用 sudo ss -ltnp | grep 3000 验证,其输出应为 127.0.0.1:3000,并从另一台机器测试访问。使用 Docker 28.0.0 或更高版本,避免旧版本存在的同一 L2 网络 localhost 暴露问题,并确认未启用直接路由。

哪个 HarnessRouter 版本添加了登录控制?

0.3.0。0.1.x 和 0.2.0 版本完全没有身份验证,因此运行这些版本时,您只能依赖没有人发现该端口。本页上次记录这些标签已在 12 October 2026 发布并可拉取;截至 8 November 2026,尚未确认它们当前是否仍可用。截至 19 August 2026,最新标签为 0.5.5,日期为 18 August 2026;在 8 November 2026,latest 指向 0.38.5。运行 docker image ls harnessrouter/harnessrouter 查看当前使用的版本,并将其与 Docker Hub 上的标签列表进行比较,而不是与本页比较,然后设置您自己的密码。当前安装会生成初始密码,而不是接受旧的共享默认密码。

为什么设置 HR_BACKENDS 后容器立即退出?

在当前版本中不应发生这种情况。自托管指南要求省略您不会使用的后端,安装失败的后端不会导致整体退出。早期实现会在省略 hermes 时以状态 1 退出,且不显示错误消息,但 0.5.5 源码已经修复了此问题,尽管其 README 仍列出了该问题。在较新的标签中,读取 docker logs:从 0.8.2 开始,使用 --user 启动的容器会退出,并输出一行说明它必须以 root 身份启动。

HarnessRouter 第一次启动时需要访问互联网吗?

需要。代理 CLI 会在第一次启动时获取,而不是随镜像一起发布;每个 CLI 仍受其自身的许可证和条款约束。0.5.5 和当前版本都会在日志中记录安装失败,并允许其他后端启动。已安装的 CLI 会缓存在卷中,因此后续启动通常更快。不过,后端工具和您运行的任务仍可能需要网络访问;新的后端或之前安装失败的后端也可能再次触发安装。

我忘记了控制台密码。如何重新登录?

本地 Console 登录不提供密码重置邮件。停止容器,从卷中删除 /data/selfhost-auth.json,然后重新启动容器。接着使用您配置的 HR_AUTH_USER 和 HR_AUTH_PASSWORD 登录;如果未设置自定义密码,则使用生成的初始密码。然后从 Profile 页面设置新密码。若容器和卷都命名为 harnessrouter,依次运行 docker stop harnessrouter、docker run --rm -v harnessrouter:/data alpine rm -f /data/selfhost-auth.json 和 docker start harnessrouter。使用 docker exec harnessrouter cat /data/selfhost-initial-password 读取生成的密码。

这篇文章对您有帮助吗?