iptv-checker 完整指南：M3U 播放列表批量播放源检测与 Docker 部署

【免费下载链接】iptv-checkerIPTV checker tool for Docker && CMD, check your playlist is available项目地址: https://gitcode.com/GitHub_Trending/ip/iptv-checker

对于手里握着大量 IPTV M3U 播放列表、又懒得逐个频道点开的用户来说，iptv-checker 是个对口的批量播放源检测工具。部署一个 Docker 容器后，你就能在 Web 界面里验证 M3U / M3U8 / TXT 列表中每个频道的可用性，跑 FFmpeg 深度检测，配定时任务，最后把只剩可用频道的列表导出给播放器。全程不需要写代码，容器起来之后都在浏览器里完成。

🚀 Docker 一条命令把服务拉起来

官方镜像托管在 Docker Hub，拉取后直接起容器：

docker run -d \ -p 8081:8089 \ --name iptv-checker \ zmisgod/iptvchecker

启动完成后，浏览器访问http://127.0.0.1:8081即可进入管理界面。容器内部服务默认监听 8089 端口（WEB_PORT环境变量），外部映射到哪个端口随意改。

想要声明式的部署方式，项目自带的 docker-compose.yaml 已经配好了8081:8089端口映射和restart: always，跑一句docker-compose up -d就行。不想用容器的话，也可以从项目 Releases 下载 CLI 二进制直接跑，或者用 Tauri 打包的桌面版（Windows / macOS / Linux 都有）。

🔑 配置 GitHub Token：60 次到 5000 次的差距

如果你计划从 GitHub 仓库直接抓取频道列表，这一步建议在首次检测前完成。GitHub API 未认证的频率限制是 60 次/小时，配置 token 之后能到 5000 次/小时：

1. 登录 GitHub，创建一个 Fine-grained token
2. 权限选Public repositories+Contents: Read-only，遵循最小化原则
3. 在 Web 后台的系统设置 → 基础配置里填入github_token字段

保存时系统会自动调 API 验证 token 有效性，无效会被直接拒掉。不配 token 也能用：服务会优先走 API，触发限流后自动降级为 HTML 页面解析。

🔍 跑第一次 M3U 验证

进入检测页面，粘贴 M3U 链接或上传本地文件，确认参数后开始检测。检测方式有两种，可以按需组合：

跑完之后，结果表格里每个频道都会标上可用 / 不可用状态。v3.2.0 起支持关键词匹配，可以用通配符*做模糊搜索，配合状态筛选快速定位目标频道。几百个频道以前得在播放器里手动点着看，现在一次批量跑完，总耗时主要取决于并发数和超时设置。

⏰ 定时检测任务怎么配最合理

一次检测跑通后，可以在「定时检查任务」里建任务，让它每天固定时间自动跑。几个关键参数：

• 并发数：同时检测的频道数量，调大缩短总时长，源站不稳定时保守一点
• 检测方式：HTTP 或 FFmpeg，按准确度需求选择
• 立即执行：距离下次运行时间超过 3 分钟时，任务列表才会展示这个按钮

v5.0.0 之后，单源检测加了强制超时、运行超 2 小时自动复位，"一个频道卡死导致后续任务全部停摆"的问题已经修复。定时任务本身也支持导入导出，换实例时不用重新配。

📦 结果筛选与可用列表导出

检测任务结束后，结果可以直接导出为 M3U 或 TXT 格式。导出时有几个值得留意的选项：

• 按状态过滤：只导出判定为可用的频道
• 地址族分开导出：IPv4 / IPv6 列表各自输出（v4.4.0 起支持），不同网络环境各用一份
• 频道名清洗：解析时自动规范化tvg-name/tvg-id，去掉 4K 这类质量后缀；可选在频道名后追加 HD / FHD 或 720p / 1080p 标签
• 字符替换配置：批量替换频道名里的特殊字符

导出的文件可以直接丢进播放器。配过 EPG 的话，M3U 里会带上节目单引用，频道在播放器里就有图标和节目名称。

🛠️ 长期维护：EPG、代理与分组映射

列表要长期维护的话，下面这几块配置值得了解：

• EPG 管理（v4.7.0 起）：EPG 源配置、同步、缓存管理一站完成，系统自带一个默认 EPG 源
• 网络配置：proxy、自定义 headers、user_agent 独立放在network.json，与基础配置分离
• 频道分组映射：本地维护tvg-name到group-title的映射，EPG 没覆盖的频道也能快速归类
• 配置导入导出：系统配置打包成 ZIP 备份，重建容器时一键恢复

项目还内置了 SSRF 防护，拦截内网 IP 和危险协议，并做 URL 合法性校验。功能的完整演进记录可以看项目根目录的 CHANGELOG.md。

整体看下来，iptv-checker 把"拿到源列表 → 验证可用性 → 定期维护 → 导出干净列表"这条链路都覆盖到了：一条命令起服务，一次检测出结果，一个任务自动跑，一次导出直接进播放器。如果只是先试试水，跑一遍 CLI 二进制对小型列表做一次验证，再迁到 Docker 也不迟。

【免费下载链接】iptv-checkerIPTV checker tool for Docker && CMD, check your playlist is available项目地址: https://gitcode.com/GitHub_Trending/ip/iptv-checker