Linux 部署 mihomo 教學：桌面客戶端與 systemd 無介面服務

1. 桌面使用圖形客戶端，伺服器交由 systemd 管理

在 Linux 上執行代理服務，常見做法有兩種。若有桌面環境，且需要從系統匣切換節點，可安裝整合 mihomo 核心的圖形客戶端；若只有 SSH 終端，並希望登出後服務仍持續運作，則可直接部署 mihomo 核心，交由 systemd 管理。兩種方式使用相同的設定概念，但設定檔目錄、訂閱更新與權限管理方式各不相同。

ClashX 是 macOS 客戶端，並非 Linux 安裝套件。Linux 桌面使用者可依發行版選擇 Clash Verge Rev、FlClash 等客戶端的相容套件。伺服器不必為了使用代理而安裝桌面環境，也無須執行圖形客戶端視窗程序。

2. 在 Linux 桌面安裝並匯入設定

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

先執行以下命令確認系統資訊。x86_64 通常對應 amd64 / x64 套件，aarch64 通常對應 arm64 套件，兩者不可混用。Ubuntu、Debian 通常選 DEB，Fedora 通常選 RPM。發行版版本也會影響系統函式庫相容性，安裝前請先閱讀所選客戶端的最新發行說明。

uname -m
cat /etc/os-release

1. 前往安裝套件下載頁，選擇 Linux，再依處理器架構與套件格式下載客戶端。
2. 在檔案管理員中開啟下載的 DEB 或 RPM 檔案，使用系統的軟體安裝工具完成安裝。若相依套件解析失敗，請先處理套件管理員回報的問題，不要強制忽略。
3. 啟動客戶端，在「設定檔」或「Profiles」頁面匯入訂閱網址或本機 YAML 檔。選單名稱會因客戶端與版本而異，請以實際介面為準。
4. 選取已匯入的設定檔，確認節點清單與策略群組均已載入，再前往「設定」查看代理連接埠，確認實際監聽的連接埠。
5. 先使用下方的明確指定代理命令進行測試，再考慮啟用客戶端的「系統代理」選項。

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

此處的 7890 是本文範例值，並非所有客戶端都使用這個連接埠。收到 HTTP 回應代表請求連線已建立，但不能只憑成功回應判斷流量是否經過特定遠端節點；若規則套用到 DIRECT，請求仍會直接連線。請一併查看連線記錄中的規則、策略群組與出口節點。

桌面自動啟動不等於系統服務

客戶端的「開機啟動」通常依賴桌面工作階段，實際上往往是在使用者登入桌面後才啟動。伺服器重新開機後若沒有使用者登入，這種方式不適合用來執行背景代理。也不要讓圖形客戶端與下文的 systemd 服務同時占用 127.0.0.1:7890；請擇一使用，或明確設定不同的連接埠。

3. 安裝 mihomo 核心並放置設定檔

以下步驟適用於使用 systemd 的 Linux 系統，命令由具備 sudo 權限的一般使用者執行。範例使用 Debian / Ubuntu 常見的系統工具；其他發行版若沒有 useradd 等命令，請先透過該發行版的套件管理員安裝相應工具。容器與部分精簡系統可能未提供 systemd，無法直接套用本節的服務設定。

安裝執行檔

請從 mihomo 專案的官方發行頁，選擇符合處理器架構與 CPU 指令集需求的 Linux 版本；解壓縮後將執行檔放到 /tmp/mihomo。檔名請以實際下載內容為準，不可將壓縮檔直接當成執行檔。舊款 CPU 不要貿然選用需要較新指令集的版本。

file /tmp/mihomo
sudo install -m 0755 /tmp/mihomo /usr/local/bin/mihomo
/usr/local/bin/mihomo -v

-v 可用來確認實際核心版本。若出現 Exec format error，請先確認 CPU 架構；若出現 Illegal instruction，請檢查所選版本的指令集需求。本文不會將特定版本號寫入服務檔，日後升級仍可沿用相同安裝路徑。

