2439 字

12 分钟

使用 Systemd 部署 Mihomo

🤖AI 摘要

AI

2026-03-12

教程

Mihomo

使用 Systemd 部署 Mihomo#

一、安装内核与准备配置#

在将 mihomo 交给 systemd 管理前，需要先把它的”骨架”搭建好。

下载并安装 mihomo 内核：从 mihomo 的官方发布页面下载对应你系统架构（如 linux-amd64）的压缩包。解压后，将二进制文件复制到系统的程序目录并赋予执行权限：
Terminal window
```
1
# 假设你已经将文件解压并重命名为 mihomo
2
sudo cp mihomo /usr/local/bin/
3
sudo chmod +x /usr/local/bin/mihomo
```
创建配置目录和文件： mihomo 默认会从 /etc/mihomo 目录读取配置。
Terminal window
```
1
sudo mkdir -p /etc/mihomo
```
然后，你需要创建一个核心配置文件 /etc/mihomo/config.yaml 。你可以将从你的服务商获取的订阅链接内容，或一个基础的配置文件模板放入其中。

二、创建 systemd 配置文件#

创建 systemd 配置文件 /etc/systemd/system/mihomo.service:

1
sudo vim /etc/systemd/system/mihomo.service

然后，粘贴以下配置内容：

1
[Unit]
2
Description=mihomo Daemon
3
# 等待网络完全就绪后再启动，避免启动时网络不可用
4
After=network-online.target
5
Wants=network-online.target
6

7
[Service]
8
# 以普通用户身份运行，最小权限原则
9
User=mihomo
10
Group=mihomo
11

12
# 资源限制
13
Type=simple
14
LimitNPROC=500
15
LimitNOFILE=1000000
16

17
# 官方推荐
18
#CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW CAP_NET_BIND_SERVICE CAP_SYS_TIME CAP_SYS_PTRACE CAP_DAC_READ_SEARCH CAP_DAC_OVERRIDE
19
#AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW CAP_NET_BIND_SERVICE CAP_SYS_TIME CAP_SYS_PTRACE CAP_DAC_READ_SEARCH CAP_DAC_OVERRIDE
20

21
# 限制：仅保留运行TUN模式和绑定低端口所必需的能力
22
# 移除了高危的 CAP_DAC_OVERRIDE, CAP_SYS_PTRACE 等
23
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW CAP_NET_BIND_SERVICE
24
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW CAP_NET_BIND_SERVICE
25

26
# 启用一系列安全沙箱选项，进一步隔离服务
27
NoNewPrivileges=yes
28
PrivateTmp=yes
29
ProtectSystem=strict
30
# 允许写入的数据目录（如缓存、持久化连接）
31
ReadWritePaths=/var/lib/mihomo
32
# 允许写入内核文件所在目录，以便面板能够更新内核
33
ReadWritePaths=/usr/local/bin
34
# 允许写入配置文件所在目录，以便面板能够更新配置
35
ReadWritePaths=/etc/mihomo
36
ProtectHome=yes
37
ProtectKernelTunables=yes
38
ProtectKernelModules=yes
39
ProtectControlGroups=yes
40

41
# 服务行为
42
Restart=always
43
ExecStart=/usr/local/bin/mihomo -d /etc/mihomo
44
ExecReload=/bin/kill -HUP $MAINPID
45

46
[Install]
47
WantedBy=multi-user.target

配置解读：

[Unit] 单元描述与依赖

配置项	设置值	作用/解释
`Description`	`mihomo Daemon`	服务的简要描述，便于管理员识别。
`After`	`network-online.target`	声明此服务应在网络完全就绪的 target 之后启动，避免启动时网络不可用导致失败。
`Wants`	`network-online.target`	表示希望 network-online.target 被激活，但并不严格要求其成功；通常与 `After` 配合使用以确保网络已配置好。

[Service] 服务运行定义

