Linux 執行 mihomo 核心：命令列部署、設定檔目錄與 systemd 開機自動啟動

1. 部署範圍：先啟用本機代理，再考慮 TUN

本文以 Debian、Ubuntu 等採用 systemd 的 Linux 環境為例。你需要具備 sudo 權限，並安裝 gzip、curl、iproute2 和 CA 憑證。請先執行下列檢查，確認 PID 1 是 systemd；容器、部分 WSL 環境及其他初始化系統，不適用本文的服務管理步驟。

ps -p 1 -o comm=
uname -m
sudo apt update
sudo apt install gzip curl iproute2 ca-certificates

mihomo 是從 Clash Meta 演進而來的代理核心，並非具備視窗介面的桌面用戶端。核心負責讀取 YAML、建立代理連線及比對規則；桌面選單、訂閱管理介面和系統代理切換功能，並不會由這個執行檔自動提供。

• 本機應用程式連線位址：本文使用 127.0.0.1:7890，同一個 mixed 連接埠可接收 HTTP 代理和 SOCKS5 要求。
• 服務權限：使用專用的非登入使用者，不為一般代理連接埠授予 root 權限。
• 流量接管範圍：先確認明確指定代理的連線正常；本文不設定透明代理、防火牆轉送或 TUN 虛擬網卡。

2. 選擇執行檔：確認架構、解壓縮並安裝

先查看 uname -m 的輸出，再到下載頁面選擇適用的 Linux 核心檔案。請勿把用戶端的 DEB、RPM 安裝套件當成獨立核心壓縮檔，也不要只憑裝置品牌判斷處理器架構。

以下步驟假設已將下載的 .gz 核心壓縮檔存放在目前使用者的 Downloads 目錄，並在本機重新命名為 mihomo.gz。這是操作時使用的本機檔名，不代表發行套件的原始名稱。如果下載的是未壓縮的執行檔，請略過 gzip 解壓縮步驟。

gzip -dc "$HOME/Downloads/mihomo.gz" > "$HOME/Downloads/mihomo"
chmod 0755 "$HOME/Downloads/mihomo"
"$HOME/Downloads/mihomo" -v
sudo install -m 0755 "$HOME/Downloads/mihomo" /usr/local/bin/mihomo
/usr/local/bin/mihomo -v

版本指令應顯示該檔案本身的版本資訊。若出現 Exec format error，請優先確認 CPU 架構與檔案是否已解壓縮；若出現 Illegal instruction，請檢查是否選到需要較新指令集的版本。這兩類錯誤都不應靠一再加上 sudo 解決。

3. 規劃目錄：設定檔放在 /etc，執行資料放在 /var/lib

固定目錄可避免手動從終端機啟動與 systemd 啟動時讀取不同檔案。本文會明確使用 -f 指定設定檔，並以 -d 指定資料目錄，不依賴目前登入使用者的預設設定路徑。

首次部署時建立服務帳號和目錄。如果系統已存在同名帳號，請先檢查 id 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

訂閱檔案可能包含伺服器位址、密碼和存取權杖。請勿將檔案存放在公開網站目錄，也不要原封不動貼到客服單。規則提供者或代理提供者的相對路徑通常以資料目錄為基準，建議使用 ./rules/、./providers/ 等資料目錄內的路徑，並確認服務帳號具有寫入權限。

4. config.yaml：先確認監聽狀態，再匯入實際設定

最小設定只用來確認啟動流程

以下 YAML 不包含代理節點，所有要求最後都會透過 DIRECT 直連。這份設定只能用來確認核心、檔案權限和本機連接埠是否正常，無法證明遠端代理可用。先建立這個基準，再匯入完整設定，方便區分部署問題與訂閱問題。

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

proxies: []
proxy-groups: []
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

-t 用於檢查設定檔。檢查通過後，再以前景模式執行一次。另開一個終端機執行後文的 curl 測試；完成後按 Ctrl+C 結束，避免前景程序與 systemd 服務爭用連接埠。

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

完整訂閱內容須包含節點與策略定義

請透過服務供應商提供的 mihomo 或 Clash Meta 設定入口取得完整 YAML，並另存至本機的 Downloads/config.yaml。只有一組節點 URI、Base64 文字或網頁內容，無法直接作為主要設定檔執行。只包含 proxies 的節點清單，也不等於包含規則與策略群組的完整主要設定檔。

sudo cp -a /etc/mihomo/config.yaml /etc/mihomo/config.yaml.bak
sudo install -o root -g mihomo -m 0640 \
  "$HOME/Downloads/config.yaml" /etc/mihomo/config.yaml

sudoedit /etc/mihomo/config.yaml

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

• 請在編輯器中確認頂層設定包含 mixed-port: 7890、allow-lan: false 和 bind-address: 127.0.0.1。若已有同名鍵，請修改原值，不要重複新增。
• 首次部署時，請先停用設定中的 tun.enable。如果啟用了監聽 53 連接埠的 DNS 服務，也應先停用或另行規劃權限；本文的服務單元不會提供這些權限。
• 請檢查 rules 引用的策略名稱，確認它確實存在於 proxy-groups 或節點清單中。YAML 縮排請使用空格，不要使用 Tab。
• 首次啟動時，可先移除非必要的控制介面設定。若需要外部控制器，請綁定回環位址並設定存取金鑰，不要直接公開至網際網路。

