1

​# PiStudio 云渲染 `/status` 对接

2026-11-06 16:31:16
45 次阅读
1 个评论

# 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),不要拿它和单个节点的任务数比。

线程已满且列表里没有任何可复用任务时,不要再分配,提示稍后再试。


0 赞
0 收藏
评论
  1. 2026-11-11 12:05:31
共 1 条
  • 1
前往
页

请登录后回答。没有帐号?注册一个。