# PiStudio 云渲染 `/status` 对接
# PiStudio 云渲染 `/status` 对接
云渲染服务地址默认 `http://{主机}:5050`。启动或重连前调用 `GET /status`,用 **PiStudio 项目 ID** 在返回的 `tasks` 里找任务。`streamUrl` 非空只说明推流地址已经就绪,接下来先连 `wsUrl` 做保活,再用 `streamUrl` 调用 `cloudrender.init` 拉起画面。
`/status` 不带项目 ID,一次返回整个集群的节点和任务。项目 ID 由调用方自己在 `tasks` 里匹配。
## 请求
```httpGET http://192.168.1.10:5050/status```
无路径参数,无 query,无 body。
## 响应
```json{ "name": "cluster-a", "status": "running", "lastActiveTime": "2026-10-26T10:00:00", "nodeCount": 1, "freeSlot": 1, "maxSlot": 2, "taskCount": 1, "maxTask": 100, "type": 0, "nodes": [ { "name": "node-1", "ip": "192.168.1.11", "gpu": "RTX 4090", "maxTask": 2, "tasks": 1, "status": "running", "project": null, "lastActiveTime": "2026-10-26T10:00:00", "type": 0 } ], "tasks": [ { "id": 18, "state": 1, "requestTime": "2026-10-26T10:00:01", "startTime": "2026-10-26T10:00:05", "projectId": "12345", "projectName": "示例项目", "userIp": "192.168.1.20", "userName": "", "nodeIp": "192.168.1.11", "nodeName": "node-1", "streamerPort": 0, "httpPort": 0, "sfuPort": 0, "clientPID": 0, "viewUrl": "", "streamUrl": "ws://192.168.1.11:88", "wsUrl": "ws://192.168.1.10:5050/ws", "error": "", "sessionCount": 1, "sessions": [ { "tabId": "7c1e...", "userIp": "192.168.1.20", "startTime": "2026-10-26T10:00:06" } ] } ]}```
字段以服务实际返回为准。上面的值只说明结构。
### 集群
| 字段 | 含义 || --- | --- || `name` | 集群名称 || `status` | 集群状态 || `lastActiveTime` | 最近活跃时间 || `nodeCount` | 节点数 || `freeSlot` | 空闲槽位。大于 0 表示还能新开一路 || `maxSlot` | 槽位上限。节点上没有 `maxTask` 时才用它做容量 || `taskCount` | 当前任务数 || `maxTask` | 根上的线程上限。可能是占位大数,不能单独拿它和 `taskCount` 比 || `nodes` | 渲染节点 || `tasks` | 当前推流任务 || `type` | 集群类型 |
### 节点 `nodes[]`
| 字段 | 含义 || --- | --- || `name` / `ip` | 节点名、地址 || `gpu` | GPU 信息,可能为空 || `maxTask` | 该节点最多同时跑几路。各节点相加才是集群真实线程数 || `tasks` | 该节点上已有任务数 || `status` | 节点状态 || `project` | 节点当前项目,可能为空 || `lastActiveTime` | 最近活跃时间 |
### 任务 `tasks[]`
| 字段 | 含义 || --- | --- || `id` | 任务 ID。后续保活、释放都用它 || `projectId` | PiStudio 项目 ID。类型可能是字符串或数字,比较时转成字符串 || `projectName` | 项目名 || `state` | 任务状态码 || `requestTime` / `startTime` | 请求时间、启动时间 || `nodeIp` / `nodeName` | 落在哪台节点 || `streamUrl` | 渲染信令地址。交给 `cloudrender.init` 去连,**不是**保活地址 || `viewUrl` | 观看地址,可能为空 || `wsUrl` | 状态保活 WebSocket。和 `streamUrl` 不是同一条连接 || `error` | 错误信息。非空表示这路启动失败 || `sessionCount` | 当前会话数 || `sessions` | 已连上的会话。`tabId` 是调用方自己的会话 ID || `userIp` / `userName` | 发起方 || `streamerPort` / `httpPort` / `sfuPort` / `clientPID` | 节点侧端口和进程 |
## 用项目 ID 找任务
把 PiStudio 项目 ID 和每条 `tasks[].projectId` 都转成字符串再比较。
```text我的任务 = tasks 里 projectId 与给定 ID 相同的那一条```
同一个项目可能有多条时,取 `startTime`(没有则用 `requestTime`,再没有则用 `id`)最新的一条。
已经拿到过 `taskId` 时,优先用 `tasks[].id` 找,不要只按项目 ID 拿第一条。这样重连的是原来那一路。
## 对接顺序
两条 WebSocket 不要混用:
| 地址 | 作用 | 何时连接 || --- | --- | --- || `wsUrl` | 向 PiStudio 报活,占住这路任务 | `streamUrl` 已经有了,并且在 `init` 之前 || `streamUrl` | 像素流信令,真正拉起云渲染画面 | 保活连上之后(没有 `wsUrl` 时直接 `init`) |
```textGET /status → 按 projectId 找到任务,等到 streamUrl 非空 → 连接 wsUrl,每秒心跳 { taskId, tabId } → cloudrender.init({ address: streamUrl }) → 画面就绪```
| `/status` 里看到的情况 | 处理 || --- | --- || 有该项目任务,且 `streamUrl` 非空 | 进入保活,再 `init` || 有该项目任务,但 `streamUrl` 为空 | 场景还在冷启动,继续轮询 `/status`,先不要连 WS,也不要 `init` || `error` 非空 | 这路失败,看 `error` || `tasks` 里没有该 `projectId` | 还没有推流任务。有空位时再 `GET /alloc/{projectId}`,然后继续轮询 `/status` |
冷启动每 500ms 拉一次 `/status`,直到目标 `id` 出现 `streamUrl`,最长约 25 秒。有地址后再等约 3 秒,给推流进程留启动时间,然后才连保活并 `init`。
## 状态 WebSocket 心跳
`streamUrl` 就绪后,用任务上的 `wsUrl` 建 WebSocket。这条连接只负责保活,不传画面。
```javascriptconst ws = new WebSocket(task.wsUrl)
ws.onopen = () => { setInterval(() => { if (ws.readyState === WebSocket.OPEN) { ws.send(JSON.stringify({ taskId: task.id, tabId })) } }, 1000)}```
约定:
- 间隔 **1 秒**。只在 `readyState === OPEN` 时发送。- 报文是 JSON 文本,字段只有两个:`taskId`(任务 `id`)、`tabId`(调用方自己的会话 ID)。- `tabId` 本次访问内保持不变。刷新页面可以沿用同一个,这样 `/status` 的 `sessions[].tabId` 能对上这一路。- 服务端不要求处理下行消息。连上之后按上面的频率发即可。- `onerror`、`onclose` 时停掉定时器。再次绑定同一任务前,先关掉旧连接,避免两路心跳打同一个 `taskId`。- 任务里没有 `wsUrl`:跳过保活,仍然用 `streamUrl` 做 `init`。- 刷新或关闭页面:只断开这条 WebSocket,**不要**调用 `/free`。心跳停掉后由服务端超时回收。刷新后重新 `GET /status`,按原来的 `taskId` 复用。- 主动结束这一路:先断心跳,再 `DELETE /free/{taskId}`。
## 用 streamUrl 做 init
保活已经连上(或确认没有 `wsUrl`)之后,再初始化云渲染。`address` 用的是 `streamUrl`,不是 `wsUrl`。
```javascriptawait piclient.cloudrender.init({ $el: container, address: task.streamUrl, appKey: '', mode: 'pixelstreaming', showUI: false, editorMode: false, token: token, initialSettings: { AutoPlayVideo: true, AutoConnect: true, StartVideoMuted: true, WaitForStreamer: true, WebRTCFPS: 30, MatchViewportRes: true, },})```
`initialSettings` 里还可以按需要带 `MinQP`、`MaxQP`、`WebRTCMinBitrate`、`WebRTCMaxBitrate`。不传就用推流端默认值。`WebRTCFPS` 默认 30。
`init` 会拿 `streamUrl` 去连像素流信令,再在 `container` 里挂出 `video`。下面任一情况都算这路已经拉起来,默认最多等 60 秒:
- `cloudrender.init` 的 Promise 成功- 容器里出现带 `srcObject` 的 `video`
回调晚一点没关系。只要 `video` 已经挂上,就继续往下走。两边都没有,并且超时,视为推流启动超时。
拉起来之后:
1. `piclient.cloudrender.enabled = true`2. `piclient.emit('page.loadCompleted', {})`3. `piclient.emit('object.GetScreenInfo')`4. `piclient.emit('mode.enterPlayMode')`5. 约 1 秒后再 `piclient.emit('ui.setClientUIVisible', { visible: 'hide' })`
到这里云渲染才算初始化完成。保活 WebSocket 在整个观看期间保持每秒一次,不要在 `init` 成功后关掉。
## 还能不能新开
先在 `tasks` 里找本项目。已经有任务时是重连,不占新线程。
没有任务时再看容量:
1. `freeSlot > 0`:有空位。2. 否则把 `nodes[].maxTask` 相加,作为集群线程上限,和 `taskCount` 比。相加结果大于 0 时,以它为准。3. 节点上都没有 `maxTask` 时,再看根上的 `maxSlot`,然后才是根上的 `maxTask`。4. `taskCount` 达到上限,或 `freeSlot` 为 0:线程已满。
根上的 `maxTask` 可能是占位大数(例如 100),不要拿它和单个节点的任务数比。
线程已满且列表里没有任何可复用任务时,不要再分配,提示稍后再试。
- 2026-11-11 12:05:31赞
- 1
请登录后回答。没有帐号?注册一个。
