dp/docs/usage.md

使用文档

1. 环境要求

• Python 3.10 到 3.12 推荐。
• macOS 本机如果没有 python 命令，使用 python3 或明确的 Python 3.12 路径。
• 浏览器建议使用 Chrome / Chromium / Edge。
• 生产输出服务器建议关闭休眠、屏保和自动更新弹窗。

当前项目依赖见：

requirements.txt
pyproject.toml

2. 首次启动

在项目根目录执行：

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

服务默认监听：

0.0.0.0:8000

如果要指定端口：

.venv/bin/python -m led_platform.cli serve --host 0.0.0.0 --port 8000

3. 日常启动

cd /Users/tjy/Documents/code/work/dp
.venv/bin/python -m led_platform.cli serve

查看本机局域网地址：

.venv/bin/python -m led_platform.cli urls

也可以直接查看：

ipconfig getifaddr en0

4. 常用地址

本机访问：

控制台:     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，例如：

http://192.168.0.182:8000/

5. 控制台使用

打开：

http://控制服务IP:8000/

控制台包含：

• 画面回显：把 left/right 两个只读预览无缝拼成一块完整画面，桌面布局下位于控制台顶部。
• 场景切换：切换 overview、energy、security。
• 输出与同步：查看输出端连接数量、FPS、frame time、RTT、clock offset。
• 生产命令回显：查看真实 /output/left 和 /output/right 的 prepared、放行、committed 状态。
• 局部动作：翻页、能源模式、告警、暂停/恢复时间轴。

画面回显使用：

/output/left?preview=1
/output/right?preview=1

控制台会把两个预览 iframe 贴在一起，形成 14880 x 3510 的完整大屏回显。它是只读预览，不会参与真实输出端 ACK。所以上方画面变化只代表控制台预览已更新；生产命令回显里的等待、放行和完成，代表真实输出端是否已经 ACK。

6. 生产输出端使用

左 GPU 输出服务器打开：

http://控制服务IP:8000/output/left

右 GPU 输出服务器打开：

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：

window.ledPlatformPrepareScene = async ({ commandId, tile, state, scene }) => {
  // 1. 根据 scene/state 准备真实资源
  // 2. 执行超分或离屏渲染
  // 3. 确认下一次 commit 可以无卡顿显示
};

只要这个 Promise 不 resolve，输出端就不会发送 prepared。后端也就不会释放 commit_scene。

如果超分失败，输出端会回：

status=error

9. 配置文件

场景配置：

config/scenes.json

字段：

id          场景 ID
name        控制台显示名
url         场景 URL，目前示例都使用 /wall-app
view        输出端内部视图名
description 描述
preload     准备阶段预加载资源

Tile 配置：

config/tiles.json

字段：

id               left / right
x, y             在完整逻辑大屏中的起点
width, height    tile 尺寸
wall_width       完整大屏宽度
wall_height      完整大屏高度
desktop_width    单台 GPU 服务器桌面宽度
desktop_height   单台 GPU 服务器桌面高度
physical_outputs 4 路 4K 输出映射

环境变量前缀：

LED_

示例：

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. 验证命令

.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

健康检查：

curl http://127.0.0.1:8000/healthz

同步状态：

curl http://127.0.0.1:8000/api/sync/status

11. 常见问题

控制台看不到画面回显

先强制刷新控制台页面。画面回显在控制台顶部，标题为“画面回显”。

如果仍然看不到，检查：

http://控制服务IP:8000/output/left?preview=1
http://控制服务IP:8000/output/right?preview=1

这两个地址应能单独打开预览画面。

命令回显一直显示等待

检查真实输出端是否打开的是：

/output/left
/output/right

不要把生产输出端打开成 ?preview=1，预览模式不会 ACK。

切换场景不放行

说明至少一个真实输出端没有回 prepared。查看：

/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 为准。