Linux mihomo 核心部署：桌面用戶端與 systemd 命令列教學

先選擇部署方式：桌面用戶端或獨立服務

如果使用桌面環境，且經常需要切換策略組，建議選擇圖形介面的 Clash 用戶端；若透過 SSH 管理伺服器，或需要在登出後持續執行，則可使用 mihomo 搭配 systemd。mihomo 是 Clash Meta 路線的 Proxy 核心，沒有完整的桌面操作介面；下載核心執行檔不代表已安裝圖形用戶端。

桌面部署：安裝、匯入與驗證

確認架構與安裝檔格式

先執行 uname -m。常見的 x86_64 對應 amd64 架構，aarch64 則對應 arm64；兩者不能只因為都是「64 位元」就互換。Debian、Ubuntu 通常選用用戶端提供的 DEB 套件，Fedora 等系統通常選用 RPM 套件。AppImage 是否需要額外執行相依套件，請以用戶端說明為準。

前往用戶端下載頁選擇 Linux 平台，再確認架構與安裝檔格式。以下以已儲存至目前目錄的 DEB 安裝套件為例，可在檔案管理員中開啟，也可以執行 sudo apt install ./ 並接上實際檔名進行安裝。請勿將獨立核心壓縮檔當成 DEB 套件交給套件管理工具。

依功能檢查介面

1. 設定頁：匯入訂閱連結或本機 YAML，完成後將目標設定設為目前使用的設定。連結可能含有存取憑證，請勿貼到公開日誌中。
2. 代理頁：將模式設為規則模式，再確認規則所使用的策略組已選取可用代理。匯入成功不代表策略組已正確選取。
3. 設定頁：查看實際混合連接埠，確認是否為 7890，再視需要啟用系統代理。用戶端介面可能會將此頁稱為「設定」或「網路設定」，請以目前版本顯示為準。
4. 日誌頁：送出一次請求，確認是否出現設定解析、連接埠繫結或上游連線錯誤。請勿只憑系統匣圖示判斷流量走向。

桌面系統代理只會影響有讀取該設定的程式。終端機中的 curl、部分開發工具及背景服務不一定會跟隨，因此下文會另外設定終端機環境變數。若已選擇桌面部署方式，可直接閱讀驗證與疑難排解部分；無須重複執行獨立服務的安裝步驟。

命令列部署：固定執行檔與設定目錄

以下命令適用於使用 systemd 的 Debian、Ubuntu 等系統，並假設目前帳戶具有 sudo 權限。容器、精簡版發行套件或 WSL 環境不一定使用 systemd 作為初始化系統，請先執行 ps -p 1 -o comm=；若輸出不是 systemd，就不能直接照用服務管理命令。

安裝執行檔

從專案發布管道取得符合架構與 CPU 需求的 Linux 核心套件，解壓縮後將執行檔命名為 mihomo，並放在目前目錄。以下命令不會下載檔案；安裝前請確認目前目錄中的檔案就是要使用的核心。

uname -m
ps -p 1 -o comm=
sudo install -m 0755 ./mihomo /usr/local/bin/mihomo
/usr/local/bin/mihomo -v

-v 顯示的是實際安裝的版本。建議將輸出與部署紀錄一併保存，以便日後排查設定欄位的相容性；請勿根據用戶端視窗顯示的版本號推測核心版本。

建立專用帳戶與目錄

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

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

• /usr/local/bin/mihomo：程式檔案由 root 管理，服務帳戶無法覆寫。
• /etc/mihomo/config.yaml：主設定檔由管理員編輯，服務帳戶只需要讀取權限。
• /var/lib/mihomo：執行資料目錄，用來存放快取及依設定需要儲存的資源。

帳戶只需建立一次；如果系統提示使用者已存在，請先確認現有帳戶的用途，不要刪除後重新建立。若設定中的 provider、規則集或資料庫使用相對路徑，請搭配 -d 指定的資料目錄確認實際位置，不要假設路徑一律相對於主設定檔。

先以最精簡設定確認服務可正常執行

初次部署時，先確認「程式能啟動、設定可讀取、連接埠可監聽」，再匯入實際訂閱。以下是用於啟動測試的直連設定，不含遠端代理；即使請求成功，也只能證明本機代理入口正常，不能證明流量已透過代理節點連線。

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 會在同一個連接埠接受 HTTP 與 SOCKS 代理連線；allow-lan: false 將服務限制為僅供本機使用。mode: rule 會依規則順序處理連線，本例最後的 MATCH,DIRECT 會讓所有請求直接連線。-t 用來檢查設定，不會讓服務持續在背景執行。

換成實際代理設定時，請檢查以下三處

1. 訂閱格式：核心的 -f 會讀取設定檔，不會直接接收訂閱 URL。只有節點清單，也不等於包含通用欄位、策略組和規則的完整設定。
2. 引用名稱：rules 引用的策略組必須存在，而策略組引用的節點或 provider 也必須能夠正常解析。
3. 資源權限：需要下載或更新的 provider、規則集應存放在服務帳戶可寫入的資料目錄，而非只有讀取權限的 /etc/mihomo。

