Linux mihomo 部署指南：安裝圖形用戶端與設定 systemd 無介面執行

先選部署方式：圖形用戶端或獨立核心

mihomo 是相容於 Clash 設定格式的代理核心，常見於標示為 Clash Meta 的設定檔與用戶端。核心負責監聽代理連接埠、比對規則及建立連線；圖形用戶端則另外提供訂閱管理、節點選擇與系統代理開關。只安裝核心不會自動出現系統匣圖示，也不會替瀏覽器修改代理設定。

使用情境	建議方式	主要管理方式
GNOME、KDE 等日常桌面環境	支援 Linux 的圖形用戶端	在介面中匯入訂閱、切換規則與節點
透過 SSH 管理的伺服器	mihomo 二進位檔搭配 systemd	編輯 YAML 設定檔、查看服務日誌
容器或精簡版發行版	先確認初始化系統	若 PID 1 不是 systemd，請改用相應的程序管理方式

本文的服務設定適用於使用 systemd 的一般 Linux 主機，並先建立僅供本機使用的明確代理。明確代理是指應用程式主動將要求傳送至指定連接埠；它不是透明代理，也不會自動接管伺服器上的所有連線。

桌面部署：安裝 Linux 用戶端並匯入設定

確認發行版與處理器架構

開啟終端機並執行以下兩個指令。第一個查看發行版，第二個查看核心回報的處理器架構。x86_64 通常對應安裝套件中的 x64 或 amd64；aarch64 通常對應 arm64。不要只因電腦使用 Intel 或 AMD 處理器，就下載 ARM 套件。

cat /etc/os-release
uname -m

前往安裝套件頁面，選擇提供 Linux 發行套件的用戶端，例如 Clash Verge Rev 或 FlClash。下載前請確認該版本支援的平台與處理器架構。
Debian、Ubuntu 系列建議選擇相應的 DEB 套件；Fedora 等發行版則選擇相應的 RPM 套件。AppImage 能否使用，取決於發行方是否有提供，以及本機是否具備 FUSE 等執行相依項目。
啟動用戶端，前往訂閱或設定管理頁面，新增訂閱 URL，更新後選取該設定檔。不同用戶端的選單可能稱為「訂閱」或「設定」；請勿將節點分享字串直接當成完整 YAML 檔案匯入。
先選擇規則模式與可用節點，再開啟系統代理。查看連線記錄，確認要求確實經過目前使用的用戶端。

以下以已下載至本機並重新命名為 client.deb 的安裝套件為例，可在所在目錄執行 sudo apt install ./client.deb。此檔名是使用者自行重新命名的結果，並非本站安裝套件的網址。RPM 套件也可同樣重新命名為 client.rpm，再執行 sudo dnf install ./client.rpm。

區分系統代理與終端機代理

在 GNOME 桌面環境中，可前往「設定」→「網路」→「網路代理」查看目前設定，實際位置會因桌面版本而略有不同。瀏覽器可能會沿用這些設定，但終端機中的命令列工具不一定會讀取。先確認用戶端顯示的混合連接埠；若為 7890，可用下文的 curl --proxy 個別測試，不必反覆切換系統代理。

桌面環境的「登入時啟動」與伺服器的「開機啟動」也不相同。前者通常要等使用者登入圖形工作階段才會執行；後者則可在無人登入時執行。若主機需要在 SSH 連線後立即提供代理，較適合採用下方的 systemd 設定方式。

伺服器準備：安裝二進位檔並建立隔離執行帳戶

先執行 ps -p 1 -o comm=，確認輸出為 systemd。接著依 uname -m 的結果取得相應的 mihomo Linux 二進位檔，解壓縮後將檔案重新命名為 mihomo。x86 版本可能還區分 CPU 指令集等級；若出現 Illegal instruction，應重新確認建置需求，而不是替程式增加權限。

以下指令假設目前終端機所在目錄已有解壓縮後的 mihomo 檔案。先賦予執行權限，再確認程式能否執行；-v 會顯示實際安裝的版本，方便日後記錄與復原。

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

