Ubuntu 安裝 mihomo 核心：桌面用戶端與純命令列 systemd 部署

選擇部署方式：桌面用戶端或獨立核心

mihomo 是負責讀取 YAML 設定、比對代理規則並建立連線的核心，也常稱為 Clash Meta。桌面用戶端則在核心之外提供訂閱管理、策略組切換、系統代理與記錄檢視等功能。只安裝 mihomo 執行檔不會出現圖形介面，也不會自動變更 Ubuntu 桌面的網路代理設定。

以下指令適用於 Ubuntu 22.04 LTS、24.04 LTS 常見的 systemd 環境。容器、WSL 與受限 VPS 的裝置權限可能不同，尤其應另外確認是否支援 TUN。本文不指定核心版本；部署時請用 mihomo -v 記錄實際版本，升級後保留版本資訊，以便排查設定相容性。

同一台機器建議一次只採用一種方式執行。若同時啟動桌面用戶端內建核心與獨立的 systemd 服務，可能會搶用 7890 連接埠，或重複建立 TUN 路由。

安裝 Ubuntu 桌面用戶端並匯入設定

確認系統架構與安裝套件格式

先在終端機執行以下指令。x86_64 通常對應 amd64 套件，aarch64 通常對應 arm64 套件；不要只憑裝置品牌判斷架構。

uname -m
dpkg --print-architecture
lsb_release -ds

從用戶端下載頁選擇支援 Linux 的版本，例如 Clash Verge Rev，並確認其相依套件適用於目前的 Ubuntu 版本。Ubuntu 建議優先使用對應架構的 .deb 套件。進入下載目錄後，執行 sudo apt install ./ 並加上實際檔名，可按 Tab 鍵自動補齊；apt 會處理可用的軟體相依套件。AppImage 是另一種發行格式，是否需要 FUSE 相容套件請依該用戶端的發行說明判斷，勿將同一組相依套件指令套用於不同 Ubuntu 版本。

設定訂閱與系統代理，並在瀏覽器中測試

1. 開啟用戶端的設定檔或訂閱頁面，匯入可信任的訂閱網址或本機 YAML 檔。訂閱連結通常含有存取憑證，請勿放入公開截圖、問題回報或 Git 儲存庫。
2. 選取匯入的設定檔，在代理群組中選擇可用節點，並先使用 Rule（規則）模式。規則模式會依規則順序選擇流量出口，不代表所有流量都會經過代理。
3. 在用戶端設定中確認實際使用的 HTTP 或 mixed-port 連接埠，再啟用系統代理。用戶端可能會覆寫連接埠設定，請勿只查看訂閱檔中的數值。
4. 開啟瀏覽器前往目標網站，並在用戶端的連線記錄中確認套用的規則、策略組與出口。

如需手動設定 GNOME 代理，可在 Ubuntu「設定」→「網路」→「網路代理」中選擇手動設定。假設本機 mixed-port 為 7890，HTTP 與 HTTPS 代理主機都填入 127.0.0.1，連接埠都填入 7890。此處的 HTTPS 代理欄位代表 HTTPS 要使用的代理端點，並不表示本機連接埠本身必須提供 TLS。

桌面系統代理只會影響遵循該設定的程式。終端機工具、容器及部分應用程式不會自動採用 GNOME 的代理設定。用戶端的設定目錄也不一定是 ~/.config/mihomo：請優先使用用戶端的「開啟設定目錄」功能，分清原始訂閱、合併範本與執行時設定，避免修改下次更新訂閱時會被覆寫的檔案。

命令列部署：執行檔與目錄權限

伺服器部署方式會將執行檔放在 /usr/local/bin/mihomo，設定檔放在 /etc/mihomo/config.yaml，執行資料則放在 /var/lib/mihomo。如此可限制寫入權限，也能避免服務的工作目錄隨登入使用者而改變。

安裝核心並建立服務帳號

取得符合 CPU 架構的官方發行版執行檔；如果下載的是 gzip 壓縮檔，請先解壓縮。以下假設解壓後的檔案已放至 /tmp/mihomo，且必須是可執行檔，不能是壓縮檔或下載失敗後取得的 HTML 網頁。請勿在舊款 CPU 上強行執行不相容的指令集版本。

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

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

