部署与运维手册 - FoxPlayer 文档

从进场到验收的实施与运维

一、交付实施总览

阶段	主要工作	产出	责任方
1. 勘查	确认屏幕、主机、网络、供电、内容来源	《现场勘查表》	实施
2. 内容准备	收集图片/视频，统一分辨率与编码	素材包	客户 / 内容制作
3. 试装	在一台样机上完整跑通	样机 + 配置基线	实施
4. 批量部署	母盘克隆或逐台脚本安装	全部终端就绪	实施
5. 联调	与中控 / 业务系统对接四通道	联调记录	实施 + 集成方
6. 试运行	连续运行观察稳定性	试运行记录	运维
7. 验收	按验收清单逐项确认	验收单	客户 + 实施
8. 移交	交付账号、授权、文档、备份	交付包	实施

关键原则：先跑通一台，再复制到全部。 样机没验收通过之前不要批量铺开，否则一个问题会变成几十个问题。

二、现场勘查与准备

2.1 勘查清单

项目	要确认的内容	不合格的后果
显示设备	分辨率、刷新率、接口（HDMI/DP）、是否拼接屏	画面比例不对、黑边、拼接错位
播放主机	CPU、内存、显卡、硬盘剩余空间、是否有独显	4K 硬解失败、转码慢、存储不足
操作系统	Windows 版本、是否已激活、是否有管理员权限	开机自启、关机重启指令失效
网络	是否有局域网、IP 规划、交换机端口、是否跨网段	中控连不上、后台打不开
供电	是否长期供电、有无 UPS、是否有定时断电	非正常关机导致数据库损坏风险
安装位置	主机是否便于维护、USB/网口是否可触及	后期维护需拆机
内容来源	谁提供素材、更新频率、是否需要现场制作	上线后无内容可播
授权	项目授权数量、到期时间、续期联系人	到期后设备锁定

2.2 网络规划建议

每台播放终端分配固定 IP（DHCP 保留或静态），避免重启后 IP 变化导致中控失联。
四通道占用 58000–58003，规划时整段预留，不要与其它服务混用。
若中控与播放机跨网段，需在防火墙上放行上述端口（至少放行实际使用的通道）。
后台默认监听所有网卡；如只允许本机运维，可在防火墙层限制来源。

2.3 素材准备规范

类型	建议	原因
图片	JPG / PNG，分辨率与屏幕一致或等比	避免拉伸变形与黑边
视频	H.264 + AAC，MP4 封装，1080p 优先	硬解兼容性最好，CPU 占用最低
视频（4K）	确认主机支持硬解，否则先转码	软解 4K 容易掉帧
文件名	中文可用，但避免特殊符号	便于检索与排障
单文件大小	不超过 5120MB（默认上传上限）	超限会被拒绝
总容量	不超过硬盘可用空间的 70%	留出转码临时文件与日志空间

编码不统一的素材不要硬塞，先在「节目单管理」里转码；转码是串行排队执行的，批量转码要预留时间。

三、单机安装（样机）

确认系统时间正确：时间错误会导致授权校验失败、日志时间错乱。
以管理员身份运行 FoxPlayer-Setup-8.0.0.exe，按向导完成安装。
首次启动会依次完成：单实例检查 → 全屏无边框 → 防休眠 → 托盘 → 播放内核初始化 → 数据库初始化 → 启动四通道 → 开始播放。
浏览器打开 http://127.0.0.1:58000，用 admin / admin123 登录。
立即修改密码（后台右上角管理员名字 → 修改密码），并记录到交付密码表。
进入「设备授权」页，复制机器码，向授权方申请授权码并激活。
上传 2–3 个素材，建一条节目单，确认全屏播放、切换、循环均正常。
用另一台电脑访问 http://<样机IP>:58000，确认局域网可访问。
重启样机，确认开机自启 + 自动全屏播放。

3.1 配置基线（建议值）

样机确认后，把下面这张表填好，后续所有机器按同一基线配置：

配置项	建议值	说明
`device_id`	按现场编号规则，如 `EXH-A-01`	每台必须唯一，中控靠它区分设备
`control_secret`	现场统一的一串随机字符	配了才要求指令带令牌
`http_port` 等四端口	`58000`–`58003`	全场统一，便于中控配置
`auto_start`	`true`	开机自启
`default_play_mode`	`loop_all` 或 `loop_one`	按业务决定
`image_hold_time`	`10`（秒）	图片停留时长
`startup_volume`	`80`	启动音量
`monitor_use_transcoded`	`true`	监视使用转码流，降低负载
`cors_origins`	留空（除非确有跨域需求）	默认不放开跨域
`trust_proxy_headers`	`false`	无反向代理时保持关闭

