Skip to content

v4.8.0

Choose a tag to compare

@adaex adaex released this 12 Sep 02:55
· 272 commits to main since this release
v4.8.0
a3b445f

清掉 CODE_REVIEW 挂着的三条服务并发缺陷(并顺着同族形态又找出三处),补齐三处用户侧缺口,并把发布可追溯性补上——此前 78 个 npm 版本一个 tag 都没有。单测 325(+24)。

新增

  • mihomo config [--json]:查看当前生效的运行配置。重新推导而非读 runtime/config.yaml——那个文件在 stop 时被 clearRuntime() 整个删掉,而「停着的时候看看配置对不对」恰是最需要它的场景;改完订阅或覆写想确认结果,也不必先把服务跑起来。推导走 buildConfig(与 start 同一条路径,故看到的就是启动会写进去的内容),刻意不调 prepareConfigForStart——那会执行内核原生校验,而这是只读展示命令,校验归 doctor 和 start。secret 脱敏后展示。
  • mihomo completion uninstall <shell>:补全此前只能装、不能卸。bash 写的是共享文件 ~/.bash_completion,故只剥掉自己的标记块、保留用户自己的补全(文件因此变空则一并删掉,避免装卸往返留下空文件);zsh/fish 独占文件名可以整个删,但删之前先确认那是本工具生成的(按脚本特征串判断),否则报错并给出手动路径——误删用户自己写的同名补全比留个孤儿文件糟得多。
  • Node 版本运行时守卫:package.json 的 engines 只让 npm 打一行 warn 就装上了,之后炸在某个语法或 API 上,报错与真实原因(Node 太旧)毫无表面关联。下限从 engines.node 读(单一来源,不另写常量),与平台/root 守卫同族、同一份豁免名单(help/version 必须能跑,否则用户连「装的是哪个版本」都问不出来),并同样排在 ensureDirs 之前——否则旧 Node 上会先建出一套数据目录再报错。

文档

  • 补上彻底卸载的顺序陷阱:先 npm uninstall -g 会留下带 KeepAlive 的 LaunchAgent plist 与已装的补全,而能清理它们的命令已经没了。给出反了之后的手动补救步骤(已逐条核对 label、域与路径)。

仓库

  • 补录 78 个历史 tag:此前仓库一个 tag 都没有,78 个 npm 版本无法定位源码,CHANGELOG 的记录也指不到代码。落点取「该版本号在 package.json 中存活、且提交时间不晚于 npm publish 时刻」的最后一个提交——直接取「该版本最后一个提交」会让 10 个 tag 指向发布之后才写的代码。规则唯一确定 74 个,4 个早期版本(先发后推,提交晚于 publish 2–7 分钟)回退取首个提交并在 tag message 注明;1.5.2 已被 unpublish,不打。
  • 为 v4.x 建 19 个 GitHub Release,正文取自 CHANGELOG 对应小节;v4.2.2 当时未留记录,改用提交主题成文并标注该缺口。
  • 新增 SECURITY.md(支持范围、私密上报渠道,以及内核下载校验、controller 鉴权、订阅凭据存放、提权范围这几条信任边界的实际实现)与 dependabot 配置(npm + github-actions,weekly)。
  • 修掉 package-lock.json 长期停留在 4.7.1 的版本号漂移。

