Docker 一键部署 COCO 音乐下载站：多源聚合 + API 可编程，让 AI 帮你搜歌下歌

起因：一篇安利文引发的折腾

刷到一篇公众号文章，介绍了一个叫 COCO Downloader 的音乐聚合下载工具。Docker 一键部署、7 大音源、无广告、还有 REST API——这不就是我一直想找的”音乐版聚合搜索”吗？当天就把容器跑了起来，顺便把 API 逆向了一遍，测了 11 个音源的真实表现。

COCO Downloader 是什么

一句话：基于 Next.js 16 构建的音乐聚合搜索 + 在线播放 + 批量下载工具。

核心能力：

多源聚合搜索：集成 11 个音源（酷狗、网易云、酷我、咪咕等），一次搜索覆盖全网
在线试听：悬浮播放器，搜到就能听
批量下载：勾选多首歌，一键打包下载
REST API：不只是 Web UI，程序和 AI Agent 也能调用
零门槛：无登录、无广告、MIT 开源

项目地址：github.com/markcxx/coco-downloader

局限：音源不稳定（过半不可用）、仅 320kbps 标准音质（无损支持有限）、只做聚合搜索不存储文件。但如果你的需求是”快速搜到、听一下、下到本地”，它够用了。

Docker 部署：两种方式任选

方式一：docker compose（推荐）

如果你的环境支持 docker compose（现在大多数 Linux 发行版都内置了），这是最干净的方式：

# docker-compose.yml
services:
  coco-downloader:
    image: markcxx/coco-downloader:latest
    container_name: coco-downloader
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - PORT=3000

# 启动
docker compose up -d

# 验证
curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:3000/
# 返回 200

方式二：docker run

如果你的 Docker 环境较老（不支持 compose 子命令），直接 docker run：

# 拉取镜像
docker pull markcxx/coco-downloader:latest

# 启动容器
docker run -d \
  --name coco-downloader \
  --restart unless-stopped \
  -e PORT=3000 \
  -p 3000:3000 \
  markcxx/coco-downloader:latest

镜像拉取失败怎么办

Docker Hub 在国内访问不稳定，拉镜像超时是很常见的问题。几个解法：

方案 A：用镜像加速站

# 替换为你的镜像加速站域名（如 docker.1ms.run、dockerpull.org 等）
docker pull docker.1ms.run/markcxx/coco-downloader:latest

# 拉取成功后重命名
docker tag docker.1ms.run/markcxx/coco-downloader:latest markcxx/coco-downloader:latest

如果你的环境配了代理，记得加速站域名要绕过代理：

NO_PROXY='*' docker pull docker.1ms.run/markcxx/coco-downloader:latest

方案 B：本地代理

如果本地有代理（如 Clash、Mihomo），直接走代理拉取：

HTTP_PROXY=http://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 \
  docker pull markcxx/coco-downloader:latest

方案 C：手动下载后导入

从 GitHub Releases 或其他渠道下载镜像压缩包，用 docker load 导入。

踩坑记录

问题	现象	解决方案
镜像拉取超时	某个层反复 Retrying，300s 超时	换镜像加速站或走代理
加速器需绕过代理	加速器域名走代理反而失败	`NO_PROXY='*'` 前缀
残留 pull 进程	超时后进程未退出，锁住镜像	手动 `kill` 后重新拉取
端口冲突	容器启动失败，端口被占用	先 `ss -tlnp \\| grep <端口>` 检查

API 接口：从逆向到实测

COCO 最让我兴奋的不是 Web UI，而是它暴露了完整的 REST API——AI Agent 可以直接调用。

API 源码位于 src/app/api/，三个接口：

1. 搜索歌曲

curl "http://localhost:3000/api/search?q=周杰伦+晴天"

{
  "items": [
    {
      "id": "https%3A%2F%2Fwww.jbsou.cn%2F...",
      "title": "晴天",
      "artist": "周杰伦",
      "cover": "https://...",
      "provider": "jianbin-kugou"
    }
  ]
}

