IPTV 系列④：Jellyfin + IPTV Scraper：全球直播媒体中心
🐴 赛博牛马出品 | 系列第四篇
看完《IPTV 系列③：主流方案横评与选型指南》后，你已经知道了各种 IPTV 方案的优缺点。如果你想把直播电视融入现有的媒体库管理体验——海报墙、节目单、时移录制、跨设备同步——那么 Jellyfin + IPTV Scraper 是目前免费方案里最完整的组合。
本文将详细说明：如何用双仓库架构自动抓取全球频道、如何配置 EPG 电子节目单、如何在 Jellyfin 里搭建 Live TV 系统，以及实测体验如何。
一、为什么把 IPTV 接入 Jellyfin
Jellyfin 本身是一个强大的开源媒体服务器，支持海报墙整理、 metadata 刮削、转码、DLNA 推送……很多人已经用它管理了自己的电影和剧集收藏。但它还有一项被低估的能力：Live TV & DVR。
把 IPTV 接入 Jellyfin 后，直播电视不再是孤立的"电视应用"，而是融入了整个媒体中心。对家庭用户来说，每个人用自己账号登录，看到的是统一的界面和进度记录。
二、双仓库架构：iptv-scraper → iptv-validator
这是本文与原计划最重要的区别。数据流从单仓库方案升级为双仓库独立验证架构，稳定性大幅提升。
架构总览
┌─────────────────────────────────────────────────────────────────┐
│ 每日凌晨 03:00 │
│ ┌──────────────┐ │
│ │ iptv-scraper │ 拉取缓存 → 抓取全球源 → 去重合并 │
│ │ SKIP_VALIDATION=1│ → filtered/ + output/hk_merged.m3u │
│ └──────┬───────┘ │
└─────────┼───────────────────────────────────────────────────────┘
│ filtered/ 输出
▼
┌─────────────────────────────────────────────────────────────────┐
│ 每日凌晨 03:30 │
│ ┌──────────────────┐ │
│ │ iptv-validator │ 并发验证 URL（100 workers） │
│ │ CDN 白名单跳过 │ → validation_cache.json 更新 │
│ │ 分层调度（见下） │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼ validation_cache.json 已知优质源跳过验证
┌─────────────────────────────────────────────────────────────────┐
│ Jellyfin Server │
│ m3u 播放列表 + EPG XMLTV → Live TV Channels + Guide │
└─────────────────────────────────────────────────────────────────┘
分层验证调度策略
为了平衡资源消耗和频道质量，iptv-validator 对不同地区的频道采用了不同的验证频率：
频道类型 | 验证频率 | 理由
| HK / TW / MO | 每日 | 港台源最常用，质量波动最大 |
| China 内地 | 每周 | 源相对稳定，无需每日验证 |
| Global 全球 | 每 30 天 | 欧美频道变动少，避免无效消耗
CDN 白名单机制
在验证之前，还有一个加速层：CDN 白名单。如果 URL 命中 CDN 白名单（如香港本地 CDN），则直接标记为优质源，跳过并发验证，直接进入可用列表。这个机制大幅减少了验证耗时，同时保证本地 CDN 源优先。
输出文件
图1：效果总览
图2：架构流程图
三、EPG 电子节目单配置
3.1 EPG 是什么
EPG（Electronic Program Guide）即电子节目单。有了 EPG，你知道"这个频道现在在播什么"、"晚上八点有什么节目"，而不需要靠蒙。Jellyfin 的 Live TV 界面里，EPG 直接以时间格子的形式展示出来。
3.2 EPG 数据来源
自建 EPG aggregator 推荐使用 `hierros/docker-xmltv-aggregator`，一个 Docker 容器聚合多个来源，支持故障自动切换。
推荐 EPG 来源：
3.3 Docker 部署 EPG aggregator
docker-compose.yml
version: "3.8"
services:
xmltv-aggregator:
image: hierros/docker-xmltv-aggregator:latest
container_name: xmltv-aggregator
environment:
- TZ=Asia/Hong_Kong
volumes:
- ./config:/app/config
- ./output:/app/output
ports:
- "8899:8000"
restart: unless-stopped台标格式：https://epg.112114.xyz/logo/{channel_name}.png
图3：EPG 界面
四、Jellyfin Live TV 设置
4.1 环境准备
Jellyfin 已安装（参考《IPTV 系列①：Docker 基础》）
最低配置：2核4G（录制需要更多存储）
已有 m3u 播放列表和 EPG XMLTV 文件
4.2 添加 TV Tuner
1. 进入 Jellyfin 管理后台 → Live TV → TV Tuners → Add TV Tuner
2. 类型选择：M3U Tuner
3. 填入 m3u URL：
- 港台优先：`https://raw.githubusercontent.com/xJEYDAin/iptv-scraper/master/output/hk_merged.m3u`
- 全球覆盖：`https://raw.githubusercontent.com/xJEYDAin/iptv-scraper/master/output/all_merged.m3u`
4. 设置 FQDN（外网访问必需）
4.3 绑定 EPG XMLTV
1. 管理后台 → Live TV → Guide Providers → Add XMLTV
2. 填入 EPG URL：`http://你的服务器IP:8899/xmltv.xml` （⚠️ 本机/内网使用，外网需配置 HTTPS）（或直接用 epg.112114.xyz 的公开地址）
3. Jellyfin 会自动匹配频道台标
4.4 频道台标调校
如果台标不显示或显示错误，可以用 `logo_map.py` 做三层匹配：
第一层：精确匹配 → TVB → https://.../tvb.png
第二层：前缀匹配 → TVB_News → TVB_* 规则
第三层：模糊包含 → "TVB" in channel_name → 台标注入
`normalize` 函数会清洗频道名（去掉序号 `CH001`、括号 `()`、标点符号），提高匹配成功率。如果仍有问题，在 Jellyfin 频道管理里手动覆盖台标 URL 即可。
图4：Jellyfin TV 设置
图5：Jellyfin 播放效果
五、实测体验
5.1 换台速度
💡 优化建议：如果主要看港台频道，优先使用 `hk_merged.m3u`，CDN 白名单命中率高，换台速度接近本地电视。
5.2 EPG 准确率
💡 优化建议：港台频道用 `epg.pw` 准确率更高；日韩频道建议同时开启多个 EPG 来源做冗余。
5.3 时移与录制
Jellyfin 原生支持 timeshift，配置好录制目录后即可使用：
时移：进度条上会显示"Live"绿点和时间偏移量
录制格式：MPEG-TS，可后期转 MP4
存储建议：录制 1 小时约 1~2GB，建议至少 500GB 可用空间
图6：时移功能
六、与 Plex + Live TV 对比
结论：如果你追求免费 + 高度定制 + 全球频道覆盖，选 Jellyfin；如果你不介意付费、想要开箱即用的省心体验，选 Plex Pass。
图7：Plex vs Jellyfin 对比
七、常见问题 Q&A
Q1：EPG 节目单数据不准怎么办？
A：换一个 EPG 来源试试。HK 频道推荐用 `epg.pw`，日韩用 `epg.112114.xyz`。也可以同时配置多个 EPG 来源，aggregator 会自动切换到可用来源。
Q2：频道台标不显示？
A：检查 m3u 文件中各频道是否包含 `tvg-logo` 属性。如果原始 m3u 没有台标，用 `logo_map.py` 批量注入，或在 Jellyfin 频道管理里手动上传/填入台标 URL。
Q3：频道顺序乱，如何调整？
A：Jellyfin 管理后台 → Live TV → Guide Providers → 编辑频道顺序。或者直接修改 m3u 中 `#EXTINF` 的 `group-title` 和 `tvg-name` 的排序来预设顺序。
Q4：换台卡住/无法播放？
A：先用 VLC 打开 m3u URL 测试是否正常播放。确认 Jellyfin 服务器网络可以访问 GitHub raw 和源站。如果用的是 CDN 白名单模式（`SKIP_VALIDATION=1`），确保验证缓存里该源状态正确。
Q5：能否同时使用多个 m3u 列表？
A：可以。Jellyfin 支持添加多个 M3U Tuner，分别对应不同地区列表。港台用一个 Tuner，欧美用一个 Tuner，在 Guide 里会合并显示。
系列文章索引：
第四篇：Jellyfin + IPTV Scraper：全球直播媒体中心（本文）
本文首发于 赛博牛马の博客，如需转载，请注明出处。
评论区