# 升级指南：v1.15.0 → v1.16.0

---

## 本次升级带来了什么

### 1. 对话历史加载更快

旧版本通过 SQLite 视图实时解析 JSON 获取对话记录，每条消息需要 13 次以上的 JSON 解析。新版本使用独立的对话记录表，直接读写结构化数据，**历史加载速度显著提升**。

### 2. Token 用量更准确

旧版本的输入 Token 统计遗漏了缓存相关的 Token（Cache Write / Cache Read），导致显示的用量低于实际消耗。新版本将三类 Token 独立统计：

| 指标 | 含义 |
|------|------|
| 输入 Token | 发送给模型的原始内容 |
| 缓存写入 | 首次写入上下文缓存的 Token |
| 缓存读取 | 命中上下文缓存的 Token（成本更低） |
| 总输入 Token | 以上三项之和（实际计入用量） |

升级后你会看到**总输入 Token 的数值比之前更大**，这是正常的——之前少算了，现在更准确了。

### 3. 数据自动清理

新增对话记录和事件的自动清理机制。默认保留 **30 天**，超期数据由后台每小时自动清理。你可以通过配置调整保留时长。

---

## 升级前须知

### 历史对话记录

**升级后，升级前产生的对话历史记录将不再可见。** 这是由于底层存储结构的变更：

- 升级前的记录存储在旧的视图中，升级后视图被替换为新表
- 新表从空开始，仅记录升级后产生的对话
- 原始事件数据仍保留在数据库中，不受影响

> 如果你有重要的对话记录，建议在升级前截图或导出。

### Session 状态

- 升级时需要重启 Gateway，正在进行的对话会中断
- 建议在无活跃对话时执行升级

---

## 升级步骤

### 1. 备份数据库

```bash
cp ~/.hotplex/hotplex.db ~/.hotplex/hotplex.db.bak
```

### 2. 执行升级

```bash
hotplex update
```

如果使用手动部署：

```bash
hotplex gateway stop
cp <新版本二进制> <安装路径>/hotplex
hotplex gateway start
```

### 3. 验证升级成功

- Gateway 启动日志无错误
- 通过飞书或 WebChat 发送一条消息，确认正常响应
- 发送第二条消息，确认能加载之前的对话历史

---

## 配置选项

### 对话记录保留时长

默认保留 30 天。如需调整，在 `config.yaml` 中添加：

```yaml
events:
  retention: 720h  # 720h = 30 天，可改为 168h（7天）、2160h（90天）等
```

修改后重启 Gateway 生效。

---

## 回滚

如需回退到 v1.15.0：

```bash
hotplex gateway stop
cp ~/.hotplex/hotplex.db.bak ~/.hotplex/hotplex.db
cp <旧版本二进制> <安装路径>/hotplex
hotplex gateway start
```

> 回退后，升级期间新产生的对话记录将丢失，但备份数据库中的记录会恢复。
