集成与 API

把 IFU 接进现有系统

1. 集成方式总览

四个通道共用同一套指令契约：同样的 cmd 与 params，在任一通道上的执行结果一致。区别只在传输、鉴权方式与响应回法。

事件上报是另一条链路：程序可以主动把 progress 等事件推到指定的 HTTP/TCP/UDP 目标，由 progress_http_enabled、progress_tcp_enabled、progress_udp_enabled 控制，默认关闭。

2. HTTP 接口清单

2.1 公开接口（无需 JWT）

2.2 认证接口

2.3 管理与业务接口（需 Bearer）

除上述接口外，其余非 /api/、非 /media/ 的路径由 SPA fallback 交给内置 Web 后台；未知 /api/ 路径返回 404 {}。

3. 认证

3.1 管理端 JWT

POST /api/auth/login
Content-Type: application/json

{"username":"admin","password":"admin123"}

成功：

{"status":"ok","token":"eyJhbGciOiJIUzI1NiIs..."}

之后请求携带：

Authorization: Bearer 

规则：

• 算法 HS256，有效期 24 小时
• payload 含 user 与 ver（令牌版本号）
• 登出或改密会使 ver 自增，所有旧 token 立即失效
• 密钥首次启动随机生成并持久化，不硬编码
• 密码使用 PBKDF2-HMAC-SHA256（10 万次迭代 + 随机盐）存储

3.2 控制通道共享密钥

配置项 control_secret 为空时，TCP/UDP/WebSocket 与 /api/pub/control 默认开放（便于联调）。一旦填入非空值：

• TCP / UDP / WebSocket：指令 JSON 顶层必须带 "token":""，常量时间比较
• HTTP /api/pub/control：可用 query ?token=、body 顶层 token，或管理端 JWT 三者之一
• 鉴权失败返回 {"status":"error","message":"unauthorized"}；HTTP 公开控制接口对应 401

正式交付必须配置 control_secret，并同步给所有调用方。

3.3 授权码

• 机器码：网卡名 + 主机名 + 操作系统与版本 + CPU 核数 的 SHA-256 前 32 位十六进制
• 授权码：Base64(JSON payload).Base64(RSA-SHA256 签名)
• payload：{"machineId":"<机器码>","expiry":<毫秒时间戳>}
• 校验顺序：机器码匹配 → RSA-2048/SHA-256 验签 → 到期时间
• 状态：有效 / 30 天内到期 / 已过期 / 未授权
• 文件：数据目录 license.key；程序每 60 秒复查

4. 指令格式

4.1 请求

{
  "id": "",
  "cmd": "setplay",
  "params": {"file": "#1"},
  "token": ""
}

4.2 响应

指令通道统一返回：

{"status":"ok","id":"","data":{...}}
{"status":"ignored","id":"","message":"已在播放状态"}
{"status":"error","id":"","message":"未知指令: xxx"}

HTTP 管理接口的写操作多为 202 Accepted：

{"status":"accepted"}

HTTP 业务查询直接返回数据对象（数组或对象），错误统一：

{"status":"error","message":"..."}

4.3 去重与延迟队列

• setplay 对同一文件有 200 ms 防抖：窗口内重复切同一文件返回 ignored（"操作过于频繁，请稍后重试"）
• 播放器处于 Preparing 时，setplay 进入最多 3 条的延迟队列；准备完成后只执行最先入队的一条，其余丢弃（避免连发导致连续跳项）
• 其他指令不做全局去重

5. 指令表

受控指令（shutdown/restart/quit_app/restart_app/setConfig）从 TCP/UDP/WebSocket 调用会返回：该指令仅允许 HTTP 管理通道调用。

5.1 setplay 细节

• {"file":"#3"}：节目单第 3 项
• {"playlist_id":"#3"}：同上
• {"file":"abc.mp4"}：按文件名在节目单中查找；找不到则按路径兜底播放
• {"playlist_id":"1"} 且无 file：回退到节目单第 1 项
• 序号越界：节目单序号无效: N
• 节目单为空且无目标：无播放目标且节目单为空

5.2 seek 细节

{"cmd":"seek","params":{"mode":"absolute","seconds":30}}
{"cmd":"seek","params":{"mode":"relative","seconds":-10}}
{"cmd":"seek","params":{"mode":"progress","percent":0.5}}

图片类型返回：图片类型不支持seek操作。

6. HTTP 调用示例

6.1 公开控制（未配置 control_secret）

Invoke-RestMethod -Method Post -Uri 'http://192.168.1.50:58000/api/pub/control' `
  -ContentType 'application/json' `
  -Body '{"cmd":"setplay","params":{"file":"#2"}}'

6.2 公开控制（已配置 control_secret）

Invoke-RestMethod -Method Post -Uri 'http://192.168.1.50:58000/api/pub/control?token=你的密钥' `
  -ContentType 'application/json' `
  -Body '{"cmd":"volume","params":{"level":60}}'

6.3 登录后控制（推荐管理端使用）

$base = 'http://192.168.1.50:58000'
$login = Invoke-RestMethod -Method Post -Uri "$base/api/auth/login" `
  -ContentType 'application/json' `
  -Body '{"username":"admin","password":"你的密码"}'
