企业官网建设流程全解析

Hermes Workspace Docker部署教程：2个容器跑起AI Agent控制平面，含远程访问配置

【免费下载链接】hermes-workspaceNative web workspace for Hermes Agent — chat, terminal, memory, skills, inspector.项目地址: https://gitcode.com/gh_mirrors/he/hermes-workspace

Hermes Workspace是 Hermes Agent 的原生 Web 控制平面，集聊天、终端、记忆管理、技能系统与调试检查器于一体。通过 Docker 部署，只需2 个容器（Agent 引擎 + Workspace Web UI）即可完整跑起整套系统，本文给出从零到远程访问的完整步骤。

先搞懂架构：为什么是 2 个容器？

Hermes Workspace 采用「UI 与引擎分离」的设计：

分离的好处很实际：两者可独立更新、可对同一 Agent 挂多个 Workspace、甚至把 UI 跑在平板上而让 Agent 留在高性能主机上。默认 Compose 文件将两者放在同一主机，开箱即用。

相关配置可参阅官方文档 docs/docker.md 与根目录的 docker-compose.yml。

部署前准备：3 样东西缺一不可

• ✅Docker与Docker Compose（新版 Docker Desktop 自带）
• ✅至少一个 LLM 提供商密钥：OpenAI、OpenRouter、Google 等任一即可（本地 Ollama / LM Studio 则无需密钥）
• ✅ 空闲端口3000（UI）与8642（Agent 网关）

一键安装：3 步快速启动

第 1 步：获取代码并配置环境变量

git clone https://gitcode.com/gh_mirrors/he/hermes-workspace cd hermes-workspace cp .env.example .env

编辑.env，填入你使用的模型提供商密钥（只填一个即可）：

OPENROUTER_API_KEY=sk-or-... # 或 OPENAI_API_KEY / GOOGLE_API_KEY 等

.env的完整变量说明（安全项、超时项等）见 .env.example。

第 2 步：启动容器

docker compose up

首次运行会自动拉取两个预构建镜像（约 1 分钟），之后秒启。Compose 配置了健康检查与启动依赖：Workspace 会等待 Agent 的/health返回 200 后才启动，见 docker-compose.yml 中depends_on: condition: service_healthy的设置。镜像内置的健康检查与入口脚本在 Dockerfile 与 docker/entrypoint.sh 中定义。

第 3 步：访问验证

打开http://localhost:3000完成引导设置。确认日志中出现以下字样即代表两容器握手成功：

docker compose logs hermes-workspace | grep '\[gateway\]' # 期望看到 mode=zero-fork 且 core 列表包含 health,chatCompletions,models,streaming

核心环境变量速查

Docker 部署最容易踩坑的就是环境变量，几个关键项：

远程访问配置：局域网 / Tailscale / VPS

默认 Compose 将端口绑定到127.0.0.1（仅本机）。要从手机、平板或其他电脑访问，需要三步改动：

1. 放开端口绑定— 新建docker-compose.override.yml（Compose 会自动合并，不污染基础文件）：

services: hermes-agent: ports: - '8642:8642' hermes-workspace: ports: - '3000:3000'

2. 补齐安全变量— 追加到.env：

HERMES_PASSWORD=你的强密码 # 必填：容器默认绑 0.0.0.0，无密码直接拒启 COOKIE_SECURE=0 # 纯 HTTP 内网访问时设为 0 API_SERVER_KEY=另一个强随机密钥 # 网关鉴权，防局域网未授权调用

3. 重启生效：

docker compose down && docker compose up -d

⚠️ 安全提醒：HERMES_PASSWORD与API_SERVER_KEY建议使用两个不同的随机长字符串；若通过 Tailscale Funnel / Cloudflare Tunnel 等 TLS 反代暴露，改设COOKIE_SECURE=1并加TRUST_PROXY=1，详见 docs/docker.md 的「Multi-host / NAS / VPS」章节。

数据持久化：容器随便删，数据不丢

两个命名卷负责持久化，docker compose down不会清除：

• hermes-agent-data→ Agent 配置、会话、技能、记忆、凭据
• hermes-workspace-files→ 通过 Workspace 文件浏览器创建的文件

只有docker compose down -v才会删除它们，升级镜像前可放心操作。

开发者进阶：从源码构建

想改 Workspace 代码并热编译进容器，用官方提供的 dev overlay，基础docker-compose.yml保持不动：

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

该 overlay 仅为 Workspace 服务追加build:配置（本地源码编译替代拉取镜像），见 docker-compose.dev.yml。

常见问题快速排查

更完整的诊断手册见 docs/troubleshooting.md，容器内网络诊断方法见 docs/docker.md 的「Connection failures」章节。

写在最后

至此，你已用 2 个容器部署好完整的 Hermes Workspace 控制平面：聊天、终端、记忆、技能、任务管理一应俱全，并掌握了远程访问与安全加固的全部要点。日常运维只需记住三条命令：docker compose up -d启动、docker compose logs排查、docker compose pull && up -d升级。

【免费下载链接】hermes-workspaceNative web workspace for Hermes Agent — chat, terminal, memory, skills, inspector.项目地址: https://gitcode.com/gh_mirrors/he/hermes-workspace