先核对能不能用，再往下看。
网络端口
| 协议 | 端口 | 用途 | 方向 | 必需 | 备注 |
|---|---|---|---|---|---|
| TCP | 58000 | HTTP API、Web 管理后台与 /media/ 静态媒体服务 | 入站 | 是 | REST + JWT；可选 HTTPS（同时配置证书与私钥后同端口启用）；视频 Range 请求走此端口 |
| TCP | 58001 | TCP 指令通道（JSON Line） | 入站 | 否 | 每行一条 JSON；支持 LF/CR/CRLF/NUL 与 ^/$ 可见分隔符；最多 50 个并发客户端 |
| UDP | 58002 | UDP 指令通道（单数据报一条 JSON） | 入站 | 否 | 无连接、不保证到达；回复发给最后发送者；当前源码未实现限流 |
| TCP | 58003 | WebSocket 实时推送与指令 | 入站 | 否 | 订阅式推送；最多 100 个会话；30 秒协议层 Ping + 应用层 ping |
默认账号
Web 管理后台
- 登录地址
- http://127.0.0.1:58000
- 用户名
- admin
- 密码
- 已设置，请向 IFU 获取
- 默认状态
- 默认
- 备注
- 首次登录请立即修改密码；密码以 PBKDF2-HMAC-SHA256 存储，前台不显示明文
FoxPlayer 是 Fox 系列里「管内容」的那一个。它是一台装在大屏后面的本地播放终端：启动后自动全屏、无边框地播放节目单里的图片和视频，没有桌面、没有弹窗、不需要人每天去点一下。它把「内容」这件事收在自己身上——素材存在自己的资源目录里，顺序由自己的节目单决定，播完一项接下一项，断电重启后接着播。
它解决的是「屏幕要一直有内容，但现场没人管」的问题。展厅、门店、酒店大堂、会议室门口这类场景，屏幕往往挂在墙上或装在机柜里，运维不可能每天去插 U 盘、点播放器。FoxPlayer 的做法是：内容通过本机 Web 后台传进来，节目单在后台排好，开机自启、播放中防休眠、关窗口只收进托盘，于是「开机就有画面」成为默认状态，而不是每天要完成的任务。
内容管理全部发生在浏览器里。FoxPlayer 在 58000 端口自带一个 Web 管理后台，同一台机器打开 http://127.0.0.1:58000 即可登录；局域网内其它电脑也可以访问 http://<终端IP>:58000。后台提供仪表盘、节目单管理、操作日志、授权管理、系统设置与 API 文档六个页面。上传素材时会自动识别图片/视频、读取时长、截取缩略图，并以文件 MD5 命名落盘，避免重名覆盖；节目单支持拖拽排序、设默认起始项、单项启停、图片停留时长与拉伸/原始比例。
播放本身是「稳」优先。视频与图片混合播放，支持单曲循环与列表循环；视频之间尽量无缝衔接，切换失败会跳过坏项而不是卡死；遇到解码错误自动跳到下一项，连续失败到节目单末尾则停下等待处理，不会无限空转。图片按节目单设定的停留时长展示。播放器还提供本机触控手势：左/右区双击切上/下一项、左右区上下滑调音量、底部横滑调进度、中央单击暂停/继续，右下角连点五下可打开调试面板。
它不是一个孤立的播放器。FoxPlayer 同时开放四个控制通道：HTTP（58000，REST + JWT）、TCP（58001，每行一条 JSON）、UDP（58002，单包 JSON）、WebSocket（58003，订阅推送）。四个通道共用同一套指令：切歌、暂停、恢复、重播、跳转、音量、下一项/上一项、状态查询、节目单查询。中控、信息发布系统或第三方平台不必理解播放器内部结构，发一条 {"cmd":"setplay","params":{"file":"#3"}} 就能把画面切到节目单第 3 项。系统级动作（关机、重启、退出软件、改配置）只允许走 HTTP 管理通道，避免局域网内一条 UDP 包就把机器关掉。
授权按机器绑定。每台终端在「授权管理」页显示一个机器码，把机器码交给供应方换取授权码，粘贴激活即可；授权码带 RSA 签名与到期时间，程序每 60 秒复查一次，到期前 30 天开始提醒，过期后暂停播放并回到授权页。未授权时程序仍可启动，但只显示授权入口，不进入播放界面。
它与同系列其它软件的边界很清楚：FoxDisplay 管网页/信息页展示，FoxAgent 管机器本身（电源、音量、键鼠、进程），FoxTimer 管会议倒计时，FoxKiosk 管 Web 应用的运行环境；FoxPlayer 只负责「把本地的图片和视频按顺序放到屏幕上」。需要「让屏幕播一段视频」用 Player，需要「让机器自己重启」用 Agent，需要「展示一个网页」用 Display。三者可以装在同一台机器上，各司其职，互不越界。
事实依据：pubspec.yaml、main.dart、config_service.dart、command_service.dart、websocket_server.dart、license_service.dart
它自己怎么跑，怎么接进来，怎么维护
FoxPlayer 启动后先做三件事：加单实例锁（防重复启动）、把窗口设为全屏无边框、申请防休眠（播放期间屏幕不黑、系统不睡），随后隐藏鼠标、进入播放。桌面平台还会初始化系统托盘：关闭窗口只是收进托盘，右键托盘可「显示窗口 / 退出应用」。
它同时启动四条监听：HTTP 58000（Web 后台 + REST API + 媒体文件）、TCP 58001、UDP 58002、WebSocket 58003。四条通道共享同一套指令，任何一个都能切内容；系统级指令（关机、重启、退出、改配置）只允许 HTTP 管理通道调用。
内容由节目单驱动：默认从「默认项」或第 1 项开始，按排序播放；支持单曲循环与列表循环，视频之间尽量无缝衔接，图片按各自设定的停留时长展示。解码失败会自动跳到下一项，连续失败到末尾则停下等待处理。
程序每 60 秒复查一次授权。未授权时只显示授权页；授权即将过期（≤30 天）会提示；过期后暂停播放。要确认它在运行，打开 http://<终端IP>:58000 能看到登录页即可；排障日志在数据目录的 logs/foxplayer.log。
单独用：装到终端上，用本机 Web 后台（http://127.0.0.1:58000）传素材、排节目单，之后开机即播，不需要任何外部系统。
接中控/第三方：FoxPlayer 自带四个入口，任选其一即可。HTTP 用 POST /api/pub/control（公开控制）或 POST /api/player/control（需 JWT，并校验 device_id）；TCP 连 58001，每行一条 JSON；UDP 发 58002，一个数据报一条 JSON；WebSocket 连 58003，先 {"type":"subscribe","events":["progress","player_changed"]} 订阅，再发指令。指令本身只有三部分：id（指令/设备标识，可空）、cmd（如 setplay、pause、volume）、params（参数）。
权限：管理类接口用 JWT（登录后 Authorization: Bearer ）；公开控制接口默认开放，一旦在系统设置里填了 control_secret，四个非 HTTP 通道都必须带匹配的 token，HTTP 的 /api/pub/control 也需带 token 或 JWT。具体字段、响应与示例见《FoxPlayer 集成与 API》。
日常看护用本机 Web 后台：仪表盘看当前播放项、状态与音量；节目单页改顺序、启停、设默认项；系统设置改端口、音量、播放模式、转码参数；操作日志页按通道/指令/结果筛选最近 500 条。
升级采用覆盖安装：先退出托盘里的应用（或发 quit_app），再运行新安装包覆盖原目录；数据库、素材、授权文件都在数据目录，不随安装目录删除，升级后原节目单与授权保留。升级前建议备份数据目录下的 foxplayer.db 与 media/。
排障先看三处：一是数据目录 logs/foxplayer.log（超 5 MB 轮转为 .log.1）；二是 Web 后台仪表盘的状态与日志页；三是 GET /api/player/status 的返回。播放没画面时，优先确认节目单是否为空、素材文件是否还在 media/、授权是否过期。
远程支持只要 58000 端口在局域网可达，运维即可在任意电脑打开 http://<终端IP>:58000 操作后台，无需到现场、无需远程桌面。频道完全离线时，可由现场人员导出日志回传定位。
安装和使用中最常被问到的几件事
更细的排障步骤与参数说明在文档中心，注册登录后即可查看。