Web 管理后台手册

本机后台逐页操作说明

一、访问与登录

1.1 访问地址

• 端口取自配置项 http_port，默认 58000；改端口后需重启程序。
• 后台使用 Hash 路由，页面地址形如 http://127.0.0.1:58000/#/playlist，刷新不会 404。
• 设备 IP 可在「系统设置 → 服务与端口 → 网络信息」中直接看到，不用去系统里查 ipconfig。

1.2 默认账号

首次启动会自动创建该账号。首次登录后请立刻改密码：点击后台右上角的管理员名字 → 「修改密码」。默认密码是公开的。

1.3 登录与登出规则

• 登录成功后浏览器保存令牌（localStorage 的 fox_token），有效期 24 小时，到期自动回登录页。
• 修改密码会让所有已签发的旧令牌立即失效，其它电脑上的后台会被踢下线，需要重新登录。
• 同一 IP 连续登录失败 5 次（10 分钟内）会被临时锁定，等窗口过去再试，或换一台机器登录。
• 点右上角「退出登录」会清掉本机令牌并回到登录页。

1.4 登录后的两道门

登录成功不等于能进后台，路由守卫按顺序判断：

1. 有没有令牌：没有或已过期 → 回登录页。
2. 设备有没有授权：未授权 → 强制跳转「设备授权」页；授权已过期同样按未授权处理。

所以一台新机器首次使用的顺序是：登录 → 复制机器码 → 申请授权码 → 激活 → 进入后台。授权页上有「进入管理后台」按钮，激活后点它即可。

二、页面地图

#/monitor-play 是唯一不需要登录的页面，设计意图是让现场人员在一台只用来监看的电脑上直接全屏看画面。它只能看和控制播放，看不到素材、设置与授权。若现场对这一点有安全顾虑，可在网络层限制 58000 端口的可访问来源。

三、逐页说明

3.1 登录页（#/login）

若忘记密码：目前没有"找回密码"入口，需在有数据目录访问权限的机器上按《4-高级配置》的密码重置方法处理，或联系技术支持。

3.2 设备授权页（#/authorize）

页面从上到下四块：

1. 状态横幅：显示「设备已授权 / 设备未授权」，已授权时同时显示到期时间。
2. 机器码卡片：显示本机机器码，右侧「复制」按钮一键复制。机器码由网卡名、主机名、操作系统与版本、CPU 核心数计算得出，换网卡或重装系统可能改变机器码，届时需重新申请授权。
3. 授权信息卡片（仅已授权时显示）：授权状态、到期时间；剩余不足 30 天时额外显示「剩余天数」并标黄。
4. 激活卡片：粘贴供应商提供的授权密钥（形如 Base64(Base64)），点「激活设备」；已授权时按钮变为「更新授权」，用于续期或换绑。 - 已授权时下方另有「清除授权」按钮，清除后设备立即锁定，除非确有必要不要点。

激活失败常见原因：密钥复制不完整（漏了中间的 .）、密钥与本机机器码不匹配、密钥已过期、系统时间不正确。

3.3 监控播放页（#/monitor-play）

面向"只看画面"的场景，全屏、无侧边栏。布局由配置决定：常规模式显示控制面板（可设为浮动、可换到上/左/右/下），clean 模式默认不显示任何元素，鼠标移动时浮出控制层。

该页依赖 WebSocket 58003 接收播放状态；WS 不通时画面仍能播（媒体走 HTTP），但控制按钮不会实时反映状态。

3.4 仪表盘（#/monitor）

登录后的默认首页，用于日常看护。

说明：

• 仪表盘里的预览是浏览器端的另一路播放，用于看护，不是把设备屏幕画面抓过来。画面比例、色彩以设备实际输出为准。
• 「关机 / 重启系统」执行的是设备操作系统级的关机与重启，需要程序具备相应权限；无人值守现场使用前请确认断电风险。
• 这些按钮最终都转换成与外部中控相同的指令（play / pause / shutdown 等），效果与《5-集成与 API》一致。

3.5 节目单管理页（#/playlist）

左右两栏，左边素材库、右边播出单，是整个后台使用频率最高的页面。

左栏：素材库

上传限制：扩展名白名单、单文件默认上限 5120MB（由 max_upload_size_mb 控制）。上传后服务端按 MD5 命名落盘，同名内容不会重复占用空间。

右栏：播出单

一次完整的换内容流程：

1. 左栏上传新素材，等缩略图出现（视频等转码状态变为「已转码」或确认可直接播）。
2. 把素材逐个加入右栏，拖动调整顺序。
3. 选择循环模式，点保存。
4. 回到仪表盘确认画面已切到新内容；或直接在右栏点某项试播。

3.6 操作日志页（#/logs）

记录经四通道下发的指令，用于追查"谁在什么时候让设备做了什么"。

列表列：ID、指令、通道、操作者、参数、结果、时间。参数以 JSON 展示，便于核对调用方传了什么。单次查询有上限（500 条），排查久远问题时请缩窄时间范围。

3.7 授权管理页（#/auth-manage）

与「设备授权」页同源，但嵌在后台布局内，登录且已授权后从这里进入。用于：

• 查看当前授权状态与到期时间；
• 到期前更新授权（粘贴新密钥 → 更新授权）；
• 核对机器码是否与申请时一致。

3.8 系统设置页（#/settings）

六个可折叠卡片，底部有吸底保存栏；有未保存改动时会提示「有未保存的更改」。

保存后的生效范围：

• 立即生效：默认播放参数、音量、解码器优先级、推送开关与目标、转码参数（对后续任务生效）。
• 需重启：四个通道的端口号、媒体目录、HTTPS 证书路径。

3.9 API 文档页（#/docs）

后台内置的接口说明，列出可用指令、参数与示例。它是给集成方看的速查页，完整、权威的接口契约以《5-集成与 API》为准；两者冲突时以交付文档与源码为准。

四、常见任务速查

五、安全与权限提示

1. 默认密码必须改：admin123 是公开的，且后台默认监听所有网卡，同一局域网内任何人都能访问到登录页。
2. 不要直接把 58000 暴露到公网：本机后台定位是局域网运维工具，没有多用户、没有角色、没有审计分级。
3. 需要限制调用来源时配 control_secret：配置后，TCP / UDP / WebSocket 与 HTTP 公开控制接口必须携带正确令牌，能挡住"知道端口就能控制"的情况。
4. 跨域默认关闭：若要从别的网页调用本机接口，需在配置里显式填写 cors_origins，只填可信来源。
5. 监控播放页免登录：这是有意设计，不是漏洞。需要收紧时请在网络层限制来源 IP。
6. 授权清除不可撤销：清除后设备立即锁定，需重新导入有效密钥。

六、后台打不开时怎么查

按顺序排查，多数问题在前三步就能定位：

1. 程序在不在跑：看系统托盘是否有 FoxPlayer 图标；没有则程序未启动或已退出。
2. 端口通不通：在设备本机执行 Test-NetConnection 127.0.0.1 -Port 58000；不通说明 HTTP 通道未启动（可能 http_enabled 被关或端口被占用）。
3. 是不是端口被占用：netstat -ano | findstr :58000，若被别的进程占用，改 http_port 或结束占用进程。
4. 本机能开、别的机器打不开：检查 Windows 防火墙入站规则是否放行该端口，以及两台机器是否在同一网段。
5. 能打开登录页但登录后白屏：多为浏览器缓存了旧版前端资源；强制刷新（Ctrl+F5）或换浏览器。程序升级时会自动重新解压前端资源，无需手工清目录。
6. 页面提示未授权：属正常拦截，去授权页完成激活。

日志位置：数据目录下 logs/foxplayer.log，按 5MB 轮转，保留一份 .log.1。反馈问题时请附上出错时间点前后的日志。

分享