Linux 安裝 mihomo：桌面用戶端與 systemd 命令列部署指南

先選部署方式：桌面工作階段或背景服務

mihomo 是 Clash Meta 專案沿用的核心名稱，負責讀取設定、比對規則及建立連線；圖形用戶端則管理訂閱、系統匣選單與系統整合。安裝核心二進位檔不會自動開啟桌面視窗，也不會讓所有 Linux 程式自動透過代理連線。

如果使用 GNOME、KDE 等桌面環境，且需要經常切換節點，建議使用內建 mihomo 核心的用戶端。若透過 SSH 管理伺服器，並希望離開終端機後服務仍持續運作，則適合部署獨立核心並交由 systemd 管理。兩種方式可使用相近的 YAML 設定，但請勿讓它們占用相同的監聽連接埠。

方式一：安裝 Linux 桌面用戶端

確認處理器架構與安裝套件格式

先在終端機執行以下兩個命令。x86_64 通常對應下載項目中的 x64 或 amd64，aarch64 則對應 arm64。CPU 架構與發行版套件格式是兩項不同條件：選對 DEB 套件，不代表套件內的 CPU 架構一定相符。

uname -m
cat /etc/os-release

• Debian、Ubuntu 系列：優先選擇與發行版相容的 DEB 套件。
• Fedora 系列：選擇適用於該發行版的 RPM 套件，並透過套件管理器安裝相依套件。
• AppImage：需要設定可執行權限；能否直接執行也取決於系統程式庫與 FUSE 支援。

前往用戶端下載頁面選擇 Linux 安裝套件。以下命令假設已將本機 DEB 套件重新命名為 clash-client.deb，並切換到該檔案所在目錄。這只是操作範例，不代表實際發布的檔名。

sudo apt install ./clash-client.deb

先確認訂閱正常，再啟用系統代理

1. 啟動用戶端，並在訂閱或設定管理頁面匯入服務商提供的 Clash YAML 訂閱。各用戶端的介面名稱不盡相同，不要將某款軟體的選單路徑套用到所有用戶端。
2. 選取匯入的設定，檢查核心啟動記錄。節點清單有內容，不代表規則、策略群組與 DNS 設定都有效。
3. 選擇規則模式，在策略群組中選取可用節點，並記下用戶端顯示的本機 HTTP 或混合連接埠。
4. 開啟用戶端的系統代理開關，再用瀏覽器瀏覽目標網站；同時查看連線清單，確認流量進入預期的策略群組。

以 GNOME 桌面為例，也可以前往「設定」→「網路」→「網路代理」，選擇手動設定，將 HTTP 和 HTTPS 代理指向 127.0.0.1 與用戶端實際使用的連接埠。這裡設定的是連往本機 HTTP 代理的連線；HTTPS 網站通常透過 CONNECT 通道存取，不需要擅自將代理位址改成 HTTPS。

系統代理主要適用於會讀取桌面代理設定的應用程式。終端機程式、容器與部分遊戲可能不會採用這些設定。遇到這類程式，請明確設定代理或個別調整應用程式設定；「系統代理已開啟」不等於「所有流量都已導入代理」。

方式二：準備 mihomo 二進位檔與設定目錄

從專案發布管道取得符合 CPU 架構與指令集需求的 Linux 核心，解壓縮後將可執行檔命名為 mihomo。以下命令請在該檔案所在目錄執行。較舊的 x86 處理器也要留意建置版本的指令集需求，不能只憑「64 位元」判斷是否相容。

chmod +x ./mihomo
./mihomo -v
sudo install -m 0755 ./mihomo /usr/local/bin/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

如果系統中已存在 mihomo 帳戶，請略過建立帳戶的步驟，並檢查其所屬群組。不同發行版的 nologin 路徑可能不同，可先執行 command -v nologin 確認。設定目錄由 root 管理，執行目錄則交由服務帳戶寫入，避免讓網路服務直接修改自己的完整設定。

