# 在线升级机制 — 技术路线与安全红线

## 当前状态

预留接口已就位（`/api/upgrade/check`），完整实现在后续版本交付。

## 优雅重启技术路线

采用标准库组合方案，禁止引入已停止维护的第三方库（如 grace、endless）：

```
方案 A（推荐）：http.Server.Shutdown + fd 继承
  1. 新进程启动，监听同一端口（SO_REUSEPORT）
  2. 旧进程调用 http.Server.Shutdown() 停止接收新连接
  3. 旧进程等待活跃请求处理完毕后退出

方案 B：SO_REUSEPORT
  1. 新旧进程同时绑定同一端口
  2. 内核自动分配连接到两个进程
  3. 旧进程优雅退出
```

## 升级安全红线（不可跳过）

1. **包签名验签** — 升级包必须使用 Ed25519 非对称签名，客户端验证公钥
2. **升级前自动备份** — 数据库 + 配置文件 + 二进制文件备份，备份文件保留 3 个版本
3. **回滚预案** — 每次升级前必须验证回滚流程可用，回滚时间 < 5 分钟
4. **Checksum 校验** — SHA-256 校验升级包完整性
5. **灰度发布** — 生产环境升级必须先灰度 1 台，观察 15 分钟无异常再全量
6. **版本兼容** — 跨主版本升级必须逐级升级（v1→v2→v3），不可跳级
7. **数据库迁移** — 升级包内嵌迁移脚本，升级时自动执行，失败则整体回滚

## 接口契约

```
GET /api/upgrade/check
Response:
{
  "current_version": "0.1.0",
  "latest_version": "0.2.0",
  "available": true,
  "critical": false,
  "manifest": {
    "version": "0.2.0",
    "min_version": "0.1.0",
    "download_url": "https://...",
    "changelog": "...",
    "checksum_sha256": "...",
    "size": 12345678,
    "published_at": "2026-10-01T00:00:00Z",
    "critical": false
  },
  "checked_at": "2026-10-02T12:00:00Z"
}
```