Clash Meta Docker 部署：Compose 與鏡像更新【2026】| Clash 部落格

為什麼在已有 Docker 的環境優先選 Compose

systemd 裸機部署的優勢是直接、除錯路徑單純、沒有額外抽象層；但一旦主機上同時維護多個服務，你會更在意可重現性與版本釘選。docker compose.yml 把映像檔名、環境變量、掛載點與重啟策略寫在同一個宣告裡，換機或重裝時只要帶上資料目錄就能還原行為。對於只在後臺提供 HTTP／SOCKS 上游、搭配 headless 維運的 Clash Meta 來說，這與其他自架服務的治理方式一致，學習成本更低。

另一個務實動機是訂閱持久化：內核會把 proxy-providers 下載結果寫進你指定的 path；若把配置根目錄整個掛到宿主機，容器重建後節點列表與快取仍在，不必在每次 docker compose up 後重新冷啟動拉取。當然，若訂閱 URL 本身必須先翻牆才能下載，容器化並不會魔法般消除「冷啟動雞生蛋」問題——這一點與裸機相同，仍需首包配置或離線同步。

與 systemd 文檔互補：設定檔語意、external-controller、健康檢查思路相通，差別主要在路徑與進程邊界。
與桌面客戶端分離：伺服器側專心提供端口；本機再用圖形客戶端時，可把容器當網關或獨立上游。

映像檔來源、tag 與 digest

社群維護的 mihomo／Clash Meta 映像檔多發佈在 Docker Hub 或 GHCR，命名空間與更新節奏不盡相同。實務上建議：選定一條你信任的發佈渠道，在 Compose 裡寫明 image: 名稱:版本標籤，避免預設拉 latest 造成半夜自動重啟後行為漂移。進階使用者可進一步用映像檔 digest（sha256:…）把位元組級版本釘死，升級時再有意識地改 digest 並做回滾演練。

維運習慣

在專案目錄保留 compose.yaml 與 .env（權限 600）分離敏感欄位；映像檔升級前用 docker compose pull 預覽變更，再在維護視窗內 up -d。

目錄結構與卷掛載

多數官方或社群 Dockerfile 會把預設配置路徑放在容器內使用者家目錄下（常見為 /root/.config/mihomo，實際以所用映像檔說明為準）。你要做的是：在宿主機建立一個專用資料夾，內含 config.yaml、providers/（訂閱落地）、可選的 ruleset 快取等，然後用唯讀或讀寫卷掛進容器相同路徑。

權限方面，避免整個目錄 777。若映像檔以非 root 執行，請在宿主機用對應 uid／gid 調整所有者；若仍以 root 跑在容器內，至少要確保宿主機目錄不暴露給同機其他低信任服務寫入。NAS 使用者還需注意共享檔案系統（NFS、SMB）對檔案鎖與 fsnotify 的行為，有時會影響熱重載或定時寫入，必要時改放到本機磁碟子卷。

掛載內容	用途
`config.yaml`	端口、模式、`proxy-providers`、`external-controller` 等主配置
`providers/`	訂閱下載結果與合併快取，實現訂閱持久化
GeoIP／規則集快取（若有）	減少啟動時重複下載，便於離線演練

docker compose 範例（示意）

下列片段僅示範結構：映像檔名、內部路徑與端口請依你所選映像檔文檔調整。埠位需與 config.yaml 中 mixed-port、external-controller 一致。

services:
  mihomo:
    image: metacubex/mihomo:v1.19.0
    container_name: mihomo
    restart: unless-stopped
    environment:
      TZ: Asia/Taipei
    volumes:
      - ./mihomo-data:/root/.config/mihomo
    ports:
      - "7890:7890"
      - "9090:9090"
    # For TUN inside container you need extra caps / host network — see warnings below.

啟動順序：cd 到專案目錄 → 確認 mihomo-data/config.yaml 已就緒 → docker compose up -d → docker compose logs -f 觀察是否成功綁定端口與拉取訂閱。若啟動失敗，多半是 YAML 語法、端口衝突或卷路徑與映像檔預設目錄不一致。

TUN 與容器

在純 headless 伺服器上，多數場景只需 HTTP／SOCKS 混合端口即可。若你堅持在容器內跑 TUN，通常涉及 privileged、額外 cap_add、甚至 network_mode: host，安全面與可攜性都會變差；請先評估是否改在宿主機跑裸機 TUN，或僅在客戶端側開 TUN。

