IPTV Manager

IPTV Manager 是一个功能强大的 IPTV 直播源聚合与优化平台，专为家庭内网部署设计。它能帮助您整合来自多个公网 M3U 订阅源的直播流，自动进行频道匹配、流质量分析和稳定性评估，并生成经过优化的增强型播放列表，实现低延迟、高画质的直播体验。

该项目基于 FastAPI (后端) 和 Vue.js 3 (前端) 构建，采用 Celery + Redis 的异步任务处理架构，支持高并发流质量分析。

核心功能

📡 多订阅源管理

支持添加多个公网 M3U 订阅源
可配置刷新频率（默认 2 小时）
自动去重和增量更新
订阅源状态监控和 Benchmark 分析

🎯 智能频道匹配

基于别名库的自动频道匹配算法
支持精确匹配和模糊匹配
未匹配流支持手动绑定或创建新频道
频道别名库自动更新（每周同步）

📊 深度流质量分析

延迟测试: TCP 连接建立 + 首包到达时间
码率测试: FFprobe 视频流元数据提取 + FFmpeg 实测码率
稳定性测试: 连接稳定性、数据流连续性、HLS 健康度
视频属性分析: 分辨率、帧率、编码格式、色彩配置

⚡ 智能任务调度

基于数据库的应用层优先级队列
手动触发 > 源刷新 > 定时触发的优先级机制
任务持久化与恢复，系统重启不丢任务
动态并发控制，保护系统资源

🔔 统一通知系统

首页通知栏: 系统重要通知和告警
最近维护面板: 任务进度和完成状态时间线
SMTP 邮件: 关键事件邮件通知

📺 动态播放列表

四种优化策略：延迟优先、画质优先、稳定性优先、综合优化
Redis 缓存加速，快速响应
自动隐藏不可达流，智能容错

🎨 现代 Web 界面

Vue.js 3 + Element Plus 构建
响应式设计，支持手机端访问
实时进度显示和状态监控
配置备份与恢复功能

🐳 容器化部署

Docker Compose 一键部署
多架构支持 (amd64/arm64)
健康检查和自动恢复

核心概念

术语	定义
互联网订阅源	通过公网 URL 访问、持续更新的 M3U 直播流列表
直播流 (Stream)	通过 M3U 等格式提供的实时视频流地址
频道 (Channel)	电视频道实体，可能拥有多个来自不同服务器的直播流地址（主备线路）
增强源	由本项目在私有内网进行评估优化后，向内网设备提供的优化版 M3U 播放列表

数据关系

互联网订阅源 (1) ──→ (N) 直播流
       ↓
直播流 (N) ──→ (1) 频道 (通过别名匹配关联)
       ↓
频道 (1) ──→ (N) 直播流（一个频道下有多条线路）

快速开始

使用 Docker Compose（推荐）

下载 docker-compose.yml

curl -o docker-compose.yml https://raw.githubusercontent.com/neon9809/iptv-manager/main/docker-compose.yml

启动服务
```
docker-compose up -d
```
访问应用
- 前端界面: http://<your-server-ip>:8001
- 后端 API: http://<your-server-ip>:8000
- 播放列表: http://<your-server-ip>:8001/playoptimized

端口说明

端口	服务	说明
8000	Backend	FastAPI 后端服务，提供 REST API
8001	Frontend	Nginx 前端服务，提供 Web 界面和播放列表代理
5432	PostgreSQL	数据库（容器内部）
6379	Redis	缓存和消息队列（容器内部）

镜像说明

项目镜像托管在 GitHub Container Registry：

后端: ghcr.io/neon9809/iptv-manager-backend:latest
前端: ghcr.io/neon9809/iptv-manager-frontend:latest

配置说明

环境变量

变量名	默认值	说明
`DATABASE_URL`	-	PostgreSQL 连接字符串
`REDIS_URL`	`redis://localhost:6379/0`	Redis 连接字符串
`ANALYSIS_FREQUENCY_MINUTES`	`45`	自动分析频率（分钟）
`ANALYSIS_WORKERS`	`6`	并发分析 Worker 数量
`ANALYSIS_TIMEOUT_SECONDS`	`3`	单流分析超时时间
`FULL_ANALYSIS_TIMEOUT_SECONDS`	`30`	完整分析超时时间
`BITRATE_RECORD_DURATION_SECONDS`	`10`	码率录制时长
`FORGIVENESS_PARAM`	`10`	不可达原谅次数
`CHANNEL_ALIAS_URL`	-	频道别名库远程地址

运行时配置

通过 Web 界面的「通用设置」面板，可以动态调整：

分析模式: 快速分析 / 完整分析
分析频率: 自动分析触发间隔
原谅参数: 连续不可达多少次后隐藏
并发 Worker: 同时分析的最大流数量
测试超时: 单个流的测试时长

架构设计

系统架构图

