feat: wire device pod gateway dispatch

2026-05-29 10:44:59 +08:00
parent dfc1b42fe3
commit 4cdc80e672
12 changed files with 543 additions and 18 deletions
@@ -269,6 +269,6 @@ manages: many devicePodId
 | 逻辑 device-pod 模型 | 已实现为规格 | 四要素、profile shape 和 Kubernetes 口径已定义。 |
 | profile server authority | 部分实现 | cloud-api 保存正式 DB profile 并向用户返回脱敏摘要；device-pod executor 不接受用户上传 profile。 |
 | 用户 grant + lease | 部分实现 | cloud-api 已实现 admin grant、可见性过滤、lease acquire/current/release、强副作用 job lease 校验和撤销授权释放 lease。 |
-| REST/job API | 部分实现 | cloud-api 已实现 list/status/events/probe/job/output/cancel 和 lease API，并可把已授权 job 转发给内部 `hwlab-device-pod` executor；executor 已实现内部 job create/get/output/cancel lifecycle，无在线 gateway/device-host-cli 时返回 blocker。 |
+| REST/job API | 部分实现 | cloud-api 已实现 list/status/events/probe/job/output/cancel 和 lease API，并可把已授权 job 转发给内部 `hwlab-device-pod` executor；executor 已实现内部 job create/get/output/cancel lifecycle 和 gateway/device-host-cli dispatch adapter，无在线 gateway/device-host-cli 时返回 blocker。 |
 | 禁止 fake 作为 DEV-LIVE | 已实现/持续约束 | 规格和服务 payload 要求显式标记 fake/source。 |

