源码系统概览
文章正文
TubeSync 是一套把 YouTube 频道与播放列表自动同步到本地媒体库的视频频道同步系统源码，相当于给自建媒体服务器加了一层 PVR 录制能力，新视频一发布就自动下载进硬盘。
项目作者 meeb 独立开发维护，采用 AGPL-3.0 许可证开源，不同于 MIT 或 Apache 宽松协议，修改后对外提供网络服务需公开修改源码，最后更新 2026 年，依赖 Django 5.2.4 框架，amd64 与 arm64 双架构镜像随仓库发布。
源码简介
内部封装 yt-dlp 与 ffmpeg 加任务调度器，按预设画质与格式下载音视频并分类存放，音频进 audio 子目录、视频进 video 子目录。
支持定时索引、失败退避重试、保留期与最大容量控制，下载失败的任务会按退避时间反复重试，长时间无人值守也能稳定运行。
配置媒体服务器地址后，下载完成自动触发 Plex 与 Jellyfin 刷新索引，打开电视就能看到新内容，全程无需人工干预。
Web 界面提供仪表盘、源列表、媒体总览等页面，订阅的频道与播放列表、下载队列与磁盘占用一目了然。
和同类视频订阅方案对比 vs yt-dlp，TubeSync 的差异点在无人值守的 PVR 体验。
| 对比维度 | TubeSync | yt-dlp |
|---|---|---|
| 使用形态 | Web 界面订阅制长期运行 | 命令行按次执行 |
| 媒体服务器 | 自动通知 Plex 与 Jellyfin | 需自行处理 |
| 失败处理 | 退避定时自动重试 | 需脚本包装 |
| 部署方式 | Docker 一条命令 | Python 环境配置 |
整体来看，给家庭媒体库做自动追更硬盘仓库，TubeSync 是目前最省心的开源自托管方案。
适用场景
- 家庭 NAS 用户自动归档订阅频道新视频。
- Plex 与 Jellyfin 用户让媒体库自动更新。
- 树莓派等低功耗设备长期无人值守下载。
- 内容创作者备份自己频道的全部历史视频。
技术栈与运行环境
技术栈为 Python 与 Django Web 框架，内部封装 yt-dlp 与 ffmpeg，官方提供 Docker 与 Podman 镜像，amd64 与 arm64 均支持，树莓派 3 以上可用。
先建好配置与下载目录再拉镜像运行容器，也可写进 Docker Compose 与其他媒体服务一起编排管理。
功能亮点
- 频道与播放列表订阅制自动下载。
- 画质与格式按源预设精细控制。
- 失败任务退避定时自动重试。
- 保留期与最大容量自动清理。
- 下载完成自动通知媒体服务器。
- Docker 单容器部署树莓派可跑。
技术架构与部署指南
安装与部署提示
下载源码包后建好 config 与 downloads 两个目录，拉取官方镜像运行容器并挂载这两个目录即可完成部署。
进入 Web 界面添加要跟踪的频道或播放列表，设置下载画质、检查频率和保留策略。
配上 Plex 或 Jellyfin 地址后，下载完成会自动触发媒体库刷新，电视端直接看到新内容。
截图与演示说明
上图为 TubeSync 的仪表盘页面，展示订阅源数量、待下载任务、磁盘占用与最近下载的媒体列表。
源详情页可对单个频道或播放列表单独设置画质、格式与下载节奏，媒体总览页按状态筛选所有已下载视频。
媒体详情页记录每条视频的下载历史与文件格式信息，配合 Jellyfin 使用时新视频数分钟内就会出现在媒体库。
常见问题
问. TubeSync 是什么项目？
TubeSync 是开源的视频频道同步系统，把 YouTube 频道与播放列表自动同步到本地目录，下载完成自动通知 Plex 与 Jellyfin 刷新。
问. TubeSync 源码怎么部署？
下载源码包后建好配置与下载目录，用 Docker 拉起官方镜像挂载目录即可，Web 界面里添加订阅源就能开始自动下载。
问. 和 yt-dlp 对比有什么区别？
与 yt-dlp 对比，TubeSync 提供长期运行的订阅制 PVR 体验与自动重试机制，yt-dlp 本体则是单次执行的命令行工具。
问. TubeSync 支持什么设备运行？
官方镜像支持 amd64 与 arm64 双架构，树莓派 3 以上即可长期运行，普通 NAS 与服务器均无压力。
安全风险提示
对 502 个源码文件做了高风险函数扫描，eval 与 exec 各命中 1 处，均为 yt-dlp 集成层的常规调用，未发现后门或恶意外联。
AGPL-3.0 协议要求修改后对外提供网络服务时公开源码，自用部署无额外义务，下载内容的版权责任由使用者自行承担。
下载说明
本页提供 TubeSync 视频频道同步系统的完整源码打包下载，含 Django 应用全部代码与部署配置。
压缩包为原始仓库文件，下载后解压按部署提示操作即可，Docker 镜像也可直接从官方仓库拉取。
