Linux mihomo 部署教學：桌面版圖形介面與 systemd 命令列服務

先決定執行方式與流量入口

Linux 上的 Clash 相容用戶端通常由圖形介面和代理核心組成。mihomo 是代理核心，會讀取 YAML 設定、監聽本機連接埠並依規則分流；圖形用戶端則負責匯入訂閱、管理設定、選擇策略組，以及呼叫系統代理或 TUN。兩者不是同一個安裝套件，也沒有共用的固定設定檔路徑。

若使用 GNOME、KDE 等桌面環境，且需要經常切換節點，建議使用圖形用戶端。只有 SSH 的伺服器，或需要開機自動啟動、集中檢視日誌時，使用 mihomo 搭配 systemd 更容易管理權限與檔案歸屬。本文的命令列做法適用於使用 systemd 的一般 Linux 主機，不適用於只有容器程序管理器的環境。

桌面環境：安裝圖形用戶端並匯入設定

1. 確認發行版、架構與安裝套件類型

前往用戶端下載頁面，選擇支援 Linux 的 Clash Verge Rev、FlClash 等用戶端。先查看系統資訊，不要只依電腦型號判斷安裝套件。x86_64 通常對應發行頁上的 x64 或 amd64；aarch64 通常對應 arm64。除了確認處理器架構相符，也要檢查用戶端要求的發行版版本與執行階段程式庫。

cat /etc/os-release
uname -m

Debian、Ubuntu 通常使用 DEB 套件，Fedora 等發行版則通常使用 RPM 套件。以下將已下載的檔案重新命名為本機的 client.deb 或 client.rpm，只是為了簡化安裝指令，並非專案實際發布的檔名。切換至檔案所在目錄，依發行版擇一執行：

# Debian / Ubuntu
sudo apt install ./client.deb

# Fedora
sudo dnf install ./client.rpm

從桌面應用程式選單啟動用戶端，不要用 sudo 啟動整個圖形介面。若需要服務模式或 TUN 權限，請使用用戶端提供的服務安裝或授權功能。這可避免使用者設定檔被 root 擁有，導致下次以一般使用者啟動時無法儲存訂閱。

2. 匯入訂閱並確認實際生效的設定

1. 在用戶端的設定或訂閱頁面，匯入有效的 Clash 相容訂閱連結，或匯入本機 YAML 檔案。不同版本的用戶端，選單名稱可能有所差異。
2. 選取剛匯入的設定，並設為目前使用的設定。只看到下載成功，不代表設定已啟用。
3. 在策略組中選擇可用節點，再查看日誌是否有設定解析錯誤。策略組名稱必須與規則引用的名稱一致。
4. 從目前設定或執行資訊確認 HTTP、SOCKS 或 mixed 監聽連接埠。以下以 7890 為例，不必強行將現有用戶端改成這個連接埠。
5. 先測試明確指定的代理，再啟用系統代理。只有需要接管不遵循代理設定的應用程式時，才進一步測試 TUN。

圖形用戶端可能會合併訂閱、覆寫設定和介面選項，最後產生一份執行設定。不要直接編輯這類暫存產生的檔案：更新訂閱或切換設定後，修改內容可能會消失。需要長期保留的連接埠、規則或 DNS 調整，應使用用戶端的覆寫機制；也不要假設它會讀取 ~/.config/mihomo/config.yaml。

3. 區分桌面系統代理與終端機代理

用戶端的「系統代理」通常會修改桌面環境的代理設定。瀏覽器可能會遵循這項設定，但新開的終端機中的 curl、套件管理器和背景服務不一定會讀取。反過來，在終端機執行 export 也不會修改已在執行的瀏覽器。測試時應記錄使用的應用程式、代理入口與連接埠，不要只記下「已開啟代理」。

無桌面環境：準備核心與獨立目錄

以下使用固定路徑部署，避免混淆目前 SSH 使用者的家目錄與服務的工作目錄。安裝核心前，根據 uname -m 的結果，從 mihomo 官方發布管道選擇符合目前架構與 CPU 指令集需求的 Linux 版本。解壓縮下載的壓縮檔，並將執行檔在本機命名為 mihomo；以下指令從該檔案所在目錄開始執行。

sudo install -m 0755 ./mihomo /usr/local/bin/mihomo
/usr/local/bin/mihomo -v

