MeTube自托管视频下载工具 - 基于yt-dlp的Web UI部署与配置教程

loveos

一、项目简介

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