# 后台自动检查更新 —— 配置说明

> 版本要求：**1.1.12 及以上**

---

## 一、效果是什么

登录后台后，系统会**自动静默检查一次**升级源。发现新版本时，「系统升级」Tab 上会直接出现红色角标：

```
[ 用户账户 ] [ 兑换码 ] [ 订单 ] [ 生成记录 ] [ 系统设置 ] [ 小程序端 ] [ 系统升级  新版本 1.1.13 ]
```

不需要手动切进去点「检查更新」——打开后台就能看到。

本地 `upgrade/incoming/` 里放了升级包的话，同样会提示（显示「有 1 个待安装包」），**这种情况不需要配升级源**。

---

## 二、配置步骤（一次性）

### 1. 准备一个能放文件的静态目录

四选一，看你哪个方便：

| 方案 | 说明 | 适合 |
|---|---|---|
| **下载站（推荐）** | 直接填下载站地址。本机 `npm run push` 发的包就挂在这儿，**不需要任何云存储凭据** | 最省事 |
| **阿里云 OSS** | 你已经在用 OSS，直接建个目录放升级包 | 站点后台「一键发布」用这个 |
| **服务器本地目录** | 用宝塔建个静态站点，把包放进去 | 不想动 OSS 就用这个 |
| **GitHub Release** | 建一个公开仓库发 Release | 公开项目适用 |

> **下载站方案怎么用**：本机执行 `npm run push`，包会自动切分片、发到下载站，
> 同时生成 `latest.json`。然后把下载站地址填到下面第 3 步即可。
> 详见《一条命令发版手册.md》。

### 2. 上传两个文件到那个目录

- `avc-upgrade-20261013-v8.zip`（升级包本体）
- `latest.json`（索引文件，后台靠它判断有没有新版本）

> 每次发新版，**这两个文件都要一起更新**。文件名不要改。

### 3. 在后台填升级源地址

后台 →「**系统升级**」→「🔗 升级源」：

| 字段 | 填什么 |
|---|---|
| 升级源地址 | 你那个目录的**公网可访问**地址，如 `https://your-bucket.oss-cn-hangzhou.aliyuncs.com/avc-releases` |
| 索引文件名 | `latest.json`（默认，不用改） |

点「**保存升级源**」。

### 4. 验证

点「🔍 检查更新」。看到「已是最新版本」或「发现新版本 X.X.X」就说明通了。

之后每次登录后台都会自动检查（结果缓存 6 小时，不会频繁请求）。

---

## 三、发现新版本后怎么升级

角标亮起后，点「系统升级」Tab：

1. 看到「发现新版本 1.1.13（当前 1.1.12）」，附版本号和更新说明
2. 点「⬇️ **下载到服务器 upgrade/incoming/**」
3. 下载完成并校验通过后，在下方列表点「**安装**」
4. 系统自动：备份 → 替换文件 → 跑数据库迁移 → 校验 → 失败自动回滚
5. 升级完执行 `pm2 restart avc`

---

## 四、不想配升级源？

完全可以。有两种替代方式，**角标照样会提示**：

### 方式 A：手动上传升级包

后台 →「系统升级」→ 点「⬆️ **上传升级包**」→ 选 zip 文件。

上传后本地 `upgrade/incoming/` 会有这个包，下次登录后台角标就显示「有 1 个待安装包」。

### 方式 B：直接用宝塔传

把升级包传到服务器 `/www/wwwroot/v.abcxcx.com/upgrade/incoming/` 目录，效果一样。

> 注意：**这种方式的角标提示只能在下次打开/刷新后台时出现**，因为它不联网查询，只扫描本地目录。

---

## 五、关于自动更新的几个细节

| 问题 | 说明 |
|---|---|
| 多久检查一次？ | 每次登录后台检查一次，但**结果缓存 6 小时**，同一浏览器 6 小时内不重复请求 |
| 会拖慢后台吗？ | 不会。检查在页面主体数据加载完之后**异步发起**，失败静默处理 |
| 没配升级源会报错吗？ | 不会。检测到未配置就直接跳过，不产生任何网络请求 |
| 检查失败会弹错吗？ | 不会。网络问题、地址写错等都静默处理，不打扰日常使用 |
| 会自动升级吗？ | **不会**。只提示，升级必须你手动点确认 —— 升级是有风险的操作，不做全自动 |
| 换设备还提示吗？ | 会。缓存基于浏览器，换设备会重新检查一次 |

---

## 六、升级源目录长什么样

```
https://your-bucket.oss-cn-hangzhou.aliyuncs.com/avc-releases/
├── latest.json                        ← 索引（指向当前最新版）
└── avc-upgrade-20261013-v8.zip        ← 升级包本体
```

`latest.json` 内容由打包脚本自动生成，大致是：

```json
{
  "appVersion": "1.1.12",
  "pkgVersion": "20261013-v8",
  "schemaVersion": 2,
  "file": "avc-upgrade-20261013-v8.zip",
  "size": 422297,
  "sha256": "98295c23..."
}
```

后台读到它，对比自己的版本号，就能判断有没有更新。

---

## 七、每次发新版，操作清单

在 WorkBuddy 沙箱里：

```bash
npm run build:upgrade:auto     # ① 自动比对改动生成包
```

产出两个文件（项目同级目录）：

- `avc-upgrade-<日期>-v<序号>.zip`
- `latest.json`

然后：

1. 把这两个文件**传到你的升级源目录**（覆盖旧的）
2. 下次登录后台，角标自动亮起
3. 点进去一键升级

> **关键**：`latest.json` 每次都要跟着更新，否则后台比对不出新版本。