先用最精簡的設定確認啟動流程

以下是用於啟動檢查的直連設定。這份設定沒有代理節點，所有請求都會依照最後一條規則直連，因此無法用來驗證遠端代理效果。先確認程序、目錄權限與連接埠監聽都正常，再換成可信來源的完整設定，排查問題時會更容易掌握範圍。

sudo tee /etc/mihomo/config.yaml > /dev/null <<'YAML'
mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info
ipv6: false

rules:
  - MATCH,DIRECT
YAML

sudo chown root:mihomo /etc/mihomo/config.yaml
sudo chmod 0640 /etc/mihomo/config.yaml
sudo -u mihomo /usr/local/bin/mihomo -t \
  -d /var/lib/mihomo -f /etc/mihomo/config.yaml

mixed-port: 7890 會在同一個連接埠接受 HTTP 與 SOCKS 代理連線；-d 用來指定工作目錄，快取等執行檔案通常會放在這裡；-f 則明確指定主要設定檔的位置。設定檢查通過，代表核心能解析並載入目前的設定，不表示所有節點都能連線。

換成完整訂閱設定後，再執行一次 -t。部分設定會參照 GeoIP、GeoSite 或遠端規則集，初次檢查可能需要下載額外檔案。如果伺服器目前無法存取相關網址，請依照設定需求預先準備資源，或先改用不依賴這些資源的設定，以排除啟動問題。

設定 systemd 服務：啟動、記錄與自動復原

將以下內容儲存為 /etc/systemd/system/mihomo.service。此服務以專用帳戶執行，只提供一般代理連接埠，不具備建立 TUN 網路介面所需的網路管理權限。尚未了解權限範圍前，請勿直接改為以 root 身分執行。

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

[Service]
Type=simple
User=mihomo
Group=mihomo
StateDirectory=mihomo
StateDirectoryMode=0750
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=5s
UMask=0027
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict
ReadWritePaths=/var/lib/mihomo

[Install]
WantedBy=multi-user.target

StateDirectory 負責管理執行資料目錄，ProtectSystem=strict 限制服務修改系統檔案，ReadWritePaths 則保留執行目錄的寫入權限。如果設定引用家目錄中的憑證或規則檔案，會受到 ProtectHome=true 限制；請將必要檔案移至專用目錄並授予唯讀權限，而不是直接取消所有防護。

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
systemctl status mihomo --no-pager
sudo journalctl -u mihomo -b -n 80 --no-pager
sudo ss -lntp 'sport = :7890'

正常情況下，服務狀態應為 active (running)，且本機 7890 連接埠正在監聽。network-online.target 只用來安排啟動順序，無法保證訂閱伺服器當時可連線；若遇到網路問題，仍應查看記錄判斷。若連續啟動失敗而觸發頻率限制，修正問題後可執行 sudo systemctl reset-failed mihomo 再重新啟動。

修改設定後的固定操作順序

1. 保留舊設定的備份，再編輯 /etc/mihomo/config.yaml；請勿將含有憑證的檔案放進公開目錄。
2. 使用與服務相同的帳戶、工作目錄和 -f 參數執行設定檢查。
3. 確認檢查成功後，執行 sudo systemctl restart mihomo，再查看記錄與監聽連接埠。

只修改 YAML 不需要執行 daemon-reload；修改服務單元檔才需要。本文沒有設定 ExecReload，因此請勿依賴 systemctl reload mihomo 套用更新。

確認代理範圍：終端機、規則與 TUN

服務啟動後，不會自動為目前的 Shell 設定環境變數。先對單一請求明確指定代理，方便分辨「應用程式沒有使用代理」與「核心轉發失敗」。以下請求用來檢視連線與 HTTP 回應，不是延遲或速度測試。

curl -I --connect-timeout 10 \
  --proxy http://127.0.0.1:7890 https://example.com

curl -I --connect-timeout 10 \
  --proxy socks5h://127.0.0.1:7890 https://example.com