這裡建立的是專用系統帳戶，不供互動式登入使用。若電腦上已存在 mihomo 帳戶，請先用 id mihomo 檢查帳戶與群組，再略過建立步驟。使用獨立帳戶能更容易控管設定檔的讀取權限與執行資料目錄；本方案不需要以 root 身分執行整個服務。

/usr/local/bin/mihomo：存放核心可執行檔。
/etc/mihomo/config.yaml：存放由管理員維護的設定檔。
/var/lib/mihomo：存放執行資料，後續會由 systemd 單元建立並設定權限。

先以最小化 YAML 設定檢查設定檔與連接埠

YAML 是以縮排排列欄位的文字設定格式。請使用空格縮排，不要使用 Tab。先用以下最小化設定建立啟動基準：只監聽本機的 7890 混合連接埠，同時接受 HTTP 代理與 SOCKS5 連線；所有要求都直接連線，不包含任何代理節點。

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 /tmp -f /etc/mihomo/config.yaml

設定檢查通過，不代表代理節點可用。 -t 用來檢查設定檔能否載入。此處的 MATCH,DIRECT 是預設直連規則，僅用於排除程式、權限與監聽設定問題；它不會讓要求經由遠端代理傳送。

需要實際分流時，再替換為可信來源提供的完整 mihomo 設定檔。完整設定通常包含 proxies、proxy-groups 和 rules；規則所引用的策略群組名稱必須存在。只有節點集合的 provider 檔案、Base64 節點字串和訂閱網頁，都不能當成可直接交給 -f 的完整設定檔。

替換設定檔後，請維持僅監聽本機的安全界線，並重新執行設定檢查。訂閱 URL 可能含有存取權杖，檔案中也可能包含節點憑證，請勿將其貼到公開日誌、截圖或 shell 歷史記錄中。若實際設定使用相對路徑，服務會以 /var/lib/mihomo 作為資料目錄；請一併確認規則檔案與 provider 檔案皆可讀取。

建立 systemd 服務並設定開機自動啟動

systemd 服務單元會定義程序的啟動方式、使用的帳戶，以及失敗後的處理方式。將以下內容寫入 /etc/systemd/system/mihomo.service。此單元適用於一般代理連接埠，不設定 TUN，也不授予網路管理權限。

