升级与备份

升级必须同时考虑程序、数据库、配置与在途任务。只保留旧镜像，不代表能够安全回滚已经迁移过的数据库。

记录当前状态

记录运行版本、代码提交或镜像标签、Compose 项目名、主库与日志库类型、数据卷、挂载目录和关键环境变量。密钥保存在受控位置，不要粘贴到工单。

检查变更说明，特别是数据库迁移、认证变化、插件 API 和计费规则。先在恢复出的测试环境验证，再安排正式维护窗口。

备份范围

对象	要保存什么
主数据库	用户、渠道、令牌、配置和其他业务数据
独立日志库	需要保留的用量与审计相关数据
配置	Compose、环境文件、代理配置与密钥
数据挂载	插件、持久化产物等实际落盘内容
版本信息	可恢复的程序、镜像和插件版本

对备份加访问控制，保存到与主机故障隔离的位置，并验证可以恢复。数据库备份可能包含凭据，不应公开上传。

SQLite 备份

最容易理解的方式是停止所有使用该 SQLite 库的实例，再保存整个相关数据目录，而不是只取主 .db 文件：

docker stop ai-gateway
# 备份实际挂载的数据目录，并确认备份完成
docker start ai-gateway

备份过程使用你已有的备份工具，保留目录权限。在线备份应使用 SQLite 提供的一致性备份能力；普通复制不能保证把 WAL 中的数据完整带走。

PostgreSQL / MySQL / ClickHouse

使用对应引擎支持的备份方案，按部署拓扑决定一致性、写入暂停和恢复策略。主库与日志库分开时，两者都应评估。数据库版本、表规模和备份账号权限会改变命令，不能把示意命令当成通用恢复方案。

备份成功的最低证据是可以在隔离实例恢复并核对代表性数据，而不是仅看到生成了一个文件。

升级步骤

1. 完成备份与恢复验证，确认维护窗口。
2. 处理在途任务并停下需要暂停的写入与后台工作。
3. 检出计划版本，保留现有 Compose 项目名与数据卷。
4. 构建并启动新版本，观察启动与迁移日志。
5. 检查管理员登录、渠道测试、普通用户调用和任务查询。
6. 再次重启并检查日志，确认运行状态与配置保持稳定。

源码构建的 Compose 实例可在相应版本目录执行：

docker compose config --quiet
docker compose up -d --build ai-gateway
docker compose logs --tail 200 ai-gateway

回滚边界

数据库已发生不兼容迁移时，不能只启动旧程序继续使用新库。应按已验证的恢复方案恢复匹配版本的数据和配置。不要执行 down -v，也不要随意更名现有数据库来追随品牌命名；配置注释中的迁移提醒同样适用。