MPD Docker 部署文档（适用于 macOS）

    本教程基于镜像 **`gists/mpd`**，并将音乐目录、配置文件、数据库、日志全部挂载到本地，方便维护与扩展。
    

# 📁 一、目录结构说明

假设：

* **MPD 服务目录**：`/Users/***/Desktop/mpdapp`
* **音乐库目录**： `/Users/***/Desktop/musicdb`（已存在）

最终结构如下：

    /Users/***/Desktop/
    │
    ├── mpdapp
    │   ├── conf
    │   │   └── mpd.conf
    │   ├── db
    │   ├── playlists
    │   ├── log
    │   └── docker-compose.yml
    │
    └── musicdb      ← 你的所有 mp3 文件

* * *

# 📦 二、创建 MPD 服务目录

    mkdir -p /Users/***/Desktop/mpdapp/{conf,db,playlists,log}

* * *

# ⚙️ 三、创建 MPD 配置文件（mpd.conf）

路径：`/Users/***/Desktop/mpdapp/conf/mpd.conf`

内容：

    music_directory      "/var/lib/mpd/music"
    playlist_directory   "/var/lib/mpd/playlists"
    
    db_file              "/var/lib/mpd/database"
    log_file             "/var/log/mpd/mpd.log"
    pid_file             "/var/run/mpd/pid"
    state_file           "/var/lib/mpd/state"
    sticker_file         "/var/lib/mpd/sticker.sql"
    
    bind_to_address      "0.0.0.0"
    port                 "6600"
    
    # 禁用 zeroconf，避免 Avahi 报错
    zeroconf_enabled     "no"
    
    audio_output {
        type        "fifo"
        name        "fifo_output"
        path        "/tmp/mpd.fifo"
        format      "44100:16:2"
    }

* * *

# 🐳 四、编写 docker-compose.yml

路径：`/Users/***/Desktop/mpdapp/docker-compose.yml`

内容：

    version: "3.8"
    
    services:
      mpd:
        image: gists/mpd:latest
        container_name: mpd
        restart: unless-stopped
        ports:
          - "6600:6600"
          - "8000:8000"
        volumes:
          # 自定义配置文件
          - /Users/***/Desktop/mpdapp/conf/mpd.conf:/etc/mpd.conf
    
          # MPD 数据目录
          - /Users/***/Desktop/mpdapp/db:/var/lib/mpd
    
          # 本地音乐库映射
          - /Users/***/Desktop/musicdb:/var/lib/mpd/music
    
          # 日志输出
          - /Users/***/Desktop/mpdapp/log:/var/log/mpd

* * *

# 🚀 五、启动服务

进入目录：

    cd /Users/***/Desktop/mpdapp

启动：

    docker compose up -d

查看状态：

    docker logs mpd

只要无严重错误（例如 database、state 文件不存在），说明启动成功。

* * *

# 🎧 六、进入容器检查音乐库

进入容器：

    docker exec -it mpd sh

查看音乐目录：

    ls /var/lib/mpd/music

若能看到你的 mp3 文件 → 映射成功。

更新数据库：

    mpc update
    mpc ls

若 `mpc ls` 输出歌曲列表 → MPD 工作正常。

* * *

# 🟢 七、服务启动成功效果

✔️ MPD 成功加载你的 mpd.conf✔️ 本地音乐库 `/musicdb` 映射成功✔️ 数据、日志、配置均持久化✔️ 可使用 MPD 客户端（ncmpcpp、Cantata、MPDroid）控制播放✔️ 支持局域网 IP 访问（多设备同控）✔️ 为今后的“多用户同步播放系统”奠定基础

* * *

# 🧪 八、测试模块说明（功能验证）

以下为完整的功能测试流程，验证 MPD 是否正常运行。

* * *

## 1️⃣ 测试 MPD 是否可连接

    mpc --host=127.0.0.1 --port=6000 ls
    mpc --host=192.168.1.20 --port=6000 ls

如输出：

    alone-296348.mp3
    groovy-vibe-427121.mp3
    ...

说明：

* MPD 运行正常
* 数据库、配置、音乐目录全部加载成功

* * *

## 2️⃣ 测试添加歌曲到播放列表

    mpc --host=127.0.0.1 --port=6600 add alone-296348.mp3

无报错 = 歌曲可正常读取。

* * *

## 3️⃣ 测试播放功能

    mpc --host=127.0.0.1 --port=6600 play

输出示例：

    alone-296348.mp3
    [playing] #1/1   0:00/1:33 (0%)
    volume: n/a   repeat: off   random: off   single: off   consume: off

代表播放成功。

* * *

## 4️⃣ 常用测试命令（可选）

暂停：

    mpc pause

继续：

    mpc play

下一首：

    mpc next

清空播放列表：

    mpc clear

查看状态：

    mpc status

* * *

# 🎉 九、测试通过

经过测试：

* ✔️ 能列出所有音乐
* ✔️ 能正常添加到播放列表
* ✔️ 能成功播放
* ✔️ MPD 工作正常、配置生效
* ✔️ 可基于 IP + 端口访问（如 192.168.xx.xx:6600）

你的 MPD 服务已完全部署成功，可用于：

* 多用户同步播放
* 自定义 Web 控制面板
* AI 自动选曲
* 后端 API 控制
* 音乐可视化
* 远程播放与管理

* * *