配置项	设置值	作用/解释
用户与组
`User`	`mihomo`	以非特权系统用户 `mihomo` 的身份运行服务，避免使用 root 账户，实现最小权限原则。
`Group`	`mihomo`	服务运行时所属的组，同样为非特权组。
服务类型与资源限制
`Type`	`simple`	默认类型，表示 `ExecStart` 启动的进程就是主进程，systemd 会将其作为服务的主控进程。
`LimitNPROC`	`500`	限制服务及其子进程的最大进程/线程数为 500。
`LimitNOFILE`	`1000000`	限制文件描述符数量为 100 万，满足高并发网络连接需求。
Linux Capabilities（能力集）
`CapabilityBoundingSet`	`CAP_NET_ADMIN CAP_NET_RAW CAP_NET_BIND_SERVICE`	限制进程可拥有的能力边界，超出此集合的能力即使通过 `exec` 也无法获得。此处仅保留网络管理、原始套接字和绑定特权端口所需的能力。
`AmbientCapabilities`	同上	在 `exec` 后仍保留上述能力，使得非 root 用户启动的进程也能保持这些能力。
安全沙箱选项
`NoNewPrivileges`	`yes`	禁止进程及其子进程通过 `execve` 获得新特权（如通过 setuid 或文件系统能力），即使文件有 suid 位也无效，增强安全性。
`PrivateTmp`	`yes`	为服务创建独立的临时文件空间 `/tmp` 和 `/var/tmp`，与其他进程隔离，防止临时文件信息泄露。
`ProtectSystem`	`strict`	以最严格模式保护系统文件：将 `/usr`、`/boot`、`/etc` 挂载为只读，服务无法修改这些关键系统目录。
`ReadWritePaths`	`/var/lib/mihomo`	在 `ProtectSystem=strict` 下，允许服务对指定目录（如数据目录）拥有写入权限。
`ReadWritePaths`	`/usr/local/bin`	允许面板更新内核文件
`ProtectHome`	`yes`	将 `/home`、`/root` 和 `/run/user` 挂载为不可访问（返回空或隐藏），保护用户隐私数据。
`ProtectKernelTunables`	`yes`	禁止修改内核可调参数（`/sys/...`、`/proc/sys/...`），防止内核配置被篡改。
`ProtectKernelModules`	`yes`	禁止加载或卸载内核模块，防止内核模块攻击。
`ProtectControlGroups`	`yes`	禁止修改 cgroup（控制组）配置，防止资源隔离被破坏。
服务行为
`Restart`	`always`	无论退出原因（正常退出或异常崩溃），服务总是自动重启，确保高可用性。
`ExecStart`	`/usr/local/bin/mihomo -d /etc/mihomo`	启动 mihomo 主程序，`-d` 指定配置目录为 `/etc/mihomo`。
`ExecReload`	`/bin/kill -HUP $MAINPID`	当执行 `systemctl reload mihomo` 时，向主进程发送 HUP 信号，触发配置重载（需 mihomo 支持）。

[Install] 安装与自启

配置项	设置值	作用/解释
`WantedBy`	`multi-user.target`	表示该服务应在系统进入多用户运行级别（通常为正常启动后）时自动启动。

三、创建用户与启动服务#

配置文件写好后，需要创建对应的用户并启动服务。

创建专用的系统用户：执行以下命令创建 mihomo 用户和组。--system 表示创建系统用户，--no-create-home 表示不创建 home 目录（我们用不到）。
Terminal window
```
1
sudo groupadd --system mihomo
2
sudo useradd --system --gid mihomo --no-create-home --shell /usr/sbin/nologin mihomo
```

设置配置目录的权限：确保 mihomo 用户能读取配置文件。

1
sudo chown -R root:mihomo /etc/mihomo
2
sudo chmod 750 /etc/mihomo

如果你的服务配置了 ReadWritePaths=/var/lib/mihomo，还需要创建该目录并授予权限：

1
sudo mkdir -p /var/lib/mihomo
2
sudo chown mihomo:mihomo /var/lib/mihomo
3
sudo chmod 750 /var/lib/mihomo
4

5
sudo chown mihomo:mihomo /usr/local/bin/mihomo
6
sudo chmod 755 /usr/local/bin/mihomo

启动服务并设置开机自启：现在，可以通知 systemd 重载配置，并启动服务了。

1
# 重新加载 systemd 管理器配置
2
sudo systemctl daemon-reload
3
# 设置开机自启
4
sudo systemctl enable mihomo
5
# 立即启动服务
6
sudo systemctl start mihomo

四、日常管理与维护#

服务运行起来后，你可以通过以下命令来管理它：

查看状态：
Terminal window
```
1
sudo systemctl status mihomo
```
查看日志：
Terminal window
```
1
sudo journalctl -u mihomo -f -n 50
```
-f 表示实时跟踪，-n 50 表示显示最后50行日志。

停止/重启：

1
sudo systemctl stop mihomo
2
sudo systemctl restart mihomo

重新加载配置（发送 HUP 信号）：修改了 config.yaml 后，可以优雅地重载配置而不用中断服务。
Terminal window
```
1
sudo systemctl reload mihomo
2
# 或者
3
sudo kill -HUP $(pidof mihomo)
```

