v0.2 hwlab-cloud-api 服务规格

hwlab-cloud-api 是 v0.2 应用层核心服务，运行在 hwlab-v02 namespace，内部端口 6667，公网经 hwlab-edge-proxy 和 FRP 暴露为 http://74.48.78.17:19667。

在系统中的职责划分

承担 runtime health、DB readiness、Code Agent 对话、trace/result 轮询、gateway outbound registry、M3 IO 控制、device-pod 只读代理和 live build inventory。
是 hwlab-cloud-web、Code Agent session、device-pod 用户态操作和 gateway outbound poll 的唯一应用层收口点。
读取 hwlab-cloud-api-v02-db/database-url、hwlab-v02-code-agent-provider/openai-api-key 和 hwlab-v02-code-agent-codex-auth/auth.json 等 v02 独立 SecretRef；文档和日志只允许记录 SecretRef 名称、key、字节数或哈希指纹，不记录值。

内部架构

cmd/hwlab-cloud-api/main.ts 负责启动 HTTP server、解析端口和 Code Agent timeout。
internal/cloud/server.ts 负责 HTTP route、REST/RPC bridge、health、live-builds、device-pod proxy、gateway poll/result 和 Code Agent chat。
internal/db/runtime-store.ts 和 internal/cloud/db-contract.ts 负责 Postgres runtime store 与 readiness 分层。
internal/cloud/code-agent-*.ts 负责 Codex stdio session、trace store、result cache、provider profile 和取消/轮询。
同 Pod sidecar hwlab-codex-api-forwarder 监听 127.0.0.1:49280/responses，用于 codex-api profile 直连 hyueapi，并保持 hyueapi 在 NO_PROXY 中。
hwlab-code-agent-workspace PVC 挂载到 /workspace/hwlab，用于长会话 workspace；它是 cloud-api 运行资源，不是独立用户入口。

API 接口说明

接口	说明
`GET /health`、`GET /health/live`	返回 service identity、environment、revision、DB/runtime/Code Agent readiness 和 blocker。
`GET /live`	轻量 live 标记。
`GET /v1`	REST adapter 索引、RPC 方法、runtime readiness 和 device-pod/M3 能力摘要。
`POST /rpc`、`POST /json-rpc`	JSON-RPC 入口，支持 system、adapter、gateway、hardware、audit、evidence 和 M3 方法。
`POST /v1/rpc/{method}`	REST 到 JSON-RPC 的桥接入口。
`GET /v1/device-pods...`	代理到 `hwlab-device-pod`；上游不可用时当前会返回 fake fallback，并必须标明来源。
`GET /v1/m3/status`、`POST /v1/m3/io`	M3 只读/受控 IO 入口；写操作必须有明确 approval。
`GET /v1/diagnostics/gate`、`GET /v1/live-builds`	诊断和 live build inventory。
`GET /v1/gateway/sessions`、`POST /v1/gateway/poll`、`POST /v1/gateway/result`	gateway 主动出站注册、取任务和回传结果。
`POST /v1/agent/chat`、`GET /v1/agent/chat/result/{traceId}`、`GET /v1/agent/chat/trace/{traceId}`、`POST /v1/agent/chat/cancel`	Code Agent 短连接提交、轮询、trace 和取消。

用户、权限、device-pod 管理 API 的最终规格见 spec-user-access.md 和 spec-device-pod.md；当前实现尚未完整落地 admin/user 表和授权链路。

测试规格

T1

阅读 docs/reference/spec-v02-hwlab-cloud-api.md，然后用 cli 手动测试以下内容：访问 http://74.48.78.17:19667/health/live，确认 environment=v02、ready=true、DB runtime 为 Postgres，且响应不包含 Secret 值。

T2

阅读 docs/reference/spec-v02-hwlab-cloud-api.md，然后用 cli 手动测试以下内容：使用短连接 POST /v1/agent/chat 提交一次对话，再轮询 /v1/agent/chat/result/{traceId}，只有 status=completed 且 assistant reply 非空才算 Code Agent 通过。

T3

阅读 docs/reference/spec-v02-hwlab-cloud-api.md，然后用 cli 手动测试以下内容：访问 /v1/device-pods 和一个 device-pod status route，确认响应标明来自 hwlab-device-pod 或明确 fake fallback，不得把 fake fallback 写成真实硬件 DEV-LIVE。

规格的实现情况

规格项	状态	说明
health/readiness	已实现	`/health/live` 汇总 DB、runtime、Code Agent 和 blocker。
Code Agent 短连接 submit/result/trace/cancel	已实现	repo-owned Codex stdio 和 provider profile 已接入。
Postgres durable runtime	已实现	通过 v02 独立 DB SecretRef 和 migration ledger 判定。
gateway outbound poll/result	已实现	支持 gateway 主动轮询和 `hardware.invoke.shell` 分发。
device-pod 正式权限/profile/job	未完全实现	当前主要是只读 proxy/fake fallback；正式规格见 device-pod specs。
v0.2 admin/user 权限模型	未完全实现	表结构和 API 规格已定义，完整应用层鉴权仍待实现。

4.6 KiB Raw Blame History