Mihomo Linux 开机自启:systemd 配置与启动失败排查
简答: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.targetnetwork-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>。
相关阅读
参考资料
- MetaCubeX Meta-Docs:Mihomo systemd 服务配置
- MetaCubeX Mihomo Releases:Linux 二进制发布资产
- MetaCubeX Mihomo FAQ:发布文件名与架构选择
- MetaCubeX Meta-Docs:Mihomo TUN 配置说明
- MetaCubeX Dashboard:配置校验与 mihomo -t 说明
- systemd.special:network-online.target 与 multi-user.target(freedesktop.org)
- systemd.exec:CapabilityBoundingSet 与 AmbientCapabilities(freedesktop.org)
- loginctl:enable-linger 用户服务持久化(freedesktop.org)