5. systemd 服務：固定使用者、路徑與啟動參數

確認前景程序已結束，再建立服務檔案。這裡使用絕對路徑，避免 systemd 的環境變數與互動式終端機不同而找不到程式。network-online.target 只代表系統的網路就緒流程完成，不保證訂閱網址或遠端節點已可連線。

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=0077
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target
UNIT

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
sudo journalctl -u mihomo.service -b -n 80 --no-pager

enable --now 會同時設定開機自動啟動並立即啟動服務。is-enabled 應顯示 enabled，is-active 則應顯示 active。這些結果只能確認程序狀態；代理是否能連上目標，仍須依下一節進行驗證。

分開處理設定檔與服務檔案的修改

• 只修改 YAML：先執行完整的 mihomo -t 設定檢查指令，確認通過後再執行 sudo systemctl restart mihomo。
• 修改 service：先執行 sudo systemctl daemon-reload，再重新啟動服務。
• 暫時停止：執行 sudo systemctl stop mihomo，不會取消下次開機時自動啟動。
• 取消開機自動啟動並停止：執行 sudo systemctl disable --now mihomo。

這項服務未定義 ExecReload，請勿假設 systemctl reload mihomo 可以使用。先檢查設定再重新啟動，流程較為明確；重新啟動會中斷現有連線，請避開正在進行的下載和遠端工作階段。

6. 連線驗證：分層檢查監聽、HTTP 與 SOCKS5

先檢查連接埠，再測試要求。使用 -q 避免使用者的 curl 設定檔影響結果，並使用 --noproxy "" 避免既有的略過代理清單跳過本次測試。以下網址僅用於示範要求流程，不適合作為節點速度測試基準。

sudo ss -lntp | grep ':7890'

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

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

socks5h 會將目標網域交由代理端解析；這與由 curl 在本機解析目標網域的 socks5 不同。使用 mihomo 時，實際的解析路徑也會受到核心 DNS 設定影響，不能只憑這個參數推斷所有 DNS 流量的出口。

• 連線遭拒：確認核心是否正在執行、連接埠是否一致，以及是否只監聽其他位址。
• 代理已連線但目標逾時：檢查實際套用的規則、所選策略和節點，不要繼續修改本機監聽連接埠。
• 使用最小設定時要求成功：這只表示明確指定的代理入口可用，流量仍會直接連線。
• 驗證實際節點：使用完整設定時，請查看 journalctl -u mihomo -f，確認該要求套用的規則與輸出策略。不要把 HTTP CONNECT 通道建立的訊息當成目標網站已成功回應。

7. 桌面與終端機：分別設定代理

GNOME 桌面設定

在 GNOME 中開啟「設定」→「網路」→「網路代理」，並選擇「手動」。HTTP 和 HTTPS 代理的主機都填入 127.0.0.1、連接埠填入 7890；SOCKS 主機也可使用相同位址與連接埠。HTTPS 欄位是為 HTTPS 目標指定代理，不代表本機連接埠本身需要提供 TLS。

也可以在目前桌面使用者的終端機執行下列指令來設定 GNOME。請勿加上 sudo，否則可能會修改 root 使用者的設定，或無法存取目前使用者的工作階段匯流排。

gsettings set org.gnome.system.proxy.http host '127.0.0.1'
gsettings set org.gnome.system.proxy.http port 7890
gsettings set org.gnome.system.proxy.https host '127.0.0.1'
gsettings set org.gnome.system.proxy.https port 7890
gsettings set org.gnome.system.proxy.socks host '127.0.0.1'
gsettings set org.gnome.system.proxy.socks port 7890
gsettings set org.gnome.system.proxy ignore-hosts "['localhost', '127.0.0.0/8', '::1']"
gsettings set org.gnome.system.proxy mode 'manual'

目前終端機的環境變數

桌面代理設定不保證終端機程式會自動採用相同設定。若命令列工具支援代理環境變數，可在目前的 shell 設定以下值。變數只會影響之後啟動的程式；不同工具對大小寫變數、SOCKS 和略過清單的支援可能有所不同。

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

如果瀏覽器手動指定了其他代理，請改用系統代理，或直接設為上述連接埠。容器和虛擬機器中的 127.0.0.1 指向自身，而非主機；本文採用的回環監聽設定不會直接提供這些環境所需的連線入口。

8. 常見錯誤與復原步驟

更新設定後若無法啟動，請先查看日誌中的第一則有效錯誤。如果確認是這次修改 YAML 所致，可還原先前保留的副本，再進行檢查並重新啟動。本文一開始保留的是直連基準設定，還原後不會恢復實際代理節點。

sudo cp -a /etc/mihomo/config.yaml.bak /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

停用服務前，請先將應用程式的連線方式切回直連。GNOME 和目前終端機可分別依照下列方式取消設定。如果先前已將變數寫入 shell 啟動檔案，也請刪除相應的設定行，並重新開啟終端機。

gsettings set org.gnome.system.proxy mode 'none'
unset http_proxy https_proxy all_proxy no_proxy
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY
sudo systemctl disable --now mihomo

最後請依序確認：執行檔可正常執行、服務帳號可讀取設定檔、設定檢查通過、7890 正常監聽、指定代理的要求成功、日誌顯示預期策略，以及系統重新啟動後服務恢復。逐層確認，才能分辨部署、設定、應用程式連線入口與遠端連線問題。