U

Emby 多網域介面 emby_ext_domains

UHD 開源的 Emby 擴充服務：為 Emby 伺服器補上 ServerDomains 多網域介面，用戶端登入後自動取得全部線路。含介面定義、Emby token 驗證順序、Nginx 部署要點與用戶端對接建議。

建立於 2026/09/04最後更新 2026/09/04Markdown

提示

emby_ext_domains 是 UHD 開源的一個 Emby 生態擴充服務：為 Emby 伺服器補上一個「可用網域清單」介面，用戶端登入後就能自動取得該伺服器的全部線路網域，不必再讓使用者手動修改伺服器位址。儲存庫位址：github.com/uhdnow/emby_ext_domains，MIT 授權，以 Go 實作。

它解決什麼問題

Emby 協定裡沒有「一個伺服器有多個網域」的概念——用戶端只認登入時填的那一個位址。但真實營運中網域是會變的：新增邊緣節點、線路故障切換、舊網域無法使用，都需要使用者手動去用戶端裡改位址，成本很高。

這個擴充介面把這件事收歸伺服器端：

  • 伺服器端維護一份網域清單，隨時可增刪
  • 用戶端登入後呼叫一次介面，就取得完整線路清單
  • 使用者在用戶端裡直接切換線路，不需要重新輸入位址、也不需要重新登入

目前已有多款第三方 Emby 播放器實作了這個介面，也有不少 Emby 伺服器基於它對外提供多網域訂閱與同步服務。

已支援該介面的第三方用戶端

SenPlayer、VidHub、Forward、Hills、AfuseKt、Flow、TVxEmby、CapyPlayer、LinPlayer。

建議

用戶端的具體入口叫法不一，常見的是「線路」「網域訂閱」「伺服器位址同步」之類的開關。UHD 使用者可先看用戶端推薦挑選用戶端，再依設定用戶端完成登入。

介面定義

一個介面，掛在 Emby 的同源路徑下：

GET /emby/System/Ext/ServerDomains

成功回應（200）：

{
  "data": [
    { "name": "Server 1", "url": "https://server1.example.com" },
    { "name": "Server 2", "url": "https://server2.example.com" }
  ],
  "ok": true
}
欄位型別說明
okboolean請求是否成功，用戶端應以此判斷
data[].namestring線路顯示名稱，呈現給使用者
data[].urlstring線路完整位址，含通訊協定與連接埠

驗證失敗回傳 401：

{ "error": "Invalid token", "ok": false }

error 有兩種取值：Token not found（請求裡沒帶 token）與 Invalid token（token 驗證沒過）。

驗證：沿用 Emby 自己的 token

介面不引入新的憑證體系，直接沿用呼叫方既有的 Emby token。伺服器端依以下順序取第一個非空值：

順序位置鍵名
1QueryX-Emby-Token
2HeaderX-Emby-Token
3Queryapi_key
4HeaderX-Emby-Authorization 中的 Token="..."
5CookieAuthorization
6HeaderAuthorization
7Querytoken
8Cookietoken
9Headertoken

涵蓋這麼多位置，是為了讓不同框架寫出來的用戶端都能直接對接——無論它習慣把 token 放在查詢參數、請求標頭還是 Cookie 裡。

取得 token 後，伺服器端拿它去問 Emby 本體：

GET {emby_server_url}/emby/System/Info?X-Emby-Token={token}

Emby 回傳 200 即認定 token 有效，其餘情況一律視為無效。參考實作的驗證逾時是 3 秒，且不快取驗證結果——每次請求都會回源驗證一次。

部署參考實作

Nginx 同域分流示意圖：精確比對 /emby/System/Ext/ServerDomains 轉送到本機 52143 的 emby_ext_domains，其餘路徑交給 Emby 本體

設定檔 config.yaml：

emby:
  server_url: "https://your-emby-server.com"  # Emby 本體位址
server:
  port: 52143                                  # 本服務監聽連接埠
domains:
  - name: "Server 1"
    url: "https://server1.example.com"
  - name: "Server 2"
    url: "https://server2.example.com"

儲存庫附了 Dockerfile 與 docker-compose.yml，直接啟動：

docker compose up -d

關鍵一步是反向代理：這個介面必須和 Emby 同網域同路徑對外，用戶端才會用同一個 base URL 請求到它。在 Emby 的 Nginx 設定裡加一條精確比對：

location = /emby/System/Ext/ServerDomains {
    proxy_pass http://127.0.0.1:52143;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_pass_request_headers on;   # token 相關的標頭必須透傳
    proxy_connect_timeout 5s;
    proxy_read_timeout 10s;
    proxy_send_timeout 10s;
}

重要

proxy_pass_request_headers on 不能省。token 可能藏在 X-Emby-Authorization 或 Cookie 裡，代理層一旦丟掉標頭，介面就只會回傳 Token not found。

部署時還有兩點要注意：

  • 本服務必須能連到設定裡的 Emby 位址，否則所有 token 都驗證不過
  • 網域清單在啟動時從設定檔讀入，改完需要重新啟動服務才會生效

UHD 的實作

UHD 正式環境沒有直接跑這份參考實作，而是依同一套介面重新實作了一份，對外行為與本文描述保持對齊。所以：

  • 對用戶端開發者：依本文的介面對接即可，不需要為 UHD 另外適配
  • 對 UHD 使用者：線路清單由伺服器端維護並下發，用戶端有支援的話就能直接看到全部可用線路

給用戶端開發者的建議

  • 登入成功後再呼叫，此時才有可用 token
  • 以 ok 欄位判斷成功與否，不要只看 HTTP 狀態碼
  • 介面不存在（404）或逾時是常態——大量 Emby 伺服器並沒有部署這個擴充，此時應靜默沿用使用者目前填寫的位址，不要報錯打斷使用
  • 取得清單後在本機快取，不必每次進入 App 都請求
  • 不要把 token 寫進記錄檔、當機回報或截圖
這篇文件對您有幫助嗎？