-v 用來查看實際安裝的版本。若出現 Exec format error，先確認是否誤將壓縮檔當成程式執行，或選錯架構；若出現 Illegal instruction，請檢查版本所需的指令集。重新下載符合主機規格的版本，比反覆調整檔案權限更能解決問題。

建立專用服務帳號

以下帳號僅用來執行代理服務，不供互動式登入使用。若帳號已存在，請略過建立步驟；若發行版的 nologin 不在此路徑，先用 command -v nologin 確認位置並調整。設定檔由 root 管理，執行資料則由服務使用者寫入。

getent passwd mihomo || sudo useradd \
  --system --user-group \
  --home-dir /var/lib/mihomo \
  --shell /usr/sbin/nologin mihomo

sudo install -d -o root -g mihomo -m 0750 /etc/mihomo
sudo install -d -o mihomo -g mihomo -m 0750 /var/lib/mihomo

• /usr/local/bin/mihomo：核心程式，一般服務使用者不得覆寫。
• /etc/mihomo/config.yaml：主要設定檔，可能包含節點憑證或訂閱網址，應限制讀取權限。
• /var/lib/mihomo：透過 -d 指定的資料目錄，用於存放執行狀態、快取及設定所需資源。

本文使用 -f 明確指定主要設定檔，不依賴預設目錄。若實際設定包含 proxy-providers、rule-providers 或外部資料檔案，還要檢查檔案路徑、讀取權限與下載條件。不要只複製主要 YAML，就假設所有相依檔案都已備妥。

先用最精簡設定驗證監聽連接埠

為了區分安裝問題與訂閱問題，先使用以下直連驗證設定。在目前目錄建立 config.yaml，並寫入以下內容。這只用來確認核心能否啟動、接收代理請求並直接連線至外部，不包含任何代理節點，也不會變更出口地區。

mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info

tun:
  enable: false

rules:
  - MATCH,DIRECT

mixed-port 會在同一個連接埠接受 HTTP 與 SOCKS 代理請求。allow-lan: false 用來限制僅本機可存取；範例也明確指定迴路位址。暫時不啟用控制介面，也不必在雲端伺服器的安全組開放 7890 連接埠。

sudo install -o root -g mihomo -m 0640 \
  ./config.yaml /etc/mihomo/config.yaml

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

-t 用來檢查目前核心能否載入設定，不等於測試節點連線。若出現 YAML 錯誤，先檢查縮排、冒號後的空格及欄位型別；若出現權限錯誤，請確認服務帳號是否能存取設定檔及其每一層上層目錄。

設定 systemd 常駐執行

建立 /etc/systemd/system/mihomo.service，並寫入以下完整內容。此服務適用於前述本機明確指定代理的方式，不會授予建立 TUN 裝置或修改系統路由的權限。

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

[Service]
Type=simple
User=mihomo
Group=mihomo
WorkingDirectory=/var/lib/mihomo
StateDirectory=mihomo
StateDirectoryMode=0750
ExecStart=/usr/local/bin/mihomo -d /var/lib/mihomo -f /etc/mihomo/config.yaml
Restart=on-failure
RestartSec=5s
UMask=0027
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict

[Install]
WantedBy=multi-user.target

StateDirectory 讓 systemd 管理可寫入的狀態目錄；ProtectSystem=strict 會限制服務寫入系統檔案，但狀態目錄仍可寫入。ProtectHome=true 會阻止服務讀取使用者家目錄，因此不要將 provider 檔案留在下載目錄後直接引用。請將相依檔案放在服務可存取的目錄，再依設定中的路徑安排檔案。

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo.service

systemctl status mihomo.service --no-pager
sudo journalctl -u mihomo.service -b -n 80 --no-pager
sudo ss -lntup 'sport = :7890'

enable --now 會同時設定開機自動啟動並立即啟動服務。network-online.target 的等待效果取決於發行版啟用的網路等待服務，無法保證外部訂閱網站一定連得上。若啟動時需要下載遠端資源，仍須從日誌確認請求是否成功。

更新設定與升級執行檔

修改 YAML 後，先以服務使用者執行前述 -t 檢查，確認成功後再重新啟動。本文未定義 ExecReload，因此不要將 systemctl reload mihomo 當作可用步驟。重新啟動會中斷現有代理連線，請選擇合適的維護時段。

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