建立 systemd 服務並啟用開機自動啟動

將下列內容儲存為 /etc/systemd/system/mihomo.service。服務使用一般專用帳戶，適用於本文的本機明確代理設定。StateDirectory 負責管理執行資料目錄，ProtectSystem=strict 則會限制檔案系統的寫入範圍。

[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

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo.service
systemctl is-enabled mihomo.service
systemctl is-active mihomo.service
sudo systemctl status mihomo.service --no-pager -l
sudo journalctl -u mihomo.service -b -n 80 --no-pager

enable 會設定為隨系統開機啟動，--now 則會同時立即啟動服務。network-online.target 實際等待網路就緒的方式取決於系統的網路管理服務，並不保證所有遠端位址都已可連線。若下載網路資源失敗，請查看日誌判斷是名稱解析、連線還是權限問題。

修改服務檔案後，必須先執行 daemon-reload 再重新啟動；若只修改 YAML，先執行前述的 -t 檢查，確認成功後執行 sudo systemctl restart mihomo.service 即可。本服務未定義 ExecReload，請勿將 systemctl reload 當成已設定的熱重載功能。

終端機代理：先明確測試，再設定變數

確認本機代理入口正在監聽

sudo ss -lntp 'sport = :7890'
curl --noproxy "" --proxy http://127.0.0.1:7890 \
  --connect-timeout 10 --max-time 30 \
  -I https://clash03.com/

第一個命令會檢查 TCP 監聽狀態，預期本機位址為 127.0.0.1:7890，而非對所有網路介面開放的 0.0.0.0:7890。第二個命令會明確指定代理，避免先前設定的環境變數干擾測試；它不會保證延遲或出口位置。使用最精簡的直連設定時，流量仍會直接連至目標網站。

為目前的 shell 設定代理

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://clash03.com/

https_proxy 的值仍是 http://，表示透過本機 HTTP 代理建立 HTTPS 連線，不代表本機代理入口需要使用 TLS。支援此格式的程式可使用 socks5h://，將目標主機名稱交由 SOCKS 代理端解析；若程式優先讀取 http_proxy 或 https_proxy，就不一定會使用 all_proxy。

這些變數只會影響目前的 shell 及之後啟動的子程序，不會自動套用至已執行的瀏覽器、其他登入工作階段或系統層級服務。若要保留設定，可依使用的 shell 寫入 ~/.bashrc 或 ~/.zshrc；不要只為了單一程式，就將代理變數寫入所有系統服務的環境設定。

unset http_proxy https_proxy all_proxy no_proxy
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY

清除變數後，新啟動的命令就不會再從這些變數讀取代理設定。sudo 預設可能會過濾環境變數，Git、套件管理工具等也可能有自己的代理設定。若遇到「curl 可以用，其他命令不行」，請分別檢查各工具的設定，不要立刻更換節點。

常見問題：分別檢查程序、設定與連線

服務不斷重新啟動

先執行 sudo systemctl stop mihomo.service，避免日誌持續大量輸出；使用相同的服務帳戶執行 -t 檢查，再查看這次啟動的日誌。若失敗次數觸發 systemd 啟動限制，請修正原因後執行 sudo systemctl reset-failed mihomo.service，再重新啟動。不要只增加重試次數來掩蓋 YAML 錯誤。

服務正常，但終端機無法連線

先確認 curl 指向的位址是否與 mixed-port 一致。若將連接埠從 7890 改為 7891，系統代理、終端機變數及應用程式自己的代理設定都必須同步更新。若從另一台電腦連線，127.0.0.1 指的是那台電腦本身，而不是執行 mihomo 的主機。

此服務不包含 TUN 所需的權限

TUN 會透過虛擬網路裝置與路由接管流量，和設定 HTTP 代理變數是不同機制。它涉及 /dev/net/tun、網路管理權限、路由與 DNS 設定；本文的服務刻意不授予這些權限。只將 tun.enable 改為 true，不代表 TUN 就能正常運作。若需要 TUN，請依照對應用戶端或核心文件，另外規劃權限與路由，並確認不會與其他 VPN 衝突。

更新與回復：保留可正常運作的設定

1. 更新前記錄 mihomo -v 的輸出，並備份主設定檔與目前的程式檔案。備份若含有訂閱資訊，請設定嚴格的存取權限。
2. 先將新版程式放在暫存位置，使用新版程式對現有設定執行 -t。檢查通過只代表設定可解析，仍須確認實際啟動狀況。
3. 停止服務後再替換程式，保留程式檔案的 root 擁有者與執行權限，然後重新啟動服務。
4. 檢查 systemctl is-active、最新日誌及一次明確指定代理的請求；若出現異常，請還原舊版程式與原設定後重新啟動。

部署完成須同時符合三項條件：服務狀態正常、本機連接埠符合預期，以及實際請求使用預期策略。桌面用戶端適合互動式管理，systemd 則適合固定路徑與長時間執行；無論選擇哪種方式，都應清楚管理設定檔位置、代理入口與更新流程，避免多個核心同時執行，卻無法判斷流量由哪個核心處理。欄位細節請參閱完整設定手冊；首次匯入設定可參考快速入門。