每天认识一个 GitHub 项目：iptv-api 项目介绍

想要流畅、频道丰富的电视直播体验，却常因找不到稳定可靠的直播源而烦恼？手动收集的源时常失效，不同地区的网络兼容性也令人头疼。如今，有了 iptv-api 项目，这些难题都将迎刃而解。它是一个强大的IPTV直播源自动更新平台，犹如一位不知疲倦的“源管家”，能够全自动地从网络各处采集直播源，再经过智能筛选、精准测速和多重验证，最终生成一份高质量、可直接使用的播放列表。

无论你是想搭建家庭媒体中心、研究流媒体技术，还是单纯享受稳定免费的电视直播，只需将生成的结果地址输入 VLC、PotPlayer 等任意播放器，瞬间就能拥有一个覆盖国内外众多频道的私人电视台。该项目高度自动化的流程和丰富的个性化配置，让你从此告别维护直播源的繁琐，忍不住想立刻体验这份“开机即看”的便捷。

项目概览

项目核心信息如下：

项目名称：iptv-api
项目简介：📺 一个全自动的IPTV直播源更新平台，支持自动采集、筛选、测速与生成流程🚀。每日更新两次，提供免费订阅结果，直接输入播放器即可观看。支持频道自定义、个性化配置，并兼容订阅源、组播源、酒店源与本地源。同时支持IPv4/IPv6、接口验证、推流等功能。可在工作流、Docker、命令行、GUI等多种环境下部署。
GitHub 地址：https://github.com/Guovin/iptv-api
主要编程语言：Python
星标数量：⭐ 20722
分支数量：🍴 6985
开源协议：MIT License
创建时间：2024-02-04
最后更新：2025-12-14

项目标签

auto-update awesome epg iptv iptv-api iptv-channels iptv-free iptv-m3u iptv-m3u8 iptv-playlist ipv4 ipv6 live m3u m3u8 playlist rtmp schedule tv tvbox

最新发布

版本: 1.7.3**发布日期: 2025-10-15发布标题: v1.7.3

发布内容摘要:

• 新功能:

  • 新增对正则表达式定义频道别名的支持，匹配机制更为灵活。
  • 新增对台标库地址 (logo_url) 和台标文件类型 (logo_type) 的配置。
  • 新增利用环境变量修改 Docker 容器内 config.ini 配置参数的功能。
  • 新增多种日志文件：频道结果统计 (statistic.log)、未匹配频道记录 (nomatch.log)、详细测速数据 (speed_test.log)。

• 优化:

  • 对频道缓存结果的解冻策略进行了优化。
  • 更新了纯真 IP 数据库及部分地区的组播 IP 信息。
  • 更新了默认的订阅源和频道别名数据，删除了无效的源地址。

查看完整发布历史

项目文档预览

核心特性

本项目是一套完整的 IPTV 直播源解决方案，其最大亮点在于高度的自动化与灵活的个性化配置。

• 全自动处理流程：项目自动执行从“采集”到“筛选”、“测速”到“生成”的完整链条。默认情况下，系统会在北京时间每天6:00和18:00自动运行两次，持续输出可用的直播源列表，无需人工操作，真正实现自动化运维。
• 多渠道聚合与智能筛选：支持从多种来源获取直播源，包括公开订阅源、组播源、酒店源以及用户自定义的本地源。系统会对所有接口进行实时测速（包括延迟、带宽和分辨率），并根据用户设置的偏好（如 IPv4/IPv6 优先级、归属地、运营商等）进行智能排序与过滤，确保输出列表的质量达到最优。
• 强大定制与扩展能力：提供丰富的配置选项，用户可通过编辑 config.ini 文件或设置环境变量，自由调整频道模板、接口数量、过滤规则及输出格式。特别支持 RTMP/HLS 推流功能，可将直播流通过服务器带宽进行转换，显著提升弱网环境下的播放流畅度与兼容性。此外，还支持 EPG 电子节目单与自定义台标。

项目运行预览

为了降低使用门槛，项目提供了图形界面（GUI）软件，适合不熟悉命令行的用户。启动后，可通过界面按钮一键完成更新与管理。


在线体验地址
该项目本身不开放直接的在线播放服务。部署完成后，可通过生成的本地地址（如 http://你的IP:5180）在浏览器中查看并订阅直播源列表。

技术栈

• 后端/核心：Python 3.13、Pipenv（虚拟环境及依赖管理）
• 前端/界面：基于 Python 的 GUI 框架（例如 Tkinter 等），同时提供 Web 服务界面
• 网络与流媒体：FFmpeg（用于分辨率检测与 RTMP 推流）、带 RTMP module 的 Nginx（用于流媒体转发）
• 部署与运行：Docker / Docker Compose、GitHub Actions（实现工作流自动更新）
• 架构概览：项目采用模块化设计，核心为调度引擎，按序协调“源采集器”、“测速引擎”、“过滤器”、“结果生成器”等模块。支持以命令行脚本、常驻后台服务、容器化应用或 GUI 程序等多种形态运行，适应不同使用场景。

快速上手

以下介绍几种主要的部署与启动方式，请根据实际环境选择合适的方法。

环境要求

• Python：版本不低于 3.8（推荐 3.13）
• Git：用于克隆项目代码
• （可选）Docker 与 Docker Compose：用于容器化部署
• （可选）FFmpeg：如需使用分辨率过滤或 RTMP 推流功能，需额外安装

部署与启动方法

推荐方式：使用 Docker Compose 快速搭建

这是搭建完整环境最便捷的方法，可一次性部署所有依赖组件。

1. 准备配置文件
   在服务器或本地机器上新建一个文件夹（例如 iptv-api），并将项目中的 docker-compose.yml 文件放入该目录。

