Music Assistant¶

概述¶

Music Assistant（簡稱 MA）係一套開源嘅音樂伺服器軟件，主要功能係將多個唔同嘅音樂來源聚合到單一介面，提供統一嘅播放、搜尋同管理體驗。同一般播放器唔同，MA 係一個「音樂後端」，本身唔自帶音樂內容，而係透過連接各種音樂供應商（例如 Spotify、YouTube Music、Apple Music、網易雲音樂等）或者本地媒體庫，再以標準協議（如 AirPlay、Chromecast、DLNA）輸出到唔同播放裝置。

本實例部署喺 Oracle Cloud Infrastructure（OCI）嘅 Always Free 計算實例上，採用 Docker Compose 管理。重點係透過 Alist 嘅 WebDAV 連接，將分散喺唔同網盤或者遠端儲存嘅音樂檔案，以統一嘅檔案系統方式呈現畀 MA 掃描同索引。另外，亦部署咗一個網易雲音樂 API 服務，作為 MA 攞網易雲資料嘅潛在橋樑，以應付日後擴充音樂源嘅需要。

架構¶

喺本機實況入面，MA 同埋網易雲 API 服務都係接入一個外部 Docker 網絡 cf_network，呢個網絡同時係 Cloudflare Tunnel 同其他服務共用嘅橋接網絡。兩個容器都用靜態 IP，方便內部服務互相以固定位址溝通，而唔需要依賴 Docker DNS 或者服務名稱解析。

+-------------------+       +-------------------+
|  music-assistant  |<----->|   netease-api     |
|  172.21.0.37      |  HTTP |   172.21.0.36      |
|  /data            |       |   :3000            |
|  /tg_cache        |       +-------------------+
+-------------------+
        |
        | WebDAV
        v
     Alist (外部服務)

music-assistant：使用官方鏡像 ghcr.io/music-assistant/server:latest，容器名稱固定為 music-assistant，設定時區為 Asia/Hong_Kong。
netease-api：使用 binaryify/netease_cloud_music_api:latest，呢個係一個開源嘅網易雲音樂 API 封裝，提供模擬網頁端接口，方便 MA 透過插件去攞網易雲嘅歌單、搜尋同播放鏈接。因為唔需要對外暴露，所以冇 publish port，只係內部以 netease-api:3000 訪問。
儲存：MA 核心數據庫（設定、索引等）持久化到 /opt/docker/music-assistant/data:/data。另外有一個 /opt/docker/music-assistant/tg_cache:/tg_cache 目錄，用作 Telegram 動態快取，設計上會由 n8n 工作流介入，例如將 Telegram 收到嘅音訊暫存喺度，再由 MA 索引播放。
網絡：cf_network 係外部已存在嘅網絡（external: true），通常由 Cloudflare Tunnel 或者其他反向代理容器建立，令到 MA 可以透過 Tunnel 提供安全嘅遠端存取。

部署¶

部署步驟簡述如下：

確認 Docker 同 Docker Compose plugin 已經安裝。
建立外部網絡（如果未存在）：docker network create cf_network。

建立目錄結構：

mkdir -p /opt/docker/music-assistant/{data,tg_cache}

將上述 compose 內容儲存為 /opt/docker/music-assistant/docker-compose.yml。
執行 docker compose up -d 啟動服務。

注意：原本官方建議用 network_mode: host 嚟支援 mDNS 自動發現裝置，但喺 Oracle Cloud 環境，多數冇辦法使用 mDNS 廣播（特別係喺 VCN 入面），所以改用橋接網絡並手動指定 IP。如果日後需要連接實體音響裝置（例如 Sonos、Chromecast），可能需要喺同一 L2 網絡或者配置特定嘅 multicast 轉發，否則只可以依靠 IP 直接控制。

配置¶

MA 嘅主要配置係透過網頁 UI（預設埠 8095）完成。首次啟動後，經瀏覽器打開 http://<伺服器IP>:8095 進行初始化，設定管理員帳號。

音樂源配置¶

