TAG官网 - TAG VPN套餐价格 | Bronze、Silver、Gold计划 - TAG Pro网络加速返回首页

Mihomo Linux 开机自启:systemd 配置与启动失败排查

更新于 2026-11-18 · tagss11.buzz

简答:Mihomo Linux 开机自启,最稳妥的处理顺序是:先确认二进制架构和配置目录,再用 <code>mihomo -t</code> 校验配置,最后创建 systemd 服务并执行 <code>enable --now</code>。无 TUN 时建议使用专用用户运行;使用 TUN 时先按实际日志确认权限需求,不要直接复制包含多项高权限 capability 的模板。启动后同时检查 <code>systemctl status</code>、<code>is-enabled</code> 和 <code>journalctl</code>。

定义:Mihomo Linux 开机自启,是让 Linux 的 systemd 在系统启动阶段自动运行 Mihomo,并通过服务状态和日志持续管理该进程。

先判断方案:无 TUN、TUN、系统级还是用户级

如果你只是希望 Mihomo 在服务器、NAS 或无桌面 Linux 上常驻,优先选择系统级 systemd;如果配置启用了 TUN,先确认系统是否需要网络管理权限,再决定以 root 运行还是使用专用用户加最小 capability。用户级 systemd 适合只为当前用户运行,但要额外处理用户会话和 lingering。

开机自启方案速查
场景建议方案先检查什么
无 TUN,仅监听代理端口系统级服务 + 专用用户二进制、配置文件和监听端口权限
使用 TUN、自动路由或自动重定向系统级服务,先用保守权限验证tun.enable、路由设置、/dev/net/tun 和日志
只为当前桌面用户运行用户级 systemd用户服务目录、systemctl --user 和 lingering
服务启动但代理不生效继续查端口、DNS、规则和 TUN不要只看进程是否为 active

本文是第三方使用指南,不是 Mihomo 官方页面。服务目录、启动参数和配置字段名称可能随当前版本变化,首次操作请对照 Mihomo systemd 文档、当前发布页和 官方文件选择说明。

第一步:核对架构、压缩格式和文件完整性

先确认本机架构,再从当前发布页选择 Linux 和对应架构的文件。不要把教程中的版本号当成固定版本;截至本文资料,具体可用版本和发布资产仍应以当前发布页为准。

uname -m
file /tmp/实际下载的文件名
sha256sum /tmp/实际下载的文件名

uname -m 常见输出可能包括 x86_64、aarch64 或 armv7l。官方 FAQ 说明,发布文件名通常包含程序名、操作系统、架构和编译标记,应按这些信息选择,而不是只看文件后缀。

根据实际资产格式解压,下面只展示对应格式的示例,文件名必须替换:

# tar.gz
mkdir -p /tmp/mihomo-unpack
tar -xzf /tmp/实际文件名.tar.gz -C /tmp/mihomo-unpack

# gzip 压缩的单个可执行文件
gzip -dc /tmp/实际文件名.gz > /tmp/mihomo-unpack/mihomo

# zip
unzip /tmp/实际文件名.zip -d /tmp/mihomo-unpack

file /tmp/mihomo-unpack/mihomo

如果发布页同时提供校验值,应将 sha256sum 的结果与发布页提供的值比对;资料未提供校验值时,不要自行声称文件已经验证通过。确认文件是适合本机的 Linux 可执行文件后,再安装:

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

若出现 Exec format error,先回到架构、操作系统和压缩包选择检查,不要先修改 systemd。

第二步:准备配置目录并先校验配置

官方 systemd 示例使用 /etc/mihomo 作为工作目录,并通过 -d /etc/mihomo 启动。先创建目录,再复制配置文件和配置引用的规则集、地理数据库等文件。

sudo install -d -m 0755 /etc/mihomo
sudo install -m 0644 /你的配置文件路径/config.yaml /etc/mihomo/config.yaml
sudo ls -la /etc/mihomo

如果配置含有相对路径,相关文件应放在 Mihomo 工作目录或配置实际引用的位置。随后使用当前二进制的测试参数校验:

sudo /usr/local/bin/mihomo -t -d /etc/mihomo

官方面板文档将 mihomo -t 作为配置激活前的最终校验步骤;如果当前版本帮助信息与此不同,应先执行 /usr/local/bin/mihomo -h,以当前版本为准。校验失败时先修复 YAML 缩进、字段、引用文件和端口配置,再继续创建服务。

第三步:创建无 TUN 的最小权限系统级服务

系统级服务文件放在 /etc/systemd/system/mihomo.service。下面模板适用于不使用 TUN、自动路由或自动重定向的基础场景,显式使用专用用户运行,避免默认以 root 运行所有进程。

