LibreTV Wiki
LibreTV 是一个免费的在线视频聚合搜索与观看平台，基于 Next.js 15（App Router）重构。本 Wiki 是项目的完整文档；README 保持精简，细节都在这里。
我想……
- 部署一个自己的实例 → 部署（最小配置只需一个
PASSWORD），环境变量含义见 配置； - 添加影片源 / 直播源，或给别人分享一份源列表 → 数据源 与 直播 / IPTV；
- 看看能怎么用（快捷键、换源测速、进度同步）→ 播放器、首页推荐；
- 排查问题 → FAQ；
- 了解设计或参与开发 → 架构、开发、代理与安全。
快速开始
# Docker 部署（推荐）
echo "PASSWORD=your-password" > .env
docker compose pull && docker compose up -d
# 本地开发
npm install
PASSWORD=dev-password npm run dev # http://localhost:8080
生产部署务必通过 HTTPS 访问（localhost 除外），否则会话 cookie 会被浏览器丢弃——表现为「密码正确却无法登录」，详见 部署。
文档目录
部署与配置
| 文档 | 内容 |
|---|---|
| Deployment | Docker / 手动部署、镜像分发与版本管理、升级与旧版迁移 |
| Configuration | 环境变量权威表、部署者预置（源 / 直播 / 订阅）、用户级运行时设置、IndexedDB 存储结构 |
使用指南
| 文档 | 内容 |
|---|---|
| Data-Sources | 点播源接入、健康度自动停用、数据源订阅（LibreTV-SourceList / TVBOX）与分享 |
| Live-IPTV | 直播源管理、频道浏览、HLS/FLV 播放、节目单（EPG）、分片级批量测活 |
| Recommendations | 首页推荐三源（豆瓣 / Bangumi / 影视榜单）与切换 |
| Player | 播放器功能、快捷键、广告过滤、代理回退、进度与历史 |
| FAQ | 按主题分组的常见问题排查 |
开发者
| 文档 | 内容 |
|---|---|
| Architecture | 技术栈、目录结构、组件一览、数据流、与旧版的架构差异 |
| Development | 开发环境、测试、发布流程、文档职责边界 |
| Proxy-Security | 会话鉴权、SSRF 双层防护、代理行为与上游伪装 |
核心特性
- 聚合搜索：多采集站服务端并行搜索，流式逐源呈现，单源失败不影响整体，用户 IP 不暴露给第三方；异常源按健康度自动停用（30 分钟 → 24 小时 → 长期），无需手动剔除；
- 跨源同名聚合与换源测速：同名影片合并为一张卡片，跨源测速排序，一键切换保留集数位置；
- HLS 播放：ArtPlayer + hls.js，广告分片过滤、自动连播、倍速、快捷键、移动端长按 3 倍速；直连失败自动代理重试；
- 直播 / IPTV：M3U 解析 + XMLTV 节目单，HLS / HTTP-FLV 站内播放，分片级批量测活；
- 源订阅：一份 JSON 同时下发点播源与直播源，兼容 TVBOX 配置，支持导出文件或一键发布为订阅链接；
- 首页推荐：豆瓣 / Bangumi 新番 / 影视榜单三源可选，免 key 免配置；
- 进度同步：播放进度与观看历史存于本机 IndexedDB，精确到秒续播；支持配置导入导出整机迁移；
- PWA + 亮暗主题：可安装到桌面 / 主屏幕，主题切换无首屏闪烁。
与旧版（静态 HTML + Express）的关系
本项目是 LibreTV 旧版（backup-2025 分支）的完整重构。功能对齐的同时修复了旧版的多项问题（历史记录 XSS、m3u8 分片鉴权丢失、密码哈希暴露等），架构差异详见 Architecture，配置迁移见 Deployment · 从旧版迁移。