Yubal自托管音乐下载工具：自动归档油管音乐，轻松搭建私人乐库

在之前的介绍中，我们聊过Navidrome、道理鱼音乐这类音乐服务器。将它们部署在 NAS 上之后，可以把本地音乐统一汇总、整理，并通过原生或第三方应用进行接入，实现随时随地的播放，构建起属于自己的私人音乐库。

音乐服务器解决的是管理与播放层面的问题，但音乐文件本身仍需自行准备。如今正处于大版权时代，不同音乐平台之间的曲库互不相通，部分歌曲还会遇到下架、变灰或者需要切换平台才能收听的情况。正因如此，对于个人已经合法拥有或获得授权的音乐内容，进行一次集中的备份、分类与长期保存就显得十分必要。

为了进一步缓解这种状况，这次我们来分享一款围绕油管音乐打造的 Docker 项目。它能够对用户有权使用的媒体内容进行解析和归档，并自动整理封面、歌词、歌曲标签等信息。轻松帮你扩充乐库，同时大幅减少手动整理的时间。

截屏2026-07-16 13.48.26.png

项目介绍

完整项目名称：guillevc/yubal，可在 GitHub 中搜索到。

yubal 是一款自托管的油管音乐下载工具。它提供了完整的网页管理界面，能够实时查看任务进度和等待队列，并且针对移动端进行了适配，用手机也能方便地操作。

在已获得内容使用权限的前提下，用户可以添加单曲、专辑或播放列表链接，Yubal 会自动完成媒体文件的整理，并按歌手、专辑等信息建立清晰的目录结构。

功能特性

  • • 播放列表定时同步：定期检查已订阅的列表，当出现新增曲目时，可自动同步到个人音乐库。
  • • 智能去重：同一首歌曲即便出现在不同列表中，也只会保存一份文件，有效减少空间的重复占用。
  • • 任务自动重试：任务中断或执行失败时可自动重试，并支持安全取消。
  • • 歌词自动整理：支持同步歌词，同时生成兼容常见播放器的 .lrc 文件。
  • • 音量标准化标签：支持 ReplayGain 标签，缓解不同歌曲之间音量忽大忽小的问题。
  • • 多种音频格式：支持 Opus、MP3 和 M4A，可根据播放设备和存储需求灵活选择。
  • • 适配音乐服务器：整理好的音乐可以继续交由 Navidrome、Jellyfin、Gonic 等媒体服务器进行扫描与管理。
  • • 命令行工具：除了网页界面，还可以通过命令行查看媒体信息或执行相关任务。

将 Yubal 与 Navidrome 等音乐服务器组合使用，可以形成一套相对完整的个人音乐库流程：由 Yubal 负责内容导入、标签补充和目录整理，再由音乐服务器负责扫描、分类和多终端播放。

部署流程

这里以威联通 NAS 为例，通过 Docker Compose 的方式进行部署。

部署配置如下：

services:  
  yubal:  
    image: ghcr.io/guillevc/yubal:latest  
    container_name: yubal  
    restart: unless-stopped  
  
    ports:  
      - "9527:8000"  
  
    environment:  
      PUID: "0"  
      PGID: "0"  
      YUBAL_TZ: "Asia/Shanghai"  
  
      # 请自行调整格式：opus、mp3 或 m4a  
      YUBAL_AUDIO_FORMAT: "mp3"  
  
      # 请自行调整音质：0 最佳，10 最低  
      YUBAL_AUDIO_QUALITY: "0"  
  
      # 是否获取同步歌词  
      YUBAL_FETCH_LYRICS: "true"  
  
      # 是否开启播放列表定时同步  
      YUBAL_SCHEDULER_ENABLED: "true"  
  
      # 设置定点检查更新  
      YUBAL_SCHEDULER_CRON: "0 3 * * *"  
  
      # 是否下载用户自行上传的非官方音乐  
      YUBAL_DOWNLOAD_UGC: "false"  
  
    volumes:  
      - /share/Container/yubal/music:/app/data # 该路径请按需修改  
      - /share/Container/yubal/config:/app/config

打开威联通的 Container Station，创建新的应用程序即可。

截屏2026-07-16 13.12.57.png

使用简览

部署完成后，在浏览器中访问NAS_IP:9527，初始界面如下。

截屏2026-07-16 13.16.46.png

我们先找一首非官方发布的音乐进行测试，将完整的网址复制下来。

截屏2026-07-16 13.26.54.png

回到项目页面，粘贴到输入框中，点击「Download」，等待任务执行即可。

截屏2026-07-16 13.28.04.png

测试了单曲和播放列表，都没有问题。

截屏2026-07-16 13.48.52.png

另一个功能区是播放列表订阅与自动同步。订阅列表后，这里会定期检查内容变化，如果出现新增曲目，就会自动同步到 NAS 中。

截屏2026-07-16 13.43.50.png

本次演示虽然没有切换到实际的媒体库目录，但从缓存后的目录结构来看，文件组织得十分清晰，是不是省了不少事？

截屏2026-07-16 13.50.32.png

最后

又一个实用工具分享给大家。至此，Yubal 的部署与基本使用就介绍完了，希望能对您的个人音乐库建设有所帮助。