NAS福音-MyTube 完整文档指南

MyTube 完整文档指南

自托管视频下载与播放器 支持 YouTube、Bilibili、Twitch、MissAV 及所有 yt-dlp 支持的站点

📑 目录

1. 项目简介
2. 系统架构
3. 核心功能
4. 应用场景
5. 快速开始
6. 使用文档
7. Docker 部署
8. API 参考
9. 浏览器扩展
10. 常见问题

🎯 项目简介

MyTube 是一个功能强大的自托管视频下载和播放平台，让你能够轻松下载、管理和观看来自多个视频平台的媒体内容。

主要特点

• 🚀 100% 提示词工程 – 零手动代码编写
• 🎬 多平台支持 – YouTube、Bilibili、Twitch、MissAV 及所有 yt-dlp 支持的站点
• 📥 批量下载 – 支持队列下载和并行处理
• 📚 智能管理 – 收藏夹、标签、作者分类
• 🌐 多语言 – 支持 10+ 种语言
• 🔐 安全访问 – 密码保护 + WebAuthn 密钥登录
• 📱 移动友好 – 响应式设计，支持移动端
• ☁️ 云存储 – 支持 OpenList/Alist 云存储集成

🏗️ 系统架构

架构概览

MyTube System Architecture

技术栈

层级	技术	说明
前端	React 19 + Vite	现代化构建工具，快速开发
UI 框架	Material-UI (MUI)	美观的组件库
状态管理	React Query + Context	高效的数据获取和状态管理
后端	Express.js + TypeScript	类型安全的 Node.js 框架
数据库	SQLite + Drizzle ORM	轻量级关系型数据库
下载引擎	yt-dlp	强大的视频下载工具
容器化	Docker + Docker Compose	便捷的部署方案

目录结构

mytube/├── backend/                    # Express 后端 (TypeScript)│   ├── src/│   │   ├── controllers/        # HTTP 控制器│   │   ├── services/           # 业务逻辑│   │   │   ├── downloaders/    # 平台下载实现│   │   │   │   ├── bilibili/   # Bilibili 下载器│   │   │   │   └── ytdlp/      # yt-dlp 下载器│   │   ├── db/                 # Drizzle 数据库配置│   │   └── routes/             # API 路由│   ├── data/                   # 运行时数据 (数据库、Cookie)│   └── uploads/                # 媒体文件存储├── frontend/                   # React 前端│   ├── src/│   │   ├── components/         # UI 组件│   │   ├── pages/              # 页面组件│   │   └── hooks/              # 自定义 Hooks│   └── public/                 # 静态资源├── chrome-extension/           # Chrome 浏览器扩展└── documents/                  # 文档 (中英文)

✨ 核心功能

1. 视频下载

功能	说明
URL 下载	粘贴视频链接即可下载
批量下载	一次添加多个视频到队列
并行下载	支持同时下载多个视频
自动字幕	自动下载 YouTube/Bilibili 默认语言字幕
Cookie 支持	上传 cookies.txt 下载年龄限制/付费内容

2. 视频管理

功能	说明
收藏夹	将视频组织到自定义收藏夹
标签系统	为视频添加标签便于分类
作者视图	按创作者浏览视频
观看历史	记录观看进度和历史
评分系统	为视频打分 (1-5 星)

3. 订阅功能

功能	说明
频道订阅	订阅 YouTube/Bilibili/Twitch 频道
自动下载	新视频自动下载到库中
订阅管理	设置检查间隔和下载偏好

4. 元数据增强

功能	说明
TMDB 集成	自动获取电影/电视剧元数据
智能匹配	根据文件名智能匹配 TMDB 信息
海报下载	自动下载电影海报和封面

5. 安全与访问

功能	说明
密码保护	设置管理员密码保护应用
WebAuthn	支持 Passkey 无密码登录
访客模式	只读角色，安全分享
API 密钥	支持 API 密钥认证

🎯 应用场景

场景一：个人媒体库建设

需求背景：用户希望建立一个私人的视频收藏库，保存喜欢的教程、纪录片和娱乐视频。

MyTube 解决方案：

1. 部署方式：使用 Docker 在家庭 NAS 上部署
2. 下载管理：

• 订阅技术频道，自动下载最新教程
• 批量下载系列课程
• 使用收藏夹分类整理（技术、娱乐、学习）

3. 访问方式：

• 内网直接访问
• 通过 Cloudflare Tunnel 外网访问
• 启用访客模式分享给家人

场景二：教育内容归档

需求背景：教育机构需要保存在线课程视频，供学生离线学习。

MyTube 解决方案：

1. 批量下载：使用 Chrome 扩展批量添加课程链接
2. 元数据管理：