2. 启动服务
   打开终端，切换到该文件夹，然后运行以下命令：

   docker compose up -d

   该指令会自动从 Docker Hub 下载最新镜像，并在后台启动服务。

3. 验证运行状态
   等待启动完成后，在浏览器中输入 http://你的服务器IP:5180 即可访问直播源列表页面。服务默认在启动时立即执行一次更新，后续会根据配置定期自动刷新。

第二种方式：通过 Docker 手动运行

若希望更灵活地控制容器参数，可执行如下命令：

1. 拉取镜像：

   docker pull guovern/iptv-api:latest

2. 运行容器（以下为常用挂载示例）：

   docker run -d \ --name iptv-api \ -p 5180:5180 \ -p 8080:8080 \ -p 1935:1935 \ -v /你的本地路径/config:/iptv-api/config \ -v /你的本地路径/output:/iptv-api/output \ guovern/iptv-api

• 使用 -p 参数映射端口：5180 用于 Web 服务、8080 用于 HLS 流、1935 用于 RTMP 流。
• 使用 -v 参数挂载目录：将本地的 config 和 output 目录挂载至容器内，便于修改配置及持久化保存结果。

方法三：Python 环境（适合开发或深度定制场景）

1. 克隆项目：

   git clone https://github.com/Guovin/iptv-api.git
   cd iptv-api

2. 安装依赖（使用 Pipenv）：

   pip install pipenv   # 若未安装 pipenv
   pipenv install --dev

3. 启动更新：

   pipenv run dev

4. 启动 Web 服务（可选，用于提供结果访问页面）：

   pipenv run service

方法四：使用预编译的GUI软件（适合Windows用户）

1. 访问项目的 Release页面。
2. 下载与操作系统匹配的最新GUI软件压缩包（例如 iptv-api-windows-amd64.zip）。
3. 解压文件后，直接运行主程序（如 iptv-api.exe），在图形界面中点击“启动”按钮即可开始使用。

基础操作与进阶功能

• 基本使用: 部署完成后，播放列表地址通常为 http://你的IP:5180 或 http://你的IP:5180/m3u。将此地址添加到VLC、PotPlayer或Tivimate等播放器的“打开网络串流”选项，即可开始播放。

• 自定义频道列表: 编辑 config/demo.txt 文件，按格式 频道名称,频道ID 添加所需频道，例如 CCTV-1,cctv1。

• 配置调整: 所有核心设置均通过 config/config.ini 文件管理。你可以在此文件中设定更新频率、偏好IPv4或IPv6、过滤低分辨率源、指定归属地等。修改后需重启服务才能生效。

• API调用: 内置Web服务提供多个API端点，例如：

  • GET / 或 GET /m3u: 获取默认M3U列表。
  • GET /ipv6/m3u: 获取IPv6专用的M3U列表。
  • GET /log/result: 查看本次更新的有效结果日志。

• 开启RTMP推流: 在 config.ini 中设置 open_rtmp = True，并确保服务器已安装FFmpeg。开启后，直播流将通过RTMP或HLS协议转发，访问 http://你的IP:8080/hls/m3u 可获取推流后的列表，从而获得更好的播放兼容性。

项目分析

热度与健康度指标

• 星标/分支比: 2.97（星标20,722，分支6,985）。这一比例相当高，说明项目不仅广受欢迎，还有大量用户在进行二次开发、定制和部署，社区活跃度极佳。
• 更新活跃度: 高。项目始于2024年2月，截至2025年12月14日仍在持续更新，版本发布规律，修复和功能迭代频繁，是一个积极维护中的项目。
• 社区参与度: 高。项目拥有近7000个分支，Issue列表中已解决问题数量多且开放问题为零，表明开发者能高效响应并处理社区反馈。同时设有专门讨论区用于收集频道别名，体现了良好的协作氛围。

推荐理由

本项目是开源领域一个成熟且实用的工具类项目，强烈推荐的原因包括：

1. 技术栈实用且清晰: 核心使用Python开发，语言易于上手，代码结构清晰，方便开发者阅读、学习网络请求、异步处理、流媒体等实现逻辑，是Python实战项目的优秀参考。
2. 社区高度认可: 获得超过 2万个GitHub星标，充分证明了其功能、稳定性和实用性。在IPTV相关开源项目中位居前列，是同类方案中的顶尖选择。
3. 持续维护与迭代: 项目保持高频更新，不断引入如正则表达式别名、Docker环境变量支持、更详尽的日志等新特性，并持续优化核心算法和数据库，确保了长期生命力及对新需求的适应能力。
4. 文档完整详尽: 提供中文和英文README，文档结构清晰，涵盖简介、特性、配置说明及多种部署方式的详细教程。特别是配置部分，每个参数都有详细解释和默认值，降低了使用门槛。

使用建议

• 学习与参考: 适合Python开发者学习如何构建一个完整的自动化系统，涵盖定时任务、网络爬虫、性能测试、Web服务及多模式部署。
• 即拿即用的工具: 对于普通用户，可直接通过Docker或GUI软件部署，作为可靠的家庭娱乐基础设施，轻松享受高清直播。
• 二次开发基础: 项目的模块化设计可作基础组件，集成到更大的媒体管理系统或智能家居项目中。
• 关注动态: 建议留意项目的Releases页面和讨论区，及时获取更新以享受最新功能和性能改进，同时参与频道源的共建。

本文档基于Guovin/iptv-api项目官方仓库内容整理，旨在提供清晰的项目介绍和使用指引。所有工具的使用者应遵守当地法律法规，请勿用于非法用途！关注我，每天8点带你解锁一个GitHub开源项目！