建立帳號的指令只需執行一次；若已存在同名帳號，請先用 id mihomo 確認用途，不要直接變更既有服務的執行身分。設定檔由 root 擁有，mihomo 群組可讀取；執行資料目錄則允許服務帳號寫入，以供快取及必要的規則、資料庫等檔案使用。

建立可啟動的最小設定

使用 sudoedit /etc/mihomo/config.yaml 寫入以下內容。此設定只用於測試本機監聽與規則處理，所有連線都會 DIRECT 直連，不具備遠端代理功能。實際使用時，請改用可信且完整的設定，加入有效節點、策略組與規則，而非只貼上訂閱網址。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false

rules:
  - MATCH,DIRECT

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

-f 用來明確指定設定檔，-d 指定執行資料目錄，-t 則執行設定檢查。檢查通過只表示目前的核心可接受這份設定，無法證明節點連線正常或規則符合預期。完整設定若引用外部規則集、Geo 資料或本機檔案，也請確認路徑、下載條件及服務帳號的讀取權限。

設定 systemd 服務並啟用開機自動啟動

使用 sudoedit /etc/systemd/system/mihomo.service 建立服務。以下設定適用於一般本機代理模式，暫不授予建立網路裝置的權限。以獨立帳號執行服務，即可避免僅為監聽 7890 等非特權連接埠而使用 root。

[Unit]
Description=mihomo proxy core
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
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/mihomo

[Install]
WantedBy=multi-user.target

ProtectSystem=strict 會限制服務對檔案系統的寫入權限，只有明確指定的執行資料目錄可寫入。需要持續更新的 provider 檔案請勿放在 /etc/mihomo 下；可在設定中改用 /var/lib/mihomo 內的路徑。network-online.target 實際等待網路就緒的方式取決於系統的網路管理服務，並不保證外部訂閱伺服器已可連線。

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)，且本機代理已開始監聽。若記錄出現 address already in use，請先找出占用連接埠的桌面用戶端或舊程序。不要先強制結束程序，也不要直接改成監聽所有網路介面來嘗試解決。

在終端機測試並更新設定

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

此指令會明確指定代理位址，方便判斷問題是「程式未使用代理」還是「代理核心處理失敗」。使用本文的最小設定時，請求仍會由本機直接連線至目標網站；換成實際設定後，應搭配記錄確認流量出口，不能只憑 HTTP 回應碼判定節點是否生效。

修改 YAML 後，請先重新執行含 -t 的檢查，再執行 sudo systemctl restart mihomo。此服務未設定 ExecReload，因此不要假設 systemctl reload 會有效。只有修改 unit 或 drop-in 時，才需要額外執行 daemon-reload。重新啟動可能中斷既有連線，請在伺服器上選擇合適時段操作。

TUN 模式：裝置、權限與 DNS 接管

TUN 會建立虛擬網路介面，適合接管不遵循系統代理設定的應用程式流量。它不是一般 HTTP 代理連接埠的別稱，也不會自動讓 Ubuntu 伺服器成為區域網路閘道器。要轉發閘道流量，還須設定 IP 轉送、防火牆及其他裝置的路由，這些不屬於本機流量接管設定。

確認 TUN 裝置可用

ls -l /dev/net/tun
sudo modprobe tun

如果裝置不存在且載入模組失敗，請確認主機是否提供 TUN；容器環境通常還需要由主機傳入裝置並授予網路管理權限。不要將 /dev/net/tun 設為所有使用者皆可寫入，藉此取代服務權限設定。

為非 root 服務授予網路權限

執行 sudo systemctl edit mihomo，並加入以下 drop-in 設定。CAP_NET_ADMIN 用於操作網路介面與路由，CAP_NET_RAW 則支援相關原始通訊端操作。只有確實需要 TUN 的服務才應取得這些權限。

[Service]
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW

這裡由 systemd 在程序啟動時授予權限，不必再對執行檔執行 setcap。本文的基本 unit 未啟用 PrivateDevices=true；如果自行加入裝置隔離或裝置存取白名單，務必確認服務仍可存取 /dev/net/tun。