• 启用 TMDB 获取课程封面
• 按学科创建收藏夹
• 添加标签便于搜索

3. 访问控制：

• 设置只读访客账号给学生
• 管理员账号负责内容管理

场景三：内容创作者素材库

需求背景：视频创作者需要收集参考素材和音效视频。

MyTube 解决方案：

1. 快速下载：

• Chrome 扩展一键下载
• 支持多平台素材收集

2. 组织管理：

• 按项目创建收藏夹
• 标签标记素材类型
• 评分标记素材质量

3. 云存储：

• 配置 Alist 自动上传到云盘
• 多设备同步访问

场景四：家庭娱乐中心

需求背景：家庭用户希望集中管理家庭成员的视频内容。

MyTube 解决方案：

1. 本地部署：树莓派或旧电脑部署
2. 内容管理：

• 儿童动画专区
• 家庭电影收藏夹
• 个人视频上传

3. 多设备访问：

• 电视浏览器访问
• 平板、手机随时观看
• 观看进度同步

🚀 快速开始

前置要求

软件	版本	说明
Node.js	v18+	运行环境
npm	v9+	包管理器
Python	3.8+	yt-dlp 依赖
Docker	最新版	可选，用于容器部署

安装步骤

方式一：源码安装

# 1. 克隆仓库git clone https://github.com/franklioxygen/mytube.gitcd mytube# 2. 安装依赖npm run install:all# 3. 配置环境变量cp backend/.env.example backend/.env# 编辑 backend/.env 设置必要配置# 4. 启动开发服务器npm run dev

访问地址：

• 前端界面：http://localhost:5556
• 后端 API：http://localhost:5551

方式二：Docker 部署（推荐）

# 1. 创建项目目录mkdir mytube-deploycd mytube-deploy# 2. 创建 docker-compose.ymlcat > docker-compose.yml << 'EOF'services:  backend:    image: franklioxygen/mytube:backend-latest    container_name: mytube-backend    restart: unless-stopped    ports:      - "5551:5551"    environment:      - PORT=5551      - PUID=1000      - PGID=1000    volumes:      - ./uploads:/app/uploads      - ./data:/app/data  frontend:    image: franklioxygen/mytube:frontend-latest    container_name: mytube-frontend    restart: unless-stopped    ports:      - "5556:5556"    depends_on:      - backend    environment:      - VITE_API_URL=/apiEOF# 3. 启动服务docker-compose up -d

📖 使用文档

首次使用

1. 访问应用

打开浏览器访问 http://localhost:5556，进入 MyTube 主界面：

MyTube 主界面

2. 设置管理员密码

1. 点击右上角设置图标
2. 进入 Security 选项卡
3. 启用登录保护
4. 设置管理员密码（默认密码为 123）

3. 配置下载设置

1. 进入 Download Settings 选项卡
2. 设置并行下载数量（建议 2-3 个）
3. 配置下载质量偏好
4. 设置下载路径

下载视频

单视频下载

1. 在顶部搜索框粘贴视频 URL
2. 点击搜索按钮
3. 确认视频信息后点击下载

批量下载

1. 在下载对话框中启用批量模式
2. 粘贴多个视频 URL（每行一个）
3. 点击批量下载

使用 Cookie

对于年龄限制或付费内容：

1. 从浏览器导出 Cookie（使用 Cookie-Editor 等扩展）
2. 保存为 cookies.txt
3. 在设置中上传 Cookie 文件

管理收藏夹

创建收藏夹

1. 点击左侧 Collections 区域的 + 按钮
2. 输入收藏夹名称
3. 选择封面图片

添加视频到收藏夹

1. 在视频卡片上点击更多按钮
2. 选择 Add to Collection
3. 选择目标收藏夹

视频播放

视频播放器

播放器功能：

• 播放控制：播放/暂停、进度拖拽、音量控制
• 播放速度：0.5x – 2x 可调
• 全屏模式：支持全屏和画中画
• 自动播放：可设置自动播放下一个
• 评分：1-5 星评分

订阅管理

添加订阅

1. 进入 Subscriptions 页面
2. 点击 Add Subscription
3. 输入频道 URL
4. 设置检查间隔

管理订阅

• 启用/禁用订阅
• 设置下载偏好（全部/仅新视频）
• 配置通知选项

🐳 Docker 部署

部署架构

Docker 部署架构

单容器模式

适合资源受限的环境：

services:  mytube:    image: ghcr.io/franklioxygen/mytube:latest    container_name: mytube    restart: unless-stopped    ports:      - "5551:5551"    environment:      - PORT=5551      - PUID=1000      - PGID=1000    volumes:      - ./uploads:/app/uploads      - ./data:/app/data

环境变量