@@ -34,6 +34,7 @@
 | `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/internal/device-pod/gateway-dispatch` | 仅接受 `hwlab-device-pod` 内部服务凭据，用于把 executor job dispatch 到 gateway poll/result；普通用户和 Code Agent 不可调用。 |
 | `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-user-access.md) 和 [spec-device-pod.md](spec-device-pod.md)。
@@ -60,6 +61,6 @@
 | 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 | 部分实现 | profile/grant/list/status/job 持久化在 cloud-api；无在线 gateway/device-host-cli 时返回 blocker。 |
+| device-pod 正式权限/profile/job | 部分实现 | profile/grant/list/status/job 持久化在 cloud-api；已提供内部 gateway dispatch route 供 `hwlab-device-pod` executor 下发到 device-host-cli，无在线 gateway/device-host-cli 时返回 blocker。 |
 | v0.2 admin/user 权限模型 | 部分实现 | `/auth/*`、admin user/device-pod/grant API 和 Code Agent owner binding 已接入；生产 bootstrap 依赖 SecretRef。 |

@@ -14,6 +14,7 @@
 - `cmd/hwlab-device-pod/main.ts` 返回 `contractVersion=device-pod-executor-v1`，并声明 `authority=hwlab-cloud-api`、`fake=false`。
 - `internal/device-pod/fake-data.mjs` 只保留为 legacy 前端/smoke fixture，不是 `hwlab-device-pod` 服务运行契约。
 - `HWLAB_DEVICE_POD_ID` 可指定默认 executor devicePodId；正式 profile 仍由 `hwlab-cloud-api` 的 `device_pods.profile_json` 管理。
+- `HWLAB_CLOUD_API_INTERNAL_URL` 配置后，executor 可用内部服务凭据回调 `hwlab-cloud-api` 的 gateway dispatch route，把已授权 job 下发到 gateway/device-host-cli；未配置、profile route 缺失或 gateway 不在线时返回 blocker。

 ## API 接口说明

@@ -23,7 +24,7 @@
 | `GET /v1/device-pods` | 返回 executor boundary 摘要，不表达用户可见 device pod authority。 |
 | `GET /v1/device-pods/{devicePodId}/status` | 返回 blocked executor status；真实 profile/status 以 cloud-api `/v1/device-pods/{devicePodId}/status` 为准。 |
 | `GET /v1/device-pods/{devicePodId}/events` | 返回 bounded executor boundary event，不伪造硬件事件。 |
-| `POST /v1/device-pods/{devicePodId}/jobs` | 只接受 `hwlab-cloud-api` 内部调用；创建内部 executor job 并返回 job、freshness、output/cancel URL；当前无 gateway/device-host-cli 连接时返回 `gateway_dispatch_unavailable`。 |
+| `POST /v1/device-pods/{devicePodId}/jobs` | 只接受 `hwlab-cloud-api` 内部调用；创建内部 executor job 并返回 job、freshness、output/cancel URL；有可用 profile route 和 `HWLAB_CLOUD_API_INTERNAL_URL` 时通过 cloud-api gateway dispatch 下发到 device-host-cli，否则返回 `gateway_dispatch_unavailable`。 |
 | `GET /v1/device-pods/{devicePodId}/jobs/{jobId}`、`GET /output`、`POST /cancel` | 只接受 `hwlab-cloud-api` 内部调用，用于查询内部 job、bounded output 和取消非终态 job；普通用户仍必须走 cloud-api 用户态 API。 |

 用户态 `POST /jobs`、job output/cancel 和 admin profile/grant API 由 `hwlab-cloud-api` 实现，应以 [spec-device-pod.md](spec-device-pod.md) 为目标。
@@ -45,6 +46,6 @@
 | health 和 executor boundary REST | 已实现 | 服务声明内部 executor、cloud-api authority 和非 fake 来源。 |
 | bounded events/status | 已实现 | 只返回 executor boundary/blocker，不伪造硬件事件。 |
 | 正式 profile authority | 已在 cloud-api 实现 | `hwlab-device-pod` 不读取或覆盖 `device_pods.profile_json`。 |
-| job lifecycle | 部分实现 | 用户态 job 由 cloud-api 鉴权、授权、lease 校验和持久化；executor 侧已提供内部 job create/get/output/cancel lifecycle，当前执行结果仍受 gateway/device-host-cli adapter 可用性限制。 |
-| gateway/device-host-cli adapter | 部分实现 | cloud-api 已能向 gateway registry 分发；无在线 gateway 时返回 blocker。 |
+| job lifecycle | 部分实现 | 用户态 job 由 cloud-api 鉴权、授权、lease 校验和持久化；executor 侧已提供内部 job create/get/output/cancel lifecycle，并能把 job dispatch 结果写回 bounded output。 |
+| gateway/device-host-cli adapter | 部分实现 | executor 已通过 cloud-api internal dispatch 接入 gateway poll/result 和 device-host-cli 命令映射；真实执行仍依赖 profile route、在线 gateway 和 host CLI。 |

@@ -6,6 +6,7 @@

 - 接收 FRP 转入的 API/health 请求，并代理到 `hwlab-cloud-api:6667`。
 - `/health/live` 必须透传 cloud-api live health，因此公网 API readiness 以 cloud-api 为准。
+- `/v1/internal/*` 是集群内部服务路由，必须在 public edge 上 fail-closed，不透传到 cloud-api。
 - 不实现业务 API，不读取 Secret，不替代 cloud-api 权限和 runtime readiness。

 ## 内部架构
@@ -21,6 +22,7 @@
 | `GET /health/live` | 代理到 upstream `/health/live`，代表公网 API live readiness。 |
 | `GET /health`、`GET /edge/health` | 返回 edge-proxy 自身 health 和 upstream 配置。 |
 | `GET /status`、`GET /routes` | 返回代理路由表。 |
+| `/v1/internal/*` | 公网 edge 返回 `404`，不代理内部服务路由。 |
 | 其他路径 | 透明代理到 `hwlab-cloud-api`。 |

 ## 测试规格
@@ -37,8 +39,9 @@

 | 规格项 | 状态 | 说明 |
 | --- | --- | --- |
-| API edge proxy | 已实现 | 其他路径透明代理 cloud-api。 |
+| API edge proxy | 已实现 | 用户态路径透明代理 cloud-api。 |
 | live health 透传 | 已实现 | `/health/live` 代理 upstream。 |
+| internal route 阻断 | 已实现 | `/v1/internal/*` 不经 public edge 暴露。 |
 | 长请求 timeout | 已实现 | 默认支持 Code Agent 长窗口。 |
 | 业务权限/鉴权 | 不在本服务 | 由 cloud-api 承担。 |