巡检服务观察 API

since vid-inspect 1.2.0

本页接口跑在 vid-inspect 进程 上（独立观察端口，默认本机 18288），不是 流媒体 POST /v1/vid_inspect 所在的端口。创建/查询巡检任务仍走 streaming，见 巡检抓拍 API 使用说明。

配置（config.json）：

"http": {
  "port": 18288,
  "token": "observe-token"
}

• port == 0 或缺 http：不绑定端口，与无 HTTP 的 worker 行为一致。
• 只读；快照 best-effort、非事务，与真实队列可差数毫秒。
• 高频轮询建议 ≥ 200ms。
• 列表最多 200 条，超出只返回队头并设 truncated: true。

查询就绪与限额

GET /v1/info

无需 token（与 streaming /v1/info 同类）。响应不含 http.token。

GET http://127.0.0.1:18288/v1/info
Accept: application/json

应答实体属性

属性	类型	说明
appId	string	出站调用 streaming 所用 appId
mqReady	boolean	MQ 已启动、Master 进入调度
zkLocked	boolean	已拿到 ZooKeeper 执行锁
maxConcurrentTasks	int	全局并发上限
maxQueuedTasks	int	Master 等待队列上限
executingCount	int	当前占用的全局槽位数
waitQueueSize	int	Master waitQueue 长度
termCount	int	已创建的终端调度器数

{
  "errCode": 0,
  "data": [{
    "appId": "app",
    "mqReady": true,
    "zkLocked": true,
    "maxConcurrentTasks": 2,
    "maxQueuedTasks": 200,
    "executingCount": 1,
    "waitQueueSize": 3,
    "termCount": 2
  }]
}

mqReady == false 时不宜跑巡检自动化。

查询内存调度快照

GET /v1/queue

需要 头 X-Auth-Token 等于配置 http.token（vid-inspect 无用户库，不走 streaming login）。无 token / 错 token 拒绝（非 2xx，不是空队列冒充成功）。

队内已按 (priority DESC, reqTm ASC)。元素只含调度字段（taskId、simNo、priority、reqTm），不含文件路径、token、密码。

GET http://127.0.0.1:18288/v1/queue
Accept: application/json
X-Auth-Token: observe-token

应答实体属性

属性	类型	说明
maxConcurrentTasks	int	全局并发上限
maxQueuedTasks	int	等待队列上限
executingCount	int	全局占用槽位
truncated	boolean	任一列表超过 200 条被截断
waitQueue	array	Master 等待队列（队头在前）
terms	array	每终端：simNo、executingTaskId、pending[]

waitQueue[] / pending[] 元素：taskId、simNo（wait 层）、priority、reqTm（yyyy-MM-dd HH:mm:ss）。

{
  "errCode": 0,
  "data": [{
    "maxConcurrentTasks": 10,
    "maxQueuedTasks": 200,
    "executingCount": 1,
    "truncated": false,
    "waitQueue": [
      { "taskId": "...", "simNo": "8888000001", "priority": 2, "reqTm": "2026-08-26 16:01:02" }
    ],
    "terms": [
      {
        "simNo": "8888000001",
        "executingTaskId": "aaa",
        "pending": [
          { "taskId": "bbb", "simNo": "8888000001", "priority": 2, "reqTm": "..." },
          { "taskId": "ddd", "simNo": "8888000001", "priority": 1, "reqTm": "..." }
        ]
      }
    ]
  }]
}

POST /v1/vid_inspect（streaming）仍阻塞到 CREATED（约 10s）。观察 API 不改变 该契约。要看 Term pending 而不是 Master waitQueue，须 maxConcurrentTasks ≥ 突发条数。