Jellyfin TVHeadend插件安装启用后完整操作流程
重要前提：TVHeadend插件只是连接器，本身不提供直播源。必须单独部署TVHeadend后端服务（群晖Docker容器），插件只是让Jellyfin去读取TVHeadend里面已经准备好的频道、EPG、录制任务。 插件安装 ≠ 能看电视，后端TVHeadend才是核心。
阶段1：插件页面填写连接参数（你当前这个页面）
- TVHeadend Hostname or IP Address：填写NAS内网IP
192.168.0.51，禁止 localhost - HTTP Port：
9981（TVHeadend网页后台端口） - HTSP Port：
9982（流媒体通信端口） - Username / Password：填写TVHeadend后台的管理员账号密码（在TVHeadend网页后台创建）
- Pre-recording Padding：
60，Post-recording Padding：60（录制前后各多录60秒，防止漏片头片尾） - 其余全部保持默认，点保存。
✅ 保存后，插件只是建立通信，频道不会自动出现，需要TVHeadend后端提前配置好频道。
阶段2：先去TVHeadend网页后台（http://192.168.0.51:9981）完成后端配置【这一步是关键，很多人漏掉】
- 登录TVHeadend后台，新建 IPTV Network，导入M3U直播源
- 扫描MUX，识别所有直播流，生成Services
- 将Services映射为【频道Channels】，所有频道必须填写非0的频道编号（数字，如1、2、3），没有编号，Jellyfin插件无法同步频道列表（高频踩坑点）
- 在TVHeadend配置EPG节目源，绑定频道与节目单
- 确认TVHeadend后台可以直接播放频道，确认源本身正常。
阶段3：回到Jellyfin控制台，同步TVHeadend频道与节目指南
- 左侧菜单：直播电视
- 点【刷新节目指南】，Jellyfin会通过TVHeadend插件拉取TVHeadend内的频道列表、EPG节目单
- 等待刷新任务执行完毕
- 刷新完成后，【直播电视】→【频道】里面就会出现所有TVHeadend导入的频道，可以直接点击播放；节目指南页面可以看到电视节目预告。
阶段4：录制功能使用（PVR）
- 在节目指南页面，选中节目，点击录制，任务会下发到TVHeadend后端执行
- 录制文件保存在TVHeadend容器挂载的NAS硬盘目录，Jellyfin【数字录像机】页面查看已完成录制视频
常见失败排查清单
- 保存插件设置后，刷新节目指南，频道空白
- 原因：TVHeadend里面频道没有填写频道编号（Number），必须给每个频道分配大于0的数字编号
- 解决：TVHeadend后台 → Configuration → Channel/EPG → Channels，编辑频道，填入编号，保存后重新刷新Jellyfin节目指南
- 插件保存报错，连接失败
- ① IP填错，填了localhost；② TVHeadend容器没有映射9981、9982端口；③ TVHeadend账号密码错误；④ TVHeadend的访问权限没有放行Jellyfin容器IP
- 频道刷新出来，但播放失败
- TVHeadend后端本身无法播放该频道，问题根源在TVHeadend的M3U源，不是Jellyfin插件
- 有频道，但节目指南空白
- TVHeadend后端没有配置EPG，或者频道没有和EPG节目完成映射
补充对比
- TVHeadend插件方案：适合需要DVR定时录制、精细化频道管理
- Jellyfin原生M3U调谐器方案：不需要TVHeadend容器、不需要插件，最简单快速看直播，没有录制功能