wehub-resource-sync
513 lines
20 KiB
Markdown
513 lines
20 KiB
Markdown
# Agent Runtime 开发规范
|
||
|
||
本文是 ClawManager 托管 runtime 的 agent 侧开发规范，适用于 OpenClaw、Hermes，以及后续新增的任意 runtime。开发新 runtime 时，应先满足本文的通用要求，再补充 runtime 自己的启动命令、配置文件和健康检查细节。
|
||
|
||
相关协议和背景请同时参考：
|
||
|
||
- `docs/clawmanager-agent-v2-development-guide.md`
|
||
- `docs/clawmanager-agent-v2-contract.md`
|
||
- `docs/runtime-agent-integration-guide.md`
|
||
- `docs/hermes-lite-pro-agent-development.md`
|
||
- `docs/hermes-runtime-agent-development.md`
|
||
|
||
## 1. 范围和目标
|
||
|
||
一个托管 runtime 镜像不能只启动业务进程。它必须内置一个常驻 runtime agent，由 agent 在 Pod 内负责：
|
||
|
||
- Runtime Pod 注册、heartbeat、metrics、gateway 状态上报。
|
||
- 接收 ClawManager 下发的 create、delete、drain、restart 等控制指令。
|
||
- 管理本 Pod 内多个 gateway 子进程。
|
||
- 管理端口池、进程、workspace、UID/GID、资源限制和健康检查。
|
||
- 把 ClawManager 注入的 AI Gateway、实例 token、代理信任和 runtime 配置写入每个实例自己的 workspace。
|
||
|
||
一句话原则：agent 是 Pod 内 gateway 管理器，不是同步启动脚本。
|
||
|
||
## 2. 架构约束
|
||
|
||
每个 Runtime Pod 内只能有一个 runtime agent 控制进程。一个用户实例对应一个 gateway 子进程和一个 workspace。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
CM["ClawManager Backend"]
|
||
POD["Runtime Pod"]
|
||
AG["runtime-agent"]
|
||
GW1["gateway: instance 101"]
|
||
GW2["gateway: instance 102"]
|
||
WS["/workspaces shared volume"]
|
||
|
||
CM -- "POST /v1/gateways" --> AG
|
||
CM -- "DELETE /v1/gateways/{id}" --> AG
|
||
CM -- "POST /v1/drain" --> AG
|
||
AG -- "register / heartbeat / metrics / gateways report" --> CM
|
||
AG --> GW1
|
||
AG --> GW2
|
||
GW1 --> WS
|
||
GW2 --> WS
|
||
```
|
||
|
||
浏览器只访问 ClawManager 的 HTTPS 入口。ClawManager 再反代到 Pod 内部 gateway。runtime agent 不应把每个 gateway 的自签 HTTPS 地址直接暴露给前端。
|
||
|
||
## 3. 必须遵守的原则
|
||
|
||
| 原则 | 要求 |
|
||
| --- | --- |
|
||
| 异步创建 | `POST /v1/gateways` 必须快速返回，通常 1 到 3 秒内返回 `status=starting`，不能阻塞等待业务 gateway 完全启动。 |
|
||
| 幂等创建 | 以 `instance_id + generation` 为主要幂等键，重复请求必须返回同一个 gateway 元数据，不能重复启动进程。 |
|
||
| 状态以真实进程为准 | `running` 只能在进程存在且健康检查通过时上报，不能只读旧缓存。 |
|
||
| 端口统一管理 | 端口由 agent 本地分配器加锁分配，启动前检查监听占用，停止后释放。 |
|
||
| 配置按 workspace 隔离 | 每个实例的 runtime 配置写入自己的 workspace，不能写全局配置。 |
|
||
| 不覆盖用户配置 | 修改 runtime 配置必须做 JSON merge，保留已有字段，数组 append 后去重。 |
|
||
| 不写死环境地址 | 不写死外部 IP、域名、CIDR，必须从 env 或 ClawManager 请求中读取。 |
|
||
| 内部服务优先 | runtime 内部访问 ClawManager 使用 Kubernetes Service DNS，不使用浏览器访问的外部地址。 |
|
||
| 时间必须可信 | token、设备签名、JWT 和 WebSocket 校验依赖时间，agent 必须检测时钟偏移，不能在明显偏移时报告健康。 |
|
||
| 安全默认开启 | 控制接口校验 token，路径校验不能越权，命令执行不能拼 shell 字符串。 |
|
||
|
||
## 4. Runtime Pod 环境变量
|
||
|
||
agent 至少支持以下环境变量：
|
||
|
||
| 变量 | 说明 |
|
||
| --- | --- |
|
||
| `CLAWMANAGER_RUNTIME_TYPE` | runtime 类型，例如 `openclaw`、`hermes`。 |
|
||
| `RUNTIME_WORKSPACE_ROOT` | workspace 根目录，默认 `/workspaces`。 |
|
||
| `RUNTIME_GATEWAY_PORT_START` | gateway 端口起始值，默认 `20000`。 |
|
||
| `RUNTIME_GATEWAY_PORT_END` | gateway 端口结束值，默认 `20099`。 |
|
||
| `RUNTIME_AGENT_CONTROL_TOKEN` | ClawManager 调 agent 控制接口使用。 |
|
||
| `RUNTIME_AGENT_REPORT_TOKEN` | agent 上报 ClawManager 使用。 |
|
||
| `CLAWMANAGER_BACKEND_URL` | ClawManager backend 内部地址，推荐 `http://clawmanager-gateway.clawmanager-system.svc.cluster.local:9001`。 |
|
||
| `RUNTIME_AGENT_LISTEN_ADDR` | agent 控制接口监听地址，默认 `0.0.0.0:19090`。 |
|
||
| `RUNTIME_AGENT_PUBLIC_PORT` | 注册给 ClawManager 的 agent 端口，默认 `19090`。 |
|
||
| `CLAWMANAGER_RUNTIME_IMAGE_REF` | 当前 runtime 镜像标识。 |
|
||
| `POD_NAME` / `POD_NAMESPACE` / `POD_IP` / `NODE_NAME` | 通过 Downward API 注入的 Pod 身份。 |
|
||
| `CLAWMANAGER_TRUSTED_PROXY_CIDRS` | ClawManager app 或 gateway Pod 的来源网段，供 runtime 的 trusted proxy 配置使用。 |
|
||
| `CLAWMANAGER_CONTROL_UI_ORIGIN` | ClawManager 内部 Control UI origin，默认可由 `CLAWMANAGER_BACKEND_URL` 推导。 |
|
||
|
||
要求：
|
||
|
||
- `CLAWMANAGER_BACKEND_URL` 必须是内部服务地址，不能使用 `https://172.16.1.12:39443` 这类浏览器外部入口。
|
||
- 只有对浏览器生成页面 URL 时才使用外部入口。runtime gateway 的信任来源和 LLM base URL 都应使用内部服务 DNS。
|
||
- agent 启动时要校验必填 env，缺失时上报 `unhealthy`，并在 `/v1/health` 返回 503。
|
||
|
||
## 5. Gateway 创建协议
|
||
|
||
ClawManager 调用：
|
||
|
||
```http
|
||
POST /v1/gateways
|
||
X-ClawManager-Control-Token: ${RUNTIME_AGENT_CONTROL_TOKEN}
|
||
Content-Type: application/json
|
||
```
|
||
|
||
请求字段以 `docs/clawmanager-agent-v2-contract.md` 为准，当前应支持：
|
||
|
||
```json
|
||
{
|
||
"instance_id": 123,
|
||
"user_id": 45,
|
||
"agent_type": "hermes",
|
||
"workspace_path": "/workspaces/hermes/user-45/instance-123",
|
||
"port_range": {
|
||
"start": 20000,
|
||
"end": 20099
|
||
},
|
||
"uid": 200123,
|
||
"gid": 200123,
|
||
"cpu_cores": 2,
|
||
"memory_mb": 4096,
|
||
"disk_quota_mb": 20480,
|
||
"generation": 7,
|
||
"environment": {
|
||
"CLAWMANAGER_LLM_BASE_URL": "http://clawmanager-gateway.clawmanager-system.svc.cluster.local:9001/api/v1/gateway/llm",
|
||
"CLAWMANAGER_LLM_API_KEY": "instance-token",
|
||
"CLAWMANAGER_LLM_MODEL": "[\"auto\"]",
|
||
"CLAWMANAGER_LLM_PROVIDER": "openai-compatible",
|
||
"CLAWMANAGER_INSTANCE_TOKEN": "instance-token",
|
||
"OPENAI_API_KEY": "instance-token"
|
||
}
|
||
}
|
||
```
|
||
|
||
成功响应必须快速返回：
|
||
|
||
```json
|
||
{
|
||
"gateway_id": "gw-123-7",
|
||
"instance_id": 123,
|
||
"port": 20017,
|
||
"pid": null,
|
||
"status": "starting",
|
||
"workspace_path": "/workspaces/hermes/user-45/instance-123"
|
||
}
|
||
```
|
||
|
||
创建流程：
|
||
|
||
1. 校验控制 token、`agent_type`、`instance_id`、`user_id`、`generation`、`workspace_path`、端口范围。
|
||
2. 检查当前 Pod 是否 draining。draining 时返回 409 或 503。
|
||
3. 按 `instance_id + generation` 查询本地状态。已存在 `starting` 或 `running` 时直接返回已有元数据。
|
||
4. 若收到更高 generation，停止并释放同实例旧 generation gateway。
|
||
5. 加锁分配端口，先标记 reserved。
|
||
6. 创建 workspace 和 home 目录，设置 owner 为请求中的 `uid/gid`。
|
||
7. 写入或合并 runtime 配置。
|
||
8. 记录 gateway 元数据为 `starting`。
|
||
9. 后台启动进程，立即返回。
|
||
10. 后台健康检查通过后，上报 `/api/v1/runtime-agent/gateways/report`，状态为 `running`。
|
||
11. 启动失败或健康检查失败时，上报 `error`，释放端口，并保留错误信息。
|
||
|
||
禁止事项：
|
||
|
||
- 禁止在 HTTP handler 里直接运行前台命令并等待它退出。
|
||
- 禁止同一个 create 请求触发多个 gateway 进程。
|
||
- 禁止把请求里的任意字符串拼接成 shell 命令。
|
||
- 禁止创建不在端口范围内的监听端口。
|
||
|
||
## 6. 端口和资源管理
|
||
|
||
agent 必须实现并发安全的端口分配器：
|
||
|
||
```text
|
||
reserve(instance_id, generation, count) -> port_set
|
||
commit(instance_id, generation, port_set)
|
||
release(instance_id, generation)
|
||
list_used()
|
||
```
|
||
|
||
要求：
|
||
|
||
- 分配时持有互斥锁。
|
||
- 在锁内检查 agent 内存状态和系统监听端口。
|
||
- runtime 如果需要主端口、control 端口、browser 端口或 sidecar 端口，必须一次分配一组端口。
|
||
- 启动失败、健康检查失败、DELETE 成功后必须释放端口。
|
||
- `used_slots` 来自真实 `starting` 和健康 `running` gateway 数量，不能来自旧缓存。
|
||
|
||
资源隔离要求：
|
||
|
||
- 每个 gateway 使用独立进程组。
|
||
- 业务进程最终以请求里的 `uid/gid` 运行。
|
||
- CPU、Memory 使用 cgroup 限制。
|
||
- Disk 使用 filesystem quota 或周期扫描加错误上报。
|
||
- 删除 gateway 不删除 workspace。
|
||
|
||
## 7. Workspace 和配置写入
|
||
|
||
workspace 固定格式：
|
||
|
||
```text
|
||
/workspaces/{runtime}/user-{user_id}/instance-{instance_id}
|
||
```
|
||
|
||
agent 必须：
|
||
|
||
- 对 workspace root 和请求路径执行 realpath。
|
||
- 拒绝 `..`、符号链接逃逸、跨用户或跨实例路径。
|
||
- 创建 `${workspace}/home`，并设置 `HOME=${workspace}/home`。
|
||
- 密钥、token、provider 配置文件权限建议 `0600`。
|
||
- owner 设置为该 gateway 的 `uid/gid`。
|
||
|
||
runtime 配置必须写在 workspace 内。例如：
|
||
|
||
| Runtime | 推荐配置路径 |
|
||
| --- | --- |
|
||
| OpenClaw | `{workspace}/home/.openclaw/openclaw.json` |
|
||
| Hermes | `{workspace}/home/.hermes/hermes.json` 或 Hermes 原生配置路径 |
|
||
|
||
JSON merge 规则：
|
||
|
||
- 对象字段递归 merge。
|
||
- 已存在字段默认保留。
|
||
- 平台必须控制的字段可以覆盖，但要在代码中显式列出。
|
||
- 数组字段 append 后去重，例如 `allowedOrigins`。
|
||
- 不删除用户已有的未知字段。
|
||
- 写入前先生成临时文件，再原子 rename。
|
||
|
||
## 8. AI Gateway 和模型凭证注入
|
||
|
||
ClawManager 会在 `POST /v1/gateways` 的 `environment` 字段中下发实例级 LLM 环境变量。agent 必须把这些变量传给 gateway 子进程，并按 runtime 需要写入配置文件。
|
||
|
||
允许转发给子进程的变量应使用白名单：
|
||
|
||
```text
|
||
CLAWMANAGER_LLM_BASE_URL
|
||
CLAWMANAGER_LLM_API_KEY
|
||
CLAWMANAGER_LLM_MODEL
|
||
CLAWMANAGER_LLM_PROVIDER
|
||
CLAWMANAGER_INSTANCE_TOKEN
|
||
OPENAI_BASE_URL
|
||
OPENAI_API_BASE
|
||
OPENAI_API_KEY
|
||
OPENAI_MODEL
|
||
```
|
||
|
||
要求：
|
||
|
||
- `CLAWMANAGER_LLM_BASE_URL` 使用 ClawManager 内部服务 DNS。
|
||
- `CLAWMANAGER_LLM_API_KEY` 和 `OPENAI_API_KEY` 使用当前实例 token。
|
||
- 不能要求用户在 runtime 页面手工填写 OpenAI key。
|
||
- 不能把 API key、实例 token、bootstrap token 打到日志。
|
||
- 如果 `environment` 里缺少 API key，agent 不应报告 gateway `running`，应上报 `error`，错误消息明确说明缺少实例 LLM token。
|
||
|
||
Hermes 落地时应把上述 env 转换成 Hermes 的 provider 配置，推荐语义：
|
||
|
||
```json
|
||
{
|
||
"models": {
|
||
"providers": {
|
||
"auto": {
|
||
"type": "openai-compatible",
|
||
"baseUrl": "${CLAWMANAGER_LLM_BASE_URL}",
|
||
"apiKey": "${CLAWMANAGER_LLM_API_KEY}"
|
||
}
|
||
},
|
||
"primary": "auto/auto"
|
||
}
|
||
}
|
||
```
|
||
|
||
如果 Hermes 使用不同配置 schema，也必须满足同样的安全和可用性要求：通过 ClawManager AI Gateway 访问模型，不在镜像内写死厂商 key。
|
||
|
||
## 9. 代理信任和浏览器访问
|
||
|
||
runtime gateway 在 Pod 内部推荐使用 HTTP。浏览器访问链路应为：
|
||
|
||
```text
|
||
Browser HTTPS -> ClawManager HTTPS -> ClawManager backend proxy -> Runtime Pod HTTP gateway
|
||
```
|
||
|
||
agent 写入 runtime 配置时必须配置：
|
||
|
||
- Control UI 的 `basePath` 为 `/api/v1/instances/{instance_id}/proxy`。
|
||
- 允许的 origin 使用 ClawManager 内部 origin，例如 `http://clawmanager-gateway.clawmanager-system.svc.cluster.local:9001`。
|
||
- trusted proxies 使用 `CLAWMANAGER_TRUSTED_PROXY_CIDRS` 或等价 env，不写死 `100.68.x.x`。
|
||
- 不使用外部地址 `https://172.16.1.12:39443` 作为 runtime 内部信任来源。
|
||
|
||
OpenClaw 参考配置：
|
||
|
||
```json
|
||
{
|
||
"gateway": {
|
||
"auth": {
|
||
"mode": "trusted-proxy"
|
||
},
|
||
"controlUi": {
|
||
"allowedOrigins": [
|
||
"http://clawmanager-gateway.clawmanager-system.svc.cluster.local:9001"
|
||
],
|
||
"basePath": "/api/v1/instances/123/proxy",
|
||
"dangerouslyDisableDeviceAuth": true
|
||
},
|
||
"trustedProxies": [
|
||
"100.68.0.0/16"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- `dangerouslyDisableDeviceAuth` 只能在 ClawManager trusted proxy 模式下使用。
|
||
- 如果 runtime 不支持 trusted proxy 模式，必须明确实现一种等价机制，保证浏览器通过 ClawManager 代理即可自动进入，不需要用户手工粘贴 gateway token。
|
||
- 如果出现 `origin not allowed`，优先检查 `allowedOrigins` 是否使用内部 origin，以及 WebSocket 代理是否正确传递 Origin。
|
||
- 如果出现 `Proxy headers detected from untrusted address`，优先检查 trusted proxies CIDR。
|
||
|
||
## 10. 时间同步规范
|
||
|
||
runtime 侧不能忽略时间问题。以下问题通常与时钟偏移有关：
|
||
|
||
- `device signature expired`
|
||
- token 未过期但被拒绝。
|
||
- JWT、签名 URL、WebSocket 鉴权异常。
|
||
- ClawManager 显示状态和 gateway 实际状态不一致。
|
||
|
||
agent 必须实现：
|
||
|
||
- 注册和 heartbeat 响应如果带 `server_time`，记录本地时间与服务端时间偏移。
|
||
- 若偏移超过 30 秒，在日志和 health 中上报 `clock_skew_warning`。
|
||
- 若偏移超过 120 秒，不应报告 `ready` 或 gateway `running`，应上报 `unhealthy` 或 `error`。
|
||
- 生成或校验任何带时间的签名时使用 UTC。
|
||
- 不在容器里自行修改系统时间。时间同步由 Kubernetes 节点的 NTP、chrony 或宿主机配置负责。
|
||
|
||
运维要求：
|
||
|
||
- 所有 Kubernetes 节点必须启用 NTP 或 chrony。
|
||
- 发现签名过期类错误时，先比较浏览器机器、ClawManager Pod、runtime Pod、Kubernetes Node 的 UTC 时间。
|
||
- agent 健康检查输出应包含当前本地时间、最近服务端时间和估算偏移，便于排查。
|
||
|
||
## 11. 状态上报和恢复语义
|
||
|
||
Runtime Pod 注册 payload 必须包含容量：
|
||
|
||
```json
|
||
{
|
||
"runtime_type": "hermes",
|
||
"capacity": 100,
|
||
"used_slots": 12,
|
||
"available_slots": 88,
|
||
"state": "ready",
|
||
"draining": false
|
||
}
|
||
```
|
||
|
||
Gateway report 每个 gateway 建议包含：
|
||
|
||
```json
|
||
{
|
||
"instance_id": 66,
|
||
"gateway_id": "gw-66-7",
|
||
"gateway_port": 20000,
|
||
"gateway_pid": 1234,
|
||
"state": "running",
|
||
"generation": 7,
|
||
"workspace_path": "/workspaces/hermes/user-1/instance-66",
|
||
"started_at": "2026-06-03T06:00:00Z",
|
||
"updated_at": "2026-06-03T06:00:10Z",
|
||
"error_message": ""
|
||
}
|
||
```
|
||
|
||
状态规则：
|
||
|
||
- `starting`：进程准备中或健康检查尚未通过。
|
||
- `running`：进程存在、端口监听、HTTP 健康检查通过、必要的代理和 LLM 检查通过。
|
||
- `error`：启动失败、配置失败、健康检查失败、凭证缺失或端口冲突。
|
||
- `stopped`：进程已停止，端口已释放。
|
||
- `unhealthy`：进程存在但健康检查失败。
|
||
|
||
Pod 重启或升级时：
|
||
|
||
- agent 启动后先初始化 workspace root、端口池、控制服务和报告客户端。
|
||
- 控制服务可用后注册 Runtime Pod。
|
||
- 只有初始化完成后才能上报 `ready`。
|
||
- 不要把旧 Pod 的 gateway 当成运行中，除非进程确实存在且健康。
|
||
- 收到 SIGTERM 时进入 draining，拒绝新 create，尽量上报最后状态。
|
||
- 支持 ClawManager 下发 drain、stop、restart gateway 指令。
|
||
|
||
## 12. 健康检查
|
||
|
||
`/v1/health` 只有在 agent 能接受控制指令时才返回 2xx。以下情况必须返回 503：
|
||
|
||
- 必填环境变量缺失。
|
||
- workspace root 不可访问。
|
||
- 端口池不可用。
|
||
- report token 或 control token 缺失。
|
||
- 时钟偏移超过健康阈值。
|
||
- agent 正在关闭且不再接受请求。
|
||
|
||
gateway 从 `starting` 转为 `running` 前至少校验：
|
||
|
||
- 端口已监听。
|
||
- HTTP `/` 或 runtime 约定健康端点可访问。
|
||
- 代理 base path 配置已写入。
|
||
- 使用 ClawManager 内部 Origin 的 Control UI 或 WebSocket 握手不再返回 `origin not allowed`。
|
||
- runtime 如果需要 LLM，使用实例 token 调用 ClawManager AI Gateway 可以返回模型列表或完成一次轻量探测。
|
||
|
||
健康检查失败时不要上报 `running`。应上报 `error`，并带短错误文本。
|
||
|
||
## 13. 安全规范
|
||
|
||
agent 控制接口必须校验：
|
||
|
||
- `X-ClawManager-Control-Token`。
|
||
- `instance_id`、`user_id`、`generation` 类型和值范围。
|
||
- `agent_type` 必须等于当前 Pod runtime type。
|
||
- `workspace_path` 不越权。
|
||
- 端口只能来自允许范围。
|
||
- `environment` 只允许白名单 key。
|
||
|
||
进程启动必须使用 argv 数组，不使用 shell 拼接：
|
||
|
||
```text
|
||
execve(binary, ["hermes", "gateway", "run", "--port", "20017"], env)
|
||
```
|
||
|
||
禁止：
|
||
|
||
- 把请求参数拼成 `sh -c`。
|
||
- 日志打印 token、API key、channel secret。
|
||
- 允许用户覆盖 agent 自己的控制 token 和上报 token。
|
||
- 删除 gateway 时顺手删除 workspace。
|
||
- 为了调通临时写死 IP、CIDR 或 `allowedOrigins=["*"]`，除非明确是本地开发环境。
|
||
|
||
## 14. Hermes Runtime 开发落地清单
|
||
|
||
开发 Hermes runtime 时，至少完成以下事项：
|
||
|
||
| 项目 | 要求 |
|
||
| --- | --- |
|
||
| Runtime 类型 | `CLAWMANAGER_RUNTIME_TYPE=hermes`，注册和上报 payload 中都使用 `hermes`。 |
|
||
| Agent 控制服务 | 监听 `0.0.0.0:19090`，实现 `/v1/health`、`/v1/gateways`、`DELETE /v1/gateways/{id}`、`/v1/drain`。 |
|
||
| Gateway 启动 | 后台启动 Hermes gateway，使用实例 workspace、端口、UID/GID、HOME。 |
|
||
| 配置文件 | 写入 `{workspace}/home/.hermes/hermes.json` 或 Hermes 原生配置，必须 JSON merge。 |
|
||
| AI Gateway | 将 `CLAWMANAGER_LLM_*` 和 `OPENAI_*` 注入 Hermes provider 配置。 |
|
||
| 代理路径 | Hermes UI 或 WebSocket 必须支持 `/api/v1/instances/{instance_id}/proxy` base path。 |
|
||
| Trusted proxy | 信任 ClawManager 内部 proxy 来源，不信任任意外部来源。 |
|
||
| 自动登录 | 浏览器通过 ClawManager proxy 进入时不要求手工粘贴 token 或重复确认自签证书。 |
|
||
| 端口组 | 如果 Hermes 除主端口外还有 control/browser/sidecar 端口，按端口组分配。 |
|
||
| Skills | skill inventory 和状态上报按 `instance_id`、`workspace_path` 分组。 |
|
||
| 时间 | 实现 clock skew 检测；偏移过大时不报告 ready/running。 |
|
||
| 验收 | 100 个实例并发创建无端口冲突，Pod drain 和重启后状态正确。 |
|
||
|
||
Hermes 启动命令由 Hermes 项目确定，但 agent 必须保证：
|
||
|
||
- 命令参数固定且可审计。
|
||
- 端口和 workspace 只能来自 agent 校验后的值。
|
||
- LLM、proxy、auth 配置在进程启动前已经写入。
|
||
- `POST /v1/gateways` 返回时进程可以仍在启动，但 metadata 必须已经持久化。
|
||
|
||
## 15. 测试和验收
|
||
|
||
单元测试至少覆盖：
|
||
|
||
- create gateway 幂等。
|
||
- 高 generation 替换低 generation。
|
||
- 端口分配并发无冲突。
|
||
- 端口被系统占用时跳过。
|
||
- workspace path 越权被拒绝。
|
||
- JSON merge 保留用户字段，数组去重。
|
||
- LLM env 白名单转发。
|
||
- 缺少 LLM token 时 gateway 不报告 running。
|
||
- trusted proxy 和 allowed origin 配置生成。
|
||
- clock skew 阈值判断。
|
||
|
||
集成测试至少覆盖：
|
||
|
||
- Runtime Pod 注册为 `ready`，capacity、used_slots、available_slots 正确。
|
||
- 创建 100 个 gateway，端口唯一，状态最终为 running。
|
||
- 重复创建同一个 `instance_id + generation` 不重复启动进程。
|
||
- ClawManager 反代 WebSocket 不出现 `origin not allowed`。
|
||
- 通过 ClawManager proxy 进入 runtime 不要求手工粘贴 gateway token。
|
||
- runtime 内模型调用经过 ClawManager AI Gateway，不出现 `No API key found`。
|
||
- Pod drain 后拒绝新 create，已有 gateway 持续上报，DELETE 后释放端口。
|
||
- Pod 重启后不误报旧 gateway running。
|
||
|
||
上线前 Kubernetes 验证建议：
|
||
|
||
```bash
|
||
kubectl -n clawmanager-system get pods -l app.kubernetes.io/component=runtime-agent -o wide
|
||
kubectl -n clawmanager-system logs deploy/hermes-runtime --tail=200
|
||
kubectl -n clawmanager-system exec deploy/hermes-runtime -- curl -fsS http://127.0.0.1:19090/v1/health
|
||
kubectl -n clawmanager-system exec deploy/hermes-runtime -- date -u
|
||
kubectl -n clawmanager-system exec deploy/clawmanager-app -- date -u
|
||
```
|
||
|
||
如果出现认证或签名问题，排查顺序：
|
||
|
||
1. 时间偏移。
|
||
2. 实例 token 是否下发到 `environment`。
|
||
3. runtime 配置文件是否包含 provider 和 API key。
|
||
4. ClawManager 内部 LLM base URL 是否可达。
|
||
5. allowed origins 和 trusted proxies 是否使用内部服务地址和 env CIDR。
|
||
6. gateway 是否真正健康，而不是缓存状态误报。
|
||
|
||
## 16. Do / Don't
|
||
|
||
| Do | Don't |
|
||
| --- | --- |
|
||
| 用内部 Kubernetes Service DNS 配置 runtime 到 ClawManager 的访问。 | 写死 `172.16.1.12`、NodePort、外部 HTTPS 入口。 |
|
||
| `POST /v1/gateways` 快速返回 `starting`，后台拉起进程。 | 在 HTTP 请求里阻塞等待 `gateway run` 前台进程。 |
|
||
| 按 `instance_id + generation` 幂等。 | 重试时重复启动多个 gateway。 |
|
||
| 上报状态前检查真实进程和健康。 | 只读旧状态文件就上报 `running`。 |
|
||
| JSON merge runtime 配置。 | 覆盖用户的整个配置文件。 |
|
||
| 白名单转发 env。 | 把用户请求里的所有 env 原样传给进程。 |
|
||
| 使用 trusted proxy 让浏览器通过 ClawManager 自动进入。 | 要求用户手工粘贴 gateway token。 |
|
||
| 检测并上报 clock skew。 | 忽略时间，导致 `device signature expired` 反复出现。 |
|