🚀 使用 Docker Compose 部署 Musicn 容器

项目简介

Musicn 是一个为技术爱好者准备的、强大而简洁的 命令行 MP3 音乐下载器 。它支持从咪咕、酷我、酷狗和网易云等主流音乐服务平台播放及下载高品质音乐 。

核心特点： - 多平台支持：支持从咪咕、酷我、酷狗和网易云等平台获取音乐 - 双模式访问：提供 命令行界面 和 Web 操作界面 两种使用方式 - 跨架构兼容：容器支持 amd64 和 arm64 架构 - 高品质音乐：可下载普通 MP3 格式的高品质音乐

注意事项： - 目前无法下载无损格式的音乐 - 仅支持普通 MP3 格式的下载及播放 - 部分平台的会员专属歌曲下载暂不支持 - 此项目仅供个人学习研究，严禁用于商业用途

部署前准备

系统环境要求

• 操作系统：Ubuntu、Debian、CentOS、RHEL、Rocky Linux 等主流 Linux 发行版
• 内存：至少 2GB RAM
• 用户权限：root 或 sudo 权限

Docker 环境安装

如果系统尚未安装 Docker，可使用以下一键安装脚本：

# 执行一键安装脚本（国内用户推荐）
bash <(curl -sSL https://xuanyuan.cloud/docker.sh)

此脚本会自动配置国内镜像加速源，提升下载速度 。

或者参考传统安装方法：

# 更新包管理工具
sudo apt-get update

# 安装 Docker 及相关组件
sudo apt-get -y install apt-transport-https ca-certificates curl software-properties-common
sudo curl -fsSL http://mirrors.cloud.aliyuncs.com/docker-ce/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository -y "deb [arch=$(dpkg --print-architecture)] http://mirrors.cloud.aliyuncs.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable"
sudo apt-get -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 启动 Docker 服务
sudo systemctl start docker
sudo systemctl enable docker

验证 Docker 安装

docker --version
sudo systemctl status docker

配置 Docker Compose

创建部署目录

首先创建一个专门的目录来部署 Musicn：

mkdir -p /data/mus-dw && cd /data/mus-dw

编写 Docker Compose 配置文件

创建 docker-compose.yml 文件，内容如下：

# musicn服务配置
services:
  musicn:
    image: ghcr.io/wy580477/musicn-container:latest  # 官方最新容器镜像（自动更新稳定版）
    container_name: musicn # 容器名称，便于后续管理（如进入容器、查看日志）
    restart: on-failure:3  # 容器启动失败时重启，最多重启3次（避免无限重启消耗资源）
    # 覆盖容器默认入口点：通过 tini 初始化进程（防止僵尸进程），以安静模式启动 musicn（-q 减少日志输出）
    entrypoint:
      - /sbin/tini
      - --
      - msc
      - -q
    ports:
      - 7478:7478  # 端口映射：主机 7478 → 容器 7478（服务通信端口）
    volumes:
      - ./data:/data  # 数据持久化：主机 ./data 目录挂载到容器 /data（保存音乐、配置、缓存）

配置说明： - restart: on-failure:3：容器异常退出时最多自动重启 3 次 - entrypoint：覆盖容器的默认入口点，-q 参数启用安静模式 - ports：将容器的 7478 端口映射到宿主机的 7478 端口 - volumes：将容器内的 /data 目录挂载到宿主的 ./data 目录，持久化下载的音乐文件

启动与验证

拉取镜像并启动服务

# 拉取最新镜像
docker pull ghcr.io/wy580477/musicn-container:latest

# 启动服务
docker compose up -d

验证服务状态

# 检查容器状态
docker compose ps

# 查看容器日志
docker compose logs

# 检查服务运行状态
docker ps | grep musicn

正常启动后，应该看到 Musicn 容器处于 "Up" 状态。

访问 Web 界面

在浏览器中访问 http://服务器IP地址:7478，即可打开 Musicn 的 Web 操作界面 。

如果无法访问，请检查： - 服务器防火墙是否放行了 7478 端口 - 云服务器安全组规则是否配置正确

基础配置与使用

命令行模式使用

除了 Web 界面，Musicn 还提供了强大的命令行操作方式：

# 进入容器执行命令
docker exec -it musicn msc 周杰伦

# 设置命令别名方便使用
echo "alias msc='docker exec -it musicn msc'" >> ~/.bashrc
source ~/.bashrc

# 查看命令帮助
msc -h

# 指定下载目录
msc 周杰伦 -p ./test

通过 Web 界面下载音乐

1. 打开 Web 界面后，首先选择音源（酷狗、咪咕、网易云等）
2. 在搜索栏输入想要下载的歌曲名称
3. 点击下载按钮即可将音乐保存到本地

数据持久化

配置文件中的卷映射 ./data:/data 确保了下载的音乐文件会持久保存在宿主机上，即使容器删除或重建，音乐文件也不会丢失 。

---

基础配置与使用2

musicn 核心功能通过 msc 命令实现，以下为新手常用操作（均在容器内执行）：

1. 核心命令：搜索与下载音乐

（1）搜索音乐

语法：msc search [关键词]（关键词可包含歌手名、歌曲名）示例：搜索 “周杰伦 晴天”：

msc search 周杰伦 晴天

• 搜索结果会显示音乐 ID、名称、歌手、平台、音质等信息（如 ID: 123456 | 晴天 - 周杰伦 | 网易云音乐 | 无损）。

（2）下载音乐

语法：msc download [音乐ID]（使用搜索结果中的音乐 ID）示例：下载 ID 为 123456 的音乐：

bash

msc download 123456

• 下载完成后，音乐文件会保存在容器 /data/downloads 目录，对应主机 ./data/downloads 目录（可直接在主机播放或管理）。

2. 查看已下载音乐

（1）容器内查看

ls /data/downloads  # 列出所有下载的音乐文件

（2）主机查看（无需进入容器）

直接在主机部署目录查看：

ls ./data/downloads  # 音乐文件格式通常为 MP3 或 FLAC

3. 基础配置（可选）

musicn 配置文件保存在容器 /data/config.yaml（主机 ./data/config.yaml），新手无需修改默认配置；如需自定义下载音质（如默认无损）、下载路径，可编辑该文件（需重启容器生效）：

# 主机编辑配置文件（用 nano 或 vim）
nano ./data/config.yaml

---

维护与管理

日常维护命令

# 查看实时日志
docker compose logs -f

# 停止服务
docker compose down

# 重启服务
docker compose restart

# 查看资源使用情况
docker stats musicn

版本更新

# 拉取最新镜像
docker pull ghcr.io/wy580477/musicn-container:latest

# 重新启动服务
docker compose down
docker compose up -d

# 清理旧镜像
docker image prune -f

数据备份

由于使用了卷映射，只需定期备份宿主机上的 ./data 目录即可保存所有下载的音乐文件。

常见问题排查

1. 容器启动失败

问题：容器无法正常启动，状态持续为 Restarting 解决：

# 查看详细日志
docker compose logs

# 检查端口占用
sudo netstat -tulnp | grep 7478

# 如果端口被占用，可修改 compose 文件中的端口映射
# 例如改为 - "7479:7478"

2. 无法访问 Web 界面

问题：浏览器无法打开 Web 界面 解决： - 检查服务器防火墙设置，确保 7478 端口已开放 - 确认云服务器安全组规则已正确配置 - 验证 Docker 服务正常运行：systemctl status docker

3. 无法下载音乐

问题：搜索正常但无法下载音乐 解决： - 检查磁盘空间：df -h - 检查目录权限，确保 Docker 有写入权限 - 尝试更换音源，某些音源可能暂时不可用

4. 容器资源占用过高

问题：容器占用过多 CPU 或内存资源 解决：

# 在 docker-compose.yml 中添加资源限制
deploy:
  resources:
    limits:
      cpus: '0.5'
      memory: 512M

5. 镜像拉取失败

问题：无法从镜像仓库拉取镜像 解决： - 配置国内 Docker 镜像加速器 - 检查网络连接 - 手动拉取镜像：docker pull ghcr.io/wy580477/musicn-container:latest

通过以上步骤，你应该能够成功部署并运行 Musicn 音乐下载服务。如果在使用过程中遇到其他问题，可以查看容器日志获取更详细的错误信息。