下载地址：https://wwbse.lanzoue.com/iD76D3p2ifih
NexPlay v1.0.0 详细功能说明
一、应用概述
| 项目 |
内容 |
| 应用名称 |
NexPlay |
| 版本 |
1.0.0（内部版本号 v1.7.26） |
| 开发者 |
最北的北 |
| 应用类型 |
飞牛NAS（fnOS）第三方应用 |
| 运行架构 |
x86_64 |
| 最低系统版本 |
fnOS 0.9.0 |
| 依赖 |
Python 3.12 |
| 应用入口 |
iframe 类型，URL 为 /cgi/ThirdParty/NexPlay/index.cgi/ |
| 应用描述 |
NexPlay 是一款 IPTV 直播播放器，支持 M3U 播放列表导入、EPG 节目单、分组管理、FLV/HLS 直播流播放，数据服务器端存储，节目单智能刷新，内存优化，全屏播放优化 |
二、核心功能模块
1. 直播流播放
1.1 多协议支持
| 协议 |
实现方式 |
说明 |
| HLS（M3U/M3U8） |
hls.js |
流式播放，支持直播和点播，自动解析 M3U8 清单 |
| FLV |
flv.js |
FLV 直播流播放，支持元数据解析和分辨率检测 |
| 原生播放 |
浏览器原生 <video> |
浏览器原生支持的视频格式直接播放 |
| PHP 代理链接 |
CGI 后端代理 |
自动识别 .php 后缀的代理链接，通过后端代理播放 |
| AllInOne 直播 |
CGI 代理 + flv.js/hls.js |
支持抖音、B站等平台的 AllInOne 聚合直播源 |
1.2 智能播放策略
- 自动协议检测：根据 URL 后缀自动判断流类型
.m3u8 / .m3u → HLS 播放.flv → FLV 播放.php → PHP 代理播放:10055 / /allinone → AllInOne 播放- 其他格式 → 先尝试直连，失败后代理
- 直连优先，代理兜底：优先直连播放，直连失败自动切换至 CGI 代理模式
- FLV → HLS 自动降级：FLV 播放失败（8 秒超时或网络错误）时自动切换 HLS 播放（抖音平台除外，抖音仅有 FLV 流）
- 错误自动恢复：
- 网络错误：自动重连（最多 5 次），重连失败则重建播放器
- 媒体错误：调用
recoverMediaError() 恢复
- 缓冲停滞：自动从最新位置重新加载（
startLoad(-1)）
- HTTP 500 自动隐藏：FLV 播放返回 500 错误时自动隐藏该频道
1.3 CGI 代理服务（后端 Python）
| 端点 |
功能 |
说明 |
/live?url= |
HLS/M3U8 代理 |
自动重写 M3U8 中的 TS 分片和嵌套 M3U8 URL 为代理 URL，解决跨域问题 |
/raw?url= |
原始资源代理 |
用于代理 TS 分片、密钥 URI 等资源，支持重定向跟踪 |
/allinone/* |
AllInOne 平台代理 |
抖音直播、B站直播等平台的直播源代理 |
代理特性：
- 支持 SSL 证书验证跳过（适应自签名证书环境）
- 支持重定向跟踪，自动获取最终 URL
- M3U8 代理时自动重写内部 URL：
- TS 分片 →
/raw?url= 代理
- 嵌套 M3U8 →
/live?url= 代理
- 密钥 URI →
/raw?url= 代理
1.4 HLS 播放优化配置
| 配置项 |
值 |
说明 |
lowLatencyMode |
true |
低延迟模式 |
maxBufferLength |
10 秒 |
最大缓冲长度（默认 30 秒，缩短以降低延迟） |
maxMaxBufferLength |
30 秒 |
最大后退缓冲（默认 60 秒） |
maxBufferSize |
30MB |
最大缓冲大小 |
startLevel |
-1 |
自动选择码率 |
startFragPrefetch |
true |
快速分片预取 |
abrEwmaDefaultEstimate |
1Mbps |
初始带宽估计（默认 500Kbps，提高以获得更高质量起始） |
forceKeyFrameOnDiscontinuity |
true |
不连续时强制关键帧 |
fixAudioTimestampGap |
true |
修复音频时间戳间隙 |
manifestLoadingMaxRetry |
3 |
清单加载重试次数 |
fragLoadingMaxRetry |
3 |
分片加载重试次数 |
1.5 播放信息展示
- 状态栏：实时显示当前播放状态（加载中 / 播放中 / 错误等）
- 分辨率显示：自动检测视频分辨率，标注清晰度等级（4K / 1080P / 720P / 480P / SD）
- 连接模式标识：
- 频道信息条：切换频道时底部浮现 5 秒，显示：
- 频道台标（大图）
- 频道名称
- 正在播放的节目名称 + 时间段
- 下一节目名称 + 时间段
1.6 全屏播放
- 支持全标准全屏 API：
requestFullscreen（标准）webkitRequestFullscreen（WebKit）webkitEnterFullscreen（iOS Safari）mozRequestFullScreen（Firefox）msRequestFullscreen（IE/Edge）
- X5 内核适配（微信 / QQ 浏览器）
- 双击视频区域切换全屏（防止单击误触）
- 全屏切换保持播放状态不中断（延迟 100ms 恢复播放）
- 竖屏模式优化：16:9 比例显示
- 降级方案：全屏 API 失败时使用 CSS 模拟全屏（fixed 定位 + 100vw/100vh）
- 全屏状态监听：通过
fullscreenchange / webkitfullscreenchange 事件同步状态
2. 频道管理
2.1 频道列表
- 左侧边栏展示所有频道
- 每个频道项显示：台标、频道名称、当前节目信息（时间 + 节目名）
- 底部显示频道总数
- 点击频道立即播放
- 悬停显示操作按钮：
2.2 频道编辑
可编辑字段：
| 字段 |
说明 |
是否必填 |
| 频道名称 |
显示名称 |
是（默认"未命名"） |
| 播放地址 |
直播流 URL |
是 |
| 台标 URL |
自定义台标图片地址 |
否 |
| 分组 |
所属分组 |
否 |
| EPG 匹配名称 |
用于精确匹配节目单的名称（如 **1, 湖南卫视） |
否 |
支持删除频道（需确认）。
2.3 收藏功能
- 点击星标按钮收藏 / 取消收藏频道
- 收藏频道在列表中高亮显示（特殊背景色）
- 侧边栏有独立的"⭐ 收藏"分组标签
- 收藏状态持久化存储
2.4 频道隐藏与恢复
- 自动隐藏：直播源检测失效或 HTTP 500 错误时自动隐藏，记录隐藏时间和原因
- 手动隐藏：通过直播源检测批量隐藏失效频道
- 查看隐藏频道：在分组管理中查看所有被隐藏的频道及隐藏原因
- 恢复隐藏频道：一键恢复，重新显示在频道列表中
- 30 天前的隐藏记录自动清理
3. 播放列表导入
3.1 文件导入
- 支持点击上传或拖拽文件到上传区域
- 支持格式：
.m3u / .m3u8 / .txt
- 拖拽时视觉反馈（边框高亮 + 背景色变化）
3.2 网络 URL 导入
- 输入 M3U/M3U8/TXT 链接在线导入
- 直连失败时自动通过 CGI
/raw 代理获取
3.3 格式解析
M3U 格式（标准 IPTV 播放列表）：
#EXTM3U
#EXTINF:-1 tvg-logo="http://..." tvg-name="**1" group-title="央视",**1综合
http://example.com/live/**1.m3u8
解析字段：
- 频道名称：逗号后的文本
- 台标：
tvg-logo 属性
- 分组：
group-title 属性（自动创建不存在的分组）
- EPG 匹配名：
tvg-name 属性
简单列表格式（国内常用）：
央视,#genre#
**1,http://example.com/live/**1.m3u8
**2,http://example.com/live/**2.m3u8
卫视,#genre#
湖南卫视,http://example.com/live/hunan.m3u8
解析规则：
分组名,#genre# → 识别为分组行频道名,URL → 识别为频道行（支持 http/https/rtmp/rtsp 协议）
导入时可选择目标分组。
3.4 手动输入
- 顶部输入框可直接输入直播地址播放
- 自动以 URL 中提取的文件名作为频道名
- 输入的地址会自动添加到频道列表
4. 分组管理
4.1 分组操作
| 操作 |
说明 |
| 新增分组 |
输入分组名称，自动生成唯一 ID |
| 重命名分组 |
点击分组名即可编辑，实时保存 |
| 删除分组 |
需确认，删除后频道移至默认分组 |
M3U 导入时根据 group-title 标签自动创建分组。
4.2 分组筛选
- 侧边栏顶部显示分组标签页
- 预置标签：全部 / ⭐ 收藏
- 自定义分组标签
- 点击标签切换当前显示的频道分组
- 分组标签支持横向滚动和换行
4.3 分组诊断
在分组管理弹窗中提供诊断工具，显示：
- 各分组名称、ID、频道数量
- 频道分组字段分布统计
- 未匹配的分组 ID 检测（频道引用了不存在的分组）
4.4 数据工具
分组管理弹窗底部提供以下工具按钮：
| 按钮 |
功能 |
| 👁️ 显示隐藏频道 |
查看所有被隐藏的频道及原因，支持恢复 |
| 📊 查看分组诊断 |
显示分组诊断报告 |
| 🔍 检测直播源 |
批量检测频道直播源可用性 |
| 🗑️ 清除所有数据 |
删除所有频道、分组、收藏、EPG 缓存（需确认，清除后需重新导入） |
5. EPG 节目单
5.1 节目单来源
- 默认源：
http://epg.51zmt.top:8000/e.xml（标准 XMLTV 格式）
- 支持自定义 XMLTV 格式的 EPG 源 URL
- 支持重置为默认源
5.2 节目单加载与缓存策略
| 触发条件 |
行为 |
| 页面加载 |
强制刷新 EPG（清除缓存后重新获取） |
| 缓存有效期 3 小时 |
有效期内使用缓存，过期后重新获取 |
| 0 点自动刷新 |
定时器调度，0 点时自动刷新 EPG |
| 日期变更检测 |
检测到跨天时自动刷新 |
| 节目数据过期 |
每 2 分钟检测，节目结束时间超过 15 分钟自动刷新 |
| 手动刷新 |
用户点击刷新按钮 |
| 代理失败降级 |
代理加载失败时自动尝试直连 |
EPG 请求超时：15 秒。
缓存存储：
iptv_epg_data - EPG 数据iptv_epg_time - 缓存时间戳iptv_epg_date - 缓存日期iptv_ep**ax_stop - 数据最大有效时间（用于判断数据是否过期）
5.3 节目单匹配算法
多级匹配策略（匹配分数越高优先级越高）：
| 分数 |
匹配类型 |
示例 |
| 3 |
完全匹配 |
"**1" = "**1" |
| 3 |
核心名匹配 |
"**1综合" → "**1" = "**1" |
| 3 |
前缀+数字精确匹配 |
"**" + "1" = "**" + "1" |
| 2 |
包含匹配（长度差 ≤ 3） |
"**5" ⊂ "**5Plus" |
| 2 |
核心名/原名交叉匹配 |
"**1" = 去除后缀的 "**1综合" |
| 0 |
前缀相同数字不同 |
"**1" ≠ "**13" |
特殊处理：
- 保留
+ 号区分 **5 和 **5+
- 频道名标准化：去除空格、连字符、下划线、点号
- 去除常见后缀：HD / 4K / 高清 / 超清 / 标清 / 综合 / 新闻 / 频道 / 直播
- 支持 tvg-id / tvg-name 自定义匹配（优先级高于频道名匹配）
- 只接受分数 ≥ 2 的匹配结果
时区转换：
- 自动处理 XMLTV 中的时区偏移（如
+0800、+0000）
- 转换为浏览器本地时区时间
5.4 节目信息展示
- 频道列表：每个频道下方实时显示当前节目名称和时间段（如
20:00-22:00 新闻联播）
- 播放信息条：切换频道时显示"正在播放"和"接下来"节目
- 自动更新：每 60 秒刷新一次节目显示
- 预告：距离下一节目开始不到 5 分钟时，显示
当前节目 → 下一节目
5.5 节目单测试
在节目单设置弹窗中提供测试功能：
- 显示响应状态码、Content-Type、耗时
- 校验 XML 格式是否正确
- 显示频道数量和节目数量
- 列出前 5 个频道信息
- 给出测试结论（✅ 格式正确 / ❌ 内容不完整 / ❌ 请求失败）
6. 台标系统
6.1 台标来源
| 来源 |
URL |
优先级 |
| 主 CDN |
https://gcore.jsdelivr.net/gh/taksssss/tv/icon/ |
1（最高） |
| 备用 CDN |
https://raw.githubusercontent.com/taksssss/tv/master/icon/ |
2 |
| EPG 台标 |
EPG XML 中的 <icon src="..."> |
3 |
| 城市地标 |
本地生成的 SVG Data URL |
4 |
| 文字台标 |
本地生成的 SVG Data URL |
5（最低） |
6.2 智能台标匹配
预置频道名称映射表，覆盖范围：
- ** 全系列：**1-**17，含 **5+
- 各省卫视：湖南、浙江、江苏、东方、北京、广东、深圳、山东、四川、湖北、安徽、河南、辽宁、天津、重庆、江西、福建（东南卫视）、贵州、云南、广西、河北、山西、陕西、甘肃、青海、宁夏、新疆、**、内蒙古、吉林、黑龙江、海南
- 地面频道：杭州综合、南京新闻等
- 专题频道：风云足球、高尔夫网球、CHC 电影、华诚电影、金鹰卡通、卡酷少儿、嘉佳卡通、纪实、上海纪实等
- 港澳及海外：凤凰中文、凤凰资讯、星空、华娱、MTV
自动标准化匹配规则：
- 去除空格、连字符、下划线、点号
- 去除常见后缀（HD / 4K / 高清 / 超清 / 标清 / 综合 / 新闻 / 频道 / 直播 / 括号内容）
- ** 特殊正则匹配：
**13新闻 → **13
- 过滤 EPG 服务器域名（避免误请求）
6.3 台标降级策略
主 CDN 加载 → 失败 → 备用 CDN 加载 → 失败 → 文字台标（SVG）
↑
城市频道 → 城市地标台标（SVG）
文字台标：根据频道名生成带颜色背景的缩写图标
- 中文名取前两个字（如"湖南" → "湖南"）
- 英文名取前两个字母或单词首字母（如"**5" → "CC"）
- 颜色根据频道名哈希值生成固定色相
城市地标台标：为主要城市频道生成带地标 emoji 的 SVG 图标，覆盖 30+ 城市：
- 直辖市：北京（🏛️）、上海（🗼）、天津（🎡）、重庆（🏯）
- 省会城市：广州（🏗️）、深圳（🌆）、杭州（🏛️）、成都（🐼）、武汉（🏯）、西安（🏛️）等
6.4 台标缓存
- 内存缓存：
logoCache 对象，避免重复 URL 生成
- localStorage 缓存：
iptv_text_logo_cache，持久化文字台标 Data URL
- 缓存优先查询，减少网络请求
7. 直播源检测
7.1 批量检测
- 检测所有可见频道（排除已隐藏频道）
- 分批并发检测：每批 5 个频道，间隔 100ms
- 进度条实时显示检测进度和百分比
- 显示正常 / 失效频道计数
7.2 检测方式
| 链接类型 |
检测方式 |
超时 |
| 普通链接 |
HEAD 请求 + no-cors 模式 |
10 秒 |
| PHP 代理链接 |
通过 CGI /live 端点 HEAD 请求 |
10 秒 |
7.3 结果处理
- 检测完成后显示结果面板：
- 正常频道计数（绿色 ✓）
- 失效频道计数（红色 ✗）
- 失效频道列表：显示频道名称 + URL 预览（前 60 字符）
- 全选 / 反选失效频道
- 批量隐藏选中的失效频道（记录隐藏原因为"直播源检测失效"）
8. 健康检测
- 定时自动检测所有可见频道
- 检测间隔：3 小时
- 分批并发控制：每批 3 个，间隔 2 秒
- 支持
AbortController 中止检测（页面关闭或新检测启动时）
- 失效频道自动隐藏并弹出 Toast 提示
9. 数据存储与同步
9.1 本地存储（localStorage）
| Key |
内容 |
过期策略 |
iptv_channels |
频道数据（JSON） |
手动清除 |
iptv_groups |
分组数据（JSON） |
手动清除 |
iptv_epg_data |
EPG 节目单数据（JSON） |
3 小时 / 数据过期 |
iptv_epg_time |
EPG 缓存时间戳 |
同上 |
iptv_epg_date |
EPG 缓存日期 |
同上 |
iptv_ep**ax_stop |
EPG 数据最大有效时间 |
同上 |
iptv_epg_url |
EPG 源 URL |
手动修改 |
iptv_hidden_channels |
隐藏频道数据（JSON） |
30 天自动清理 |
iptv_text_logo_cache |
文字台标缓存（JSON） |
手动清除 |
9.2 服务器端存储
- 后端 Python CGI 提供数据持久化 API
- 数据存储目录：
/var/apps/fnnas.liveplayer/config/data/
| 文件 |
内容 |
channels.json |
频道数据 |
favorites.json |
收藏数据 |
groups.json |
分组数据 |
settings.json |
设置数据 |
epg_cache.json |
EPG 缓存数据 |
epg_time.txt |
EPG 缓存时间戳 |
9.3 数据同步机制
页面加载 → 从服务器读取数据（5秒超时）
↓ 成功 ↓ 超时/失败
使用服务器数据 使用本地数据
↓ ↓
渲染界面 渲染界面
↓ ↓
标记 isDataLoaded = true 标记 isDataLoaded = true
- 自动同步：数据变更时标记
isDataModified，2 秒防抖后自动同步到服务器
- 手动同步：点击同步状态指示器触发
- 同步状态指示器：
- 🟢 已同步（绿色对勾）
- 🟡 同步中（**圆圈）
- 🔴 同步失败（红色叉号）
9.4 数据清理
| 清理项 |
条件 |
时机 |
| EPG 缓存数据 |
超过 7 天 |
页面加载时 |
| 隐藏频道记录 |
超过 30 天 |
页面加载时 |
| 文字台标缓存 |
localStorage 溢出时 |
按需 |
10. 界面与交互
10.1 界面布局
**─────────────────────────────────────────────────**
** NexPlay ** 输入直播地址 ** 播放 导入 分组 节目单 清空 ** 🟢已同步 **
**───────────**─────────────────────────────────────**
** 频道列表 ** **
** ──────── ** **
** 全部**收藏 ** 视频播放区域 **
** 央视**卫视 ** **
** ──────── ** **
** **1 ** **
** 20:00 新闻** **
** **2 ** **
** 20:00 经济** **──────────────────────** **
** ... ** ** 📺 **1 ** **
** ** ** 正在播放: 新闻联播 ** **
** ** ** 接下来: 天气预报 ** **
** ** **──────────────────────** **
** 12 个频道 ** **
** 更新: 20:00**─────────────────────────────────────**
** ** 就绪 1920x1080 (1080P) 代理 全屏 **
**───────────**─────────────────────────────────────**
10.2 主题与配色
- 深色主题设计
- 主背景色：
#0a0a0f
- 侧边栏背景：
#0f0f15
- 头部背景：
#1a1a2e
- 主色调：渐变
#667eea → #764ba2（紫蓝色系）
- 自定义滚动条样式
10.3 弹窗系统
| 弹窗 |
触发方式 |
内容 |
| 导入弹窗 |
点击"导入"按钮 |
文件上传区域 + URL 输入 + 目标分组选择 |
| 分组管理弹窗 |
点击"分组"按钮 |
新增分组 + 分组列表 + 数据工具 |
| 节目单设置弹窗 |
点击"节目单"按钮或 EPG 状态标签 |
EPG URL 配置 + 测试 + 调试信息 |
| 直播源检测弹窗 |
点击"检测直播源" |
进度条 + 检测结果 + 批量操作 |
| 频道编辑弹窗 |
点击频道的 ✏️ 按钮 |
名称/URL/台标/分组/EPG匹配 编辑 |
| 调试信息弹窗 |
播放出错时自动弹出 |
错误类型 + 详细信息 |
| 自定义对话框 |
查看隐藏频道等场景 |
自定义标题和内容 |
10.4 移动端适配
playsinline / webkit-playsinline 属性：iOS 内联播放- X5 内核适配：
x5-video-player-type="h5" - H5 同层播放器x5-video-player-fullscreen="true" - X5 全屏x5-video-orientation="portrait" - 竖屏方向
- 视频初始静音（适应移动端自动播放策略），播放后自动取消静音
- 响应式布局：工具栏 flex-wrap 自动换行
三、后端 API 接口清单
3.1 数据 API
| 端点 |
方法 |
功能 |
请求体 |
响应 |
/api/data |
GET |
获取所有数据 |
- |
{ channels, favorites, groups, settings, epgCache, epgTime } |
/api/data |
POST |
保存所有数据 |
{ channels?, favorites?, groups?, settings?, epgCache?, epgTime? } |
{ ok, saved } |
/api/channels |
GET |
获取频道列表 |
- |
频道数组 |
/api/channels |
POST |
保存频道列表 |
频道数组 |
{ ok } |
/api/favorites |
GET |
获取收藏列表 |
- |
收藏数组 |
/api/favorites |
POST |
保存收藏列表 |
收藏数组 |
{ ok } |
3.2 代理 API
| 端点 |
方法 |
功能 |
参数 |
/raw?url= |
GET |
代理原始资源 |
url - 目标资源 URL |
/live?url= |
GET |
代理 HLS 直播流 |
url - M3U8 地址 |
/allinone/* |
GET |
代理 AllInOne 平台直播源 |
路径参数 |
3.3 静态文件服务
- 提供 HTML / CSS / JS / 图片等静态资源
- 支持的 MIME 类型：html、css、js、json、png、jpg、gif、svg、ico、xml、m3u、m3u8、txt
- 路径安全检查：禁止
.. 路径穿越
3.4 CORS 支持
所有 API 响应均包含跨域头：
Access-Control-Allow-Origin: *Access-Control-Allow-Methods: GET, POST, OPTIONSAccess-Control-Allow-Headers: *- 支持 OPTIONS 预检请求
四、安装与运维
4.1 安装信息
| 项目 |
内容 |
| 安装方式 |
FPK 包标准安装 |
| 运行依赖 |
Python 3.12 |
| 应用类型 |
iframe（通过飞牛 NAS 桌面 iframe 加载） |
| 数据目录 |
/var/apps/fnnas.liveplayer/config/data/ |
| 应用目录 |
/var/apps/fnnas.liveplayer/target/ui/ |
| 授权路径 |
已禁用（disable_authorization_path=true） |
| 端口检测 |
已关闭（checkport=false） |
4.2 生命周期脚本
| 脚本 |
触发时机 |
说明 |
install_init |
安装初始化 |
无特殊操作 |
install_callback |
安装完成后 |
输出"安装完成" |
upgrade_init |
升级初始化 |
无特殊操作 |
upgrade_callback |
升级完成后 |
输出"升级完成" |
uninstall_init |
卸载初始化 |
无特殊操作 |
uninstall_callback |
卸载完成后 |
可选保留或删除用户数据（默认保留，注释中有 rm -rf 命令） |
config_init |
配置初始化 |
无特殊操作 |
config_callback |
配置变更后 |
无特殊操作 |
main |
服务管理 |
支持 start/stop/status 命令（当前均为空操作） |
4.3 卸载数据保留
卸载时默认保留用户数据，如需清除需手动删除：
rm -rf /var/apps/fnnas.liveplayer/data
五、版本更新日志
v1.7.26
- 修复节目单过期问题
- 缩短缓存时间至 3 小时
- 添加手动刷新按钮
- 显示最后更新时间
- 智能检测过期节目自动刷新
六、技术栈
| 组件 |
技术 / 版本 |
| 后端语言 |
Python 3.12 |
| 前端框架 |
原生 HTML / CSS / JavaScript |
| HLS 播放器 |
hls.js（CDN 引入） |
| FLV 播放器 |
flv.js（CDN 引入） |
| EPG 格式 |
XMLTV 标准格式 |
| 数据格式 |
JSON |
| CGI 协议 |
标准 CGI（环境变量 + stdin/stdout） |
| 台标 CDN |
jsDelivr / GitHub Raw |