$h = @{ Authorization = "Bearer $($login.token)" }

# 带设备校验的控制
Invoke-RestMethod -Method Post -Uri "$base/api/player/control" -Headers $h `
  -ContentType 'application/json' `
  -Body '{"id":"FOX-STORE-001","cmd":"next"}'

# 查询状态
Invoke-RestMethod -Uri "$base/api/player/status" -Headers $h

6.4 上传素材

$h = @{ Authorization = "Bearer $($login.token)" }
Invoke-RestMethod -Method Post -Uri "$base/api/upload" -Headers $h -Form @{
  files = Get-Item 'D:\media\promo.mp4'
}

字段名 files；扩展名白名单与大小上限见《使用手册》。上传接口必须带 JWT。

6.5 媒体文件与 Range

GET http://192.168.1.50:58000/media/3f2a....mp4
Range: bytes=0-1048575

返回 206 与 Content-Range；越界返回 416。未知扩展名强制 application/octet-stream + 附件下载。

7. TCP / UDP / WebSocket

7.1 TCP（58001）

• 每行一条 JSON；分隔符支持 LF、CR、CRLF、NUL、$
• 行首 ^ 自动剥离；推荐 ^{"cmd":"play"}$
• 响应为一行 JSON + \n
• id 非空只回来源连接；id 为空广播给所有客户端
• 最多 50 客户端；单连接缓冲超过 1 MB 断开

$client = New-Object System.Net.Sockets.TcpClient('192.168.1.50', 58001)
$stream = $client.GetStream()
$writer = New-Object System.IO.StreamWriter($stream)
$writer.AutoFlush = $true
$writer.WriteLine('^{"cmd":"status"}$')

$reader = New-Object System.IO.StreamReader($stream)
$reader.ReadLine()
$client.Close()

7.2 UDP（58002）

• 一个数据报一条 JSON；回复发给最后发送者
• 无连接、不保证到达；源码当前未实现令牌桶限流，上层应自行控制发送频率
• 单包建议不超过 64 KB

$udp = New-Object System.Net.Sockets.UdpClient
$bytes = [Text.Encoding]::UTF8.GetBytes('{"cmd":"status"}')
$udp.Send($bytes, $bytes.Length, '192.168.1.50', 58002) | Out-Null
$ep = New-Object System.Net.IPEndPoint([Net.IPAddress]::Any, 0)
[Text.Encoding]::UTF8.GetString($udp.Receive([ref]$ep))

7.3 WebSocket（58003）

连接：ws://192.168.1.50:58003

订阅：

{"type":"subscribe","events":["progress","player_changed","command","volume"]}

发送指令：

{"id":"c1","cmd":"setplay","params":{"file":"#1"}}

响应会回到该连接（因为 id 非空）。服务端每 30 秒发协议 Ping 与应用层 {"type":"ping"}；客户端可回 {"type":"pong"}。二进制帧被忽略；最多 100 会话。

8. 推送事件

事件信封（WS pushEvent / 事件上报）：

{
  "device_id": "FoxPlayer-001",
  "event": "progress",
  "ts": 1750000000,
  "data": { }
}

config_changed、files_changed 走广播通道，信封为：

{"event":"config_changed","data":{ },"ts":1750000000}

WS 的 progress / player_changed / command / volume 受 progress_ws_enabled 与 push_ws_events 白名单过滤（默认只开 progress,player_changed）。想收到 command / volume，需把它们加入 push_ws_events。config_changed / files_changed 不受该白名单限制。

8.1 外推目标（可选）

9. 错误码与常见消息

9.1 HTTP 状态码

9.2 指令层消息

10. 集成注意事项

1. id 有两层含义：在 WS/TCP/UDP//api/pub/control 中是指令标识（用于定向回包）；在 /api/player/control 中同时被当作设备 ID 校验。跨系统对接时建议统一使用空 id + 业务侧自建请求号。
2. cmd 用小写：注册表按字符串精确匹配，SetPlay 不会命中 setplay。
3. 系统指令只走 HTTP：不要让中控通过 UDP 关机；这是有意的安全边界。
4. 控制密钥必须配：不配 control_secret 等于把播放控制开放给整个局域网。
5. 重复切同一文件会被去重：200 ms 内的第二次 setplay 返回 ignored，不是故障。
6. 状态查询优先用 /api/pub/status：字段最全（含 media_url_transcoded 与监视布局）；/api/player/status 更精简。
7. 上传要 JWT：/api/upload 已套认证，匿名上传会 401。
8. 视频 seek 用 Range：浏览器/播放器拉 /media/ 时可能发 Range，服务端已支持 206/416。
9. HTTPS 是可选：证书与私钥都配置才启用；加载失败会回退 HTTP 并记录告警，不会中断启动。
10. 事件不是可靠消息：UDP 推送会丢包；关键状态以轮询 /api/pub/status 为准。

事实依据：http_server.dart、auth_routes.dart、pub_routes.dart、player_routes.dart、playlist_routes.dart、command_service.dart、websocket_server.dart、tcp_server.dart、udp_server.dart

分享