Hermes 引擎容器化

架构

Portal Chat (Vue 3) → Gateway (:8010) → engine-hermes-{id}:8642 → DeepSeek v4 Flash
                         ↑
                  DNS 命名规范路由 (X-Agent-ID 头)

容器构建

• 基础镜像: veyraos/gateway:latest (python:3.11-slim + FastAPI)
• 运行时: hermes-agent pip 包
• 入口: entrypoint.sh — 自动配置 provider、启动 API server

entrypoint.sh 流程

1. 写入 ~/.hermes/.env (API_SERVER_ENABLED, API_SERVER_KEY 等)
2. 如果 PROVIDER_NAME 有值, 写入 ~/.hermes/config.yaml
3. 透传 OPENAI_API_KEY / ANTHROPIC_API_KEY / DEEPSEEK_API_KEY 等变量
4. 如果 HERMES_PROFILE != "default", 创建该 profile
5. 配置模型 provider/default/base_url/api_key
6. 启动: hermes -p <profile> gateway run

注意：不创建 "default" profile（它是 Hermes 内置的，无需创建）。

Provider 配置

引擎 Pod 的环境变量来自 Agent 的 config.engine 字段：

{
  "engine": {
    "PROVIDER_NAME": "deepseek",
    "MODEL_NAME": "deepseek-v4-flash",
    "DEEPSEEK_API_KEY": "sk-..."
  }
}

通过 Manager API 设置：

curl -X PUT /api/agents/{id} \
  -d '{"config": {"engine": {"PROVIDER_NAME": "deepseek", ...}}}'

环境变量

变量	用途	来源
PROVIDER_NAME	提供商名称 (deepseek)	Agent config
MODEL_NAME	模型名 (deepseek-v4-flash)	Agent config
DEEPSEEK_API_KEY	DeepSeek API Key	Agent config
PROVIDER_API_KEY	通用 API Key	Agent config
PROVIDER_API_BASE	API Base URL	Agent config
HERMES_PROFILE	Profile 名称	默认 "default"
API_SERVER_KEY	引擎 API Key	K8s secret
API_SERVER_ENABLED	启用 API Server	固定 "true"
API_SERVER_HOST	监听地址	固定 "0.0.0.0"
API_SERVER_PORT	监听端口	固定 8642
GATEWAY_ALLOW_ALL_USERS	允许所有用户	固定 "true"

K8sManager 创建 Pod 时的 env 注入

K8sManager 在 create_agent_engine() 中设置的环境变量：

V1EnvVar(name="AGENT_ID", value=agent_id),
V1EnvVar(name="API_SERVER_KEY", value_from=secretRef("api-server-key")),
V1EnvVar(name="API_SERVER_ENABLED", value="true"),
V1EnvVar(name="API_SERVER_HOST", value="0.0.0.0"),
V1EnvVar(name="API_SERVER_PORT", value="8642"),
V1EnvVar(name="GATEWAY_ALLOW_ALL_USERS", value="true"),
# + config.engine 中的键值对

引擎 API

Hermes Agent API Server 暴露 OpenAI 兼容接口：

端点	说明
POST /v1/chat/completions	聊天补全（支持 stream=true SSE）
GET /v1/models	模型列表
GET /health	健康检查

Gateway 集成注意事项

• Gateway 转发请求前必须去掉 Origin 和 Referer 头，否则引擎会返回 403
• 引擎 API 通过 Authorization: Bearer {API_SERVER_KEY} 认证
• 引擎 Pod 命名规范：engine-hermes-{agent_id[:8]}

注意事项

• Hermes Agent 使用 profile 隔离多实例配置
• 本地已安装桌面版 Hermes，所有容器化运行必须在 colima/k3s 中进行

命令沙箱（OpenSandbox）

智能体实例可在表单中启用「命令沙箱」：启用后，hermes terminal 工具的命令不再直接跑在引擎 Pod 内，而是提交到独立的 OpenSandbox 沙箱（K8s 原生沙箱服务）执行。

行为语义

• 粒度：实例内每位终端用户（profile）一个沙箱；同一用户跨会话共享（pip 安装的包、生成的文件延续）
• 生命周期：沙箱跨回合常驻，空闲超过实例配置的时长后自动回收；回收前命令产物自动同步回实例数据卷，跨会话可继续访问
• 文件互通：执行前引擎侧文件（凭据、技能等）自动推送到沙箱；执行产物按需取回 —— 用户视角文件工具与终端命令操作同一份文件
• 隔离边界：沙箱是独立 Pod（数据面 opensandbox ns），与引擎 Pod 资源互不占用；实例之间、用户之间沙箱互相隔离

配置链路

实例 runtime_config.sandbox 段（enabled / image / cpu_millicores / memory_mb / disk_mb / lifetime_seconds）→ manager 部署时经 sandbox_engine_envs 注入引擎 Pod env（TERMINAL_ENV=opensandbox + OPENSANDBOX_*）→ 引擎镜像内置的 OpenSandbox 后端读取。沙箱 API key 经 veyraos-secret（secretKeyRef）透传，manager 不落库。

沙箱服务本体部署见 deploy/k8s/infra/opensandbox.yaml（部署指南「命令沙箱」节）。

引擎镜像固化

引擎镜像在 pip 安装 hermes-agent（vendored wheel，engines/hermes/vendor/）后追加两步：安装 tools/environments/opensandbox.py（OpenSandbox 执行后端）+ patch_terminal.py 给 terminal_tool 打 5 处补丁（后端注册）。补丁带锚点断言，hermes 升版导致锚点漂移时构建显式失败（engines/hermes/tests/test_patch_terminal.py 同步守护）。