HarnessRouter Docker 部署完整指南：备份、升级、Caddy TLS 与公网安全配置

HarnessRouter Docker 部署完整指南备份、升级、Caddy TLS 与公网安全配置【免费下载链接】harnessrouterHarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.项目地址: https://gitcode.com/gh_mirrors/ha/harnessrouterHarnessRouter Community Edition 是一款自托管、开源的Agent Harness 统一 API 网关让你通过一个 API 运行 Codex、Claude Code、Hermes、PI、DSH 等主流智能体框架并内置会话管理、流式输出、文件传输、任务取消与失败处理。本文带你完成HarnessRouter Docker 部署并覆盖四大运维主题 数据备份、容器升级、Caddy TLS 反向代理、公网安全配置。没有 HarnessRouter 时接 4 个框架意味着承担 36 项集成职责接入后你的产品只需要维护1 套API 集成而会话、流式、取消、失败处理都由网关统一兜底。自托管版本基于 Apache-2.0 许可状态是 SQLite 文件全部落在一个 Docker 卷里——这既是部署简单的原因也是下面备份策略的出发点。部署前的系统要求与环境准备开始之前确认你手头有三样东西条件要求运行时Docker支持docker run或 Compose磁盘约4 GB镜像约 700 MB 数据卷凭据任一模型供应商的 API Key如 Anthropic、OpenAI无需注册任何账号。几个容易踩的坑先说清楚不要给容器加--user容器必须以 root 启动后自行降权Runner 依赖它为每个会话分配独立系统用户写入隔离墙。0.8.2 起容器会拒绝非 root 启动。端口规划容器内部固定监听3000对外只发布这一个端口。Gateway:8080与 Runner:8081只走容器内回环永远不需要、也不应该暴露。镜像里不含 Agent CLI出于许可证要求各框架 CLI 在首次启动时安装到数据卷因此首次启动会慢一些之后启动秒级完成。完整的六步安装说明见官方文档 docs/self-hosting-guide.md本文聚焦部署之后的运维。HarnessRouter Docker 一键启动安全的最小化部署步骤启动容器并绑定回环地址执行以下命令其中-p 127.0.0.1:3000:3000是关键安全细节——控制台只对本机可达让你可以在默认口令下安全地完成首次登录之后再改密码docker run -d --name harnessrouter \ -p 127.0.0.1:3000:3000 \ -v harnessrouter:/data \ harnessrouter/harnessrouter-v harnessrouter:/data所有持久化数据的家。数据库、文件、密钥库、会话工作区都在这个命名卷里保住它 保住整个实例。若 3000 端口被占用只改左侧主机端口即可-p 127.0.0.1:3100:3000。想脚本化部署可用docker compose up -d服务定义在 docker-compose.yml记得把端口改成127.0.0.1:3000:3000并参考 .env.example 配置环境变量。确认就绪并登录控制台先别急着开浏览器。docker run一秒返回但控制台大约还需要半分钟docker logs -f harnessrouter等待日志出现ready on :3000首次启动会看到逐个安装框架 CLI 的过程。打开http://localhost:3000用默认凭据登录用户名harnessrouter密码harnessrouter。⚠️登录后立刻改密码账号菜单 →Profile。容器在默认口令未改期间每次启动都会打印一条 WARNING 提醒。忘记密码怎么办删除/data/selfhost-auth.json后重启实例回退到环境变量HR_AUTH_USER/HR_AUTH_PASSWORD见 .env.example。登录成功后的控制台首页会列出全部可用框架及健康状态连接模型供应商不做这一步任何任务都跑不起来——镜像不内置模型、没有试用 Key。进入侧边栏Bring Your Own KeyIntegrations 页面点击Add Integration填入名称、提供商和 API Key该 Key 只用于向模型供应商发起请求与后续创建给产品后端使用的 HarnessRouter API Key 是两回事。之后在Agent harnesses → 选择框架 → New task发起第一个任务看到流式回传即代表部署完成。HarnessRouter 数据备份完整保护 /data 卷自托管实例的全部家当都在/data卷SQLite 数据库、文件 Blob、密钥库含/data/selfhost-auth.json的控制台凭据以及各会话工作区。删除卷 删除整个实例所以备份是第一运维动作。备份前为什么要停止容器SQLite 是写时复制型的嵌入式数据库热拷贝可能得到不一致的文件。官方建议先停容器再打包卷这样数据库和文件才构成一份一致快照。一条命令打包数据卷docker stop harnessrouter docker run --rm -v harnessrouter:/data -v $(pwd):/backup alpine \ tar czf /backup/harnessrouter-$(date %F).tar.gz -C /data . docker start harnessrouter三条注意事项源自 docs/self-hosting-guide.md 的运维章节保留卷权限解包恢复时保持属主不变否则容器内进程可能无法读写。HR_SECRET_KEY与部署记录放在一起保管如果你为数据库连接设置了该密钥连接串用它派生的密钥加密存储密钥丢失意味着所有数据库连接需要重连。恢复顺序先恢复卷 相同配置端口、环境变量再启动替换实例不要急着换镜像版本。 建议把上面的命令放进定时任务并额外把备份包同步到另一台机器——单机备份不是备份。HarnessRouter 容器升级步骤安全切换到新版镜像⚠️ 一个常见误区docker pull只下载新镜像不会升级已有容器。正确的升级流程是备份 → 拉取 → 删旧容器 → 用原配置重建。docker run 方式升级# 1. 备份见上一节 docker stop harnessrouter docker rm harnessrouter # 2. 拉取指定版本推荐固定 tag而不是 latest docker pull harnessrouter/harnessrouter:0.9.0 # 3. 用完全相同的参数重建同名卷、同端口、同环境变量 docker run -d --name harnessrouter \ -p 127.0.0.1:3000:3000 \ -v harnessrouter:/data \ -e HR_SECRET_KEY保持不变 \ harnessrouter/harnessrouter:0.9.0重建后照旧docker logs -f harnessrouter确认ready on :3000。数据卷原样沿用已安装的 CLI 会直接复用所以升级启动通常比首次快得多。Docker Compose 方式升级docker compose pull docker compose up -d千万不要用docker compose down -v——-v会连数据卷一起删掉等于格式化整个实例。两个版本相关的红线固定版本号生产实例用具体 tag 而非latest升级节奏自己掌握。不要运行 0.1.x / 0.2.0这些版本完全没有登录门禁谁都能访问0.3.0才是第一个带登录的版本。Caddy 反向代理配置自动申请 TLS 证书上公网前推荐架构是控制台继续绑回环前面放一个 TLS 终止的反向代理。Caddy 只需一个配置文件证书自动申请、自动续期console.example.com { encode zstd gzip reverse_proxy 127.0.0.1:3000 { flush_interval -1 # 关键禁用缓冲否则流式输出会卡住 } }一行配置的价值远超想象flush_interval -1智能体的一个回合可能持续数分钟期间以 SSE 事件流推送进度。若代理按默认行为缓冲响应控制台会看起来卡死直到回合结束才一次性刷出。禁用缓冲后进度实时到达。自动 HTTPS无需手动申请证书Lets Encrypt 证书由 Caddy 自动获取并续期。同一域名即可托管 API产品后端把 base URL 指向https://console.example.com/api/harness即可复用同一套 TLS。该配置与官方文档 docs/self-hosting-guide.md 的 Putting it on a public URL 章节一致。HarnessRouter 公网安全配置清单控制台能创建框架、读取所有任务记录、并用你的供应商 Key 运行智能体——它的权限就是你的权限上限。曝光到公网前逐项核对已修改默认密码从Profile页面。这是第一优先级默认凭据是公开的占位符不是秘密容器每次启动的 WARNING 提醒没消失前实例只应留在回环地址上未启用HR_AUTH_DISABLED1。该变量移除整个登录门禁只适合一台谁也够不着的机器反向代理只放行 80/4433000端口仍绑定127.0.0.1防火墙不对外产品后端使用API Keys页面创建的 Key作用域限定在工作区、可随时轮换吊销绝不放进前端代码或 Git需要连接数据库时已设置HR_SECRET_KEY连接串加密存储并且数据库侧使用只读账号——网关本身已强制只允许SELECT只读账号是不依赖解析器正确性的第二道防线备份包与HR_SECRET_KEY已异地保存且升级前先备份架构上你可以放心的是容器只发布控制台一个端口Gateway 与 Runner 始终留在回环见 Dockerfile 中UI 是唯一发布端口的设计登录门禁内置在镜像里而非依赖前置代理。每个智能体进程以独立系统用户运行无法读写其他会话的文件与数据库——隔离逻辑见 docker/entrypoint.sh。部署常见问题快速排查症状原因与处理容器秒启动但浏览器拒绝连接正常现象首次启动还在安装框架 CLI。docker logs -f等到ready on :3000某个框架不可用单个 CLI 安装失败不致命其他照常工作。查日志中backends available:行与 requested but not installed 警告用HR_BACKENDS精简可装列表端口冲突只改主机侧端口-p 127.0.0.1:3100:3000容器内永远是 3000忘了控制台密码删除/data/selfhost-auth.json并重启回退到环境变量凭据流式输出整段延迟检查反向代理缓冲Caddy 加flush_interval -1参考文档完整安装与运维指南含插件、环境、API 集成docs/self-hosting-guide.md快速上手六步安装摘要README.md容器编排与数据卷定义docker-compose.yml构建参数与运行时用户隔离设计Dockerfile环境变量样例供应商连接、登录凭据.env.example容器启动流程与权限模型docker/entrypoint.sh开放标准 UHP 规范与机器可读 Schemaprotocol/按这份清单走完你就拥有一台可备份、可升级、带自动 TLS、且公网安全的 HarnessRouter 实例——剩下的就是把任务丢给智能体了 【免费下载链接】harnessrouterHarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.项目地址: https://gitcode.com/gh_mirrors/ha/harnessrouter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考