升級核心前，請保留原有程式與設定。停止服務後，使用 install 寫入新程式、確認版本並重新檢查設定，再啟動服務。不要直接覆寫正在執行的程式，也不要假設新版一定支援舊設定中的所有已淘汰欄位。

設定終端機代理環境變數並驗證請求

先執行一次明確指定代理的請求

在執行 mihomo 的同一台主機上執行以下測試。--noproxy "" 可避免既有的 NO_PROXY 設定讓這次請求繞過代理。收到 HTTP 回應代表請求鏈路有所進展；網站回傳的實際狀態碼仍須另外判斷。

curl --noproxy "" --proxy http://127.0.0.1:7890 \
  --connect-timeout 10 --max-time 30 -I https://example.com/

測試最精簡的直連設定時，成功只代表本機代理入口可用。換成實際節點設定後，應搭配連線日誌中的目標、規則與策略組，判斷流量是否經過節點；不能只因網頁能開啟，就認定出口已切換。

為目前終端機及其子程序設定代理

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 --connect-timeout 10 --max-time 30 -I https://example.com/

https_proxy 的值使用 http:// 並不矛盾：這裡描述的是連線至本機 HTTP 代理的方式，HTTPS 目標通常會透過 CONNECT 建立通道。對支援此格式的程式而言，socks5h:// 代表將目標網域交由 SOCKS 代理解析；不同工具支援的變數與優先順序不盡相同。

• 這組 export 只會影響目前的 shell 及之後啟動的子程序，不會修改其他登入工作階段。
• 若要長期生效，可加入所用 shell 的啟動檔，例如 Bash 互動式終端機常用的 ~/.bashrc；但並非所有程式都會讀取這個檔案。
• sudo 通常會過濾環境變數；不要因為「一般 curl 成功」，就推斷 sudo apt 一定會使用相同代理。
• systemd 系統服務不會讀取使用者的 ~/.bashrc。其他需要代理的服務應個別設定環境，也不要替 mihomo 設定指向自身連接埠的代理變數。

若機器先前設定過大寫變數，也應一併檢查並保持一致。基於安全考量，curl 不接受大寫的 HTTP_PROXY，因此本文使用小寫形式。停止代理前，可清除目前終端機中的常見變數，避免殘留設定導致後續指令連線失敗：

unset http_proxy https_proxy all_proxy no_proxy
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY

TUN、遠端存取與故障排查

TUN 涉及獨立的權限與路由變更

TUN 會透過虛擬網路介面接管符合路由條件的 IP 流量，並不保證「所有程式、所有流量都一定經過代理」。排除路由、DNS、IPv6 與現有 VPN 都會影響結果。在 Linux 上通常需要存取 /dev/net/tun，並具備網路管理權限；只將 tun.enable 設為 true，無法略過這些要求。

本文的非 root systemd 服務單元並未授予上述權限。若需要 TUN，應依所用用戶端或 mihomo 的最新文件，重新評估服務權限、DNS 接管與路由設定，不要只加上一條提權指令。在 SSH 伺服器上操作前，請保留另一個連線工作階段與雲端主控台入口，並確認管理網段的排除方式，避免接管路由後中斷連線。

遠端使用時，優先採用 SSH 轉發

若要在個人電腦上暫時使用伺服器的本機代理，可在個人電腦執行 SSH 本機轉送，而非將代理連接埠直接暴露於公網。以下假設 SSH 設定中已有名為 mihomo-host 的主機別名：

ssh -N -o ExitOnForwardFailure=yes \
  -L 127.0.0.1:17890:127.0.0.1:7890 mihomo-host

保持 SSH 連線，並在個人電腦將應用程式的代理設為 127.0.0.1:17890。其中遠端的 127.0.0.1:7890 指的是伺服器本機，不是個人電腦。若確實要提供區域網路代理，還須另外設定身分驗證、防火牆與存取範圍，不能只開啟 allow-lan。

依錯誤狀況縮小排查範圍

排查時請保留三項資訊：mihomo -v 的版本輸出、服務日誌中的第一筆有效錯誤，以及應用程式實際使用的代理位址。分享日誌前，請移除訂閱憑證、節點密碼與控制介面金鑰。若要查詢欄位用途，可繼續閱讀完整文件；首次匯入訂閱與切換設定的操作，請參閱設定教學。