provider 参数可选，默认 jianbin-kugou。

2. 获取播放地址

curl "http://localhost:3000/api/url?id=<歌曲ID>"

{
  "url": "https://kw-er.kuwo.cn/.../M800000bYDlc2XxKLs.mp3",
  "type": "mp3"
}

3. 下载音频流

curl -o 晴天.mp3 "http://localhost:3000/api/download?id=<歌曲ID>&filename=晴天.mp3"

直接返回音频流（Content-Type: audio/mpeg），带 Content-Disposition 下载头。通过环境变量 ENABLE_DOWNLOAD=0 可禁用下载。

11 个音源实测：3 个能打

理论上有 11 个音源，实测稳定可用的就 3 个：

音源	搜索	下载	音质	推荐度
jianbin-kugou ⭐	10 条	✅	320kbps/44.1kHz	日常首选
jianbin-kuwo ⭐	10 条	✅	320kbps/44.1kHz	音质最好
jianbin-netease ⭐	10 条	✅	320kbps/48kHz	稳定
gequbao	5 条	✅	128kbps	凑合用
migu	20 条	❌	—	下载返回错误
qq / bugu	0 条	—	—	完全不可用
livepoo	30 条	⚠️	MP4	格式不对

以”周杰伦晴天”为测试曲目，三个主力音源都能输出标准 320kbps MP3（ID3v2 标签完整）。gequbao 只有 128kbps，勉强能听。

AI 可编程化：Agent 自动搜歌下歌

这是我认为 COCO 最大的差异化价值。有了 REST API，整个流程完全脚本化：

import requests

COCO_BASE = "http://localhost:3000"

def search_and_download(keyword: str, provider: str = "jianbin-kugou"):
    """搜索 → 展示结果 → 下载"""
    # 1. 搜索
    resp = requests.get(f"{COCO_BASE}/api/search",
                        params={"q": keyword, "provider": provider})
    items = resp.json()["items"]

    for i, item in enumerate(items[:5]):
        print(f"[{i+1}] {item['title']} - {item['artist']}")

    # 2. 选择第一首下载
    target = items[0]
    resp = requests.get(f"{COCO_BASE}/api/download",
                        params={"id": target["id"],
                                "filename": f"{target['title']}.mp3"})

    filename = f"{target['title']}.mp3"
    with open(filename, "wb") as f:
        f.write(resp.content)
    print(f"已下载: {filename} ({len(resp.content) / 1024 / 1024:.1f}MB)")

放到 AI Agent 的场景下：用户说”帮我下首晴天”→ Agent 调 API 搜索 → 返回列表让用户选 → 下载 → 推送文件。全程无需打开浏览器。

与 go-music-dl 对比：什么时候用哪个

场景	COCO Downloader	go-music-dl
AI Agent 自动化	✅ REST API 可直接调用	❌ 需 tmux 交互
无损 FLAC	❌ 仅 320kbps	✅ 部分平台支持
歌单/专辑批量	❌	✅
部署复杂度	极简（单容器）	简单（需 data 目录）
支持平台数	11 个音源	10+ 平台

结论：日常快速下载、AI Agent 集成用 COCO（API 可编程、容器化部署极简）；需要无损音质或歌单功能时用 go-music-dl。

总结

COCO Downloader 的完成度超出预期：

部署极简：一个 Docker 容器，compose 或 run 都行，一分钟搞定
API 完整：搜索、播放、下载三个接口，天然适合脚本和 AI Agent 调用
音源够用：11 个里 3 个稳定 320kbps，覆盖主流曲库
可编程：这是它相比同类工具最大的优势

不足也很明显——音源不稳定、无损缺失、不支持歌单。但在”快速搜到 → 听一下 → 下到本地”这个场景下，加上 API 可编程的加分项，COCO 是目前最轻量的 Docker 音乐工具。

一条命令部署，一个 API 搜歌——音乐自由，不过如此。