修复

  • 并发的停止在六条路径上仍会被覆盖或被误报。v4.7.7 把并发判据换成停止计数后,CODE_REVIEW 里挂着三条静态发现的残留缺口;本轮逐条修掉,并顺着同一族形态又找出三处。共同签名是递增点与消费点没有成对枚举——收口的对象是判据,不是调用点。

    「停止被静默覆盖」类(终态与用户最后一条命令相反,而两个终端都拿到成功回执):

    • stop 的两条提前返回一次都不记账。「不在运行」(未装载、且未安装或已 disabled、无内核进程)与「只杀游离内核」都成功返回却不碰 disableServiceAutoStart,于是对并发的 start 完全隐形。前者的前置恰是最常见的组合:上次 stop/tun 留下 disable 位,A 正在 start 的慢速阶段(订阅更新约 10s),B 此时 stop 走的就是这条。
    • reset 在服务未装时删掉运行前提也不记账。reset logs/runtime/kernel/subs 在 serviceActive 为假时不走 stopService,却已经把 runtime/config.yaml 或 kernel/ 删掉——并发的 start 随后 bootstrap 一个内核已被删除的 plist,落进 KeepAlive 每约 10s 拉起一次的崩溃循环。
    • restartService 的回退启动没有防线。kickstart -k 失败后回退 enable + bootstrap,与 startService 是同一动作却少了同一道判据,而热重载探测加 kickstart 最长可达 60s。
    • installService 的恢复分支快照取得太晚。取在 bootoutService() + waitUntilUnloaded()(最多 5s)之后。更关键的是 stopService 在自己的锁内先递增、之后才等卸载,所以存在「B 已递增而 launchctl print 仍报 running」的区间:cmdInstall 会合理地读到 wasRunning=true,而在 bootout 之后现取的快照必然已经 ≥ B 的值,并发就此隐形。快照改由命令层传入。

    「把用户自己的停止报成内核故障」类(终态正确,但报错指向完全错误的排查方向):

    • bootstrap 成功到健康确认结束的 1.2–3s 完全在锁外(SERVICE_OBSERVE_MS + GRACE),v4.7.7 的防线只覆盖了锁内那一瞬。这段窗口在最常走的 mihomo start 路径上,且比上面几条都长:期间的 stop 把任务 bootout,waitServiceHealthy 于是走 !loaded 分支,用户拿到「内核未能进入运行状态」加一段与问题无关的日志尾部。cmdInstall 的恢复运行确认有同样的暴露,此前会报「恢复运行失败」。两处都改为失败后复读计数再下结论。
    • 取消文案本来就不实:递增点不止 stop,tun 与 install 首装同样会关闭自启并递增,而文案写死「另一个终端执行了 mihomo stop」——说的是一件没发生的事。改为「检测到停止操作」并说明哪些命令会关闭自启。

    判据仍是唯一那份 shouldAbortStartOnDisable,本轮只增加消费点、不新增判据。不变式不是放宽而是承认第二种同等强度的证据:递增只发生在「已确认不会自启且无内核在跑」之后,证据可以是复核过的 disable,也可以是刚读到的状态本身(这些读取失败时都抛错而非降级,故「走到了这条路径」本身就是独立依据);因此调用点必须放在该路径最后一道失败检查之后——抢在前面就会让一次失败的停止把并发的 start 白白中止。新入口取名 recordServiceStopped 而非 …Intent:叫「意图」会引来「那就在 cmdStop 开头记一次」的改法,那正是要防的。

    launchOrRestart 的 stopEpochBefore 由可选改为必填:可选默认值会让新调用方静默退化成「只防本函数执行期间的 stop」,而这正是本轮六条缺陷的共同形态。

变更

  • 删除 quickstart.sh,只维护 TypeScript CLI 的下载、配置和启动流程
  • 配置语义交给已安装的 mihomo -t 校验,通过后才替换运行配置;删除 CLI 中自动删节点、分组、规则和注入 exclude-filter 的逻辑,错误配置需显式修正
  • 不再生成三份分阶段调试 YAML,只保留最终 config.yaml,校验临时文件用后清理
  • 简化 reset 为明确执行阶段,删除回调与目标顺序约束;部分覆写重置恢复默认开启,删除失败报错,内核不存在时仍清理下载残留
  • 移除 settings 进程缓存,保留原子写与持锁读改写,空补丁不创建或重写文件
  • 删除 daemon/up/down 墓碑、log 过渡别名、reset daemon 及旧选项专用迁移分支;未知输入统一报错,布尔开关拒绝附带值
  • 删除未使用的配置中间类型与状态字段;status JSON 的 ports 仅保留 mixed/tun
  • 保留必要的 root 服务清理、launchd 健康确认与文件锁;同步精简开发文档和发布流程中的旧实现说明

验证

  • 更新配置、设置并发与 reset 的行为测试;reset 测试同时隔离数据目录和服务 label
  • 用 mihomo v1.19.30 验证 Mixed/TUN 配置以及重名节点、缺失引用等拒绝场景,确认失败保留原有运行配置
  • 单测 325(+24)。新增 commands/stop.spec:隔离数据目录加不存在的服务 label 天然走「不在运行」分支,一次 launchctl 写操作都不做,故这条能自动化;断言消费者可见的后果而非计数文件内容,并含负向对照(status 不得改变计数)。游离内核用真实桩进程验证,判活以 ps 状态列为准而非 kill -0(僵尸进程会骗过它)
  • 新增 commands/node-guard.spec(伪造 process.versions.node 而非真装旧 Node——真旧 Node 连 tsx 都未必起得来,反而测不到守卫)、commands/completion-install.spec(把 HOME 指向临时目录跑真实装卸,断言文件最终内容:用户自有内容完好、标记块消失、非本工具产物拒绝删除)、commands/config.spec(全部在没有 runtime/config.yaml 的目录里跑,锁住「重新推导」这一性质;输出用 js-yaml 实际解析,确认是合法 YAML 且 secret 已脱敏)
  • 三种 shell 的补全脚本经 zsh -n / bash -n 语法校验;fish 未装,其脚本未做语法校验
  • 复核测试有效性:临时注掉两处 recordServiceStopped,两条用例即转红
  • install 恢复与 restart 回退的并发交错仍只能手工双终端复现(需真装内核的机器),已记入 CODE_REVIEW 的未覆盖项,未假称已自动化

npm: https://www.npmjs.com/package/mihomo-cli/v/4.8.0