家庭NAS环境搭建 -- 部署media-harbor用于下载YouTube视频

通过 Media Harbor 下载 YouTube 视频和 Instagram 内容。除了单个视频或帖子，也可以创建博主主页任务，定期检查新内容，并按博主和日期整理文件。

本次继续使用前面配置好的 Docker 环境：服务数据与下载暂存目录放在 SSD 上，归档文件放到 NAS 的共享目录。Instagram 的 Cookie 在“系统设置”中配置。

功能说明

下载单个视频、帖子，或持续获取博主主页的新内容。
YouTube 默认下载最高画质 MP4 和额外的 m4a 音频，也可选择字幕、评论、缩略图与元数据。
跳过已下载内容，支持补全下载、取消、重试，以及重启后继续执行。
在界面中查看任务进度、日志与下载历史，并按目录规则自动归档。

准备目录

拉取镜像，创建部署配置与数据目录：

docker pull ghcr.io/leapsea/media-harbor:latest

mkdir -p /mnt/ssd/docker/compose/media-harbor
mkdir -p /mnt/ssd/docker/data/media-harbor/{data,downloads}
mkdir -p /mnt/ssd/docker/logs/media-harbor
mkdir -p /mnt/hdd/nas/share/media-harbor

sudo chown -R 1000:2000 /mnt/ssd/docker/data/media-harbor
sudo chown -R 1000:2000 /mnt/ssd/docker/logs/media-harbor
sudo chown -R 1000:2000 /mnt/hdd/nas/share/media-harbor

本例使用 UID 1000、GID 2000 运行容器，与前文的 docker-nas 共享组对应。如果使用其他用户或用户组，需要同步调整目录所有者和下文的 PUID、PGID。

容器目录	宿主机目录	用途
`/data`	`/mnt/ssd/docker/data/media-harbor/data`	保存任务、设置、Cookie 与下载索引
`/downloads`	`/mnt/ssd/docker/data/media-harbor/downloads`	保存下载文件，作为归档前的暂存目录
`/archive`	`/mnt/hdd/nas/share/media-harbor`	保存归档文件
`/logs`	`/mnt/ssd/docker/logs/media-harbor`	保存任务日志

挂载后，重建容器也可以保留这些数据。不使用自动归档时，可以去掉 /archive 的挂载；启用归档则需要挂载该目录，并保证容器有写入权限。

创建配置文件

Compose 配置

创建 /mnt/ssd/docker/compose/media-harbor/compose.yaml：

services:
  media-harbor:
    image: ${IMAGE:-ghcr.io/leapsea/media-harbor:latest}
    restart: unless-stopped
    user: "${PUID:-1000}:${PGID:-2000}"
    ports:
      - "${PORT:-8080}:8080"
    volumes:
      - ${DATA_PATH:-./data}:/data
      - ${DOWNLOAD_PATH:-./downloads}:/downloads
      - ${ARCHIVE_PATH:-./archive}:/archive
      - ${LOG_PATH:-./logs}:/logs
    environment:
      LOG_DIR: /logs
      YTDLP_MAX_CONCURRENT: ${YTDLP_MAX_CONCURRENT:-5}
      GALLERY_DL_MAX_CONCURRENT: ${GALLERY_DL_MAX_CONCURRENT:-20}
      INSTAGRAM_USER_AGENT: ${INSTAGRAM_USER_AGENT:-}
      TZ: ${TZ:-Asia/Singapore}

环境变量

在同目录下创建 .env：

PORT=2050
PUID=1000
PGID=2000
IMAGE=ghcr.io/leapsea/media-harbor:latest

DATA_PATH=/mnt/ssd/docker/data/media-harbor/data
LOG_PATH=/mnt/ssd/docker/logs/media-harbor
DOWNLOAD_PATH=/mnt/ssd/docker/data/media-harbor/downloads
ARCHIVE_PATH=/mnt/hdd/nas/share/media-harbor

YTDLP_MAX_CONCURRENT=2
GALLERY_DL_MAX_CONCURRENT=10
TZ=Asia/Singapore

# 可选：按登录浏览器覆盖 Instagram 的 User-Agent。
INSTAGRAM_USER_AGENT=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/154.0.0.0 Safari/537.36

按需修改访问端口、挂载路径和运行身份。镜像默认使用 1000:1000，这里通过 Compose 的 user 改为 1000:2000。

本例直接使用发布镜像，不需要配置 GALLERY_DL_VERSION、YTDLP_VERSION 或 FFMPEG_VERSION 等构建参数。测试时限制处理条目的功能，可直接在界面的“系统设置 → 调试”中开启。

启动服务

进入配置目录并启动：

cd /mnt/ssd/docker/compose/media-harbor
docker compose up -d
docker compose logs --tail=100 media-harbor

打开浏览器，访问 http://服务器IP:2050，进入管理界面。

创建下载任务

下载单个视频或帖子

打开“任务管理”，点击“新增任务”。
选择 YouTube 或 Instagram，粘贴视频或帖子地址，确认自动解析的目录名称。
按需选择下载内容并保存，详情地址会立即执行一次。
在任务列表查看进度，完成后到“下载历史”查看产物，也可以复制文件夹路径。

持续下载博主主页

新增任务时粘贴博主主页地址，设置目录名称与执行间隔，保存任务。
点击“全量初始化”，下载当前可获取的内容。创建主页任务只保存配置，不会自动开始下载。
首次手动执行后启动周期，后续扫描只排队新增内容；可以暂停或恢复定时执行。

操作	使用场景
全量初始化	首次获取主页内容
增量扫描	手动检查新增内容；未初始化时也可以用于首次下载
补全下载	复用已有文件、补齐缺失产物，并刷新所选评论与元数据
重试	重新执行失败任务

“下载历史”按实际文件展示视频、音频、字幕等标签。评论保存在元数据 JSON 中，与元数据对应同一个文件。清空历史记录只会清除展示记录，下载文件和索引仍然保留，后续扫描也会继续跳过已下载内容。

常用设置

大部分配置都在“系统设置”中调整，修改后点击“保存设置”。

使用 Instagram 时，在 Cookie 设置中粘贴浏览器 Cookie 并保存，后续扫描与下载会自动使用。平台访问失败时，先查看任务日志，再检查网络和 Cookie 状态。

下载内容与并发

在下载设置中调整平台并发与 YouTube 默认下载内容。单个任务也可以覆盖默认下载选项。

目录规则与归档

默认目录规则为：

{platform}/{directory_name}/{year}/{month}{day}/{filename}

日期默认使用网站上传或发布时间，缺失时使用任务创建日期，并按本地时区计算。

需要将下载结果保存到 NAS 共享目录时，在目录规则设置中配置自动归档。本例已挂载 /archive，对应 /mnt/hdd/nas/share/media-harbor。

存储与调试

存储设置可以查看占用、清空日志，以及清理已完成和无关联任务的缓存。首次试用时，可以在调试设置中开启条目限制，先处理少量内容；确认流程正常后，再关闭限制。