feat(local): 依赖安装自愈:源探测 + 换源重试 + 本地缓存 + 看门狗

国内网络下首装依赖最容易卡死,启动器现在自己处理,用户不用懂环境:

- 自动选源:并行探 npmmirror 与官方源(各 3s 超时)取最快,缓存一天;
  只在命令行传 --registry,不写 ~/.npmrc、不改用户全局配置。
- 换源重试:公共源之间自动互换,换源成功即记住;显式指定或公司私有源不兜底
  (乱兜底可能装错东西)。重试前清掉半成品 node_modules。
- 本地缓存:装成功后把 node_modules 打成
  ~/.cache/agent-local/deps-<平台>-<架构>-abi<ABI>-<依赖哈希>.tgz,
  重启/删 node_modules/换 clone 都解压恢复(零网络),只留最近 3 份。
- 看门狗:npm 10 + Node 22 断网时既不报错也不退出(Exit handler never called),
  超过 AGENT_LOCAL_NPM_TIMEOUT(默认 240s)直接 SIGKILL 整棵树再换源。
- 报错翻译:状态页只显示「网络没通 / 缺编译工具链 / 没有写权限 / 源没响应」,
  npm 原文仍完整落 npm-install.log。

同时修掉两个埋着的 bug:

- kill_tree 先把参数赋给变量再递归,POSIX sh 无局部变量导致递归覆盖,
  回到外层 kill 的是子进程,留下 PPID=1 的孤儿 npm。改为只用 $1。
- 看门狗不能先 TERM:TERM 先杀掉外壳会让 npm 变孤儿,kill -0 判不到。
  改为直接递归 SIGKILL(先子后己)。

全部改动只在 local/ 与文档,app/ 未动。
This commit is contained in:
2026-11-11 12:16:35 +08:00
parent f451027729
commit b5cfa36832
3 changed files with 339 additions and 41 deletions
+30
View File
@@ -213,6 +213,32 @@
改成先看 `supervisor.pid`(子进程一启动就写,秒级就绪;`kill -0` + 命令行含 `start.sh` 防 pid 被回收),
health 只作为「端口上有服务但不是本启动器拉起的」兜底提示。
### 4.12 依赖安装:源探测 + 换源重试 + 本地缓存(只在 `local/` 里做)
首装联网是逃不掉的,但「哪个源能用、卡住了怎么办」不该让用户想。启动器的策略:
1. **已装齐 → 不联网**(逐包检查 + `.agent-installed` 时间戳,见 4.10);
2. **缓存命中 → 解压**:装成功后把 `node_modules` 打成
`<平台>-<架构>-abi<ABI>-<依赖哈希>.tgz` 放 `~/.cache/agent-local/`;原生模块与 ABI 绑定,
所以文件名必须含 ABI(`process.versions.modules`)。换 clone / 删 `node_modules` 都走这里,
秒级且零网络;只留最近 3 份。
3. **缓存未命中 → 选源安装**:并行探 `npmmirror` 与官方源(各 3 秒超时),取最快的;
结果缓存一天。**只用命令行参数传源,绝不写 `~/.npmrc`**。
4. **失败换源**:仅当用的是公共源(npmmirror / 官方)时换下一个重试,换源成功就记住;
用户显式指定或公司私有源不兜底(乱兜底可能装错东西)。重试前先删半成品 `node_modules`。
5. **看门狗**:npm 10 + Node 22 在断网时既不报错也不退出(已知的
`Exit handler never called`,实测卡死超过 2 分钟),所以每次 `npm install` 都带超时,
超时就 `SIGKILL` 整棵树再换源。
6. **报错翻译**:把 npm 原文归成「网络没通 / 缺编译工具链(`xcode-select --install`)/
没有写权限 / 源没响应」,状态页只显示这一句,原文仍完整落在 `npm-install.log`。
两个容易踩的实现细节(都踩过):
- `kill_tree` 不能把参数先赋给变量再递归:POSIX sh 没有局部变量,递归会覆盖它,回到外层
kill 的是子进程而不是原本那个。
- 看门狗只用 `SIGKILL`:先 `TERM` 会先干掉外壳让 npm 变成孤儿(`PPID=1`),`kill -0` 判不到,
再想硬杀就找不到它了。
## 5. 验证结果(macOS 12.7.6 / x86_64 / Node 22.21 / python3 3.10 / 本机无 ffmpeg)
静态检查:`sh -n local/start.sh`、`sh -n local/stop.sh`、`node --check` 均通过。
@@ -235,6 +261,10 @@ health 只作为「端口上有服务但不是本启动器拉起的」兜底提
| `stop.sh`:命中 pid 文件分支;pid 文件丢失时按 core 父进程/端口也能停;未运行时幂等返回 | 通过 |
| 重复执行 `start.sh`:打印「已在运行(启动器 pid N)」+ 停止命令,exit 0,不起第二个进程 | 通过 |
| 启动器被 `kill -9` 后的恢复:残留 pid 文件被清理,端口仍被占时明确提示先 `stop.sh` | 通过 |
| 依赖源自动探测:删依赖后启动,自动选中 `registry.npmmirror.com`(本机 npm 全局源也是它),状态页显示「依赖源」 | 通过 |
| 依赖缓存:装成功后生成 `~/.cache/agent-local/deps-...tgz`;删掉 `node_modules` 重启,日志为「使用本地依赖缓存」、`npm-install.log` 为空(零网络) | 通过 |
| 换源自愈:把缓存里的源改成不可达地址 → 看门狗超时 → 自动换到 npmmirror 装完,缓存里的源被改回可用值 | 通过 |
| 失败翻译:源不可用 + 冷 npm 缓存 → 状态页标题「依赖安装失败」、提示「源没有响应…(已自动换源重试)」,无 npm 残留进程 | 通过 |
| 前台模式 `AGENT_LOCAL_DETACH=0`:阻塞运行,`TERM` 后端口全部释放 | 通过 |
| 无 node(PATH 里剥掉 node/npm):入口直接拦下,**不** 先让选目录、不生成配置;终端打出安装方式;状态页列出自检项(X Node.js / X npm) | 通过 |
| 失败时只开一个状态页标签(不再两个) | 通过 |