四、批量部署

4.1 两种模型

模型	适用	做法	注意事项
母盘克隆	同型号主机、数量多、配置一致	做好一台样机 → 关机 → 磁盘镜像 → 恢复到其它机器	克隆前不要激活授权，克隆后每台重新申请；`device_id` 需逐台改
逐台安装	机型混杂、数量少	每台装程序 → 按基线配置 → 单独授权	慢但可控，适合异型机

4.2 每台机器必须单独处理的四件事

device_id：复制母盘会得到相同的设备 ID，必须逐台改成唯一值，否则中控无法区分。
授权：机器码与硬件绑定，母盘克隆后机器码不同，必须逐台申请授权，旧授权码不可复用。
密码：母盘里的管理员密码会一起被复制；若采用统一密码，须在交付文档中登记并由客户确认。
IP：逐台配置固定 IP，并登记到设备台账。

4.3 部署后逐台验证（建议脚本化）

在每台机器上依次确认：

检查项	命令 / 方法	期望结果
进程在跑	任务管理器看 `foxplayer.exe`	存在
HTTP 通	`Test-NetConnection 127.0.0.1 -Port 58000`	`TcpTestSucceeded : True`
设备信息	`curl http://127.0.0.1:58000/api/pub/status`	返回 JSON，`device_id` 正确
授权状态	后台授权页	「设备已授权」，到期时间正确
播放正常	看屏幕	全屏播放、无黑边、循环正常
开机自启	重启一次	无需人工操作即开始播放
局域网可达	从运维机访问 `http://:58000`	登录页正常
Android 遥控器（仅 Android 终端）	用方向键依次按上/下/左/右/OK/返回	音量变化、切上/下一项、暂停继续；返回不会直接退出
Android 调试面板（仅 Android 终端）	按「菜单」键打开面板 → 方向键移动焦点 → OK 激活「关闭面板」；再打开后点「系统设置」	面板可开可关、焦点白色高亮随方向键移动、能跳到安卓系统设置页

建议把设备 ID、IP、机器码、授权到期时间、安装日期登记成一张设备台账，后续巡检与续期都靠它。

五、备份与恢复

5.1 需要备份什么

内容	位置	是否必须
数据库 `foxplayer.db`	程序数据目录	必须（节目单、配置、账号、日志都在里面）
授权文件 `license.key`	程序数据目录	必须（丢失需重新申请）
素材目录 `media/`	程序数据目录	建议（重新上传也可恢复）
日志 `logs/`	程序数据目录	排障时备份
安装包	交付包	必须留存对应版本

程序数据目录由 Flutter 的 Application Support 目录决定（Windows 通常在 %APPDATA% 下的 com.foxplayer\foxplayer）。不同安装环境可能不同，以实际机器为准，首次交付时记录下来。

5.2 备份步骤

退出 FoxPlayer（托盘右键退出），确保数据库不再写入。
整目录复制上述内容到备份介质，命名带日期，如 FoxPlayer-Backup-20261019。
记录当前版本号（更新日志中的版本）。
恢复时反向操作：先退出程序 → 覆盖回数据目录 → 启动 → 确认节目单与授权都在。

不要只复制 foxplayer.db 而漏掉 foxplayer.db-wal / foxplayer.db-shm（WAL 模式会生成这两个文件）。最稳妥的做法是退出程序后整目录复制。

5.3 建议备份策略

场景	频率	保留
每次内容大改前	一次性	至少保留 1 份
试运行期	每周	4 份
稳定运行期	每月	3 份
升级前	必做	保留到新版本验证通过

六、日常巡检

6.1 巡检表

频率	检查项	正常标准	异常处置
每日	画面是否在播	全屏、无黑屏、无卡顿	看日志、重启程序
每日	内容是否正确	与计划一致	检查节目单是否被误改
每周	磁盘剩余空间	剩余 > 30%	清理旧素材、导出并清理日志
每周	授权剩余天数	> 30 天	提前申请续期
每周	日志有无连续错误	无成片 `ERROR`	按错误类型排查
每月	重启一次（可选）	重启后自动恢复播放	记录重启前后状态
每月	备份数据目录	备份成功且可读	重做备份
每季度	核对设备台账	IP、ID、授权一致	更新台账

6.2 无人值守的六条硬要求

关闭系统自动更新重启，或设置活动时间，避免播放中被重启。
关闭睡眠与休眠；程序已启用防休眠，但系统策略仍建议确认。
BIOS 设置断电恢复后自动开机。
关闭屏幕保护与锁屏密码弹窗。
固定 IP，不要依赖 DHCP 随机分配。
保留至少 30% 磁盘空间，转码与日志都需要写入。