網路模式：bridge 與 host

預設 bridge 透過埠映射把容器服務暴露到宿主機，最直覺，也最容易與 NAS 反向代理、防火牆規則對接。若你希望 Clash 看見的來源位址與宿主機網卡完全一致、或要跑某些對綁定地址敏感的場景，可能會考慮 host 模式——此時容器與宿主共享網路命名空間，埠映射不再適用，需直接在配置裡綁定正確位址，並留意與宿主機上其他服務的端口衝突。

對於僅本機其他容器或同一宿主上的應用要連線到 Clash，也可以使用自訂 Docker 網路，用服務名當 DNS，減少把代理端口暴露到 LAN；是否開放給區網則交給宿主機防火牆與 bind-address 策略決定。

external-controller、secret 與暴露面

external-controller 提供 REST API，用於切換節點、觸發重載與健康檢查。預設應只監聽 127.0.0.1，由宿主機透過 SSH 埠轉發管理；若必須對區網開放，務必設置強 secret，並在防火牆層限制來源 IP。把管理埠直接映射到公網而無認證，等價於贈送遠端切換代理的能力，風險極高。

最小暴露檢查

Compose 只映射業務需要的埠（例如 mixed-port）；管理埠留在本機迴環。
secret 放 .env 並排除出版本庫。
定期檢視 docker compose ps 與宿主機 ss -lntp 是否與預期一致。

鏡像更新與回滾

建議把升級當成一次小型變更：先讀發行說明（是否有不兼容的 YAML 欄位），再在低峰時段執行 docker compose pull，接著 docker compose up -d。若新版本行為異常，回滾方式很直接：把 Compose 中的映像檔 tag（或 digest）改回上一個已知良好版本，再執行一次 up -d。因為配置與訂閱快取掛在卷上，回滾映像檔通常不會丟失本機策略檔，但若新版本曾改寫快取格式，仍應保留備份。

升級前備份整個資料目錄（含 config.yaml 與 providers/）。
拉取新映像檔並重建容器。
檢查日誌與 API 健康狀態；必要時還原映像檔 tag。

與 systemd 路徑如何並存

同一臺機器不建議同時以 systemd 與 Docker 各跑一個監聽同一端口的實例。若你從裸機遷到容器，流程可以是：停掉舊服務 → 確認端口釋放 → 把原配置目錄複製到卷 → 校正內部路徑與權限 → 用 Compose 啟動。站內《Clash Meta Linux 無頭》一文中的 YAML 與訂閱思路可直接沿用，只是把「工作目錄」換成容器視角。

常見問題

容器內訂閱下載失敗？

先在容器外宿主機用 curl -v 測試訂閱 URL；若宿主能拉而容器不能，檢查 DNS（可在 Compose 加 dns: 或固定 resolv.conf 策略）、MTU、以及是否走了錯誤的出站路由。若兩者皆失敗，屬網路出口或機場端問題，與是否 Docker 無關。

提示無法寫入 providers？

核對卷掛載是否可寫、容器執行使用者與宿主機目錄所有者是否一致；可進容器執行 id 與目錄權限檢查。NAS 上常見為 SMB 掛載權限映射錯誤。

群暉／威聯通上要注意什麼？

使用官方容器套件時，確認 CPU 架構與映像檔相符；儘量把配置放在本機儲存空間而非遠端掛載，減少 I/O 延遲導致的間歇性寫入失敗。重啟策略建議 unless-stopped，避免 NAS 計畫性重開機後服務未起。

操作摘要

選定映像檔與明確版本 tag，必要時用 digest 釘選。
將配置與訂閱快取目錄以卷掛載，確保訂閱持久化與可備份。
依需求選 bridge 或 host 網路，謹慎對待 TUN 與權限。
鎖好 external-controller 暴露面與 secret。
升級先拉映像檔、再重建容器；保留回滾用舊 tag 與資料備份。

需要圖形客戶端與下載入口？

容器適合在伺服器側穩定提供代理；日常桌面使用仍可從下載頁取得整合介面與說明。若你尚未安裝任何 Clash 系客戶端，亦可先參考《新手入門完整指南》建立整體概念。

立即免費下載 Clash，開啟流暢上網新體驗

Clash Meta Docker 部署：Compose 與鏡像更新完整步驟