Alist WebDAV：喺 MA 嘅「音樂提供者」入面新增 WebDAV 類型，填寫 Alist 嘅 WebDAV 端點、使用者名稱同密碼。通常 Alist WebDAV 路徑格式係 /dav 或者 /webdav，視乎 Alist 版本。MA 會掃描指定路徑，讀取音訊檔案嘅 metadata（例如標題、藝術家、專輯）並建立索引。
網易雲音樂：由於 MA 內建插件未必直接支援網易雲音樂，可以透過自訂 API 橋接，即係指到 http://netease-api:3000。呢個 API 提供類似「播放鏈接」同「歌詞」嘅接口，MA 可以透過插件或者自訂音樂源嚟整合。

音訊輸出¶

MA 支援多種輸出協議。如果喺 Oracle Cloud 上，通常冇直接連接喇叭，所以常見做法係： - 用 Chromecast Audio 或者 AirPlay 裝置（如果網絡可以到達）； - 將 MA 經由 DLNA 輸出到另一個 Media Server； - 或者用「文件輸出」插件，將播放串流寫入 /tg_cache 目錄，再由 Telegram bot 擷取。

維運與監控¶

日常維運包括：

更新：docker compose pull 同 docker compose up -d 更新鏡像。因為使用 latest tag，建議定期手動更新，避免突然升級造成兼容性問題。
日誌：docker logs -f music-assistant 查看運行日誌。如果發現連唔到 Alist，要檢查 Alist 服務是否正常、WebDAV 憑證是否有效。
備份：/opt/docker/music-assistant/data 係核心數據庫，建議定期備份。可以用 tar 或者 rclone 同步去其他儲存。
監控：可以接入 Prometheus/Grafana，但 MA 本身冇內建 metrics endpoint。較簡單嘅做法係用 Uptime Kuma 監測 http://172.21.0.37:8095 或者經 Cloudflare Tunnel 嘅對外地址。另外，可以監測容器重啟次數同日誌錯誤。
網絡檢查：由於 MA 需要訪問外網去攞音樂源，如果發現音樂載入失敗，要檢查 Oracle Cloud Security List 同 iptables 規則，確保 MA 可以出站存取。

常見問題¶

Q: 連接 Alist WebDAV 時顯示「無法連線」？
A: 首先確認 Alist 容器或者服務喺 cf_network 入面，或者 MA 可以路由到 Alist 嘅 IP。如果 Alist 喺另一部機，要檢查防火牆同網路 ACL。另外，確認 WebDAV 路徑正確，唔少 Alist 版本要求結尾斜線或者特定路徑。

Q: MA 掃描唔到任何音樂檔案？
A: 多數係檔案權限或者路徑問題。檢查 WebDAV 掛載嘅資料夾名稱是否包含空格同特殊字元；MA 對 Unicode 檔案名稱支援尚可，但建議一律用英數底線命名。另外，確認 Alist 用戶有讀取權限。

Q: 網易雲音樂播放失敗，有冇 log？
A: netease-api 嘅 log 可以通過 docker logs netease-api 檢查。常見錯誤係 API 被風控或者需要 Cookie。可以將 cookies 環境變數加入 netease-api 容器，並重啟。

Q: 想對外網存取 MA 介面，點做好？
A: 官方推薦經 Cloudflare Tunnel 接入 cf_network，因為 Tunnel 可以直接以 Docker 容器加入同一網絡，無需額外開放端口。喺 Cloudflare Zero Trust 面板建立一個 Tunnel，將 hostname 指到 http://music-assistant:8095。記住要禁止公開註冊，並用 Access 保護 admin 路徑。

Q: /tg_cache 有咩用？
A: 呢個目錄係設計畀 n8n 工作流使用。例如 n8n 收到 Telegram 嘅音訊訊息，可以下載落嚟放到 /tg_cache，MA 作為本地資料夾音樂源，自動掃描並讓用戶透過 MA 播放。如果唔需要呢個功能，可以唔掛載，但保留有助日後擴充。

來源¶

自動生成（2026-08-19 容器覆蓋率補完第二批）

Music Assistant¶

概述¶

架構¶

部署¶

配置¶

音樂源配置¶

音訊輸出¶

維運與監控¶

常見問題¶

相關鏈接¶

來源¶