sealks
280 lines
6.2 KiB
Markdown
280 lines
6.2 KiB
Markdown
# 使用文档
|
||
|
||
## 1. 环境要求
|
||
|
||
- Python `3.10` 到 `3.12` 推荐。
|
||
- macOS 本机如果没有 `python` 命令，使用 `python3` 或明确的 Python 3.12 路径。
|
||
- 浏览器建议使用 Chrome / Chromium / Edge。
|
||
- 生产输出服务器建议关闭休眠、屏保和自动更新弹窗。
|
||
|
||
当前项目依赖见：
|
||
|
||
```text
|
||
requirements.txt
|
||
pyproject.toml
|
||
```
|
||
|
||
## 2. 首次启动
|
||
|
||
在项目根目录执行：
|
||
|
||
```bash
|
||
cd /Users/tjy/Documents/code/work/dp
|
||
/Users/tjy/.local/bin/python3.12 -m venv .venv
|
||
.venv/bin/python -m pip install -r requirements.txt
|
||
.venv/bin/python -m led_platform.cli serve
|
||
```
|
||
|
||
服务默认监听：
|
||
|
||
```text
|
||
0.0.0.0:8000
|
||
```
|
||
|
||
如果要指定端口：
|
||
|
||
```bash
|
||
.venv/bin/python -m led_platform.cli serve --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
## 3. 日常启动
|
||
|
||
```bash
|
||
cd /Users/tjy/Documents/code/work/dp
|
||
.venv/bin/python -m led_platform.cli serve
|
||
```
|
||
|
||
查看本机局域网地址：
|
||
|
||
```bash
|
||
.venv/bin/python -m led_platform.cli urls
|
||
```
|
||
|
||
也可以直接查看：
|
||
|
||
```bash
|
||
ipconfig getifaddr en0
|
||
```
|
||
|
||
## 4. 常用地址
|
||
|
||
本机访问：
|
||
|
||
```text
|
||
控制台: http://127.0.0.1:8000/
|
||
左输出: http://127.0.0.1:8000/output/left
|
||
右输出: http://127.0.0.1:8000/output/right
|
||
健康检查: http://127.0.0.1:8000/healthz
|
||
同步状态: http://127.0.0.1:8000/api/sync/status
|
||
API 文档: http://127.0.0.1:8000/docs
|
||
```
|
||
|
||
局域网访问时，把 `127.0.0.1` 换成控制服务 IP，例如：
|
||
|
||
```text
|
||
http://192.168.0.182:8000/
|
||
```
|
||
|
||
## 5. 控制台使用
|
||
|
||
打开：
|
||
|
||
```text
|
||
http://控制服务IP:8000/
|
||
```
|
||
|
||
控制台包含：
|
||
|
||
- 画面回显：把 left/right 两个只读预览无缝拼成一块完整画面，桌面布局下位于控制台顶部。
|
||
- 场景切换：切换 overview、energy、security。
|
||
- 输出与同步：查看输出端连接数量、FPS、frame time、RTT、clock offset。
|
||
- 生产命令回显：查看真实 `/output/left` 和 `/output/right` 的 prepared、放行、committed 状态。
|
||
- 局部动作：翻页、能源模式、告警、暂停/恢复时间轴。
|
||
|
||
画面回显使用：
|
||
|
||
```text
|
||
/output/left?preview=1
|
||
/output/right?preview=1
|
||
```
|
||
|
||
控制台会把两个预览 iframe 贴在一起，形成 `14880 x 3510` 的完整大屏回显。它是只读预览，不会参与真实输出端 ACK。所以上方画面变化只代表控制台预览已更新；生产命令回显里的等待、放行和完成，代表真实输出端是否已经 ACK。
|
||
|
||
## 6. 生产输出端使用
|
||
|
||
左 GPU 输出服务器打开：
|
||
|
||
```text
|
||
http://控制服务IP:8000/output/left
|
||
```
|
||
|
||
右 GPU 输出服务器打开：
|
||
|
||
```text
|
||
http://控制服务IP:8000/output/right
|
||
```
|
||
|
||
输出端打开后会：
|
||
|
||
1. 请求 `/api/bootstrap/{tile_id}` 获取 tile、场景和当前状态。
|
||
2. 连接 `/ws/output/{tile_id}`。
|
||
3. 上报 `hello`，注册为真实输出节点。
|
||
4. 定时进行时钟同步。
|
||
5. 定时上报 FPS、frame time、dropped frames。
|
||
6. 收到场景命令后执行 prepare/barrier/commit。
|
||
|
||
## 7. 场景切换流程
|
||
|
||
控制台点击“切换”后：
|
||
|
||
1. 后端生成新场景状态和 `command_id`。
|
||
2. 后端广播 `prepare_scene`。
|
||
3. left/right 真实输出端预加载或预渲染。
|
||
4. left/right 都回 `prepared`。
|
||
5. 后端记录 `released_at_ms` 并广播 `commit_scene`。
|
||
6. left/right 等到 `apply_at_ms` 同步显示。
|
||
7. left/right 回 `committed` 或 `late`。
|
||
|
||
在控制台“命令回显”里可以看到每个阶段。
|
||
|
||
## 8. 接入真实超分渲染
|
||
|
||
输出端预留了 hook：
|
||
|
||
```js
|
||
window.ledPlatformPrepareScene = async ({ commandId, tile, state, scene }) => {
|
||
// 1. 根据 scene/state 准备真实资源
|
||
// 2. 执行超分或离屏渲染
|
||
// 3. 确认下一次 commit 可以无卡顿显示
|
||
};
|
||
```
|
||
|
||
只要这个 Promise 不 resolve，输出端就不会发送 `prepared`。后端也就不会释放 `commit_scene`。
|
||
|
||
如果超分失败，输出端会回：
|
||
|
||
```text
|
||
status=error
|
||
```
|
||
|
||
## 9. 配置文件
|
||
|
||
场景配置：
|
||
|
||
```text
|
||
config/scenes.json
|
||
```
|
||
|
||
字段：
|
||
|
||
```text
|
||
id 场景 ID
|
||
name 控制台显示名
|
||
url 场景 URL，目前示例都使用 /wall-app
|
||
view 输出端内部视图名
|
||
description 描述
|
||
preload 准备阶段预加载资源
|
||
```
|
||
|
||
Tile 配置：
|
||
|
||
```text
|
||
config/tiles.json
|
||
```
|
||
|
||
字段：
|
||
|
||
```text
|
||
id left / right
|
||
x, y 在完整逻辑大屏中的起点
|
||
width, height tile 尺寸
|
||
wall_width 完整大屏宽度
|
||
wall_height 完整大屏高度
|
||
desktop_width 单台 GPU 服务器桌面宽度
|
||
desktop_height 单台 GPU 服务器桌面高度
|
||
physical_outputs 4 路 4K 输出映射
|
||
```
|
||
|
||
环境变量前缀：
|
||
|
||
```text
|
||
LED_
|
||
```
|
||
|
||
示例：
|
||
|
||
```bash
|
||
LED_APP_PORT=9000 .venv/bin/python -m led_platform.cli serve
|
||
LED_SWITCH_PREPARE_DELAY_MS=3000 .venv/bin/python -m led_platform.cli serve
|
||
```
|
||
|
||
## 10. 验证命令
|
||
|
||
```bash
|
||
.venv/bin/python -m pytest -q
|
||
.venv/bin/python -m compileall led_platform tests
|
||
node --check led_platform/web/static/output/main.js
|
||
node --check led_platform/web/static/admin/main.js
|
||
```
|
||
|
||
健康检查：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8000/healthz
|
||
```
|
||
|
||
同步状态：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8000/api/sync/status
|
||
```
|
||
|
||
## 11. 常见问题
|
||
|
||
### 控制台看不到画面回显
|
||
|
||
先强制刷新控制台页面。画面回显在控制台顶部，标题为“画面回显”。
|
||
|
||
如果仍然看不到，检查：
|
||
|
||
```text
|
||
http://控制服务IP:8000/output/left?preview=1
|
||
http://控制服务IP:8000/output/right?preview=1
|
||
```
|
||
|
||
这两个地址应能单独打开预览画面。
|
||
|
||
### 命令回显一直显示等待
|
||
|
||
检查真实输出端是否打开的是：
|
||
|
||
```text
|
||
/output/left
|
||
/output/right
|
||
```
|
||
|
||
不要把生产输出端打开成 `?preview=1`，预览模式不会 ACK。
|
||
|
||
### 切换场景不放行
|
||
|
||
说明至少一个真实输出端没有回 `prepared`。查看：
|
||
|
||
```text
|
||
/api/sync/status
|
||
```
|
||
|
||
重点看 `nodes` 是否有 left/right，`commands[].acks` 是否有两个 tile。
|
||
|
||
### 局域网机器打不开
|
||
|
||
检查：
|
||
|
||
- 服务是否监听 `0.0.0.0:8000`。
|
||
- 控制服务机器防火墙是否允许 8000。
|
||
- 输出服务器是否和控制服务在同一网络。
|
||
- URL 是否使用控制服务的局域网 IP，而不是 `127.0.0.1`。
|
||
|
||
### 控制台预览和生产输出不同步
|
||
|
||
控制台预览是观察用途，运行在控制台浏览器中，不参与 ACK，也不代表生产输出端性能。最终验收应以真实 `/output/left` 和 `/output/right` 为准。
|