平台部署 預計閱讀 14 分鐘

Linux 部署 Clash：桌面用戶端與無桌面 mihomo 服務設定

整理圖形用戶端與命令列核心的部署方式，說明設定目錄、systemd 服務、代理環境變數和日誌查看，避免混用兩套入口。

先確認部署方式：桌面用戶端還是 mihomo 服務

Linux 上常說的「安裝 Clash」，實際上對應兩條不同的路線。第一條是在 GNOME、KDE Plasma、Xfce 等桌面環境中安裝圖形用戶端，由用戶端負責匯入訂閱、切換設定、啟動核心、管理系統代理及顯示日誌。第二條是在伺服器、軟路由、開發機或沒有桌面環境的主機上直接執行 mihomo 核心，再透過 systemd 管理程序。兩種方式可以使用相近的 YAML 設定，但操作入口、權限範圍與問題定位方式並不相同。

部署方式 適用環境 設定入口 程序管理 流量接管
桌面用戶端 日常桌面、開發工作站 用戶端介面與設定目錄 用戶端本身 系統代理或 TUN
mihomo 服務 伺服器、無桌面主機、旁路閘道 手動維護 YAML 檔案 systemd 環境變數、明確代理或 TUN

桌面用戶端和 mihomo 並不是可以互換稱呼的同一層產品。用戶端提供介面、更新與設定管理，mihomo 則是讀取設定並執行代理、DNS 與規則的核心。有些用戶端內建 mihomo，另一些則允許選擇核心版本。若已由桌面用戶端啟動核心，就不要再同時啟動監聽相同連接埠的 systemd 服務，否則通常會出現 address already in use。

Linux 桌面用戶端：安裝後先確認核心與設定目錄

依發行版選擇安裝套件

Debian、Ubuntu、Linux Mint 等系統通常使用 .deb，Fedora、RHEL 系列和 openSUSE 常見 .rpm，其他發行版則可依用戶端提供的版本選擇 AppImage 或壓縮檔。下載前先執行 uname -m 查看架構：輸出 x86_64 對應 amd64 或 x64，輸出 aarch64 對應 arm64。安裝套件格式與 CPU 架構必須同時相符。

uname -m

# Debian、Ubuntu 安裝本機 deb
sudo apt install ./client-linux-amd64.deb

# Fedora 安裝本機 rpm
sudo dnf install ./client-linux-x86_64.rpm

首次啟動後，先進入用戶端的「設定」→「核心設定」或「設定」→「參數設定」，確認目前的核心名稱、核心版本與工作目錄。不同用戶端的選單文字可能略有差異，重點是找到核心、設定目錄、監聽連接埠與日誌這四項。不要把「用戶端版本」當成「核心版本」；排查規則或 DNS 相容性問題時，應記錄兩者。

匯入訂閱不代表流量已經進入代理

  1. 在「設定」或「訂閱」頁面貼上訂閱網址並執行匯入。
  2. 選取剛匯入的設定，等待用戶端完成解析並啟動核心。
  3. 在「代理」頁面選擇策略群組；設定中的 PROXY 通常是策略群組名稱，不是固定的內建出口。
  4. 依需要開啟「系統代理」或「TUN 模式」，兩者處理的流量範圍不同。
  5. 查看日誌，確認沒有連接埠遭佔用、YAML 解析或 DNS 初始化錯誤。

系統代理通常會向桌面環境寫入 HTTP 和 SOCKS 代理參數，適合遵循系統代理設定的瀏覽器與圖形應用程式。TUN 模式透過虛擬網路介面接管更廣泛的流量，可能需要管理員授權、網路權限或額外的 DNS 設定。只匯入訂閱但沒有啟用任何流量入口時，即使核心正在執行，應用程式也不會自動使用它。

透過連接埠確認用戶端是否真正啟動核心

