一、项目简介
MeTube 是一款自托管的 Web UI 工具，基于强大的 yt-dlp 引擎，支持从 YouTube 及数十个其他网站下载视频、音频、字幕和缩略图。
核心能力：
通过浏览器界面下载视频、音频、字幕和缩略图
下载播放列表和频道，支持自定义输出和下载选项
订阅频道和播放列表，定期检查新内容并自动排队下载
GitHub 地址：https://github.com/alexta69/metube
开源协议：AGPL-3.0
Docker 镜像：ghcr.io/alexta69/metube
二、快速部署
2.1 使用 Docker 运行
docker run -d -p 8081:8081 -v /path/to/downloads:/downloads ghcr.io/alexta69/metube
2.2 使用 Docker Compose 运行
services:
metube:
image: ghcr.io/alexta69/metube
container_name: metube
restart: unless-stopped
ports:
- "8081:8081"
volumes:
- /path/to/downloads:/downloads
部署完成后，访问 http://your-server-ip:8081 即可打开 MeTube 的 Web 界面。
三、环境变量配置
所有配置项均可通过 Docker 命令行的 -e 参数或 docker-compose 的 environment: 字段设置。
3.1 下载行为
环境变量
说明
默认值
MAX_CONCURRENT_DOWNLOADS
最大同时下载数
3
DELETE_FILE_ON_TRASHCAN
在 UI 中删除时同时删除服务器文件
false
DEFAULT_OPTION_PLAYLIST_ITEM_LIMIT
播放列表最大下载项数
0（无限制）
SUBSCRIPTION_DEFAULT_CHECK_INTERVAL
订阅自动检查间隔（分钟）
60
SUBSCRIPTION_SCAN_PLAYLIST_END
每次订阅检查最大获取条目数
50
SUBSCRIPTION_MAX_SEEN_IDS
每个订阅存储的视频 ID 上限
50000
CLEAR_COMPLETED_AFTER
完成后自动清除的秒数
0（禁用）
3.2 存储与目录
环境变量
说明
默认值
DOWNLOAD_DIR
视频下载目录
/downloads
AUDIO_DOWNLOAD_DIR
音频专用下载目录
同 DOWNLOAD_DIR
CUSTOM_DIRS
启用自定义下载子目录
true
CREATE_CUSTOM_DIRS
自动创建不存在的目录
true
STATE_DIR
状态文件存储目录
/downloads/.metube
TEMP_DIR
临时下载文件目录
/downloads
提示：将 TEMP_DIR 设置为 SSD 或 RAM 文件系统（如 tmpfs）可提升性能，但使用 RAM 文件系统可能导致下载无法恢复。
3.3 文件命名与 yt-dlp
环境变量
说明
默认值
OUTPUT_TEMPLATE
视频文件命名模板
%(title)s.%(ext)s
OUTPUT_TEMPLATE_PLAYLIST
播放列表命名模板
%(playlist_title)s/%(title)s.%(ext)s
OUTPUT_TEMPLATE_CHANNEL
频道命名模板
%(channel)s/%(title)s.%(ext)s
YTDL_OPTIONS
额外的 yt-dlp 选项（JSON 格式）
-
YTDL_OPTIONS_FILE
yt-dlp 选项 JSON 文件路径
-
YTDL_OPTIONS_PRESETS
命名的 yt-dlp 选项预设
-
YTDL_OPTIONS_PRESETS_FILE
预设 JSON 文件路径
-
ALLOW_YTDL_OPTIONS_OVERRIDES
允许 UI 中自定义 yt-dlp 选项
false
3.4 Web 服务器与 URL
环境变量
说明
默认值
HOST
服务器绑定地址
0.0.0.0
PORT
服务器监听端口
8081
URL_PREFIX
反向代理基础路径
/
PUBLIC_HOST_URL
下载链接的基础 URL
-
HTTPS
启用 HTTPS
false
CORS_ALLOWED_ORIGINS
允许跨域请求的来源列表
空（拒绝所有）
3.5 基础设置
环境变量
说明
默认值
PUID / PGID
运行用户/组 ID
1000
DEFAULT_THEME
UI 主题（light/dark/auto）
auto
LOGLEVEL
日志级别
INFO
四、yt-dlp 选项配置详解
MeTube 支持三个层级的 yt-dlp 选项配置，从全局到具体依次为：
全局选项 — 适用于所有下载
预设（Presets） — 命名的选项包，用户可在 UI 中按下载选择
单次下载覆盖 — 在 UI 中为单个下载输入的自由格式选项
当下载启动时，这些层级按顺序合并。如果同一选项出现在多个层级中，更具体的层级优先：单次覆盖 > 预设 > 全局选项。
4.1 全局选项
方式一：通过环境变量内联
environment:
- 'YTDL_OPTIONS={"writesubtitles": true, "subtitleslangs": ["en", "de"], "updatetime": false, "writethumbnail": true}'
方式二：通过 JSON 文件
volumes:
- /path/to/ytdl-options.json:/config/ytdl-options.json
environment:
- YTDL_OPTIONS_FILE=/config/ytdl-options.json
JSON 文件内容示例：
{
"writesubtitles": true,
"subtitleslangs": ["en", "de"],
"updatetime": false,
"writethumbnail": true
}
文件会被自动监控，修改后无需重启容器。如果两种方式同时使用且定义了相同的键，文件优先。
4.2 预设（Presets）
预设文件示例：
{
"sponsorblock": {
"postprocessors": [
{ "key": "SponsorBlock", "categories": ["sponsor", "selfpromo", "interaction"] },
{ "key": "ModifyChapters", "remove_sponsor_segments": ["sponsor", "selfpromo", "interaction"] }
]
},
"embed-subs": {
"writesubtitles": true,
"writeautomaticsub": true,
"subtitleslangs": ["en", "de"],
"postprocessors": [{ "key": "FFmpegEmbedSubtitle" }]
},
"limit-rate": {
"ratelimit": 5000000
}
}
以上预设含义：
sponsorblock — 去除视频中的赞助商、自我推广和互动片段
embed-subs — 下载英德字幕并嵌入视频文件
limit-rate — 限制下载速度约 5 MB/s
4.3 单次下载覆盖
启用方式：
environment:
- ALLOW_YTDL_OPTIONS_OVERRIDES=true
️ 安全提示：启用此功能允许任何有 UI 访问权限的人提供任意 yt-dlp API 选项，根据使用的选项，可能允许在容器内执行任意命令。仅在受信任的环境中启用。
五、浏览器 Cookie 使用
如需使用浏览器 Cookie 下载受限或私密视频：
安装浏览器 Cookie 导出扩展：
Firefox 扩展
Chrome 扩展
导出 Cookie 为 cookies.txt 文件
在 MeTube 中打开 Advanced Options，点击 Upload Cookies 上传文件
上传后 Cookie 指示器将显示为激活状态
六、浏览器扩展
浏览器扩展支持右键点击视频直接发送到 MeTube。使用扩展时需设置 CORS_ALLOWED_ORIGINS=*。
Chrome：由 Rpsl 贡献，可从 Chrome Web Store 安装
Firefox：由 nanocortex 贡献
七、相关链接
GitHub 仓库：https://github.com/alexta69/metube
Docker 镜像：ghcr.io/alexta69/metube
yt-dlp 项目：https://github.com/yt-dlp/yt-dlp
配置 Cookbook：MeTube Wiki