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 优先考虑对应架构的 .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 直连，不提供远端代理能力。实际使用时应换成可信且完整的配置，包含真实的节点、策略组及规则，而不是只粘贴一个订阅 URL。

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.enable 也不意味着系统所有解析请求已进入内核。不要为排障直接删除 /etc/resolv.conf 或停止系统解析服务，应先查看实际 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。对桌面用户，优先由客户端管理系统集成；对服务器，明确文件路径、服务身份和路由边界，比反复切换代理模式更容易定位问题。