Clash 類設定常將混合代理連接埠設為 7890，也可能分別使用 HTTP 7890 與 SOCKS 7891。這些只是常見值，最終應以目前的設定與用戶端設定為準。可以使用 ss 查看監聽程序：

ss -lntp | grep -E '7890|7891|9090'

# 透過本機 HTTP 代理測試
curl -I -x http://127.0.0.1:7890 https://example.com

# 透過 SOCKS5，並由代理端解析網域名稱
curl -I --proxy socks5h://127.0.0.1:7891 https://example.com

curl 成功但瀏覽器失敗，通常應檢查瀏覽器自己的代理擴充功能或桌面系統代理；瀏覽器成功但終端機失敗，則應檢查終端機環境變數。兩類應用程式的代理入口可能完全獨立，切換規則模式不能取代入口設定。

無桌面主機：準備 mihomo 二進位檔與工作目錄

建立固定目錄與專用帳戶

伺服器部署應將二進位檔、設定與執行狀態分開。以下範例將程式放在 /usr/local/bin/mihomo，主要設定放在 /etc/mihomo/config.yaml，執行時資料放在 /var/lib/mihomo。專用系統帳戶可以限制一般代理服務存取檔案的範圍。

sudo install -m 0755 mihomo /usr/local/bin/mihomo
sudo useradd --system --home /var/lib/mihomo --shell /usr/sbin/nologin mihomo
sudo install -d -o mihomo -g mihomo /etc/mihomo
sudo install -d -o mihomo -g mihomo /var/lib/mihomo
sudo install -m 0640 -o mihomo -g mihomo config.yaml /etc/mihomo/config.yaml

部分發行版的 nologin 位於 /sbin/nologin，可以先執行 command -v nologin 確認路徑。若設定引用 GeoIP、GeoSite、規則集或憑證檔案，也要確保 mihomo 帳戶具備讀取相應檔案的權限。設定中使用相對路徑時，路徑通常以 mihomo 的工作目錄為基準，因此 systemd 中的 WorkingDirectory 與啟動參數需要保持一致。

先測試設定，再交給 systemd

sudo -u mihomo /usr/local/bin/mihomo \
  -t \
  -d /var/lib/mihomo \
  -f /etc/mihomo/config.yaml

-t 用於測試設定，-d 指定執行目錄，-f 指定設定檔。測試通過只代表設定能被目前的核心解析，不代表所有節點都能連線，也不代表系統流量已經進入代理。升級 mihomo 或修改規則提供者後，應再次執行測試，再重新啟動服務。

使用 systemd 管理 mihomo 服務

基本代理服務單元

只提供 HTTP、SOCKS 或 mixed-port 時，通常不需要 TUN 權限。建立 /etc/systemd/system/mihomo.service：

[Unit]
Description=mihomo proxy service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=mihomo
Group=mihomo
WorkingDirectory=/var/lib/mihomo
ExecStartPre=/usr/local/bin/mihomo -t -d /var/lib/mihomo -f /etc/mihomo/config.yaml
ExecStart=/usr/local/bin/mihomo -d /var/lib/mihomo -f /etc/mihomo/config.yaml
Restart=on-failure
RestartSec=5
LimitNOFILE=1048576

[Install]
WantedBy=multi-user.target

儲存後重新載入 systemd 設定並啟動：

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
systemctl status mihomo --no-pager
sudo journalctl -u mihomo -n 100 --no-pager

ExecStartPre 會在每次啟動前驗證 YAML。若測試失敗，主程序不會啟動；執行重新啟動操作時，舊程序仍可能已經結束，因此在正式環境修改設定前仍應先手動執行測試指令。Restart=on-failure 適合處理異常退出，但不會修正無效設定或被其他程序佔用的連接埠。

啟用 TUN 時再增加網路權限

mihomo 的 TUN 設定常見結構如下。實際可用欄位取決於目前的 mihomo 版本及系統網路堆疊，移轉舊設定時應以所用版本的文件為準。

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

