排障与设备维护

错误码对照、连通性自检、设备恢复与指定设备。能力参数见能力参考。

1. 管理接口速查

接口	用途
`GET admin/capabilities/`	机器可读能力目录
`GET admin/devices/online/?capability=script`	选设备（权威 presence 口径）
`POST admin/tasks/`	201 即时下发／202 排队＋status_url
`GET admin/tasks/<id>/`	轮询；pending 期字段为 `null`
`GET admin/tasks/<id>/logs/?limit=100`	执行日志（level/since 可过滤）
`GET admin/tasks/?status=&type=&device_id=`	列表（cursor 分页）
`POST admin/tasks/<id>/cancel/`	取消任务（仅 pending / dispatched 状态可用）
`GET/PUT admin/devices/<id>/shadow/`	查影子／写 desired（PUT 带当前 version，409 则重取再试）
`GET admin/models/`	模型登记表（name/version/sha256/qiniu_key）
`POST admin/models/assignments/`	把某版本模型分配给设备
`GET admin/models/deliveries/`	分发看板（installed / confirmed / failed）
`POST admin/models/rollback/`	回滚到指定版本（重写 current 指针）

2. 错误对照

下表是所有能力共用的传输层与调度层错误。每项能力特有的失败模式（参数形状、模型缺失、权限不足等）列在该项的「注意」里。

错误	含义	处理
`401`	Key 无效/缺失	核对 `$KEY`
`403`	设备已吊销，或下载跨命名空间对象	换设备；改用本设备命名空间内的 key
`404`	设备/任务不存在	核对 id
`409 DEVICE_OFFLINE`	指定设备离线	换在线设备或不指定走自动调度
`409 CONFLICT`	影子版本冲突/任务不可取消	GET 最新 version 重试
任务 `failed`	执行层失败	看 `task.error`
`success` 但 `result.error`	端侧回绝（最常见：args 传参风格写错）	对照「两种 args 传参约定」一节
任务长时间 `running` 后转 `failed`	超出后端时间预算被提前终止	调大 `timeout_sec`
`429`	超出调用频率上限	等待当前 60 秒窗口结束后重发，见参考页 §3.3
任务 `timeout`	超过 `timeout_sec` 未完成	调大 `timeout_sec` 后重发，见参考页 §3.4
WS 大输出失败	设备版本低于 2.0.53，单包上限 1 MB	升级设备版本，或改用 `rknn.detect`

3. 连通性自检

任何能力报 409 DEVICE_OFFLINE 或长时间无回包时，先跑这一条确认下发与回传通路正常。它不承载业务能力，只验证鉴权、下发、执行、回传四步能否走通，无副作用。

post_task custom '{"subtype":"ping"}' "acme-ping-001"   # 不传设备, 交由自动派发
# → {"status":"success","result":{"pong":true,"ts":1789105290288}}
# 判定: status=success 且 result.pong=true

若本条也不通，问题在鉴权或调度侧，与具体能力无关。

4. 设备自愈与状态

下面四条针对设备自身，不属于能力清单，因此没有编号。仅在任务反复失败、需要人工将节点恢复可用时使用。

# 采集设备型号/系统版本/内存/存储/运行时长, 排查问题时先看这条
post_task command '{"command":"report_status"}' "acme-rep-001"
# 立即让设备上报一次当前配置与运行指标
post_task command '{"command":"sync_config"}' "acme-sync-001"
# 磁盘吃紧或缓存污染时清理缓存(不会删除已同步的模型目录)
post_task command '{"command":"clear_cache"}' "acme-cc-001"
# 进程状态异常时重启 App, 设备会短暂离线约 10-20s 后自动重连
post_task command '{"command":"agent_restart"}' "acme-rs-001"

只想换 JS 逻辑而不重启进程，用 system.reload；它属于能力清单里的逻辑下发。

5. 指定设备

只有当你要把任务钉在某一台特定机器上（例如对比不同硬件的结果）才需要这个接口。日常集成请不要用它——设备会上下线，硬编码 id 是最常见的失败原因。

curl -s "${H[@]}" "$BASE/admin/devices/online/?capability=script"
# → {"success":true,"code":"OK","count":13,"authoritative":"redis-presence",
#    "results":[{"device_id":"edge_0e38…","status":"ACTIVE","is_online":true,…}]}

post_task script '{"module":"vision","func":"image_labeling","args":["a.png",0.5]}' "acme-x-001" "edge_0e38…"

authoritative 恒为 redis-presence（权威在线口径，与调度器同口径）；capability 可过滤 script/command/file/custom；status 为 ACTIVE/OFFLINE/REVOKED。指定了离线设备会返回 409 DEVICE_OFFLINE。