docs: 记录 D601 F103 device-pod gateway SOP

2026-05-31 15:57:27 +08:00
parent 153156768d
commit 7bad130e5d
1 changed files with 77 additions and 0 deletions
@@ -270,6 +270,83 @@ manages: many devicePodId
 - mutating job 继续由 cloud-api 侧强制 lease/reason；CLI 只转发 `reason` 和 `leaseToken`，不在本地绕过。
 - `profile create` 这类本地 profile bootstrap 在正式默认路径中返回 `legacy_profile_create_removed`；管理员应使用 cloud-api admin API 管理服务端 profile/grant。

+## D601 F103 v0.2 Gateway SOP
+
+D601 Windows F103 gateway 的稳定命名使用 `gws_D601_F103`。不要因为当前 `devicePodId` 或样例设备名是 `device-pod-71-freq` / `71-FREQ`，把 gateway session 改成旧的 `gws_d601_win_71_freq`；profile route 和 Windows gateway 运行脚本必须使用同一组 F103 命名。
+
+Windows 侧固定入口：
+
+```text
+Task Scheduler: HWLAB-DevicePodGateway-D601-F103
+run script: C:\Users\liang\device-pod-gateway-rust\run-D601-F103.cmd
+local status: http://127.0.0.1:7001/status
+cloud API: http://74.48.78.17:19667
+```
+
+`run-D601-F103.cmd` 中的关键环境变量应保持为：
+
+```cmd
+set "HWLAB_GATEWAY_CLOUD_URL=http://74.48.78.17:19667"
+set "HWLAB_GATEWAY_ID=gtw_D601_F103"
+set "HWLAB_GATEWAY_SESSION_ID=gws_D601_F103"
+set "HWLAB_GATEWAY_RESOURCE_ID=res_windows_host"
+set "HWLAB_GATEWAY_BOX_ID=box_windows_host"
+set "HWLAB_GATEWAY_CMD_CAPABILITY_ID=cap_windows_cmd_exec"
+set "HWLAB_GATEWAY_CMD_EXEC_ENABLED=1"
+set "HWLAB_GATEWAY_MAX_INFLIGHT=4"
+set "HWLAB_GATEWAY_CMD_TIMEOUT_MS=120000"
+set "HWLAB_GATEWAY_PORT=7001"
+```
+
+v0.2 `device-pod-71-freq` 的服务端 profile route 必须和 gateway 注册保持一致：
+
+```json
+{
+  "gatewaySessionId": "gws_D601_F103",
+  "resourceId": "res_windows_host",
+  "capabilityId": "cap_windows_cmd_exec",
+  "hostWorkspaceRoot": "F:\\Work\\ConStart",
+  "hostCli": "node C:\\Users\\liang\\AppData\\Local\\Temp\\hwlab-v02-device-host-cli\\device-host-cli.mjs"
+}
+```
+
+重启 gateway 时使用计划任务，不从临时 shell 直接启动长期进程：
+
+```cmd
+schtasks /End /TN HWLAB-DevicePodGateway-D601-F103
+schtasks /Run /TN HWLAB-DevicePodGateway-D601-F103
+powershell -NoProfile -Command "Invoke-RestMethod http://127.0.0.1:7001/status | ConvertTo-Json -Depth 12"
+```
+
+通过 UniDesk Windows route 操作时，工作目录应直接定位到 gateway 目录，例如 `D601:win/c/Users/liang/device-pod-gateway-rust`，再读取 `run-D601-F103.cmd` 或查询 `/status`。`/status` 中至少应看到 `gatewaySessionId=gws_D601_F103`、`cloudUrl=http://74.48.78.17:19667`、`session.status=connected`、`outbound.lastPollError=null`。
+
+G14 v0.2 验收在 `G14:/root/hwlab-v02` 执行，先确认 Cloud Web 同源 CLI 能看到 device pod 状态，再用正式 `device-pod-cli` 创建并轮询 job：
+
+```bash
+bun tools/hwlab-cli/bin/hwlab-cli.ts client device-pods status device-pod-71-freq \
+  --base-url http://74.48.78.17:19666 \
+  --full
+
+COOKIE=$(node -pe 'require("./.state/hwlab-cli/session.json").cookie')
+bun tools/device-pod-cli.ts device-pod-71-freq:workspace:/ ls \
+  --api-base-url http://74.48.78.17:19667 \
+  --cookie "$COOKIE" \
+  --reason "v02 gws_D601_F103 smoke" \
+  --timeout-ms 120000 | tee /tmp/hwlab-device-pod-job.json
+
+JOB=$(node -e 'const fs=require("fs"); const payload=JSON.parse(fs.readFileSync("/tmp/hwlab-device-pod-job.json", "utf8")); console.log(payload.body.job.id)')
+
+bun tools/device-pod-cli.ts job status --pod-id device-pod-71-freq "$JOB" \
+  --api-base-url http://74.48.78.17:19667 \
+  --cookie "$COOKIE"
+
+bun tools/device-pod-cli.ts job output --pod-id device-pod-71-freq "$JOB" \
+  --api-base-url http://74.48.78.17:19667 \
+  --cookie "$COOKIE"
+```
+
+验收通过条件：`client device-pods status` 返回 `status=ok` 且 `blocker=null`；gateway sessions 中 `gws_D601_F103` 为 online；`device-pod-cli` job 进入 `completed`，且 D601 Windows gateway `/status.lastDispatch.operationId` 与该 job 的 `operationId` 一致并有 `lastResultAt`。旧 `gws_d601_win_71_freq` session 只能作为历史 stale 线索，不能作为 v0.2 F103 gateway 的目标命名。
+
 ## 测试规格

 ## T1