im0o/mihomo-up
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a275e76206aff9b0dc1f8a12d7cc5213c8b6f1b4
mihomo-up/README.md
T
im0oandClaude Opus 5 a275e76206 feat: 加快捷命令 mihomo-up，并按 edit-article / think-twice 过一遍文案 
快捷命令:
- 一键安装会往 /usr/local/bin/mihomo-up 装一个启动器，每次执行先拉最新脚本再跑，
  仓库更新后机器上无需手动更新
- 与纯"每次重新下载"的区别: 落一份缓存到 /var/lib/mihomo-up/，
  拉不到 (断网/仓库挂) 或拉到的内容 bash -n 不过时回落缓存。
  代理管理脚本尤其需要这条 —— 最需要它的时候往往正是网络不正常的时候
- 抓取带 5s 连接 / 20s 总超时；参数和退出码原样透传
- 新增 shortcut 子命令、服务菜单第 8 项、--script-url / MIHOMO_UP_URL
- uninstall 连启动器和缓存一起清理

修复:
- 子命令失败时 ERR trap 会在人话提示后再补一句「第 N 行出错」，看起来像崩了。
  分发点改用 || exit 1 收尾
- --mirror 缓存失败的提示原本描述错了后果，改成照实说
- 升级闸门失败、缺配置两处只给菜单路径，命令行模式下是悬空引用，补上等价命令
- allow-lan 开启时报出具体端口号；管理接口设 0.0.0.0 时补一句暴露后果
- 无效菜单选项说清什么才有效

README:
- 按依赖顺序重排章节: 环境要求提到快速开始之前，快捷命令移到一键安装之后，
  GitHub 镜像移到选项表之前以消掉「见下」悬空引用
- 开头「管三样东西」与实际不符，改为完整清单
- 拆开超过 240 字符的长段

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XpjLPV4JvAsuq9ACb3u6B4
2026-08-09 17:26:57 +08:00

