先说问题:找一首歌,为什么要开四个 App
想听或者想存一首歌的时候,流程通常是这样的:先开网易云搜一遍,没有;再开 QQ 音乐搜一遍,有,但要登录;换酷狗,有另一个版本;Bilibili 上还有个现场版。四个平台四个账号体系,搜索结果各说各话,真要下载更是各下各的,文件散落一地,命名格式还都不一样。
这件事麻烦的根源不在某个平台,而在于入口太碎:同一批歌被切在十几个平台里,你却只能一个一个进去找。go-music-dl 的解法是把入口收拢成一个:一个程序同时对接十多个平台,一次搜索多源并发返回结果,哪个源有、哪个源音质好,一眼看完,当场试听、当场下载。
自建一个音乐搜索下载服务的核心价值就一句话:一个入口搜遍全网,下载的文件进自己的目录、按自己的规则命名。
本篇主线:认识 go-music-dl 与支持平台 → Web、TUI、桌面端四种用法逐个上手 → Docker 部署到自己的服务器 → 登录拿回自己的歌单 → 本地音乐库与 WebDAV 同步 → AI 接口操控播放器 → 安全收尾。
它是什么:一个程序聚合十多个平台
go-music-dl 是一个用 Go 语言写的全网音乐搜索与下载工具,AGPL-3.0 开源。它不是某一个平台的下载器,而是一个聚合层:
- 多源并发搜索:一次关键词同时打到多个平台,结果合并展示,还能一键换源——同一首歌在 A 平台没有或音质差,直接切到 B 平台的版本。
- 无损音质解析:在来源提供的范围内解析可用的最高音质,搜索时可屏蔽 Live、Remix、Demo 等版本和 60 秒以下的试听片段,结果更干净。
- 覆盖面完整:单曲、歌单、专辑、排行榜都支持;粘贴歌单或专辑链接能自动识别来源并进入详情,曲目可批量播放、批量下载、导入本地歌单。
支持的平台包括网易云、QQ、酷狗、酷我、咪咕、汽水、Apple Music、Spotify、Bilibili、Jamendo、JOOX、千千等十多个,实际可用来源以界面列表为准。首页的排行榜聚合了网易云、QQ、酷狗、酷我、咪咕、汽水、Apple Music 和 Spotify 的官方榜单,各平台的热门单曲就是当地的热歌榜,榜上歌曲可直接播放和下载。
先和另外两条路线拉个对照,看看它到底站在什么位置:
| 维度 | go-music-dl | 各平台官方客户端 | 单个平台下载脚本 |
|---|---|---|---|
| 平台覆盖 | 十多个平台聚合在一个入口 | 一个客户端只管自家曲库 | 通常只对接一个平台 |
| 搜索方式 | 多源并发,一次出多平台结果,可换源 | 只能搜自家 | 只能搜目标平台 |
| 批量与歌单 | 单曲、歌单、专辑、排行榜均可批量处理 | 歌单在自家生态内可用 | 多数只处理单曲链接 |
| 部署形态 | Web 服务、TUI、桌面端、Android、Docker | 装在每台设备上 | 本地跑脚本,无服务形态 |
| 登录要求 | 搜索试听下载免登录;个人歌单与设置才需要登录 | 基本都要登录自家账号 | 视脚本而定,常要自己拼 Cookie |
| 文件归宿 | 自己的目录,文件名模板可控,可同步 WebDAV | 多在 App 内部目录 | 当前目录,自己收拾 |
简单说:官方客户端是「一平台一世界」,脚本是「一平台一锤子」,go-music-dl 想做的是把搜索和下载这一层抽出来,做成一个跑在自己手里的服务。它和本系列上一篇的 LibreGet 是兄弟关系:LibreGet 管视频与课程那类文件的下载,go-music-dl 专攻音乐这一摊,下好的歌再顺手归进自己的文件库即可。
用法一:Web 服务,浏览器里全搞定
Web 是最推荐的用法,起服务只需要一条命令:
# 启动 Web 服务./music-dl web默认访问地址是 http://localhost:8080/music。搜索、试听、下载、浏览歌单都不需要登录,打开页面就能用;只有修改设置、管理 Cookie 这类操作才需要管理员账号。首次启动时,启动日志里会打印一行 Web setup token,拿它去创建管理员账号,创建完这个令牌就完成使命了。
如果你的服务器上已经有一套反向代理,想把这个服务挂在二级目录下面,加一个参数:
# 挂载到反向代理的二级目录 /dl./music-dl web --base-path /dl这样它就老老实实待在 /dl 路径下,和同机的其他服务互不打扰。
Web 界面里能做的事比想象中多:三种搜索类型(单曲、歌单、专辑)随便切;各平台的分类歌单可以直接逛,汽水还提供每日推荐、流行、华语、欧美、国风等分类;播放器支持逐字歌词、歌词字体调整、全局快捷键和媒体键。
用法二:TUI 与 CLI,终端里搜歌下歌
不想开浏览器、就想在终端里快速下两首歌,用 TUI 模式:
# 终端搜索,直接进入交互界面./music-dl -k "周杰伦"TUI 的操作键位很顺手,记住这几个就够用了:
↑/↓:上下移动空格:勾选当前歌曲a:全选 / 清空r:对勾选的歌曲换源Enter:下载勾选的歌曲b:返回w:每日推荐歌单q:退出
纯脚本化的场景用 CLI 参数一把梭:
# 查看全部帮助./music-dl -h
# 指定搜索源,只搜 QQ 和网易云./music-dl -k "周杰伦 晴天" -s qq,netease
# 指定下载目录./music-dl -k "周杰伦" -o ./my_music
# 下载时连封面和歌词一起带上./music-dl -k "周杰伦" --cover --lyrics-s 指定源在目标明确时特别有用:你很清楚这首歌在哪个平台的版本最好,就别让十几个源一起陪跑了。
用法三:桌面端与 Android,装上就用
不想碰命令行的,Releases 里有现成的桌面包,Windows、Linux、macOS 都有,分为 music-dl-desktop-rust 和 music-dl-desktop-go 两个版本,下载对应平台的包解压后直接运行,桌面端会自动把内置服务拉起来,用法和 Web 版一致。
Android 优先下载 music-dl_arm64-v8a.apk,已经内置 FFmpeg,不需要再额外装任何东西。装好之后建议进 Web 界面右上角的「设置」,把本地下载目录改成 /sdcard/Music,这样下载的文件直接进系统音乐目录,任何播放器都能扫到。iOS 则提供未签名包,需要自行签名,门槛相对高一些。
Docker 部署:上服务器就一行命令
自建服务的正经归宿是自己的服务器。go-music-dl 的 Docker 部署简单到只有一条命令——把仓库的 docker-compose.yml 拿下来,执行:
docker compose up -d --pull always --remove-orphans启动后访问 http://localhost:8080 即可。几个贴心之处值得点名:
- 首次启动会自动创建
./data目录并配好容器写权限,不用手动建目录再改属主,这是很多自建服务最容易卡住新手的一步,它直接替你做了。 - Compose 只依赖
docker-compose.yml和镜像本身,不需要把整个仓库拉下来,更不需要本地的 Dockerfile。 - 真要改源码自建镜像,仓库另备了开发用 Compose:
docker compose -f docker-compose.dev.yml up -d --build。
服务起来之后,前面说的 Web setup token 在容器日志里找:
docker compose logs | grep -i "setup token"拿它建好管理员账号,Web 端的部署就算齐活了。下载好的文件默认落在 data/downloads,这个目录后面讲本地音乐库时还会回来。
登录与音质:把你自己的歌单拿回来
不登录能搜能下,但你自己账号里的东西得登录后才认:网易云、QQ、酷狗、汽水、Spotify 的个人歌单、收藏和喜欢的歌曲,都要在登录或配置 Cookie / Token 后才能读取;部分平台的下载本身也要求有效的登录状态(比如 QQ 下载需要有效 Cookie)。
登录方式有两种:
- 扫码登录:网易云、QQ、酷狗、Bilibili 都支持,在设置页打开对应平台扫码即可,成功后 Cookie 自动保存。汽水音乐暂不支持扫码,需要在设置页手动填写 Cookie,设置页里附了手动抓取的步骤和请求域名,照着做即可。
- 手动 Cookie:设置页可集中管理各平台的 Cookie。
Cookie 等同于你的账号登录态,只保存在本地数据目录里,千万不要把配置文件公开分享出去。这是用一切此类工具的第一原则:方便是方便,账号安全不能搭进去。登录只为两件事——读取你自己的歌单收藏、获取你账号权益范围内的音质,仅此而已。
本地音乐库:下好的歌别躺着吃灰
下载只是上半场。go-music-dl 还能把本地已有的音频文件管起来,变成一个可搜索的本地曲库:
- 扫描入库:默认读取
data/downloads(Android 是/sdcard/Music),支持mp3、flac、m4a、ogg、wav、wma、aac;也支持手动上传导入。 - 自动识别:优先读取文件内嵌的元数据、封面和歌词,缺失时查找同名资源并用
ffprobe补全信息。 - 当作一个搜索源:本地音乐以
local源的身份参与搜索,和在线结果并列出现;底层用 SQLite 建索引,支持分页、扫描快照、元数据缓存和后台刷新,歌多了也不卡。 - 文件名模板:设置页支持
{name}、{artist}、{album}、{source}、{id}、{ext}等变量,下载和整理时按你的规则命名,告别一堆乱码文件名。 - 歌单操作:本地歌曲可批量收藏进自制歌单;删除本地文件需要二次确认,已收藏的条目可以保留,之后换源恢复。
工作流就此闭环:在线搜到下载回来,自动进本地库,再把目录交给 Alist 做文件管理、交给 Jellyfin 做跨设备播放,一个自建音乐小生态就成型了。
下载与同步:断点、内嵌信息与 WebDAV
下载环节的细节决定了长期使用的舒适度,这块它做得比较扎实:
- 流式下载:默认流式模式,支持 HTTP
Range,意味着断点续传和边下边播拖动进度都有底子,不会因为网络抖一下就从头再来。 - 内嵌封面与歌词:开启后下载时把封面和歌词写进音频文件内部,依赖
ffmpeg完成;如果环境里没有ffmpeg,这一步自动跳过,不影响原始音频下载。也可以选择在音频同目录生成同名标准 LRC 歌词文件,不动已有的歌词文件。 - WebDAV 同步:设置页填上 WebDAV 地址、账号、密码和远端目录,下载完成即可同步一份到远端——服务器上下歌、家里 NAS 上存档,这个搭配很顺手;仓库还专门备了一个
docker-compose.webdav.yml方便对照配置。
环境依赖只有一个要注意:ffmpeg 与 ffprobe 负责本地音乐探测和元数据写入。Docker 镜像和 Android APK 已经内置,CLI、桌面端和 iOS 包需要自行安装,装没装好一条命令验明:
ffmpeg -versionAI 接口:让助手直接操控你的播放器
这是 go-music-dl 最出人意料的一块:Web 服务对外暴露了一套给 AI 调用的接口,助手能直接操控你正开着的网页播放器——点歌、切歌、暂停、调音量、拖进度,全靠 HTTP 请求完成,不需要浏览器自动化,不需要模拟点击。
设计上它没有另起一套 AI 专用路由,而是把能力索引列出来,复用现有的 /music/* 接口:
- 能力索引:
http://localhost:8080/music/api/ai/index - 精简说明(给模型读的):
http://localhost:8080/music/llms.txt
普通搜索接口本身就是 AI 可用的,比如只搜 QQ 和网易云:
curl "http://localhost:8080/music/search?q=周杰伦&type=song&sources=qq&sources=netease"播放器控制的原理是:页面自己维持一条 SSE 长连接订阅服务端事件,AI 把命令 POST 到服务端,服务端推给在线页面执行,页面再把真实播放状态回传。所以助手读到的 playing、position、current 都是页面当下的真实状态,不是猜的。典型流程是「帮我放一首 ClariS 的歌」:先调搜索接口找歌,再调点播接口播放,最后轮询状态确认已经在放:
# 1. 看当前有哪些播放器在线、在放什么curl "http://localhost:8080/music/api/ai/player/state"
# 2. 直接点播(给 id + source;或只给 query 让服务端自己搜第一首)curl -X POST "http://localhost:8080/music/api/ai/player/play" \ -H "Content-Type: application/json" \ -H "X-Requested-With: XMLHttpRequest" \ -d '{"id":"1958384591","source":"netease","name":"ALIVE","artist":"ClariS"}'
# 3. 播放控制(暂停)curl -X POST "http://localhost:8080/music/api/ai/player/command" \ -H "Content-Type: application/json" \ -H "X-Requested-With: XMLHttpRequest" \ -d '{"action":"pause"}'控制动作支持 play、pause、toggle、stop、next、previous、seek、volume 和 rate。多设备场景也考虑到了:每个打开的页面是一个独立客户端,连接时用 client_id 声明身份,命令带上 client_id 就只投给那一台,各控各的、绝不串台;多台在线又不带 client_id 时接口返回 409 ambiguous_client 并给出候选列表,宁可报错也不让所有页面一起切歌——这个克制很对。没有播放器在线时返回 409 player_not_connected,页面关掉后状态保留 10 分钟供查询。
这套接口的意义在于:音乐服务第一次有了「可被助手直接调用」的标准姿势,点歌从点鼠标变成了说句话。
安全:这个服务不要裸奔在公网上
WARNINGAI 控制接口默认无鉴权,仅靠
X-Requested-With请求头做 CSRF 防护,这只防得住浏览器的跨站请求,防不住任何能直接发 HTTP 请求的人。不要把 go-music-dl 直接暴露到公网。自己远程使用时,走 SSH 隧道,或者把它放在带鉴权的反向代理后面;Web 端改设置需要管理员账号,但播放器控制接口并不在账号体系内,别拿前者给后者壮胆。
同样的道理适用于整个服务:它最适合的部署位置是内网、自己的可信网络,或者鉴权网关之后。自建服务的第一课永远是先想清楚谁能访问,再谈功能。
常见问题与排障
Q:Docker 起来了,但找不到 Web setup token,怎么建管理员?
A:token 只在首次启动的日志里打印。用 docker compose logs | grep -i "setup token" 翻出来;如果日志已被刷掉,先停服务备份好 ./data 再排查,不要急着删数据目录重来,那等于把配置和下载记录一起清零。
Q:能搜到歌,但某些歌点下载没反应或失败? A:先分清是全平台失败还是单个平台失败。部分平台的下载要求有效登录状态(例如 QQ 下载需要有效 Cookie),去设置页扫码登录或补上 Cookie 再试;单个源失败时用换源功能切到其他平台的同一首歌,往往当场解决。
Q:汽水音乐扫不了码怎么办? A:汽水暂不支持扫码登录,在设置页按附带的步骤手动抓取并填写 Cookie 即可。网易云、QQ、酷狗、Bilibili 四家是支持扫码的。
Q:下载的歌没有封面和歌词,是 bug 吗?
A:大概率是环境里没有 ffmpeg。内嵌封面歌词依赖它,缺失时自动跳过且不报错。Docker 镜像和 Android APK 已内置;二进制或桌面端部署的,装好后用 ffmpeg -version 验证,并确认设置页里的内嵌开关已打开。
Q:AI 点播返回 409 player_not_connected? A:说明当前没有打开着的播放页面。控制接口操控的是已打开的页面,先在浏览器里打开 Web 播放器(后台标签页也可以,但浏览器会节流定时器,进度上报会变慢),再发命令。
Q:家里两台设备都开着页面,AI 切歌切错台了?
A:多客户端必须带 client_id 定向。不带时多台在线会返回 409 ambiguous_client 和候选列表,照着列表选定目标再发;用 GET /state?client_id=xxx 可以精确读某一台的状态。
Q:升级之后 AI 定向控制失灵了?
A:先对页面按 Ctrl+F5 硬刷新。前端脚本是编译进二进制的,升级后旧页面还拿着老脚本,client_id 定向这类新能力用不了,刷新即可。
Q:Android 上下载的歌在别的播放器里找不到?
A:默认下载目录不在系统音乐目录里。进设置把本地下载目录改成 /sdcard/Music,之后下载的文件会直接进系统音乐目录。
Q:本地音乐库扫不进新放进去的文件?
A:确认文件放在扫描目录下(默认 data/downloads),格式在支持列表内;索引有缓存和后台刷新机制,稍等片刻或重启服务触发重新扫描。元数据残缺的文件会用 ffprobe 补全,补不全的会以文件名示人,先检查文件本身是否完好。
小结
go-music-dl 把一件高频小事做成了完整的自建服务:一头聚合十多个平台的搜索与下载,一头管好本地曲库的整理与同步,中间还留了一套能让 AI 助手直接操控播放器的接口。部署上 Docker 一行命令、桌面端解压即用、Android 一个 APK,门槛压得很低。
适合部署的人很明确:歌单散落在好几个平台、想把「搜歌—下载—归档—播放」收进自己手里的人。按本篇的顺序走——Docker 起服务、建管理员、按需扫码登录拿回自己的歌单、下载目录与 WebDAV 打通、最后确认服务没有裸奔在公网——一个属于你自己的音乐入口就立起来了。