sudo tee /etc/systemd/system/mihomo.service > /dev/null <<'UNIT'
[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
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=0077
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict

[Install]
WantedBy=multi-user.target
UNIT

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
systemctl status mihomo --no-pager
systemctl is-enabled mihomo

顯示 active (running) 代表程序正在執行；is-enabled 輸出 enabled 則代表已設定為開機啟動。兩者需分別確認：服務即使已設為開機啟動，也可能因設定錯誤而無法啟動。

StateDirectory=mihomo 會建立可寫入的資料目錄。ProtectSystem=strict 會限制對其他檔案系統的寫入，ProtectHome=true 則會限制存取使用者家目錄。因此，請勿讓設定檔引用 /home 下的訂閱檔案。若需要其他資源，請將它們放進合適的資料目錄，並確認檔案擁有者與權限。

network-online.target 用來表示網路就緒時的啟動順序，但實際效果仍取決於發行版是否啟用相應的等待網路服務；它不保證此刻能連上訂閱伺服器。若設定需要從遠端下載規則，請配合日誌判斷是等待網路的問題，還是遠端資源已失效。

修改設定後的操作順序

sudo -u mihomo /usr/local/bin/mihomo \
  -t -d /var/lib/mihomo -f /etc/mihomo/config.yaml
sudo systemctl restart mihomo
sudo journalctl -u mihomo -n 80 --no-pager

只有前一個設定檢查成功後，才執行重新啟動。修改 YAML 不需要執行 daemon-reload；只有修改服務單元時才需要。本範例未定義 ExecReload，因此請勿直接用 systemctl reload mihomo 取代重新啟動。重新啟動會中斷現有代理連線，請避開長時間下載或遠端作業期間。

驗證要求：監聽、HTTP 代理與 SOCKS5

依「程序執行 → 連接埠監聽 → 應用程式要求 → 規則命中」的順序排查。先查看 7890 連接埠；預期的監聽位址是 127.0.0.1:7890，而不是公網介面。

sudo ss -lntp 'sport = :7890'

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

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

這裡的 10 秒是連線逾時上限，20 秒則是整個要求的時間上限，並非效能測試結果。使用 socks5h 時，目標網域名稱會交由代理端解析；使用 socks5 時，通常由 curl 在本機解析，兩者會影響 DNS 問題的排查結果。

使用最小化設定時，要求成功只能證明本機代理連線與直連出口可用。換成實際設定後，還要檢查日誌中的規則與策略群組選擇，確認流量沒有命中 DIRECT。只看到 HTTP 狀態碼，無法證明要求使用了特定遠端節點。

僅讓目前終端機使用代理

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

curl -I --max-time 20 https://example.com

unset http_proxy https_proxy no_proxy

https_proxy 的值仍可使用 http://，表示用戶端會透過 HTTP 代理建立 CONNECT 通道，並非將目標 HTTPS 降級為明文。環境變數只會影響讀取這些變數的程式；已在執行中的 systemd 服務不會自動沿用目前終端機的設定。這裡使用小寫變數，也可避免部分工具對大寫 HTTP_PROXY 的特殊處理。

常見問題與部署限制

啟動失敗或不斷重新啟動

出現 203/EXEC：檢查 ExecStart 路徑、檔案執行權限與二進位檔架構。請勿將尚未解壓縮的壓縮檔放在執行路徑中。
出現 address already in use：使用 ss 找出占用 7890 的程序，常見原因是另一個桌面用戶端或舊版核心仍在執行。
出現 permission denied：確認設定檔的群組為 mihomo，並檢查路徑中的每一層目錄是否皆可進入；請勿直接將敏感設定檔改為所有使用者皆可讀取。
出現 YAML 解析錯誤：檢查縮排、冒號與清單層級，尤其留意從網頁複製時帶入的 Tab。通過 -t 檢查後再啟動。
觸發啟動頻率限制：先修復根本原因，再執行 sudo systemctl reset-failed mihomo 和 sudo systemctl start mihomo，不要只是不斷重新啟動。

訂閱更新、控制介面與 TUN

獨立核心不會自動沿用圖形用戶端的「訂閱更新」流程。完整遠端設定需要另外安排取得與替換；更新時應先下載至暫存檔、限制檔案權限、檢查語法，再取代目前設定。設定中的 proxy-providers 可依更新間隔刷新節點集合，但不代表整份主要設定也會同步更新。

本範例未啟用 external-controller，因此不會提供管理 API。若確實需要控制面板，請先規劃回環位址監聽、存取金鑰與 SSH 通道，勿將管理連接埠直接開放至公網。allow-lan: false 搭配本機監聽，也表示其他區域網路裝置無法直接透過這台伺服器使用代理。

TUN 是透過虛擬網卡接管流量的方式，還涉及 /dev/net/tun、路由、DNS 與網路權限。本文的普通帳戶與安全強化單元並非 TUN 部署設定，不能只新增一行 enable: true 就當作完成。透過 SSH 管理的伺服器尤其應先保留管理連線的直連路徑，再規劃透明代理接管方式。

升級與停止服務

升級前請記錄 mihomo -v 的輸出，並備份目前的二進位檔與設定檔。停止服務後再替換二進位檔，確認新檔案的架構、版本與設定相容性，最後啟動服務並重新驗證連接埠與要求。若要停止服務並取消開機自動啟動，執行以下指令即可；這不會刪除設定檔或執行資料。

sudo systemctl disable --now mihomo

最後驗收時應確認四項結果：設定檢查通過、服務正在執行、監聽位址符合預期，以及實際應用程式命中預期規則。桌面使用者應著重設定檔選擇與系統代理；伺服器使用者則應著重帳戶權限、服務日誌與可重複執行的啟動流程。