socks5h 會讓 curl 將目標網域交由代理端解析；socks5 通常會先在用戶端解析網域。兩者可能採用不同的 DNS 路徑。使用最精簡設定時，請求仍會直連；換成包含節點與策略群組的設定後，請查看連線記錄，確認套用的規則與實際出口。

若要讓目前終端機中支援這些變數的程式使用代理，可以暫時設定：

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

# 只取消目前 Shell 的這些代理變數
unset http_proxy https_proxy all_proxy no_proxy

並非所有程式都會讀取相同的變數，systemd 服務也不會自動繼承互動式終端機中的 export。若其他背景服務需要使用代理，請個別設定該服務的環境，並評估排除本機資源的規則。

連接 Web 面板：控制連接埠只監聽回環位址

Web 面板是控制 API 的前端，不是代理核心。7890 用於轉發代理流量；以下範例中的 9090 則用來管理核心。兩者用途不同，請勿將 9090 設為瀏覽器的 HTTP 代理。

產生控制密鑰並啟用 API

以下命令需要系統已安裝 OpenSSL，而且目前設定中沒有同名的 external-controller 或 secret 欄位。命令會在設定檔末尾加入監聽位址與隨機產生的密鑰。若這些欄位已存在，請編輯原有欄位，避免重複設定鍵。

sudo sh -c '
set -eu
key=$(openssl rand -hex 24)
printf "\nexternal-controller: 127.0.0.1:9090\nsecret: \"%s\"\n" "$key" >> /etc/mihomo/config.yaml
'

sudo -u mihomo /usr/local/bin/mihomo -t \
  -d /var/lib/mihomo -f /etc/mihomo/config.yaml
sudo systemctl restart mihomo
sudo ss -lntp 'sport = :9090'

密鑰屬於管理憑證，不應貼到公開記錄或截圖中。面板連線參數請填入 http://127.0.0.1:9090 和剛產生的密鑰。即使只綁定回環位址，也應保留驗證機制，因為主機上的其他本機程序仍可能存取此連接埠。

託管本機靜態面板

取得與目前核心 API 相容的面板靜態建置檔，解壓縮至 /var/lib/mihomo/ui，確認該目錄下直接包含 index.html，並讓 mihomo 帳戶具備讀取權限。接著在 YAML 頂層加入以下設定，檢查通過後重新啟動：

external-ui: /var/lib/mihomo/ui

在本機瀏覽器開啟 http://127.0.0.1:9090/ui/。如果面板還要求填寫後端位址與密鑰，請使用前述控制 API 參數。只下載面板原始碼、沒有取得建置檔，或檔案多包了一層目錄，都可能造成頁面無法載入。

遠端伺服器建議使用 SSH 本機連接埠轉送。以下命令中的 proxy-host 是已在本機 SSH 設定中建立的伺服器別名，請先將該別名設定為實際主機：

ssh -N -L 19090:127.0.0.1:9090 proxy-host

建立通道後，在本機開啟 http://127.0.0.1:19090/ui/，面板後端也填入本機的 19090 位址。伺服器端仍維持回環監聽，不需要將控制連接埠開放至公網。通道不能取代 API 密鑰驗證，兩層防護各自生效。

常見問題排查：從架構、連接埠、權限與設定著手

桌面用戶端與獨立服務同時執行時，也要確認「目前連線的是哪個核心」。兩個執行個體使用不同連接埠即可並存，但用戶端顯示的節點選擇不會自動影響另一個服務的策略。日常使用時，建議明確指定主要執行個體，避免在錯誤的面板中修改設定。

判斷部署是否完成，可分四個層次檢查：程序持續運作、連接埠依預期監聽、應用程式確實使用該連接埠，以及連線套用預期的規則與節點。依照這個順序檢查，比直接切換 TUN、關閉防火牆或反覆重新安裝更容易找出問題。設定結構與規則順序可參考Clash 設定說明。