Skip to content

README.md

Latest commit

 

History

History
443 lines (335 loc) · 17.5 KB

README.md

File metadata and controls

443 lines (335 loc) · 17.5 KB

IPTV Manager

GitHub Actions Workflow Status GitHub release (latest by date) Docker Pulls

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（推荐）

  1. 下载 docker-compose.yml

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

  2. 启动服务

    docker-compose up -d

  3. 访问应用

    • 前端界面: 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 综合优化 加权得分排序

综合优化算法

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

  1. Min-Max 归一化:

    • 延迟（越小越好）: (max - value) / (max - min)
    • 码率（越大越好）: (value - min) / (max - min)
    • 稳定性（越大越好）: (value - min) / (max - min)

  2. 加权计算:

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

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

过滤规则

流级别过滤:

  • 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 连接、最近分析时间

致谢

数据来源

AI 协助开发

v0.4.5 贡献者

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

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

v0.3.0 及之前贡献者

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

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

许可证

本项目采用 MIT 许可证。