把散落的直播源聚成一套自托管频道系统（iptv）

想在电视上看直播的人，手头往往攒着一堆来路不一的对 m3u 链接：央视频一套、咪咕一套，B站和抖音的直播间又要单独找。链接失效了没人管，节目单还得自己拼。这类需求有个共同点，来源太多、维护太少。akiralereal/iptv 的做法是把它们收进一套自己跑的服务里：内置多个平台的抓取模块，也能接订阅、自定义直连和需要网页解析的源，统一聚合去重后输出播放列表与 EPG 节目单。

akiralereal/iptv 是一套用 JavaScript 写的自托管直播源管理工具，把央视频、咪咕、B站等平台的直播信号聚合成 M3U 播放列表与 EPG 节目单，供电视端播放器订阅。

默认部署可聚合 800+ 频道，覆盖央视频的 63 个公开频道加 10 个本人账号可访问的会员频道、iPanda 熊猫直播、央视与全国卫视、各省地方台、体育赛事、亚太与国际频道，以及 B站、抖音、虎牙、斗鱼的直播抓取。运行方式是 Docker Compose 或 Node.js，官方镜像 akiralereal/iptv:latest，官方说明把 NAS 与家庭服务器列为主要场景。仓库地址是 https://github.com/akiralereal/iptv ，许可证 GPL-3.0，主要语言 JavaScript，当前 1121 Star、352 Fork、7 个开放 Issue。

下面按「装起来之后会遇到什么」来组织：先列部署后常见的几类状况，再逐个拆开看触发条件和处理方式，最后区分哪些是改不了的设计限制、哪些只是没配好。

装上之后最先遇到的事

• 用仓库里的 docker-compose.yml 在 NAS 上启动后日志看着正常，管理台却打不开。有过极空间 NAS 的用户报过这个情况，该 Issue 已解决。
• 订阅地址粘进 APTV 后每个频道都能看，大约两小时之后一个都看不了。
• 央视频会员频道要导入登录态，Docker 与 NAS 部署没有桌面，得从自己电脑的浏览器开发者工具里复制整段 Cookie。
• 央视频在官网播放很流畅，换成本项目的源之后每隔十几秒卡顿转圈。
• 咪咕含电视端权益的会员，理论上能拿到「超清4K (投屏专享)」这一档，实际只出 1920 的频道。

逐个拆开看

管理台打不开

触发条件是容器起来了、日志没有报错，但浏览器访问管理台没有响应。报这个情况的用户用的是极空间 NAS 和仓库自带的 compose 文件。这条 Issue 状态是已解决，仓库里没有写清楚最终是哪一处配置引起的，遇到时只能按 Issue 里的排查路径走一遍。

订阅过一阵子全部失效

现象是刚把订阅地址粘进 APTV 时每个频道都能看，约两小时后一个都看不了，换手机端重新粘贴会弹出提示。报这个情况的部署在群晖 NAS 上。项目对这一类的处理分散在几个版本里：v4.27.0 把公开频道的清单加厚到约 30 秒，官方清单入口偶尔卡住十来秒时播放器不再停在原地；v4.30.0 加了登录失效的提醒中心。这条 Issue 已解决。

会员频道的登录态怎么进去

央视频的会员频道靠后台浏览器打开官网页面来解扰，用的是部署者本人的持久登录态。有桌面的机器可以从源管理自动打开登录窗口；Docker 与 NAS 没有桌面，只能从自己电脑浏览器的开发者工具里复制整段 Cookie 导入，会话 cookie 是 HttpOnly，书签工具读不到。服务端之后自动续期。v4.28.0 为了让会员频道首次打开快一点，让播放页和账号检查同时打开官网，触发了官网刷新令牌的互斥，把这台服务器上的央视频登录全部清掉、会员频道无法播放；v4.28.1 修复了这个问题，已经被登出的需要升级后重新导入一次登录态。

官网流畅、本项目卡顿

有用户反馈带宽足够、央视频官网长时间观看不卡顿，换成本项目的源后每隔十几秒卡顿转圈，并猜测原因涉及请求头校验与加密 key。项目侧的对应改动是：v4.27.0 把公开频道清单加厚到约 30 秒，并让播放器在官方入口短暂卡住时自动续上（issue #158）；v4.28.0 收紧了公开频道向官方取票的节奏，避免扫台和版权停播时的反复重试把服务器出口打进限流（issue #162、#158）。这条 Issue 已解决。