sudo useradd --system --no-create-home --shell /usr/sbin/nologin mihomo 2>/dev/null || true
sudo chown -R mihomo:mihomo /etc/mihomo
sudo chmod 0755 /etc/mihomo
sudo chmod 0644 /etc/mihomo/config.yaml
sudo nano /etc/systemd/system/mihomo.service

将以下内容写入服务文件。ExecStart 使用绝对路径,配置目录也明确写出,避免 systemd 工作目录与手动运行时不同。

[Unit]
Description=Mihomo Daemon
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=mihomo
Group=mihomo
WorkingDirectory=/etc/mihomo
ExecStart=/usr/local/bin/mihomo -d /etc/mihomo
Restart=on-failure
RestartSec=5
LimitNOFILE=1000000

[Install]
WantedBy=multi-user.target

network-online.target 适合必须等待网络配置完成后再启动的网络客户端,但它是否真正等待到“网络可用”,取决于发行版使用的网络管理器及其 wait-online 服务。systemd 文档明确区分了 network.target 与 network-online.target;如果仍在启动后加载远端资源失败,应检查对应的 NetworkManager-wait-online.service 或 systemd-networkd-wait-online.service 是否启用。

创建后先检查服务文件,再重载并启动:

sudo systemd-analyze verify /etc/systemd/system/mihomo.service
sudo systemctl daemon-reload
sudo systemctl enable --now mihomo

如果服务需要读取配置目录中的其他文件,确认它们也归 mihomo 用户可读;如果配置要监听低位端口或执行特定网络操作,权限需求可能不同,应根据日志逐项处理。

第四步:使用 TUN 时不要直接套用高权限模板

Mihomo 官方 systemd 示例包含多项 capability,但这不代表每种配置都需要全部权限。systemd 文档说明,CapabilityBoundingSet 会限制进程可获得的 capability,AmbientCapabilities 会将指定 capability 传递给非特权进程;因此应按实际功能逐项增加,而不是把 CAP_SYS_TIME、CAP_SYS_PTRACE、CAP_DAC_OVERRIDE 等权限作为默认模板。

如果你启用了 TUN、自动路由或 Linux 自动重定向,先确认配置中的 tun.enable、auto-route 和 auto-redirect,并查看启动日志是否出现 TUN、路由、iptables 或 nftables 错误。Mihomo TUN 文档说明,Linux 下 auto-redirect 依赖 auto-route,DNS 劫持等行为也会随相关配置变化。

排查阶段可以先使用系统级 root 服务验证功能边界,但应明确这是诊断步骤,而不是默认的最小权限方案:

[Unit]
Description=Mihomo Daemon with TUN
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
WorkingDirectory=/etc/mihomo
ExecStart=/usr/local/bin/mihomo -d /etc/mihomo
Restart=on-failure
RestartSec=5
LimitNOFILE=1000000

[Install]
WantedBy=multi-user.target

如果 root 服务可以运行,而专用用户服务失败,再根据日志确认是否只需要 CAP_NET_ADMIN、CAP_NET_RAW 或其他特定能力。不要在没有错误证据时追加能力;添加后重新执行 systemd-analyze verify、重载服务并查看日志。TUN 配置字段和行为应以当前 Mihomo TUN 文档为准。

第五步:验证开机自启是否真正生效

“当前进程在运行”不等于“已经设置开机自启”。至少同时检查服务状态、启用状态、最近启动日志和实际监听端口:

sudo systemctl status mihomo --no-pager -l
sudo systemctl is-enabled mihomo
sudo journalctl -u mihomo -b --no-pager
sudo ss -lntup
验证结果怎么判断
结果含义下一步
is-enabled 显示 enabled,状态为 active服务已启用且当前运行继续核对监听端口和实际代理功能
状态为 failed服务启动或运行中退出先看 journalctl -u mihomo -b
找不到服务单元服务文件路径或文件名不正确检查 /etc/systemd/system/ 后执行 daemon-reload
服务 active 但端口未监听配置未加载、监听地址不同或服务启动后异常检查配置、日志和实际监听地址

确认服务已经设置后,可重启系统进行最终验证:

sudo reboot

重启后再次执行 systemctl status、is-enabled 和 journalctl -u mihomo -b。如果服务启动但远端规则集或地理数据库加载失败,先测试系统 DNS、HTTPS 连接和网络管理器状态;不要把远端资源失败直接判断为 systemd 自启失败。

系统级与用户级 systemd:不要混用命令

系统级服务使用 /etc/systemd/system/ 和 sudo systemctl;用户级服务使用 ~/.config/systemd/user/ 和 systemctl --user。本文主流程是系统级服务,下面给出用户级的最小流程,适合无 TUN、只为当前用户运行的场景。