建立專用帳號與目錄

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

若帳號已存在，請略過建立步驟並確認其使用者群組；若發行版的 nologin 位於其他路徑，請先執行 command -v nologin 確認，再調整路徑。設定檔放在 /etc/mihomo，快取與執行資料放在 /var/lib/mihomo。服務帳號只需讀取設定檔，無須修改存放訂閱憑證的檔案。

先以最精簡的設定檔驗證程序

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

匯入服務商提供的設定時，請先確認取得的是 mihomo 可讀取的 YAML，而不是網頁、登入提示或只包含節點 URI 的文字。替換設定檔後，請重新檢查監聽位址、控制連接埠與規則末尾的預設策略。訂閱中的設定可能會覆寫本文對本機監聽位址的限制。

-t 用來檢查設定，不代表遠端節點、規則下載網址或目標網站一定可連線。檢查期間也可能會讀取設定引用的資料檔。若檢查失敗，請閱讀詳細記錄，區分 YAML 語法錯誤、路徑權限錯誤與資源讀取錯誤。

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

先以非 root 帳號執行一般代理服務。監聽 7890 這類高連接埠不需要 root 權限。下方服務未設定 TUN 權限，適用於明確指定的 HTTP / SOCKS 代理，不適合直接做為透明閘道。

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
WorkingDirectory=/var/lib/mihomo
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
UNIT

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

enable --now 會同時設定開機啟動並立即啟動服務。network-online.target 實際等待效果取決於發行版是否設定相應的網路等待服務；即使等待完成，也不代表網際網路或訂閱網址已可連線。遠端資源應安排適當的重試與更新機制。

• 修改 config.yaml：先檢查設定，再執行 sudo systemctl restart mihomo。
• 修改服務單元檔：先執行 sudo systemctl daemon-reload，再重新啟動服務。
• 只查看狀態：執行 systemctl is-active mihomo 與 systemctl is-enabled mihomo。
• 停止服務並取消開機啟動：執行 sudo systemctl disable --now mihomo。

這份服務單元沒有設定 ExecReload，因此不要將 systemctl reload mihomo 當成通用的更新命令。使用重新啟動最容易確認新設定是否載入，但可能會中斷現有連線。若需要平滑更新，請依照目前核心的控制 API 文件另行規劃流程。

5. 驗證連接埠、代理連線與應用程式行為

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/

混合連接埠可接收 HTTP 代理與 SOCKS 代理請求。上方的 socks5h 會將目標網域名稱交由代理端解析；socks5 通常則會先在本機解析目標網域名稱。兩者會影響 DNS 問題的排查結果，不能因為使用相同連接埠就認定行為完全相同。

僅讓目前 shell 中的部分程式使用代理

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

unset http_proxy https_proxy no_proxy

https_proxy 的值仍可使用 http://，表示透過 HTTP 代理建立 CONNECT 通道，並非要求本機代理連接埠本身提供 TLS。環境變數只會對讀取這些變數的程式及其子程序生效，不會自動套用至瀏覽器、其他 systemd 服務或所有 UDP 流量。

套件管理員、容器服務與背景服務可能有各自獨立的代理設定。在終端機中使用 curl 成功，不代表 Docker 映像檔下載或系統更新也已透過代理連線。請分別確認各程式的代理設定方式；也不要將含有憑證的代理變數寫入所有使用者都能讀取的檔案。

6. 透過 SSH 通道存取控制介面與面板

mihomo 的控制介面與代理連接埠用途不同。7890 用來接收代理請求，下方設定的 9090 則用於控制 API。伺服器面板建議透過 SSH 本機連接埠轉送存取，不要為了遠端管理而讓控制介面直接監聽公網位址。

啟用本機控制介面

以下命令以先前的最小設定為基礎，只需執行一次。若現有設定已包含 external-controller 或 secret，請編輯原有欄位，避免重複設定。命令會產生隨機密鑰並寫入權限受限的設定檔，不會在終端機顯示密鑰。