咪咕 4K 投屏档拿不到

持有咪咕含电视端权益的会员（四屏、超级足球通等），在列着「超清4K (投屏专享)」的赛事上把画质选到 4K 时，应该按咪咕 App 投屏的取法拿到 3840×2160、H.265。有用户反馈订阅了足球通、也调了 4K 画质，仍然只拿到 1920 的频道。v4.27.0 与 v4.30.0 的版本说明都提到修复 issue #117，而这条 Issue 目前的状态仍是待解决。

哪些是限制、哪些是配置问题

属于设计限制的部分改不了。频道数量随平台接口状态、地区网络和启用的模块动态变化，800+ 只是默认部署下的一个量级。部分模块的可用性绑在上游平台的行为上：陕西广电的官网会整批换地址名、旧名立即失效，所以地址不写进播放列表；山西省级频道的播放路径按「频道码 + 当天日期」算出，只认当天、零点即换。海外频道与澳门两个模块的官网和视频只对大陆以外开放，部署服务的机器和播放设备都要能连到大陆以外。公告分组只要显示就固定在播放列表第一位，不支持删除、移动、排序或重命名。

属于配置问题的部分，基本都能在后台对应页面处理。央视频会员频道、北京广播电视台的 9 个电视频道、四川广电的 9 个固定电视台，都要在「源管理」里导入本人账号的登录态；凤凰卫视登录普通凤凰秀账号可以拿到 720p / 25 帧，不需要付费会员；抖音的抓取分类和数量、以及是否改用公开网页「全部」页原始顺序或 HLS，都在源管理里改；海外频道与澳门模块默认关闭，需要时在后台打开。

版权边界上，项目在 README 里声明自己是自托管软件工具，除自制使用公告短片外不托管第三方音视频节目。仓库及运行时可能整理互联网上公开可访问的播放地址与频道元数据，但「公开可访问」不代表内容属于公有领域，也不代表已获得复制、转播或商业使用授权。这类工具能用的范围是自有资产或已获授权的目标，超出这个范围的抓取、转发与分发会带来法律与平台侧的风险。

同类项目放在一起看

如果连一台常开的机器都不想维护，这个项目就不合适：它要跑 Docker 或 Node.js，还要跟着上游平台接口的变动升级，v4.28.0 那次升级甚至会把央视频登录态清掉，得重新导入一次。这种情况下，形态更轻的 indefined/UserScripts 一类浏览器脚本更顺手。只关心 B 站一个平台的直播间，xfgryujk/blivechat 这类单点工具也比装一整套系统省事。

绕开的办法

1. 央视频会员频道登录态导不进去时，有桌面的机器用源管理里的自动登录窗口；Docker 与 NAS 从自己电脑浏览器复制整段 Cookie，不要指望书签工具。
2. 后台网页里播放报错（例如提示 levelParsingError），按页面提示「新窗口打开」，或改用 VLC / IINA 播放。
3. 播放器直连分片会被拒的频道，比如广东体育赛事、澳门莲花卫视，改用带 ?relay=2 的全代理订阅。
4. 播放器对订阅格式挑剔时，改用兼容版或全代理版的播放列表输出。
5. 某个平台模块用不上或持续报错，在源管理里关掉对应开关；v4.29.0 起后台的「抓取模块」页可以按开关筛选，详情里能看到该模块包含哪些频道。
6. 不想在电视上看到公告分组，在「我的频道」里逐条隐藏，随时可以在「已隐藏」里恢复。

仓库与 Issue 里没有给出更多规避方案，上面之外的替代做法需要自行评估。

这套系统适合手里有一台常开的 NAS 或家庭服务器、要把多个平台的直播源统一编排并分发给家里几台电视的人，也适合愿意为更高画质配置本人平台账号、并且接受跟着上游接口变动升级的人。只想在浏览器里随手看两眼、或者不愿意维护一台常开设备的人，用不上它；只关心 B 站一个平台的直播，用 xfgryujk/blivechat 这类单点工具更省事。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.3 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。