使用專用帳戶執行 TUN 時，服務通常需要 CAP_NET_ADMIN，而且主機需要提供 /dev/net/tun。可以在服務的 [Service] 區段加入：

AmbientCapabilities=CAP_NET_ADMIN
CapabilityBoundingSet=CAP_NET_ADMIN
DeviceAllow=/dev/net/tun rw

修改服務後執行 sudo systemctl daemon-reload 和 sudo systemctl restart mihomo。接著使用 ip link、ip route 與服務日誌檢查虛擬介面和路由。容器環境還需要主機向容器開放 TUN 裝置及網路管理權限；只在容器內修改 YAML，無法突破主機的裝置與權限限制。

代理環境變數：讓終端機程式使用 mihomo

僅在目前終端機暫時生效

未開啟 TUN 時，命令列程式通常需要明確指定代理。假設 mihomo 在本機監聽 mixed-port 7890，可以設定：

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=socks5h://127.0.0.1:7890
export no_proxy=localhost,127.0.0.1,::1

curl -I https://example.com

變數名稱同時存在大寫與小寫寫法，不同程式的讀取習慣不完全一致。需要相容特定工具時，可以同步設定 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 與 NO_PROXY。但 CGI 等環境對大寫 HTTP_PROXY 有額外的安全限制，在伺服器全域設定前應確認實際執行情境。

socks5h 中的字母 h 表示由 SOCKS 代理端處理網域名稱解析。使用 socks5 時，應用程式可能先在本機解析網域名稱，再將 IP 交給代理，這會改變 DNS 路徑。診斷 DNS 問題時，應明確記錄使用的是 socks5 還是 socks5h。

分別設定 Git、APT 與 systemd 服務

Git 可以使用自身的設定，不依賴目前的 shell：

git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

# 查看
git config --global --get http.proxy

# 刪除
git config --global --unset http.proxy
git config --global --unset https.proxy

APT 可在 /etc/apt/apt.conf.d/80proxy 中指定代理：

Acquire::http::Proxy "http://127.0.0.1:7890";
Acquire::https::Proxy "http://127.0.0.1:7890";

如果另一個 systemd 服務需要經過 mihomo，不要假定它會繼承登入 shell 的變數。使用 systemctl edit 服務名稱 建立覆寫設定：

[Unit]
After=mihomo.service
Wants=mihomo.service