┌─────────────────────────────────────────────────────────────────┐
│                      前端层 (Vue.js 3 + Element Plus)            │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │ 首页面板  │  │ 订阅源   │  │ 频道线路 │  │ 通用设置 │        │
│  │          │  │ 管理     │  │ 管理     │  │          │        │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘        │
└───────────────────────────┬─────────────────────────────────────┘
                            │ HTTP/WebSocket
┌───────────────────────────┴─────────────────────────────────────┐
│                    后端层 (FastAPI + Uvicorn)                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ REST API     │  │ WebSocket    │  │ Static Files │          │
│  │ (CRUD/Query) │  │ (Progress)   │  │ (Logo/M3U)   │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└───────┬─────────────────────┬──────────────────┬────────────────┘
        │                     │                  │
┌───────┴────────┐  ┌─────────┴────────┐  ┌──────┴───────┐
│  PostgreSQL 16 │  │ Redis 7.2        │  │ Celery       │
│  (主数据库)     │  │ - Playlist 缓存  │  │ - 定时任务    │
│  - 频道/流数据  │  │ - Celery Broker  │  │ - 并发分析    │
│  - 分析历史     │  │ - 任务去重       │  │ - 优先级队列  │
│  - 任务队列     │  │                  │  │              │
└────────────────┘  └──────────────────┘  └──────────────┘
        │                                          │
        └──────────────────┬───────────────────────┘
                           │
                 ┌─────────┴─────────┐
                 │ FFmpeg + ffprobe  │
                 │ (视频流分析工具)   │
                 └───────────────────┘

异步任务系统

本项目的核心亮点是基于数据库的应用层优先级队列：

┌─────────────────────────────────────────────────────────────┐
│                     Task 数据表                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ id | task_type | priority | status | payload | ...  │   │
│  └─────────────────────────────────────────────────────┘   │
└───────────────────────────┬─────────────────────────────────┘
                            │
                   ┌────────┴────────┐
                   │ Celery Beat     │
                   │ dispatch_tasks  │
                   │ (每 10 秒)       │
                   └────────┬────────┘
                            │ 按优先级拉取 PENDING 任务
                            ▼
        ┌───────────────────┼───────────────────┐
        │                   │                   │
        ▼                   ▼                   ▼
   analysis-high       analysis            refresh
   (优先级 7-9)        (优先级 4-6)        (优先级 1-3)
        │                   │                   │
        └───────────────────┼───────────────────┘
                            │
                   ┌────────┴────────┐
                   │ Celery Worker   │
                   │ (并发执行)       │
                   └─────────────────┘

优先级机制：

优先级 9: 手动触发单个流分析
优先级 7: 手动触发批量分析
优先级 5: 订阅源刷新
优先级 3: 自动定时分析
优先级 1: 视频基本信息分析

播放列表策略

系统提供四种优化策略，每个频道自动选择最佳线路：

端点	策略	排序逻辑
`/playfast`	延迟优先	延迟从小到大排序
`/playbest`	画质优先	码率从大到小排序
`/playstable`	稳定性优先	稳定性评分从高到低排序
`/playoptimized`	综合优化	加权得分排序

综合优化算法

对于每个频道下的所有可用流：

Min-Max 归一化:
- 延迟（越小越好）: (max - value) / (max - min)
- 码率（越大越好）: (value - min) / (max - min)
- 稳定性（越大越好）: (value - min) / (max - min)

加权计算:

score = normalized_latency × 0.5 + normalized_bitrate × 0.3 + normalized_stability × 0.2

排序: 按得分从高到低，得分最高的流作为该频道的首选线路

过滤规则

流级别过滤:

unreachable > 原谅参数 且 active != 'true' 的流不显示
active = 'false' 的流不显示
active = 'true' 的流始终显示（无视原谅参数）

频道级别过滤:

若频道下所有流均被过滤，该频道不出现在播放列表中

流质量分析

分析模式

模式	测试项目	适用场景
快速分析	仅延迟测试	系统资源受限时自动切换
完整分析	延迟 + 码率 + 稳定性 + 视频属性	默认模式，提供全面评估

稳定性指标

v0.2.1 引入细化的稳定性测试：

指标	说明	范围
`connection_stability`	连接稳定性，测试期间 TCP 连接是否断开	0-1
`continuity_score`	数据流连续性，收到数据的时间片比例	0-100
`hls_health_score`	HLS 协议健康度，m3u8 和 ts 切片获取成功率	0-100
`stability_score`	综合稳定性评分（加权平均）	0-100

综合评分公式：

stability_score = connection_stability × 40 + continuity_score × 0.4 + hls_health_score × 0.2

不可达流处理

分析成功：unreachable_count = 0
分析失败：unreachable_count += 1
自动隐藏：unreachable_count > 原谅参数 且 active != 'true'
自动恢复：后续分析成功后自动取消隐藏

通知系统

三条通知渠道

渠道	Key	用途
首页通知栏	`homepage-banner`	系统重要通知、告警、进度提示
最近维护面板	`maintenance-timeline`	任务进度、完成状态时间线
SMTP 邮件	`smtp`	关键事件邮件通知（需配置）