225 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# mihomo-up
一个 bash 脚本，在 Linux 服务器上装好、配好、管住 [mihomo](https://github.com/MetaCubeX/mihomo) 内核（Clash.Meta 的继任者，MetaCubeX 维护的代理内核）。
一条命令从零到能用：下载内核 → 写 systemd 服务 → 用向导生成 `config.yaml` → 启动。之后改订阅、换端口、升级、回滚、卸载也都在同一个菜单里。
装完，这台机器上会多出这几样东西——**卸载时它们全都能一键清掉**：
| | 默认位置 |
|---|---|
| 内核二进制 | `/usr/local/bin/mihomo` |
| 配置文件 | `/etc/mihomo/config.yaml` |
| systemd 服务 | `/etc/systemd/system/mihomo.service` |
| 快捷命令 | `/usr/local/bin/mihomo-up` |
| 脚本缓存 | `/var/lib/mihomo-up/` |
| 内核备份 | `/var/backups/mihomo/` |
除此之外它不碰你系统里的任何东西。
## 环境要求
- Linux + bash 4 以上
- 依赖命令：`curl`、`gzip`、`install`、`awk`、`sed`（一般发行版自带）
- 安装、升级、改配置、卸载都需要 **root**。非 root 也能进菜单，会先提醒一句
- 没有 systemd 的机器（容器等）也能用：脚本跳过服务相关步骤，只管内核和配置，你自己 `mihomo -d /etc/mihomo` 拉起来
交互输入读的是 `/dev/tty` 而不是标准输入，所以 `bash <(curl ...)` 这种 stdin 已被占用的跑法，菜单照样能按键。
## 快速开始
**交互菜单**（推荐，装机和日常维护都用它）：
```bash
bash <(curl -fsSL https://git.im0o.top/im0o/mihomo-up/raw/branch/main/mihomo-up.sh)
```
菜单第 1 项就是一键安装。跑完你会拿到：本机的 HTTP/SOCKS5 代理端口、一个 Web 面板地址和它的访问密钥、一个开机自启的 systemd 服务。
还会拿到一个 `mihomo-up` 命令——**以后直接敲它就能进菜单**，不用再翻上面这条 URL。
**命令行**：
```bash
chmod +x mihomo-up.sh
sudo ./mihomo-up.sh install # 一键安装：内核 + systemd + 配置向导 + 启动
./mihomo-up.sh check # 只查不改：当前版本 vs 最新版本
sudo ./mihomo-up.sh update # 只换内核二进制，配置和服务定义不动
sudo ./mihomo-up.sh config # 重新跑配置向导
sudo ./mihomo-up.sh rollback # 内核回滚到上一个备份
sudo ./mihomo-up.sh uninstall # 卸载，会逐项问你配置和备份删不删
sudo ./mihomo-up.sh shortcut # 只装/刷新 mihomo-up 快捷命令
```
## 菜单里有什么
```
1. 一键安装 内核 + systemd + 配置，缺哪步补哪步
2. 检查更新 3. 升级内核 4. 装指定版本内核
5. 回滚内核 6. 查看内核备份
7. 配置管理 换订阅 / 改端口 / 局域网共享 / 面板密钥 / 导入配置 / 校验 / 编辑 / 备份还原
8. 服务控制 启停 / 重启 / 状态 / 最近日志 / 开机自启 / 重写服务文件
9. 卸载
```
## 一键安装做了什么
1. **下内核**：按机器架构从 GitHub Releases 取对应的 `.gz` 并解压
2. **验内核**：新二进制必须能执行，且 `-v` 自报的版本号和目标一致，否则不落盘
3. **配文件**：没有 `config.yaml` 就跑配置向导；已经有了就保持不动，只问一句要不要重做
4. **写服务**：按 [MetaCubeX 官方文档](https://wiki.metacubex.one/startup/service/)的推荐写 `mihomo.service`。已存在且内容不同的话，旧文件先备份成 `.bak-<时间戳>`
5. **装快捷命令**：问一句，可以拒绝。它是什么见「快捷命令 `mihomo-up`」一节
6. **起服务**：`daemon-reload` → `enable`（开机自启）→ `restart`，起不来就提示你看 `journalctl`
每一步都是「缺什么补什么」：已经装过的机器再跑一遍，不会覆盖你现有的配置。
装完会打印一段总结：代理端口怎么用、面板地址和密钥是什么、日志怎么看。
## 快捷命令 `mihomo-up`
一键安装会往 `/usr/local/bin/mihomo-up` 放一个启动器。它**不是脚本本体，而是每次执行都去拉最新脚本再跑**——你更新了仓库，机器上下次敲 `mihomo-up` 就自动用上新版，不需要谁去手动更新。
```bash
mihomo-up # 进菜单，参数原样透传
mihomo-up check --json # 子命令照样能用，退出码也透传
```
和纯粹的"每次重新下载"不同的是，它会把拉到的脚本落一份缓存到 `/var/lib/mihomo-up/`，并在这两种情况下回落到缓存：
- **拉不到**（网络断了、仓库挂了）。这条对代理管理脚本尤其要紧：你最需要它的时候，往往正是代理挂了、网络不正常的时候，那时候还得能进菜单重启服务、看日志。
- **拉到的东西没通过 `bash -n` 语法检查**（上游推了个坏版本，或者中间设备塞回来一个门户登录页）。宁可用旧的，也不以 root 执行来路不明的半个脚本。
抓取带 5 秒连接 / 20 秒总超时，网络卡住不会让菜单一直转着等。
fork 之后想让快捷命令指向你自己那份，装的时候加 `--script-url <你的 raw 地址>`，或者设环境变量 `MIHOMO_UP_URL`。
> **cron 里别用它**：每次执行都联网拉脚本，等于给定时任务多加一个失败点。定时任务直接指向缓存那份 `/var/lib/mihomo-up/mihomo-up.sh`，或者你自己固定的副本。
## 配置向导问什么
向导生成的是一份**最小可用配置**，够跑，不臃肿：
| 问题 | 说明 |
|---|---|
| 订阅链接 | 机场给的 http(s) 地址，写成 `proxy-providers`，每 24 小时自动更新一次 |
| 本地代理端口 | `mixed-port`，HTTP 和 SOCKS5 共用，默认 7890 |
| 局域网共享 | `allow-lan`，开了同网段其它设备也能连（还要放行防火墙） |
| 管理接口 | 只允许本机 / 局域网公网可访问 / 不开。面板和 API 都连这里 |
| 访问密钥 | 回车即自动生成随机串；管理接口开在 `0.0.0.0` 时务必设 |
| Web 面板 | 选是就写 `external-ui-url`，内核首次启动自己去下载 metacubexd |
| 分流规则 | 全部走代理（默认），或者指定某个国家/地区直连、其余走代理 |
生成的分组是 `PROXY`（手动选，默认跟着 AUTO）和 `AUTO`（自动挑延迟最低的）。规则里内网地址一律直连。
选了「指定国家/地区直连」会额外写一条 `GEOIP,<两位国家代码>,DIRECT`，代码填 `CN`、`US`、`JP`、`DE` 都行，小写会自动转大写。
**改配置不用手写 YAML**：菜单「配置管理」能直接换订阅、改端口、开关局域网共享、改面板密钥。
每次改动之前自动备份成 `config.yaml.bak-<时间戳>`，改完立刻用内核 `-t` 校验。**校验不过会问你要不要还原**，服务在跑的话再问一句要不要重启生效。
需要手写的复杂配置（DNS、TUN、自定义规则）请用菜单里的「手动编辑配置」，或者用「从 URL 导入完整配置」整份换掉——这两条路同样有备份、校验、还原兜底。
## 升级和回滚
`update` 只换内核二进制，不动你的配置和服务定义。替换前有两道闸门，任一不过就中止：
1. 新二进制能跑起来，且 `-v` 自报的版本号和目标一致
2. 用**新版本**去 `-t` 校验你**现有的**配置
第二道是为了挡住「新内核不认旧配置」这种升完才发现的问题。配置本来就有毛病、但你只想换内核时，加 `--skip-conf-check` 跳过它。
替换前旧内核备份到 `/var/backups/mihomo/`（保留最近 3 份）。升级后服务起不来会**自动回滚**到旧版并重启，然后提示你看 `journalctl -u mihomo -n 50`。
任何一步失败都不会留下半个系统：要么没动，要么已回滚。
## 卸载会删什么
```bash
sudo ./mihomo-up.sh uninstall # 逐项确认
sudo ./mihomo-up.sh uninstall --purge # 全删，不问
```
直接删掉：内核二进制、`mihomo.service` 及其备份、`mihomo.service.d/` drop-in 目录、快捷命令和它的缓存。systemd 那边会先 stop 再 disable，然后 `daemon-reload` + `reset-failed` 把状态清干净。
会单独问你的两项：配置目录 `/etc/mihomo`（订阅、节点选择记录、面板文件都在里面）、内核备份目录 `/var/backups/mihomo`。留着的话下次重装能直接接上。
## 在 cron / CI 里用
无参数运行时，脚本会看 stdin 是不是终端：是就进菜单，被管道或 cron 调用就安静地跑 `check`。
`check` 的退出码专为脚本化设计：
| 退出码 | 含义 |
|---|---|
| 0 | 已是最新 |
| 10 | 有新版（或还没安装） |
| 1 | 出错 |
例子——有新版就自动升级：
```bash
mihomo-up.sh check && exit 0
[ $? -eq 10 ] && mihomo-up.sh update -y
```
加 `--json` 会额外输出一行机器可读的 JSON：
```json
{"current":"v1.19.27","latest":"v1.19.28","outdated":true}
```
## GitHub 直连不通时
内核、版本号、Web 面板都从 GitHub 下载。机器直连 GitHub 失败或太慢时，用 `--mirror` 指定一个反代前缀，脚本会把它拼在所有 GitHub 地址前面：
```bash
sudo ./mihomo-up.sh install --mirror https://ghfast.top/
```
带 `--mirror` 跑配置向导时，生成的配置里会额外写上走同一个镜像的 `geox-url`，免得内核首次启动下载 GeoIP 数据库时卡住。
## 选项一览
| 选项 | 作用 |
|---|---|
| `-y, --yes` | 非交互确认，所有询问都当作同意 |
| `-n, --dry-run` | 只打印会做什么，不实际改动 |
| `--force` | 版本相同也重装 |
| `--version <v>` | 指定内核版本，如 `v1.19.28` |
| `--no-restart` | 装完不启动服务 |
| `--purge` | `uninstall` 时连配置目录和备份一起删 |
| `--skip-conf-check` | 升级时不用新版本预校验现有配置 |
| `--json` | `check` 时额外输出一行 JSON |
| `--arch <a>` | 覆盖自动识别的架构：`amd64` / `arm64` / `armv7` |
| `--variant <v>` | amd64 微架构变体：`v1` / `v2` / `v3` / `compatible` |
| `--mirror <url>` | GitHub 反代前缀，用法见上一节 |
| `--script-url <u>` | 快捷命令每次去拉的脚本地址（fork 后指到你自己那份） |
| `--bin <path>` | 内核路径，默认 `/usr/local/bin/mihomo` |
| `--conf-dir <dir>` | 配置目录，默认 `/etc/mihomo` |
| `--service <name>` | systemd 服务名，默认 `mihomo` |
| `-v` | 打印脚本自身版本 |
## 默认值与环境变量
命令行选项优先级最高，其次是环境变量，最后是下面这些默认值：
| 默认值 | 环境变量 |
|---|---|
| `/usr/local/bin/mihomo` | `MIHOMO_BIN` |
| `/etc/mihomo` | `MIHOMO_CONF_DIR` |
| `mihomo`（systemd 服务名） | `MIHOMO_SERVICE` |
| `/var/backups/mihomo` | `MIHOMO_BACKUP_DIR` |
| 空（不用镜像） | `MIHOMO_MIRROR` |
| `/usr/local/bin/mihomo-up`（快捷命令） | `MIHOMO_UP_LAUNCHER` |
| `/var/lib/mihomo-up`（脚本缓存） | `MIHOMO_UP_CACHE` |
| 仓库 raw 地址（快捷命令拉取源） | `MIHOMO_UP_URL` |
内核备份最多保留 3 份（脚本内常量 `KEEP=3`）。配置备份不自动清理，攒多了自己删 `config.yaml.bak-*`。
## 参考
systemd 服务写法来自 [MetaCubeX 官方文档](https://wiki.metacubex.one/startup/service/)。
一键安装和卸载的思路参考了 [ForLoveIcu/mihomo-for-linux-install](https://github.com/ForLoveIcu/mihomo-for-linux-install) 和 [nelvko/clash-for-linux-install](https://github.com/nelvko/clash-for-linux-install)。
Reference in New Issue View Git Blame Copy Permalink