[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
Environment="NO_PROXY=localhost,127.0.0.1,::1"

儲存後執行 sudo systemctl daemon-reload 並重新啟動目標服務。注意 After 只限制啟動順序，Wants 表示弱依賴；它們不會等待 mihomo 的某個代理節點完成連線檢查。對啟動階段必須連網的工作，可以加入應用程式自身的重試機制。

設定連接埠、規則與控制介面

最小監聽設定的界線

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false

external-controller: 127.0.0.1:9090
secret: "replace-with-a-long-random-secret"

rules:
  - DOMAIN-SUFFIX,example.org,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,PROXY

mixed-port 同時接受 HTTP 與 SOCKS 連線。allow-lan: false 適合只供本機使用的情境；若確實需要區域網路裝置存取，應同時設定監聽位址、防火牆與存取範圍。external-controller 是控制介面，不是代理連接埠，範例綁定到回送位址 127.0.0.1:9090。控制密鑰應改為實際的隨機值，並避免直接將控制介面暴露在不受信任的網路中。

規則會依序求值，第一個符合的項目決定流向。DIRECT 表示直連，REJECT 表示拒絕，PROXY 必須對應設定中已定義的策略群組。no-resolve 表示該 IP 規則不主動觸發網域名稱解析，不等於關閉所有 DNS。

分開管理訂閱與本機覆寫

圖形用戶端通常有自己的訂閱快取、執行設定與覆寫機制，手動修改產生後的執行檔案，可能在下次更新時被覆蓋。無桌面 mihomo 則不會自動將某個訂閱網址視為完整的正式環境設定；應由獨立的更新指令碼、設定產生工具或代理提供者完成下載與轉換，再執行測試、替換和重新載入。

  1. 將遠端內容下載到暫存檔，而不是直接覆蓋目前的設定。
  2. 檢查策略群組名稱、規則引用、DNS 欄位與規則提供者路徑。
  3. 使用目前執行中的 mihomo 二進位檔執行 -t 測試。
  4. 測試通過後，以原子方式替換設定檔。
  5. 重新啟動服務，並檢查最近 100 行日誌與監聽連接埠。

日誌與疑難排解：逐層確認程序、連接埠與入口

systemd 服務啟動失敗

systemctl status mihomo --no-pager
sudo journalctl -u mihomo -b --no-pager
sudo journalctl -u mihomo -f
  • 出現 YAML 行號或欄位錯誤：先執行設定測試，檢查縮排與目前核心支援的欄位。
  • 出現 permission denied：核對設定、規則集、執行目錄以及 /dev/net/tun 的權限。
  • 出現 address already in use：使用 ss -lntp 找出佔用 7890、7891 或 9090 的程序。
  • 服務不斷重新啟動：查看第一次失敗時的日誌，不要只觀察重啟次數。
  • TUN 啟動失敗：確認核心模組、裝置節點、systemd capability 與路由權限。

連接埠存在，但請求仍然失敗

先透過本機代理發出請求，排除應用程式設定問題，再檢查 mihomo 日誌中的連線目標、符合的規則與最終策略。若日誌完全沒有出現該請求，流量通常沒有抵達代理連接埠；若日誌出現請求但策略不符合預期，應檢查規則順序與策略群組選擇；若策略正確但連線逾時，再檢查節點可用性、伺服器時間、DNS 與上游網路。

# HTTP 代理入口
curl -v -x http://127.0.0.1:7890 https://example.com

# SOCKS 代理入口，遠端解析網域名稱
curl -v --proxy socks5h://127.0.0.1:7890 https://example.com

# 查看本機路由
ip route

# 查看 DNS 狀態，適用於 systemd-resolved
resolvectl status

若 mihomo 執行於另一台主機，將測試位址改為該主機的區域網路 IP，並確認 allow-lan、監聽位址與防火牆規則。不要將控制連接埠 9090 當作 HTTP 代理連接埠使用，也不要把 SOCKS URL 寫成 HTTP URL。

桌面用戶端與 systemd 衝突

同一台 Linux 工作站既安裝桌面用戶端又設定 systemd 服務時，建議只讓其中一個負責常駐執行。可以執行 systemctl disable --now mihomo 暫停系統服務，再啟動桌面用戶端；或者退出桌面用戶端，確認其核心程序結束後再啟動 systemd。只關閉用戶端視窗不一定代表已退出系統匣程序，應再次檢查監聽連接埠與程序命令列。

部署完成後的檢查清單

  • 記錄用戶端版本與 mihomo 核心版本，確認目前由誰啟動核心。
  • 確認設定檔、執行目錄與規則集檔案都能由執行帳戶讀取。
  • 使用 mihomo -t 測試目前的設定。
  • 使用 ss -lntp 確認代理連接埠與控制連接埠沒有衝突。
  • 使用 curl -x 或 curl --proxy 驗證明確代理入口。
  • 依應用程式分別設定終端機變數、Git、APT 或 systemd 環境變數。
  • 啟用 TUN 後檢查虛擬介面、預設路由、DNS 與 SSH 回程路徑。
  • 更新訂閱或核心後重新測試設定，並查看啟動日誌。

Linux 桌面部署的核心，是讓用戶端統一管理設定、核心與系統入口；無桌面部署的核心，則是將 mihomo 當作一般系統服務管理。只要始終區分「設定已匯入」「核心已監聽」「應用程式已指向代理」與「TUN 已接管流量」這四種狀態，就能避免大多數連接埠衝突與代理未生效的問題。

下載Clash 依平台選擇用戶端