# 服务器修复操作单（MySQL 兼容 + 下载通道）

> 适用场景：你已经在宝塔上跑起了服务（`pm2 status` 显示 `avc` 为 online），
> 但在**安装向导的建表步骤**卡在 MySQL 不支持 `JSON` 类型。
>
> 目标：用**最短路径**把服务器修好，不需要重装、不需要改任何配置。

---

## 一、先确认服务器现状

宝塔 → 终端：

```bash
pm2 status                  # 应为 avc / online
curl http://127.0.0.1:3000/api/health
```

期望返回：

```json
{"ok":true,"status":"up","version":"1.1.6", ...}
```

**只要 `ok:true`，说明代码与服务都正常，唯一问题就是建表 SQL 用了 MySQL 5.7 才支持的 `JSON` 列类型。**

---

## 二、二选一：怎么把修复送上去

### 方案 A：一步到位重装（推荐，最省事）

不用管旧文件，直接覆盖代码：

1. 宝塔 → **文件** → 进入 `/www/wwwroot/v.abcxcx.com/`
2. **删掉旧的 `auto-video-cut` 目录**（或先改名成 `auto-video-cut.bak` 兜底）

   > 注意：`data/` 目录里如果有你自己的数据要保留，先把它复制出来。
   > 但你现在还没装成功，`data/` 基本是空的，直接删无妨。

3. **上传** `avc-install-20261013-v3.zip` → **解压**
4. 终端里：

```bash
cd /www/wwwroot/v.abcxcx.com/auto-video-cut
npm install --omit=dev --registry=https://registry.npmmirror.com
pm2 delete avc 2>/dev/null
pm2 start server/index.js --name avc
pm2 save
```

5. 浏览器打开 `https://你的域名/install.html`，重新走安装向导 → **这次建表会成功**

### 方案 B：不重装，只打补丁（30 秒）

如果你不想重传整个包，就在现有服务器上直接改那两行：

```bash
cd /www/wwwroot/v.abcxcx.com/auto-video-cut

# 把 JSON 列类型换成 LONGTEXT（MySQL 5.5+ 都支持）
sed -i 's/data JSON NOT NULL/data LONGTEXT NOT NULL/g' server/lib/schema-sql.js
sed -i 's/data JSON NOT NULL/data LONGTEXT NOT NULL/g' migrations/001_init.sql

# 确认改成功（两条都应输出非 0 数字）
grep -c "LONGTEXT" server/lib/schema-sql.js
grep -c "JSON NOT NULL" server/lib/schema-sql.js     # 这个应该是 0

# 重启
pm2 restart avc
```

然后回浏览器**重新点「开始安装」**即可。

> 建表语句是幂等的（`CREATE TABLE IF NOT EXISTS`），已建成功的表不会重复建，
> 所以中途失败后直接重试是安全的。

---

## 三、为什么改成 LONGTEXT 是安全的

| 对比项 | `JSON` 列 | `LONGTEXT` 列 |
|---|---|---|
| 最低 MySQL | 5.7 | 5.5 |
| 存储方式 | MySQL 内部二进制 | 纯文本 |
| 读写方式 | 驱动层存字符串 / 读时 `JSON.parse` | **完全一样** |
| 依赖 MySQL JSON 函数 | 否 | 否 |
| 功能损失 | — | **无** |

本系统读取这些列时走的是驱动层 `parseData()`（就是 `JSON.parse(字符串)`），
**从来不调用 MySQL 的 `JSON_EXTRACT` / `JSON_SET` 等函数**，
所以换列类型不会影响任何业务逻辑。

---

## 四、装完之后：反向代理别忘了

安装向导能打开，说明反代已经通了。但**上传大文件可能被 Nginx 拦**，
建议在 宝塔 → 网站 → 设置 → **反向代理** 的配置文件里补一行：

```nginx
client_max_body_size 200m;
```

改完保存、重启 Nginx。

---

## 五、以后升级怎么走

### 生成升级包（在 WorkBuddy 沙箱或你本地开发机）

```bash
# 自动模式：按 sha256 指纹算出「这次改了哪些文件」，推荐日常用
npm run build:upgrade:auto

# 清单模式：明确知道改了哪几个文件时用，包最小
npm run build:upgrade

# 全量模式：兜底，或大版本跨越
npm run build:upgrade:full
```

产物在项目同级目录（`avc-upgrade-<日期>-v<序号>.zip` + `latest.json`）。

### 上传到服务器

宝塔 → 文件 → 进入 `auto-video-cut/upgrade/incoming/` → 上传 zip 和 `latest.json` → 后台「系统升级」页点检查即可。

**本次交付的 `avc-upgrade-20261013-v3.zip` 是全量包**，
即使你现在是 1.1.6，也能一口气升到 1.1.9，不用中间过渡版本。

---

## 六、本次交付清单

| 文件 | 大小 | 用途 |
|---|---|---|
| `avc-install-20261013-v3.zip` | 392 KB | **全新安装用**（含 MySQL 兼容修复） |
| `avc-upgrade-20261013-v3.zip` | 395 KB | **已有站点升级用**（全量包，1.1.6 → 1.1.9） |
| `latest.json` | 1.6 KB | 升级源索引，与升级包一起上传 |

**SHA256 校验**（上传后可核对，确保文件没传坏）：

```
eb1d5ef64cda719e83255abc946b5bed724b19e419a28dfd19f65535848f2727  avc-install-20261013-v3.zip
2b97f6bbae3962bb820f794bb098e482750d5724a363c64d2c17cc35c4bde7e4  avc-upgrade-20261013-v3.zip
```

服务器上核对：

```bash
sha256sum avc-install-20261013-v3.zip
```

---

## 七、版本变更摘要（1.1.6 → 1.1.9）

| 版本 | 内容 |
|---|---|
| 1.1.7 | 网页版创作页「清空」按钮增加确认提示，防误触丢文案 |
| 1.1.8 | 小程序创作页与网页版对齐：新增「清空」（带确认）+「文案库」入口 |
| 1.1.9 | **MySQL 兼容修复**：`JSON` 列类型 → `LONGTEXT`，支持 MySQL 5.5+ |

> 1.1.8 涉及小程序改动，升级后到后台「小程序端」页**重新下载代码包**导入微信开发者工具上传发布。