变量	说明	默认值
`PORT`	后端监听端口	5551
`PUID`	进程用户 ID	1000
`PGID`	进程组 ID	1000
`MYTUBE_AUTO_FIX_PERMISSIONS`	自动修复权限	1
`MYTUBE_ADMIN_TRUST_LEVEL`	管理员信任级别	container

数据持久化

路径	说明
`./uploads`	视频文件和缩略图
`./data`	SQLite 数据库和日志

更新服务

# 拉取最新镜像docker-compose pull# 重启服务docker-compose up -d

🔌 API 参考

认证方式

• Cookie 认证：HTTP-only JWT Cookie
• API 密钥：X-API-Key 或 Authorization: ApiKey <key>

主要端点

视频下载

POST /api/downloadContent-Type: application/json{  "youtubeUrl": "https://www.youtube.com/watch?v=...",  "collectionName": "My Collection",  "downloadAllParts": false}

搜索视频

GET /api/search?query=keyword&limit=8&offset=1

获取视频列表

GET /api/videos?page=1&limit=20&sort=date

上传视频

POST /api/uploadContent-Type: multipart/form-datavideo: <file>title: "Video Title"author: "Author Name"

管理收藏夹

# 获取收藏夹列表GET /api/collections# 创建收藏夹POST /api/collections{  "name": "New Collection",  "description": "Description"}# 添加视频到收藏夹POST /api/collections/{id}/videos{  "videoId": "video-id"}

完整 API 文档

详见 API Endpoints 文档

🧩 浏览器扩展

功能特性

• 一键下载：在视频页面显示下载按钮
• 当前页面下载：支持所有 yt-dlp 支持的站点
• 连接测试：验证服务器可访问性

安装步骤

1. 下载 mytube-extension-v1.0.2.zip
2. 解压到文件夹
3. 打开 Chrome，访问 chrome://extensions/
4. 启用 开发者模式
5. 点击 加载已解压的扩展程序
6. 选择解压后的文件夹

配置扩展

1. 点击扩展图标
2. 输入 MyTube 服务器地址
3. 测试连接
4. 开始使用

❓ 常见问题

Q: 下载失败怎么办？

A: 检查以下几点：

1. 确保 yt-dlp 已正确安装：pip install yt-dlp
2. 检查视频 URL 是否有效
3. 查看后端日志获取详细错误信息
4. 对于限制内容，尝试上传 Cookie

Q: 如何更新 yt-dlp？

pip install -U yt-dlp

Docker 用户需要重启容器：

docker-compose restart backend

Q: 数据库在哪里？

A: 默认位置：

• 源码部署：backend/data/mytube.db
• Docker 部署：./data/mytube.db

Q: 如何备份数据？

A: 备份以下目录：

# 备份数据库和数据tar -czvf mytube-backup.tar.gz ./data ./uploads

Q: 支持哪些视频平台？

A: MyTube 支持所有 yt-dlp 支持的平台，包括：

• YouTube（含播放列表）
• Bilibili（含分P视频和合集）
• Twitch（VOD 和剪辑）
• MissAV
• 以及 1000+ 个站点

Q: 如何配置 Cloudflare Tunnel？

1. 安装 Cloudflare 客户端
2. 创建 Tunnel
3. 配置 Ingress 规则指向 localhost:5556
4. 在 MyTube 设置中启用 Tunnel 集成

📊 工作流程

视频下载流程

下载工作流程

1. 用户输入 – 粘贴视频 URL 或使用扩展
2. URL 验证 – 检查是否已下载过
3. 获取信息 – 提取标题、缩略图、时长
4. 加入队列 – 添加到下载队列
5. 下载进度 – yt-dlp 下载并显示进度
6. 后处理 – 生成缩略图、获取元数据
7. 存储数据 – 保存到 SQLite 数据库
8. 通知完成 – Telegram/Webhook 通知

🤝 贡献指南

欢迎贡献！请查看 CONTRIBUTING.md 了解详情。

开发环境

# 1. Fork 并克隆仓库git clone https://github.com/YOUR_USERNAME/MyTube.git# 2. 安装依赖npm run install:all# 3. 创建分支git checkout -b feature/your-feature# 4. 提交更改git commit -m "feat: add new feature"# 5. 推送并创建 PRgit push origin feature/your-feature

📄 许可证

本项目采用 MIT 许可证。

🔗 相关链接

• GitHub 仓库: https://github.com/franklioxygen/MyTube
• 在线演示: https://mytube-demo.vercel.app
• yt-dlp 文档: https://github.com/yt-dlp/yt-dlp
• Docker Hub: https://hub.docker.com/r/franklioxygen/mytube
• GitHub Container Registry: https://ghcr.io/franklioxygen/mytube