mkdir -p ~/.config/systemd/user
mkdir -p ~/.config/mihomo
cp /你的配置文件路径/config.yaml ~/.config/mihomo/config.yaml
nano ~/.config/systemd/user/mihomo.service
[Unit]
Description=Mihomo User Service
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
WorkingDirectory=%h/.config/mihomo
ExecStart=/usr/local/bin/mihomo -d %h/.config/mihomo
Restart=on-failure
RestartSec=5
LimitNOFILE=1000000

[Install]
WantedBy=default.target

在同一个用户会话中执行:

systemctl --user daemon-reload
systemctl --user enable --now mihomo
systemctl --user status mihomo --no-pager
journalctl --user -u mihomo -e

默认情况下,用户级服务通常依赖用户会话。systemd 的 loginctl enable-linger 会让该用户的 user manager 在开机时启动、退出登录后继续运行:

loginctl enable-linger
systemctl --user is-enabled mihomo

如果你需要 TUN、全局路由、低位端口或无用户登录时也接管系统流量,优先回到系统级方案,不要把用户级服务当成系统级权限的替代品。

停止、禁用和恢复手动启动

修改配置或替换二进制前,先校验配置;修改服务文件后执行 daemon-reload。常用反向操作如下:

# 暂停当前服务,但保留开机自启
sudo systemctl stop mihomo

# 停止并取消开机自启
sudo systemctl disable --now mihomo

# 修改服务文件后重新加载并启动
sudo systemctl daemon-reload
sudo systemctl restart mihomo

# 查看完整日志
sudo journalctl -u mihomo -e

如果决定恢复手动启动,只需先执行 disable --now,保留二进制和配置目录,然后按照当前配置手动运行。删除服务文件前应先禁用服务并确认 systemctl is-enabled mihomo 不再显示启用状态。

常见问题

Mihomo Linux 开机自启必须使用 systemd 吗?

不是唯一方式,但本文只覆盖使用 systemd 的 Linux 环境。systemd 便于统一管理启动顺序、重启策略和 journal 日志;如果系统不使用 systemd,应以当前发行版的服务管理方式为准。

为什么 mihomo -t 通过了,systemctl start 仍然失败?

配置校验通过只说明测试命令能够解析配置,服务仍可能因二进制架构、ExecStart 路径、文件权限、端口占用、TUN 权限或网络资源加载失败而退出。请结合 <code>systemctl status mihomo -l</code> 和 <code>journalctl -u mihomo -b</code> 查看具体错误。

Mihomo 服务为什么建议使用 network-online.target?

当 Mihomo 启动时必须访问远端规则集、地理数据库或其他网络资源,network-online.target 可以表达“先等待网络管理器完成配置”的依赖。但它是否真正等待到网络可用,取决于 NetworkManager 或 systemd-networkd 的 wait-online 服务,不能单独保证远端资源一定加载成功。

无 TUN 时是否需要复制官方模板中的所有 capability?

不建议。无 TUN 的基础场景可以先使用专用用户和不追加 capability 的模板。官方模板包含多项 capability,但具体需求取决于配置和运行环境;应根据日志逐项增加,而不是默认授予高权限。

使用 TUN 时,Mihomo 以普通用户运行失败怎么办?

先确认 TUN、自动路由和自动重定向配置,再查看日志是否涉及 <code>/dev/net/tun</code>、路由、iptables、nftables 或 capability。可以暂时用系统级 root 服务验证是否为权限边界问题,确认后再按实际错误缩减到所需权限。

用户级 systemd 重启后没有运行怎么办?

先用 <code>systemctl --user status mihomo</code> 和 <code>journalctl --user -u mihomo -e</code> 查看服务,再确认已执行 <code>systemctl --user enable mihomo</code>。如果要求用户未登录时仍运行,还需按当前系统情况检查 <code>loginctl enable-linger</code>。

相关阅读

参考资料

  1. MetaCubeX Meta-Docs:Mihomo systemd 服务配置
  2. MetaCubeX Mihomo Releases:Linux 二进制发布资产
  3. MetaCubeX Mihomo FAQ:发布文件名与架构选择
  4. MetaCubeX Meta-Docs:Mihomo TUN 配置说明
  5. MetaCubeX Dashboard:配置校验与 mihomo -t 说明
  6. systemd.special:network-online.target 与 multi-user.target(freedesktop.org)
  7. systemd.exec:CapabilityBoundingSet 与 AmbientCapabilities(freedesktop.org)
  8. loginctl:enable-linger 用户服务持久化(freedesktop.org)