五、自动部署管理面板（可选）#

mihomo 支持在启动时自动下载并部署 Web 管理面板（如 MetaCubeXD），让你可以通过浏览器直观地查看日志、切换节点、测试延迟等。只需在配置文件中添加几行配置，mihomo 就会在启动时自动完成面板的下载、解压和挂载。

1. 修改核心配置文件#

编辑 /etc/mihomo/config.yaml，在适当位置（通常在 external-controller 相关配置段）添加以下三行：

1
external-controller: 0.0.0.0:9090      # 必须：开启外部控制 API，监听所有网卡的 9090 端口
2
external-ui: ui                         # 指定存放面板文件的目录名（相对路径，相对于工作目录 /etc/mihomo）
3
external-ui-url: "https://ghproxy.cn/github.com/MetaCubeX/metacubexd/archive/gh-pages.zip" # 面板的下载地址

配置说明：

external-controller：开启 RESTful API，mihomo 会监听此地址，供面板调用。
external-ui：面板静态文件的存放目录。此处使用相对路径 ui，即 mihomo 将在工作目录 /etc/mihomo 下创建 ui 文件夹。
external-ui-url：面板压缩包的下载链接。mihomo 启动时会自动从该地址下载并解压到 ui 目录。

2. 确保面板目录可写#

由于 external-ui 指定的目录（/etc/mihomo/ui）需要由 mihomo 用户创建和写入文件，因此必须确保该用户对 /etc/mihomo 目录有写入权限。

在之前配置的 systemd 服务中，我们启用了严格的安全保护（ProtectSystem=strict），默认会将 /etc 挂载为只读。为了让 mihomo 能在 /etc/mihomo 下创建 ui 文件夹并写入面板文件，有两种解决方案：

方案 A（推荐）：修改 systemd 服务，允许写入 `/etc/mihomo`#

编辑 /etc/systemd/system/mihomo.service，在 [Service] 部分的 ReadWritePaths 中添加一行：

1
ReadWritePaths=/etc/mihomo

修改后执行：

1
sudo systemctl daemon-reload

这样既保留了大部分系统目录的只读保护，又单独放行了配置目录。

方案 B（更安全）：将面板目录指向已有可写路径#

如果你不希望放宽对 /etc 的保护，可以将 external-ui 设置为一个已经允许写入的绝对路径，例如 /var/lib/mihomo/ui。

1
external-ui: /var/lib/mihomo/ui

并确保该目录存在且属主为 mihomo：

1
sudo mkdir -p /var/lib/mihomo/ui
2
sudo chown mihomo:mihomo /var/lib/mihomo/ui
3
sudo chmod 750 /var/lib/mihomo/ui

注意：/var/lib/mihomo 已在之前的 systemd 配置中通过 ReadWritePaths 开放了写入权限，因此无需修改服务文件。

3. 防火墙放行 9090 端口#

面板需要通过 9090 端口访问，请确保防火墙允许外部设备连接该端口。

如果使用 firewalld：

1
sudo firewall-cmd --permanent --add-port=9090/tcp
2
sudo firewall-cmd --reload

如果使用 ufw：

1
sudo ufw allow 9090/tcp

4. 重启服务并验证#

重新加载配置并重启 mihomo 服务（reload 可能不会触发面板下载，建议直接 restart）：

1
sudo systemctl restart mihomo

查看日志，确认面板是否下载成功：

1
sudo journalctl -u mihomo -f -n 50

如果日志中出现类似以下信息，说明面板已自动部署：

1
... downloading ui from https://ghproxy.cn/github.com/MetaCubeX/metacubexd/archive/gh-pages.zip ...
2
... extracted ui to /etc/mihomo/ui

5. 访问面板#

在浏览器中输入 http://<你的Linux设备IP>:9090/ui，即可打开管理面板。首次访问时，面板可能需要与 mihomo 建立连接，请确保 API 地址正确（默认为面板所在设备的 <你的Linux设备IP>:9090）。

6.故障排查#

面板无法访问：检查防火墙是否放行 9090 端口；确认 external-controller 配置正确且 mihomo 正常运行。
面板未自动下载：检查 external-ui-url 是否可访问（可手动在服务器上用 curl -I 测试）；确认 mihomo 用户对目标目录有写入权限；查看日志中是否有权限错误或下载失败信息。
手动部署面板：如果自动下载失败，可以手动从 MetaCubeX/metacubexd 仓库下载 gh-pages.zip，解压到指定的 ui 目录（确保 index.html 等文件直接位于目录内），然后重启服务。