Netease API¶

概述¶

Netease API（全稱 Netease Cloud Music API）是一個以 Node.js 撰寫的非官方網易雲音樂應用程式介面，主要用途是讓第三方服務（如 Music Assistant、Home Assistant 等）透過 HTTP 請求取得網易雲音樂的歌曲、歌單、播放清單、使用者資訊及音樂串流位址。由於網易雲音樂官方並未提供公開且穩定的 Web API，開源社群普遍採用 binaryify/netease_cloud_music_api 這個 Docker 映像檔作為中介層。該專案持續維護，並支援登入 Cookie、QR Code 登入及多種音質解析，實際部署時通常以容器方式運行。

在本站環境中，Netease API 以 Docker 容器形式部署，鏡像為 binaryify/netease_cloud_music_api:latest，運行於內網，並透過 cloudflare-tunnel 或反代提供對外存取。由於 compose 檔案未保留，實際參數以 docker inspect 還原，容器網路採用 bridge 模式，對應主機連接埠為 3000。

架構¶

Netease API 本質上是一個 Express.js 應用，啟動後監聽 TCP 3000 連接埠。其請求流程如下：

用戶端（如 Music Assistant）向 Netease API 發送 HTTP 請求，路徑如 /search、/song/url、/playlist/detail。
應用內部呼叫網易雲音樂官方網站的內部接口（music.163.com 或 interface.music.163.com）。
伺服器將回應資料正規化為 JSON 格式，回傳給用戶端。

容器層級架構非常簡單，只有一個容器，無需外部資料庫。所有 session 與 cookie 暫存於記憶體；若容器重啟，登入狀態便會消失。因此，若需持久登入，必須將 Cookie 明確寫入環境變數或設定檔。

本機網路架構方面，容器使用 bridge 網路，宿主機 NAT 將 0.0.0.0:3000 映射至容器 3000。宿主機本身另設有 Caddy 或 Nginx 作為 TLS 終止點，再交由 cloudflare-tunnel 導向公開網域，避免直接暴露主機 IP。

部署¶

本機實際部署方式如下（以 docker run 還原關鍵參數）：

docker run -d \
  --name netease-api \
  --restart unless-stopped \
  -p 3000:3000 \
  -e NETEASE_COOKIE="your_cookie_value" \
  binaryify/netease_cloud_music_api:latest

若以 Docker Compose 撰寫，等效檔案為：

services:
  netease-api:
    image: binaryify/netease_cloud_music_api:latest
    container_name: netease-api
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NETEASE_COOKIE=your_cookie_value

需注意：官方專案建議使用 latest 標籤，但實際版本更新頻繁。建議於部署前執行 docker pull binaryify/netease_cloud_music_api:latest，並以固定 tag（如 v3.x）取代 latest，以確保可重現性。

部署後測試：

curl http://localhost:3000/search?keywords=周杰倫

應回傳包含 result.songs 的 JSON。

配置¶

Netease API 支援多項環境變數，常見如下：

PORT：容器內部監聽連接埠，預設 3000。
NETEASE_COOKIE：網易雲音樂會員 Cookie，用於取得高音質或無版權限制的歌曲。
ANONYMOUS_TOKEN：匿名登入 token，可提升部分接口的可用性。
PROXY：指定上游代理，格式如 http://proxy:8080，適用於需要經由特定網絡出口的場景。
CACHE_DURATION：快取持續時間（秒），預設 300，可降低官方接口被阻擋的風險。

本機設定中，NETEASE_COOKIE 已設定，但未啟用 PROXY。由於本站位於香港，網絡連線至內地伺服器延遲約 30-50ms，目前反應良好。若將來出現 403 或 429 錯誤，建議透過 PROXY 指向香港出口或使用內地節點。

另需注意 Cookie 時效：網易雲音樂 Cookie 通常約 30 日後失效，失效後 Music Assistant 會出現 login expired 錯誤。可透過 QR Code 重新登入並更新環境變數。

維運與監控¶

基本維運指令：

docker logs -f netease-api
docker stats netease-api
docker inspect netease-api

監控上，建議檢查以下指標：

HTTP 回應狀態碼分佈（尤其 200、403、429、500）。
容器記憶體使用量（本機目前穩定維持於 120-150 MB）。
每小時請求數；正常使用下 Music Assistant 每 5 分鐘輪詢一次歌單，請求量極低。

若出現容器無回應，先嘗試：

docker restart netease-api

若重啟後問題仍在，可能是網易官方接口變更，需升級鏡像。

建議設定 Uptime Kuma 監控 http://localhost:3000/search?keywords=test，並以 200 作為健康條件。若透過 cloudflare-tunnel 暴露，亦可監控公網端點。

常見問題¶

1. 登入狀態失效 症狀：API 回傳 400 或 401，Music Assistant 無法取得歌單。解決：更新 NETEASE_COOKIE，重啟容器。

2. 歌曲串流 URL 回傳 404 原因：該歌曲可能需要 VIP 或版權限制，Cookie 權限不足。可嘗試使用已購買會員的帳號 Cookie。

3. 容器啟動後 immediately exit 多數情況是鏡像版本與 Node.js 版本不相容。執行 docker logs 查看錯誤，或改用 binaryify/netease_cloud_music_api:latest 並 pull 更新。

4. 高延遲或 timeout 若使用香港以外網絡，或經 Cloudflare 代理回源，可能因網絡路徑導致逾時。建議將本容器部署於與 Music Assistant 相同區域，或直接以內網 IP 存取。

5. 音樂平台封鎖頻繁請求 網易官方對單 IP 有速率限制，本機使用量低，一般不會觸發。若觸發，可增加 CACHE_DURATION 至 600 秒。

來源¶

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

Netease API¶

概述¶

架構¶

部署¶

配置¶

維運與監控¶

常見問題¶

相關鏈接¶

來源¶