整合 TUN 與 DNS 設定

在現有 YAML 的最上層加入以下欄位；若已有 dns 或 tun，請合併至原有區段，不要重複定義相同的頂層鍵。此範例讓 DNS 監聽本機 1053 連接埠，避免直接占用 Ubuntu 常見的 systemd-resolved 本機 DNS 端點。

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - 1.1.1.1

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

auto-route 會要求自動設定路由，auto-detect-interface 用於自動辨識出口介面。DNS 範例採用一個公共解析位址，請依實際網路連線狀況調整，並非適用所有網路的固定設定。fake-ip 回傳供核心映射使用的虛擬位址，並非目標網站的真實位址。

dns-hijack 會處理進入相應 TUN 路徑的 53 連接埠 DNS 請求，不會自動辨識並接管應用程式內建的 DoH 加密 DNS 查詢。只啟用 dns.enable 不代表系統的所有 DNS 查詢都已交由核心處理。排查問題時，請勿直接刪除 /etc/resolv.conf 或停止系統 DNS 解析服務，應先確認實際的 DNS 與路由路徑。

sudo -u mihomo /usr/local/bin/mihomo \
  -t -d /var/lib/mihomo -f /etc/mihomo/config.yaml
sudo systemctl daemon-reload
sudo systemctl restart mihomo
sudo journalctl -u mihomo -b -n 100 --no-pager
ip link show
ip rule show
resolvectl status

透過 SSH 操作遠端伺服器時，自動路由可能影響管理連線。啟用 TUN 前，請保留雲端主控台或其他頻外管理管道、備份原始設定，並確認如何停止服務。不要同時疊加桌面用戶端 TUN、獨立核心 TUN 與其他 VPN 的預設路由。

常見問題與維護步驟

啟動失敗：先判斷是檔案還是網路問題

• Exec format error：通常是系統架構不符，或誤將壓縮檔當成執行檔。請重新檢查 file 的輸出結果與 uname -m。
• Permission denied：請檢查設定檔及其上層目錄的存取權限。以登入使用者執行成功，不代表 mihomo 服務帳號也有權讀取檔案。
• 設定檔可讀取，但規則集載入失敗：請檢查 provider 路徑、網路連線及資料目錄的寫入權限。若使用 ProtectHome=true，請勿引用個人家目錄中的訂閱檔案。
• TUN operation not permitted：請依序確認裝置是否存在、drop-in 是否已載入，以及執行環境是否允許網路管理權限。可用 systemctl cat mihomo 查看合併後的 unit。

瀏覽器可連線，但終端機或容器無法使用

這通常是因為應用程式使用的代理設定來源不同，不代表核心啟動失敗。若工具支援該環境變數，可為單一終端機指令設定 HTTPS_PROXY=http://127.0.0.1:7890；使用 curl --proxy 則更方便明確測試。容器內的 127.0.0.1 指向容器本身，而非 Ubuntu 主機，必須另外規劃可連線的位址與存取控制。

預設請維持 allow-lan: false，也不要為了圖形管理面板而將控制介面直接開放至公網。若確實需要遠端管理，請採用具備驗證的存取方式與受限的網路入口，並確認防火牆設定。HTTP 代理連接埠與控制 API 連接埠用途不同，不能互相取代。

升級與停止服務

升級前請保留目前執行檔與設定的可還原副本；停止服務後再替換執行檔，確認新版本資訊，並重新檢查設定與啟動狀態。記錄中可能包含目標網域與連線資訊，分享前請移除訂閱憑證及敏感內容。

sudo systemctl stop mihomo
sudo systemctl disable mihomo
systemctl is-enabled mihomo

最後一個指令回傳 disabled 代表已取消開機自動啟動，不表示設定檔已刪除。若先前設定過 GNOME 手動代理或終端機代理環境變數，也請一併取消，否則應用程式仍會連線至已停止的 127.0.0.1:7890。桌面使用者宜優先由用戶端管理系統整合；伺服器則應明確掌握檔案路徑、服務身分與路由範圍，比反覆切換代理模式更容易找出問題。