先确定运行方式与流量入口

Linux 上的 Clash 兼容客户端通常由图形界面与代理内核两部分组成。mihomo 是代理内核，读取 YAML 配置、监听本地端口并执行分流规则；图形客户端负责导入订阅、管理配置、选择策略组，以及调用系统代理或 TUN。两者不是同一个安装包，也不共享固定的配置目录。

有 GNOME、KDE 等桌面环境，且需要频繁切换节点时，优先使用图形客户端。只有 SSH 的服务器，或需要开机启动、集中查看日志时，使用 mihomo 加 systemd 更容易明确权限和文件归属。本文的命令行方案以使用 systemd 的常规 Linux 主机为前提，不适用于只有容器进程管理器的环境。

项目 桌面图形客户端 mihomo 服务
配置入口客户端的配置或订阅页面/etc/mihomo/config.yaml，由本文明确指定
启动方式桌面启动器或登录自启systemctl enable --now mihomo
日志入口客户端日志页面journalctl -u mihomo
基础流量入口系统代理或应用独立代理应用显式连接 127.0.0.1:7890
权限边界普通界面与提权服务分开基础代理以专用非 root 用户运行

桌面方案：安装图形客户端并导入配置

1. 确认发行版、架构与安装包类型

可从客户端下载页选择支持 Linux 的 Clash Verge Rev 或 FlClash 等客户端。先读取系统信息，不要仅凭电脑型号判断安装包。x86_64 通常对应发布页的 x64 或 amd64；aarch64 通常对应 arm64。处理器架构匹配之外，还要检查客户端要求的发行版版本和运行库。

cat /etc/os-release
uname -m

Debian、Ubuntu 一般使用 DEB 包，Fedora 等发行版一般使用 RPM 包。以下将已经下载的文件在本地重命名为 client.deb 或 client.rpm，仅用于简化安装命令，不代表项目的实际发布文件名。进入该文件所在目录，按发行版只执行其中一条：

# Debian / Ubuntu
sudo apt install ./client.deb

# Fedora
sudo dnf install ./client.rpm

从桌面应用菜单启动客户端，不要用 sudo 启动整个图形界面。需要服务模式或 TUN 权限时，使用客户端提供的服务安装或授权入口。这样可以避免用户配置被写成 root 所有，导致下次普通用户启动时无法保存订阅。

2. 导入订阅，检查实际生效配置

  1. 在客户端的配置或订阅页面导入有效的 Clash 兼容订阅链接，或导入本地 YAML。不同客户端版本的菜单名称可能不同。
  2. 选中刚导入的配置并设为当前配置。仅看到下载成功，不代表该配置已经启用。
  3. 在策略组中选择一个可用节点，再查看日志是否存在配置解析错误。策略组名称必须与规则引用一致。
  4. 从当前配置或运行信息中确认 HTTP、SOCKS 或 mixed 监听端口。下文以 7890 为例，不要求把现有客户端强行改成这个端口。
  5. 先用显式代理测试，再启用系统代理。只有需要接管不遵守代理设置的应用时，才进一步测试 TUN。

图形客户端可能合并订阅、覆写设置和界面选项，最后生成一份运行配置。不要直接编辑这种临时生成文件：更新订阅或切换配置后，修改可能消失。需要长期保留的端口、规则或 DNS 调整，应使用客户端的覆写机制；也不要假定它读取 ~/.config/mihomo/config.yaml。

3. 区分桌面系统代理与终端代理

客户端的“系统代理”通常修改桌面环境的代理设置。浏览器可能遵守该设置，但新开终端里的 curl、包管理器和后台服务不一定读取它。反过来，在终端中执行 export 也不会修改已经运行的浏览器。测试时应记录具体应用、使用的代理入口和端口，不要只记录“已打开代理”。

无界面方案：准备内核与独立目录

下面使用固定路径部署，避免混淆当前 SSH 用户的家目录与服务的工作目录。安装内核前，按 uname -m 的结果，从 mihomo 官方发布渠道选择兼容当前架构和 CPU 指令集的 Linux 构建。将下载的压缩文件解压，并把可执行文件在本地命名为 mihomo，以下命令从该文件所在目录开始。

sudo install -m 0755 ./mihomo /usr/local/bin/mihomo
/usr/local/bin/mihomo -v

-v 用于查看实际安装版本。若提示 Exec format error，先检查是否仍在执行压缩文件，或是否选错架构；若提示 Illegal instruction，检查构建的指令集要求。重新下载与主机匹配的构建，比反复调整文件权限更有针对性。

建立专用服务账户

以下账户只运行代理服务，不用于交互登录。账户已存在时跳过创建；若发行版的 nologin 不在该路径，先用 command -v nologin 确认并调整。配置由 root 管理，运行数据由服务用户写入。

getent passwd mihomo || 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
  • /usr/local/bin/mihomo：内核程序，普通服务用户不能覆盖。
  • /etc/mihomo/config.yaml：主配置，可能包含节点凭据或订阅地址，应限制读取权限。
  • /var/lib/mihomo：通过 -d 指定的数据目录，用于运行状态、缓存及配置所需资源。

本文用 -f 显式指定主配置，不依赖默认目录。若真实配置包含 proxy-providers、rule-providers 或外部数据文件，还需检查它们的路径、读取权限和下载条件。不要只复制主 YAML，就默认所有依赖文件已经到位。

先用最小配置验证监听端口

为了把安装问题与订阅问题分开，先使用下面的直连验证配置。在当前目录新建 config.yaml，写入以下内容。它只验证内核能否启动、接收代理请求并直连出站，不包含任何代理节点，也不会改变出口地区。

mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info

tun:
  enable: false

rules:
  - MATCH,DIRECT

mixed-port 在同一端口接受 HTTP 与 SOCKS 代理请求。allow-lan: false 用于限制本机访问；示例同时写明回环地址。暂不启用控制接口，也不需要开放云服务器安全组的 7890 端口。

sudo install -o root -g mihomo -m 0640 \
  ./config.yaml /etc/mihomo/config.yaml

sudo -u mihomo /usr/local/bin/mihomo \
  -t -d /var/lib/mihomo -f /etc/mihomo/config.yaml

-t 检查配置能否被当前内核加载，不等于节点连通性测试。出现 YAML 错误时，先检查缩进、冒号后的空格及字段类型；出现权限错误时，检查配置文件及其每一级父目录是否允许服务账户访问。

配置 systemd 常驻运行

新建 /etc/systemd/system/mihomo.service，写入以下完整内容。此服务适用于前面的本地显式代理方案，不授予创建 TUN 设备或修改系统路由的权限。

[Unit]
Description=mihomo local proxy service
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=mihomo
Group=mihomo
WorkingDirectory=/var/lib/mihomo
StateDirectory=mihomo
StateDirectoryMode=0750
ExecStart=/usr/local/bin/mihomo -d /var/lib/mihomo -f /etc/mihomo/config.yaml
Restart=on-failure
RestartSec=5s
UMask=0027
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict

[Install]
WantedBy=multi-user.target

StateDirectory 让 systemd 管理可写状态目录；ProtectSystem=strict 限制服务写入系统文件，而状态目录仍可写。ProtectHome=true 会阻止服务读取用户家目录，所以不要把 provider 文件留在下载目录后直接引用。将依赖文件放进服务可访问的目录，再按配置中的路径组织。

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo.service

systemctl status mihomo.service --no-pager
sudo journalctl -u mihomo.service -b -n 80 --no-pager
sudo ss -lntup 'sport = :7890'

enable --now 同时启用开机启动并立即启动服务。network-online.target 的等待效果取决于发行版启用的网络等待服务，它不保证外部订阅站点一定可达。若启动时需要下载远端资源，仍要从日志确认请求是否成功。

配置更新与二进制升级

修改 YAML 后先以服务用户执行前面的 -t 检查，成功后再重启。本文没有定义 ExecReload，因此不要把 systemctl reload mihomo 当成可用步骤。重启会中断现有代理连接，应选择合适的维护时间。

sudo -u mihomo /usr/local/bin/mihomo \
  -t -d /var/lib/mihomo -f /etc/mihomo/config.yaml \
  && sudo systemctl restart mihomo.service

升级内核前保留原程序与配置。停止服务后，用 install 写入新程序，查看版本并重新检查配置，再启动服务。不要直接覆盖正在运行的可执行文件，也不要认为新版一定支持旧配置中每一个已废弃字段。

设置终端代理变量并验证请求

先执行一次显式代理请求

在运行 mihomo 的同一台主机上执行下面的测试。--noproxy "" 可避免已有的 NO_PROXY 设置让这次请求绕过代理。收到 HTTP 响应说明请求链路有进展；网站返回的具体状态码仍需单独判断。

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

测试最小直连配置时，成功只代表本地代理入口可用。换成真实节点配置后，要结合连接日志中的目标、规则和策略组判断是否经过节点，不能仅凭网页能够打开就断定出口已经切换。

为当前终端及其子进程设置代理

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=socks5h://127.0.0.1:7890
export no_proxy=localhost,127.0.0.1,::1

curl --connect-timeout 10 --max-time 30 -I https://example.com/

https_proxy 的值使用 http:// 并不矛盾：这里描述的是到本地 HTTP 代理的连接方式，HTTPS 目标通常通过 CONNECT 建立隧道。对支持该写法的程序，socks5h:// 表示把目标域名交给 SOCKS 代理解析；不同工具支持的变量和优先级不完全相同。

  • 这组 export 只影响当前 shell 及之后启动的子进程，不会修改其他登录会话。
  • 需要长期生效时，可加入所用 shell 的启动文件，例如 Bash 交互终端常用的 ~/.bashrc，但不是所有程序都会读取它。
  • sudo 通常过滤环境变量；不要用“普通 curl 成功”推断 sudo apt 一定使用同样的代理。
  • systemd 系统服务不读取用户的 ~/.bashrc，需要代理的其他服务应单独配置环境，且不要给 mihomo 自身设置指向自身端口的代理变量。

若机器原先设置过大写变量，也应检查并保持一致。curl 出于安全原因不接受大写的 HTTP_PROXY，因此本文使用小写形式。停止代理前可清理当前终端中的常见变量，避免遗留设置造成后续命令连接失败：

unset http_proxy https_proxy all_proxy no_proxy
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY

TUN、远程访问与故障检查

TUN 是独立的权限与路由变更

TUN 通过虚拟网络接口接管符合路由条件的 IP 流量，不是“所有程序、所有流量必然经过代理”的保证。路由排除、DNS、IPv6 与现有 VPN 都会影响结果。Linux 下通常需要访问 /dev/net/tun，并具备网络管理能力；仅把 tun.enable 改成 true，无法绕过这些要求。

本文的非 root systemd 单元没有授予这些能力。需要 TUN 时，应按所用客户端或 mihomo 当前文档重新评估服务权限、DNS 接管和路由配置，不要只追加一个提权命令。在 SSH 服务器上操作前，保留独立会话和云控制台入口，明确管理网段的排除方式，防止接管路由后失去连接。

远程使用优先采用 SSH 转发

如果需要从个人电脑临时使用服务器上的本地代理，可以在个人电脑执行 SSH 本地转发，而不是把代理端口直接暴露到公网。以下假设 SSH 配置里已有名为 mihomo-host 的主机别名：

ssh -N -o ExitOnForwardFailure=yes \
  -L 127.0.0.1:17890:127.0.0.1:7890 mihomo-host

保持 SSH 连接，在个人电脑将应用代理设置为 127.0.0.1:17890。其中远端的 127.0.0.1:7890 指服务器本机，而不是个人电脑。若确实要提供局域网代理，还需单独配置身份认证、防火墙和访问范围，不能只开启 allow-lan。

按错误现象缩小范围

现象优先检查
address already in use用 ss 查端口占用。桌面客户端与 systemd 服务可能同时监听 7890，只保留一个入口或分别配置端口。
Permission denied检查服务用户能否读取主配置与 provider 文件，以及数据目录是否可写。不要用全目录开放权限代替定位。
Connection refused确认服务处于运行状态、实际监听地址与应用使用的端口一致；容器里的 127.0.0.1 不是宿主机。
能连端口但请求超时查看节点是否可达、DNS 是否成功、策略组当前选择及命中规则，区分本地监听正常与上游链路正常。
终端有效，其他应用无效检查该应用是否支持环境变量，是否启用了自身代理，以及是否在设置变量之前已经启动。
终端启动正常，服务启动失败比较实际运行用户、工作目录、配置绝对路径与文件权限；检查是否引用了被 ProtectHome 隔离的文件。

排查时保留三项证据：mihomo -v 的版本输出、服务日志中的第一条有效错误、应用实际使用的代理地址。分享日志前删除订阅凭据、节点密码和控制接口密钥。需要查阅字段含义时，可继续阅读完整文档；初次导入订阅与切换配置的操作见配置教程。