# 升级报 `Cannot find module 'mysql2/promise'` 怎么办

## 报错长什么样

后台点「执行升级」后，在「数据库迁移」这一步失败：

```
✗ 数据库迁移
发生错误：Cannot find module 'mysql2/promise'
  Require stack:
  - /www/wwwroot/v.abcxcx.com/server/lib/upgrade/db-markers.js
  - /www/wwwroot/v.abcxcx.com/server/lib/upgrade/index.js
  - /www/wwwroot/v.abcxcx.com/server/index.js

开始回滚文件…
已回滚 103 个文件
版本锚点已回退到 1.1.11
```

---

## 为什么会这样

升级包里的**数据库迁移引擎**要连接 MySQL 执行 `ALTER TABLE` 之类的结构变更，
它依赖 `mysql2` 这个 npm 包。

你的站点目录（`/www/wwwroot/v.abcxcx.com/`）**没有安装这个依赖**，
所以在迁移步 `require('mysql2/promise')` 直接抛错。

> ⚠️ 注意：这不是你的操作问题，而是包的健壮性缺陷 ——
> 而且这个错误发生在**文件替换之后**，会触发整包回滚，
> 导致「明明文件都换好了又被退回去」，反复升级永远升不上去。

---

## 一条命令解决

SSH 登录服务器，进入站点目录执行：

```bash
cd /www/wwwroot/v.abcxcx.com/
npm install mysql2 --registry=https://registry.npmmirror.com
```

> `--registry=...npmmirror.com` 是淘宝镜像，国内服务器必须加，否则会卡在下载超时。

装完确认一下：

```bash
ls node_modules/mysql2/package.json && echo "✓ mysql2 已安装"
```

然后回后台 →「系统升级」→ 重新点执行升级即可。

---

## v9 包已经做了加固

从 **1.1.14** 起（对应包 `20261013-v9`），这个问题不会再导致升级失败：

| 改动 | 效果 |
|---|---|
| 迁移引擎加 `allowSkip` 降级模式 | 缺 `mysql2` 时**跳过结构迁移并告警**，不抛错 |
| 升级编排在前置检查阶段探测依赖 | 一开始就在日志里给出安装命令提示 |
| 迁移步显示为「已跳过 N 项（缺少 mysql2 依赖，待补做）」 | 不再静默通过，你能看见 |

**关键点**：数据库迁移本身是**幂等**的 ——
`_avc_migrations` 表会记账每条迁移的名称和校验和，
所以补装 `mysql2` 之后，**重新执行同一个升级包即可补齐**被跳过的那几项，
不会重复执行、也不会产生副作用。

---

## 顺带检查：你到底该不该用 MySQL 模式

如果站点其实用的是本地文件存储（`data/db.json`），
根本不会走到这段代码，也就不会报这个错。

确认当前存储模式：

```bash
cd /www/wwwroot/v.abcxcx.com/
cat config/cloud.json 2>/dev/null || echo "（无 cloud.json，说明是本地 JSON 存储模式）"
```

- 输出里的 `"driver": "mysql"` → 确实需要 `mysql2`
- 文件不存在或 `"driver": "local"` → 本地模式，报这个错说明升级包里
  `cloud-config` 读取异常，请把 `config/cloud.json` 内容发我看

---

## 升级完成后别忘了

```bash
pm2 restart avc
```

v9 包含服务端改动（迁移引擎与升级编排本身），不重启的话新逻辑不生效，
下次升级还会走老代码。