在 NAS 上部署 mihomo：从调研到全屋 GitHub 加速

⚠️ 方案已停用（2026-09-28）

本文记录的 mihomo 代理方案已彻底移除：服务、配置、订阅配置与本地数据、相关防火墙规则全部清理完毕，不再维护，也不会再更新。

停用原因：该链路频繁失效（节点不稳定，需反复排查），维护成本高于收益；GitHub 访问已改用更稳定的替代方式。

本文仅作技术记录保留——其中的方案调研方法、systemd 服务化思路与排查手段仍有参考价值；但请勿按文中步骤重新部署。文内配置示例仅为通用默认参数，不含任何有效凭证。

缘起：那个让人崩溃的 GitHub

我的 NAS 上跑着个人 Agent（Hermes），经常要和 GitHub 打交道：git push、git clone、gh 命令。国内网络环境下，这些操作像开盲盒：

1	git push → 超时 → 重试 → 超时 → 重试 8 次 → 终于成功

每次推送都要写循环重试脚本（for i in 1..8; git push && break; sleep 15），还得调大 http.postBuffer。直连 GitHub 首页实测要 15 秒——基本踩在超时边缘。

忍无可忍，决定在 NAS 上装一个代理：一次部署，全家受益——不仅 Hermes 的 git/gh 顺畅，以后手机、电脑也能通过 NAS 加速。

调研：mihomo 是什么

搜索后锁定了 MetaCubeX/mihomo——Clash.Meta 的继任者，Go 编写的规则代理核心。研究过程有几个有意思的发现：

1. 仓库元数据不可信

用 gh repo view 查这个仓库，description 竟然是：

“A simple Python Pydantic model for Honkai: Star Rail parsed data from the Mihomo API.”

一个代理核心的描述怎么会是”崩坏星穹铁道 Python 库”？但分支列表（Alpha、Meta、Mitm…）分明是 Clash 系结构。读 Alpha 分支的 README 才确认：这就是 mihomo 本体（”Another Mihomo Kernel”），description 是被改过的。教训：仓库元数据（description/topics）不可信，以代码内容为准。

2. Alpha / Meta / main 三分支的关系

按用户要求忽略 main，重点看 Alpha 和 Meta：

Alpha：最新提交分支，最新特性，官方文档站的默认分支
Meta：定期合并 Alpha 的代码——文档 FAQ 明说”Meta 不一定比 Alpha 更稳定”
生产部署选 Release 稳定版（v1.19.29），不追分支

3. 文档站学习（wiki.metacubex.one）

把安装、手册、配置、APIs 四个板块全过了一遍，最有价值的收获：

安装：Linux 二进制 + systemd 服务模板（带 CAP_NET_ADMIN 能力配置）、官方 Docker 镜像
配置：proxy-providers（订阅）、proxy-groups（select/url-test/fallback）、rules（DOMAIN/GEOIP/逻辑规则）、dns（防污染/fake-ip）
API：/configs 热重载、/proxies 切节点、/traffic 实时流量
坑：文档站的 handbook/route 页还是”画饼”状态（页面标题就叫画饼😅）

部署：踩了三个坑

第 0 步：用户的 config.yaml 骨架

用户提供了精简的 config.yaml（30 行骨架）：

mixed-port: 7890
external-controller: 127.0.0.1:9090
external-ui: ui
mode: rule
proxy-providers:
  airport:
    type: http
    url: "订阅链接"      # ← 只差这里
    interval: 86400
    path: ./airport.yaml
proxy-groups:
  - name: 节点选择        # select 手动
  - name: 自动选择        # url-test 自动测速
rules:
  - GEOIP,CN,DIRECT      # 国内直连
  - MATCH,节点选择        # 其余走代理

设计非常合理：只留骨架，订阅和规则分离，以后换机场只改一行。

坑 1：订阅格式迷雾

用户的订阅链接 ?profile=simple 返回的是 base64 编码的文本（V2RayN 格式，文件名就叫 V2RayN.txt）。我以为要自己写转换脚本（base64 解码 → 解析 vmess:// → 转 clash 格式），甚至写了两版解析脚本。

后来才发现：解码后的内容本身就是完整的 Clash YAML（mixed-port、proxies:、hysteria2 节点），而且 mihomo 的 proxy-provider 会自动解码 base64 订阅——直接把 URL 填进去就行，什么都不用转换。我白写了两版脚本（不过那套按行容错解码的思路倒是成了经验）。

教训：先验证工具能力，再动手写代码。mihomo 对机场订阅的兼容性比想象中好得多。

坑 2：GeoIP 数据库（鸡生蛋问题）

第一次启动 mihomo，端口没起来，日志停在：

1	Can't find MMDB, start download

mihomo 首次运行要从 GitHub 下载 geoip.metadb / geosite.dat（IP 归属地数据库）。这就是经典的”鸡生蛋”：装代理是为了解决 GitHub 网络，但代理自己要先从 GitHub 下载数据。

解法：用 GitHub 加速镜像（ghfast.top）手动下载两个文件放到工作目录：

1
2

curl -L -o geoip.metadb "https://ghfast.top/https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geoip.metadb"
curl -L -o geosite.dat   "https://ghfast.top/https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geosite.dat"

坑 3：本地沙箱的误伤

在 Hermes 终端里直接执行 mihomo 二进制，被工具的安全检查误判（”embedded null byte”——把二进制当脚本读了）。解法：写一个 start.sh 启动脚本再执行，绕过误判。

服务化

部署在 NAS 上一个独立的数据目录里（下称 <mihomo-dir>），用 systemd 托管（开机自启、崩溃自动重启）：

[Unit]
Description=mihomo Daemon
After=network.target

[Service]
Type=simple
User=<运行用户>
ExecStart=<mihomo-dir>/mihomo -d <mihomo-dir>
Restart=on-failure

[Install]
WantedBy=multi-user.target