通知事件

事件	默认启用	说明
订阅源自动更新异常	✅	订阅源刷新失败时通知
系统状态异常	✅	系统健康检查异常时通知
直播流不可达阈值	✅	不可达流超过 30% 时通知
可用频道阈值	✅	可用频道低于 50% 时通知
频道全线路不可用	✅	某频道所有流都不可达时通知

API 文档

播放列表端点

方法	端点	描述
`GET`	`/playfast`	获取延迟优先播放列表
`GET`	`/playbest`	获取画质优先播放列表
`GET`	`/playstable`	获取稳定性优先播放列表
`GET`	`/playoptimized`	获取综合优化播放列表

核心管理端点

方法	端点	描述
`GET`	`/api/v1/sources`	获取订阅源列表
`POST`	`/api/v1/sources`	添加订阅源
`PUT`	`/api/v1/sources/{id}`	更新订阅源
`DELETE`	`/api/v1/sources/{id}`	删除订阅源
`GET`	`/api/v1/channels`	获取频道列表
`PUT`	`/api/v1/channels/{id}/order`	更新频道排序
`GET`	`/api/v1/streams`	获取直播流列表
`PUT`	`/api/v1/streams/{id}/active`	修改流状态
`POST`	`/api/v1/analysis/trigger`	手动触发分析
`GET`	`/api/v1/benchmark`	获取性能基准数据
`GET`	`/health`	健康检查

交互式文档

FastAPI 自动生成 Swagger UI 和 ReDoc 文档：

Swagger UI: http://<your-server-ip>:8000/docs
ReDoc: http://<your-server-ip>:8000/redoc

技术栈

后端

组件	技术选型	版本	选型理由
Web 框架	FastAPI	0.115+	原生异步支持、自动 API 文档、类型验证
ASGI 服务器	Uvicorn	0.30+	高性能异步服务器
ORM	SQLAlchemy	2.0+	异步支持、复杂查询优化
数据库	PostgreSQL	16+	JSONB 支持、MVCC 并发控制、全文搜索
任务队列	Celery	5.4+	Celery Beat 定时任务、优先级队列
缓存/消息队列	Redis	7.2+	高性能缓存、Celery Broker
视频处理	FFmpeg + ffprobe	-	流质量分析、元数据提取
数据验证	Pydantic	2.0+	FastAPI 原生集成

前端

组件	技术选型	版本	选型理由
前端框架	Vue.js	3.4+	组合式 API、TypeScript 支持
UI 组件库	Element Plus	2.8+	丰富组件（Timeline/Accordion/Table）
构建工具	Vite	5.0+	快速开发体验
HTTP 客户端	Axios	1.6+	Promise 支持、拦截器

部署

组件	技术选型	说明
容器化	Docker	多架构镜像（amd64/arm64）
编排	Docker Compose	单机部署方案
反向代理	Nginx	静态文件服务、API 代理、负载均衡
健康检查	Docker HEALTHCHECK	检查 DB/Redis 连接、最近分析时间

致谢

数据来源

频道别名数据: YYKM_assets/channel_alias.json

AI 协助开发

v0.4.5 贡献者

Trae IDE 中的 GLM-5 模型完成了 v0.4.5 版本的主要开发工作：

统一通知系统设计与实现
任务进度通知功能
配置备份恢复功能
日志系统优化
M3U 格式修复
UI/UX 优化

v0.3.0 及之前贡献者

Manus AI 协助完成了项目架构设计和核心模块开发：

基于数据库的异步任务调度方案
任务队列、调度器、执行器核心模块
多架构 Docker 构建和 CI/CD 配置

许可证

本项目采用 MIT 许可证。

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.github/workflows		.github/workflows
app		app
frontend		frontend
.env.example		.env.example
.gitignore		.gitignore
Dockerfile.backend		Dockerfile.backend
Dockerfile.frontend		Dockerfile.frontend
README.md		README.md
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
nginx.conf		nginx.conf
requirements.txt		requirements.txt
update.md		update.md

Folders and files

Latest commit

History

Repository files navigation

IPTV Manager

目录

核心功能

📡 多订阅源管理

🎯 智能频道匹配

📊 深度流质量分析

⚡ 智能任务调度

🔔 统一通知系统

📺 动态播放列表

🎨 现代 Web 界面

🐳 容器化部署

核心概念

数据关系

快速开始

使用 Docker Compose（推荐）

端口说明

镜像说明

配置说明

环境变量

运行时配置

架构设计

系统架构图

异步任务系统

播放列表策略

综合优化算法

过滤规则

流质量分析

分析模式

稳定性指标

不可达流处理

通知系统

三条通知渠道

通知事件

API 文档

播放列表端点

核心管理端点

交互式文档

技术栈

后端

前端

部署

致谢

数据来源

AI 协助开发

v0.4.5 贡献者

v0.3.0 及之前贡献者

许可证

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages