更新日志

每个版本改了什么

V8.0.0（当前版本）

本次为 FoxPlayer 的架构重写基线版本：播放内核换为 FVP（libmpv），内容管理从"本机放一个文件夹"升级为"节目单 + 素材库 + 本机 Web 后台"，并把控制接口统一成 HTTP / TCP / UDP / WebSocket 四通道。这是首个带本机 Web 管理后台的版本，也是首个把授权绑到机器码的版本。

新增

播放内核与播放能力

• 播放内核切换为 FVP（libmpv 0.39.0），默认解码优先级 MFT → D3D11 → FFmpeg：Windows 上先用 Media Foundation 硬解，不可用时降级 D3D11VA，最后由 FFmpeg 软解兜底，保证 H.264 / H.265 / VP9 / AV1 等常见编码都能播
• 全屏无边框启动：启动即按主显示器分辨率铺满、隐藏标题栏与窗口按钮，不显示鼠标指针干扰画面
• 图片与视频混合播放，图片按 image_hold_time（默认 10 秒）停留后自动切下一项
• 播放列表无缝衔接：提前预排下一项，切换不黑屏；预排失败时 5 秒兜底强制切换
• 解码失败自动跳项：单个文件打不开时记录日志并跳过，不会卡在坏文件上停住整个节目单
• 断网/无公网环境下完全可用，所有素材均为本地文件

节目单与素材管理

• 节目单（Playlist）与节目项（PlaylistItem）两级结构，支持拖拽排序、单项启停、批量替换与批量排序
• 两种循环模式：loop_one（单节目单循环）与 loop_all（全部节目单轮播），由 default_play_mode 决定默认值
• 素材库：支持图片与视频上传，服务端按 MD5 命名落盘，天然去重；上传后自动探测媒体信息（时长、分辨率），视频在第 3 秒抽帧生成缩略图
• 素材变更后通过 files_changed 事件广播给所有已连接的控制端，前端列表无需手动刷新
• 删除素材时联动清理节目项引用，不会留下"节目单里有、文件已不存在"的空项

本机 Web 管理后台

• 内置 Vue 3 + Element Plus 管理后台，随程序启动、无需单独部署，浏览器打开 http://127.0.0.1:58000 即可使用
• 9 个页面：登录、设备授权、全屏监控播放、仪表盘、节目单管理、操作日志、授权管理、系统设置、API 文档
• 一个后台管一台设备：后台直接读取本机数据库与素材目录，没有云端、没有账号体系、不跨设备
• 仪表盘展示播放状态、当前文件、存储占用、四通道监听状态与运行时长

四通道控制接口

• HTTP 58000：REST API + Web 后台 + /media/ 静态媒体服务，支持视频 Range 请求（206 / 416），可拖进度
• TCP 58001：JSON Line 指令通道，支持 LF / CR / CRLF / NUL 分隔，兼容行首 ^ 与行尾 $ 包裹
• UDP 58002：单数据报一条 JSON，回复发回最后发送者，适合局域网广播式调用
• WebSocket 58003：订阅式实时推送（播放进度、文件切换、音量、配置变更等）与指令下发
• 指令统一信封 id / cmd / params，响应统一 status（success / error / accepted）语义；player 类指令返回 202 Accepted，表示"已受理、异步执行"
• setplay 200ms 防抖：对同一素材或同一节目项的重复切播返回 ignored，避免中控重复发包导致跳项；其他指令不做全局去重

认证与授权

• 后台登录使用 JWT HS256，有效期 24 小时；令牌内含 user 与 ver 字段，改密码后旧令牌立即失效（真登出）
• 密码使用 PBKDF2-HMAC-SHA256，10 万次迭代 加盐哈希，计算放在 Isolate 内执行，不阻塞 UI
• 登录限流：同一 IP 10 分钟内连续失败 5 次即锁定，防止暴力破解
• 首次启动自动创建默认账号 admin / admin123，并提示立即修改
• 机器码授权：机器码由"网卡名 + 主机名 + 操作系统 + 系统版本 + CPU 核心数"计算 SHA-256 取前 32 位；授权码为 Base64(JSON).Base64(签名)，采用 RSA-2048 + SHA-256 验签，payload 含 machineId 与 expiry
• 授权文件 license.key 存于数据目录，每 60 秒复查一次；到期前 30 天开始在后台提示续期

系统集成

• 开机自启（launch_at_startup，由 auto_start 控制，默认开启）
• 防休眠 / 防锁屏（wakelock_plus），无人值守时不会因为系统休眠黑屏
• 系统托盘常驻，右键可显示/隐藏窗口与退出
• 单实例锁：重复启动时激活已有实例，不会出现两个程序抢同一批端口
• 自动转码：源文件编码不被硬解支持时，可用 FFmpeg（ffmpeg_cube）转成统一编码，转码任务串行排队、去重、.tmp 原子改名、60 分钟超时保护，启动时清理孤儿产物
• 触控手势：左右 20% 区域双击切换上/下一项、上下滑动调音量、底部 20% 区域横滑拖进度、中央单击暂停/继续、右下角 5 连击呼出调试面板
• Android TV 遥控器适配：方向键上/下调音量（支持长按连调）、左/右切上/下一项、OK 暂停/继续，兼容播放/暂停与上/下一曲媒体键；返回键改为 2 秒内连按两次才退出，避免现场误触退出播放
• 调试面板遥控器化：菜单键与 F12 均可开关调试面板；面板内方向键移动焦点、OK/回车激活当前按钮；底部新增「关闭面板」按钮，Android 终端在其右侧新增「系统设置」按钮，点击直接跳转安卓系统设置页
• Android TV 清单声明：新增 Leanback 启动入口、touchscreen required=false、横屏锁定与 TV banner，电视桌面可直接看到应用入口
• 操作日志：登录、配置修改、节目单变更、播放控制等关键动作入库，日志文件 logs/foxplayer.log 按 5MB 轮转

安全加固

• 新增 control_secret：四通道共享密钥，配置后 TCP / UDP / WS 指令必须携带正确 token，HTTP 公开控制接口同样校验
• 新增 cors_origins：默认不返回任何跨域头，仅在显式配置白名单后按 Origin 回显
• 新增 trust_proxy_headers：默认 false，避免伪造 X-Forwarded-For 绕过登录限流
• 上传扩展名白名单 + 单文件上限 max_upload_size_mb（默认 5120MB）
• /media/ 静态服务做路径遍历防护，未知扩展名强制以附件下载，避免被当作脚本执行
• 响应统一附带 X-Content-Type-Options、X-Frame-Options、CSP 等安全头
• 可选 HTTPS：配置 https_cert_path / https_key_path 后同端口启用 TLS

变更

• 程序版本由 V7 系列提升为 V8.0.0，安装包产物为 FoxPlayer-Setup-8.0.0.exe
• 内容组织方式由"直接扫某个文件夹"改为"素材库 + 节目单"：播放什么、按什么顺序播，由节目单决定，不再依赖文件夹里的文件顺序
• 控制接口端口统一为 58000–58003 四个连续端口（HTTP / TCP / UDP / WebSocket），替代旧版分散的端口约定
• 数据存储改为 SQLite（Drift，schemaVersion=2，WAL 模式），数据库文件 foxplayer.db 位于程序数据目录
• 配置项收敛到 ConfigService.defaults 一处定义，同时作为 setConfig 指令的白名单：不在表里的键一律无法通过接口写入

修复

• 修复长时间播放后内存持续增长的问题：播放状态推送按 250ms 节流，转码 URL 缓存 5 秒，避免频繁查询数据库
• 修复重复启动导致端口占用、后启动实例静默失败的问题（引入单实例锁）
• 修复删除素材后节目单残留空项、播放到该项时卡住的问题
• 修复转码产物未写完就被播放器读取导致的"文件损坏"误报（改为 .tmp 写完再原子改名）
• 修复 WebSocket 客户端异常断开后会话未释放的问题（增加 30 秒协议层 Ping 与应用层心跳）

影响说明

• 数据不兼容旧版：V8.0.0 使用新的数据库结构（foxplayer.db），旧版基于文件夹的播放方式没有对应数据可迁移；升级后需重新建节目单、重新导入素材
• 端口变更：中控 / 第三方系统若仍指向旧版端口，升级后需改为 58000–58003
• 授权需重新申请：本版首次引入机器码授权，升级后需用本机机器码重新申请授权码并导入 license.key
• 接口字段以本文档与《5-集成与 API》为准：仓库根目录 README.md 中若干历史描述（如 JWT 48 小时、bcrypt、UDP 令牌桶限流）与本版实现不一致，实现以源码与本交付资料为准
• 默认无跨域：若需从其他域名的网页直接调用本机 API，必须先在系统设置里填写 cors_origins，否则浏览器会拦截

升级方法

• 覆盖安装：运行 FoxPlayer-Setup-8.0.0.exe，安装程序会先结束正在运行的 FoxPlayer 再替换程序文件
• 数据目录（foxplayer.db、media/、license.key、logs/）不在安装目录内，覆盖安装不会删除；卸载时也不会自动清除，需要彻底清理时手工删除数据目录
• 升级后按顺序做四件事： 1. 打开 http://127.0.0.1:58000，用原账号登录；若为全新安装，用 admin / admin123 登录并立即改密码 2. 进入「系统设置」核对四个端口、device_id、control_secret 是否与现场中控约定一致 3. 进入「授权管理」，复制机器码申请新授权码并导入 4. 重新建立节目单并确认全屏播放正常
• 批量升级前建议先在一台机器上验证素材格式与授权流程，确认无误后再按母盘克隆或脚本方式铺开（见《8-部署与运维手册》）

模板（后续版本按此追加）

## V<主>.<次>.<修订>（YYYY-MM-DD）

### 新增
- …

### 变更
- …

### 修复
- …

### 影响说明
- 本版升级后需要调整的配置 / 接口 / 数据变化

### 升级方法
- 覆盖升级 / 重新安装，以及升级后必须完成的动作

分享