controller_secret=$(openssl rand -hex 32)

printf '\nexternal-controller: 127.0.0.1:9090\nsecret: "%s"\n' \
  "$controller_secret" | \
  sudo tee -a /etc/mihomo/config.yaml > /dev/null

unset controller_secret

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

此步驟需要系統已安裝 OpenSSL。密鑰是控制憑證，輸入面板前可透過受控的管理終端查看設定檔中的 secret 欄位，請勿將整份設定檔貼到公開的支援工單。只啟用控制介面不會自動提供網頁面板。

部署面板靜態檔案

請從相容面板專案的正式發行套件取得已建置的靜態檔案，並將包含 index.html 的目錄內容放到 /etc/mihomo/ui。不要將尚未建置的原始碼目錄當成靜態頁面目錄，也不要多包一層資料夾，否則入口檔會位於錯誤路徑。

sudo install -d -o root -g mihomo -m 0750 /etc/mihomo/ui
sudoedit /etc/mihomo/config.yaml

在設定檔頂層加入以下欄位，並確認服務帳號可讀取面板目錄中的檔案：

external-ui: /etc/mihomo/ui

完成設定檢查後重新啟動服務。在本機電腦執行 SSH 命令，將本機的 9090 轉送至伺服器回送位址的 9090。下方的 mihomo-server 是自行在 SSH 設定中建立的主機別名，請換成實際可連線的主機名稱或已設定的別名。

ssh -N -L 127.0.0.1:9090:127.0.0.1:9090 mihomo-server

保持 SSH 工作階段連線，再於本機瀏覽器開啟 http://127.0.0.1:9090/ui/。面板後端填入 http://127.0.0.1:9090，密鑰則填入設定中的 secret。此處的本機位址是瀏覽器所在電腦的位址，透過 SSH 通道連到伺服器；不是讓瀏覽器直接連線至伺服器的回送位址。

7. TUN、訂閱更新與常見問題排查

啟用 TUN 不只是切換一個選項

Linux TUN 需要可用的 /dev/net/tun，通常也需要網路管理權限，並涉及自動路由、策略路由與 DNS 接管。本文的專用使用者服務未授予相關權限，直接加入 tun.enable: true 可能會因權限不足而失敗。不要一遇到問題就讓所有元件長期以 root 身分執行。

伺服器尤其需要保護 SSH 管理連線。錯誤的預設路由、DNS 劫持或代理迴圈都可能造成連線中斷。規劃啟用 TUN 時，請先準備雲端主控台或序列主控台等復原方式，確認目前核心文件中的權限需求，再分別規劃服務權限、路由排除與還原步驟。桌面客戶端提供的 TUN 服務模式，也不等同於這份一般代理服務單元。

訂閱更新需要另外管理

將完整訂閱 YAML 下載為 config.yaml，不代表核心會定期重新下載整份設定。圖形客戶端通常提供設定更新排程；無介面部署則應明確選擇使用完整設定更新腳本，或使用 proxy-providers 的 url、path 與 interval 更新節點提供者。

節點提供者檔案與完整設定檔的結構不同，不能將任意訂閱網址直接填入 provider。provider 快取路徑應設在服務可寫入的 /var/lib/mihomo。更新完整設定時，請先下載至暫存檔並檢查格式，再取代正式檔案；不要直接以網路下載內容覆寫唯一可用的設定檔。

升級與還原前檢查

升級前請保留舊版執行檔、設定檔與服務單元，並記錄 mihomo -v 的輸出。先使用新版執行檔對現有設定執行 -t，再安排替換與重新啟動。升級後依序確認服務狀態、7890 監聽狀況、明確指定代理的請求與面板連線；若失敗，請還原舊版執行檔與相容設定，不要接連修改多項網路設定。

部署完成的基本標準：系統重新啟動後服務狀態為 active、代理連接埠只監聽預期位址、應用程式能依規則送出請求，且控制介面只能透過受保護的管理通道存取。分別驗證這四項，比只確認程序正在執行更可靠。