6.3 日志使用

位置：数据目录 logs/foxplayer.log，超过 5MB 轮转为 foxplayer.log.1。
排查顺序：先看出错时间点前后 2 分钟，再搜关键词（ERROR、授权、转码、端口、上传）。
反馈问题时提供：设备 ID、版本号、出错时间、日志片段、复现步骤。

七、版本升级与回滚

7.1 升级步骤

阅读《6-更新日志》对应版本的「影响说明」，确认是否需要改配置或改接口。
备份数据目录（见第五节）。
运行新版本安装包覆盖安装；安装程序会先结束正在运行的程序。
启动后检查：授权状态、节目单、四通道端口、播放是否正常。
抽一台先升，观察 1–2 天再批量。

7.2 回滚

卸载新版本 → 安装旧版本 → 恢复升级前的数据目录备份。
数据库结构可能已升级，仅回退程序而不回退数据，可能出现读取异常；回滚必须连数据一起回退。
回滚后授权一般仍有效（同一机器码），但若新版本改动过授权格式，需按对应版本文档确认。

八、常见故障处置

现象	先查什么	处置
开机后不自动播放	是否开机自启、程序是否在托盘	开启 `auto_start`；检查系统启动项
后台打不开	进程、端口、防火墙	见《7-Web管理后台手册》第六节
黑屏但程序在跑	素材是否损坏、解码是否失败	换素材验证；看日志中的解码错误
播放卡顿 / 掉帧	分辨率、编码、是否软解	转码为 H.264；确认硬解生效
素材上传失败	大小、扩展名、磁盘空间	压缩/转码；清理空间
转码一直不动	队列是否卡住、FFmpeg 是否可用	看转码状态；重启程序清理队列
授权失效	到期时间、系统时间、机器码是否变化	校时；重新申请授权
中控控制无响应	端口、`control_secret`、`device_id`	用 `curl` 直连验证；核对令牌
局域网其它机器打不开后台	防火墙、网段、IP	放行端口；确认同网段
程序重复启动	是否已有实例在跑	单实例锁会激活已有窗口，属正常
数据库损坏	是否非正常断电	恢复备份；后续配 UPS

处置原则：先恢复播放，再定位原因。现场优先保证画面在播，把日志和现场状态保留下来，事后再分析。

九、交付验收清单

打印本表，逐项打勾，双方签字。

9.1 功能验收

[ ] 开机自动启动并全屏播放，无标题栏、无鼠标指针
[ ] 图片、视频均能正常播放，切换无黑屏
[ ] 循环模式符合约定（单曲 / 列表）
[ ] 触控手势可用（切项、音量、进度、暂停）
[ ] Android 终端：遥控器方向键、OK、返回均按约定工作
[ ] Android 终端：菜单键可开关调试面板，面板内方向键/OK 可用，「系统设置」可跳转
[ ] 本机 Web 后台可登录，默认密码已修改
[ ] 素材上传、删除、节目单编排、排序均正常
[ ] 局域网内其它电脑可打开后台
[ ] 四通道按约定开启，中控可正常下发指令
[ ] 播放状态可推送到约定地址（如启用）
[ ] 授权状态正常，到期时间已记录
[ ] 操作日志能查到指令记录

9.2 运维验收

[ ] 设备台账已填写（设备 ID、IP、机器码、授权到期、安装日期）
[ ] 管理员密码已登记并交接
[ ] 数据目录位置已记录
[ ] 备份已成功执行一次并验证可读
[ ] 巡检表与责任人已明确
[ ] 授权续期联系人与流程已明确
[ ] 安装包、交付资料、更新日志已移交
[ ] 常见故障处置方式已向客户运维说明

9.3 资料移交清单

资料	用途
《1-软件介绍》	了解定位与边界
《2-开始使用》	安装与首次配置
《3-使用手册》	日常操作
《4-高级配置》	批量部署与安全加固
《5-集成与 API》	中控 / 第三方对接
《6-更新日志》	版本变化与升级影响
《7-Web管理后台手册》	后台逐页操作
《8-部署与运维手册》	实施、巡检、故障处置
安装包 `FoxPlayer-Setup-8.0.0.exe`	重装与回滚

十、运维边界

FoxPlayer 的运维范围到播放终端本机为止：

它负责：本机内容的组织与播放、四通道控制、授权校验、日志记录。
它不负责：素材的拍摄与制作、网络的规划与维护、中控系统的开发、跨设备的统一编排（这些属于内容制作方、网络方、集成方）。
多台设备的统一管理需要中控 / 业务系统通过四通道调用，FoxPlayer 本身不做集中管理，也不主动向云端同步任何数据。