升级与迁移
升级前记录当前版本和目标版本,阅读目标版本的兼容性变化。跨多个版本升级时,执行全部尚未应用的迁移,不能只运行最后一个版本新增的 SQL。
- 备份数据库,确认可恢复路径。
- 根据迁移要求安排维护模式,等待在途请求结束。
- 按编号应用目标数据库对应的待执行迁移。
- 更新匹配版本的 Proxy、Admin 和迁移工具。
- 验证健康、登录、真实请求、日志及额度变化,再解除维护。
具体版本可能要求更严格的切换顺序,不要仅根据本摘要执行跨版本生产迁移。
2.20.0 的升级入口
Section titled “2.20.0 的升级入口”从 2.19.0 升级需要 0036:新增内置 OAuth 授权服务器所需的应用目录、客户端注册与授权请求表,并给 OAuth 访问令牌增加可空列。先执行迁移,再把 Proxy、Admin 和迁移镜像更新到同一版本;旧版 Proxy / Admin 配合已迁移的库可以正常运行。即使暂不启用内置授权服务器,也不能跳过结构迁移。
- 0036:内置 OAuth 授权服务器
- 新增
MCP_OAUTH_ISSUER与可选的MCP_OAUTH_CONSENT_URL;MCP_OAUTH_ISSUER为空时行为与升级前一致。Admin 新增可选的运行时变量GATEWAY_PROXY_URL,用于 REST 文档、模拟器与 MCP 接入的默认 Proxy 地址。 - 调用
/api/admin/oauth/*的集成密钥需要授予oauth.read、oauth.write或oauth.consent。 - 「调用记录」已并入「请求日志」,旧地址
/gateway/tools/invocations会带着筛选跳转过去。 - 新目录项(如
gemini-4-hydrogen、gemini-4-carbon、qwen4-max-preview、minimax-h3-image)需要手工导入并配置路由。 - 切换到内置授权服务器需要在每个部署区单独完成,见 MCP OAuth 授权。完整变更见 v2.20.0 发布说明。
2.19.0 的升级入口
Section titled “2.19.0 的升级入口”从 2.18.0 升级到 2.19.0 没有新增数据库迁移,也没有新增或改名的环境变量与 system_config 键;将 Proxy、Admin 和迁移镜像更新到同一版本后滚动重启即可。从更早版本升级时,仍需补齐其间尚未应用的迁移。
- 维护模式已并入「系统 → 配置」的「维护模式」分区,旧地址会自动跳转;「集成密钥」现在归入「系统」分组。
- 新目录项(如
claude-fable-5-2、glm-5v-turbo、hy4、gpt-image-2.6-flare)需要手工导入并配置路由,不会覆盖已导入的模型。 gemini-2.5-pro与gemini-2.5-flash在 2026-12-01 起由 Google 自动改路由,请提前检查相关路由。- 升级后抽查路由、请求日志、调试台和模拟器,确认新界面下的筛选与跳转符合预期。完整变更见 v2.19.0 发布说明。
2.18.0 的升级入口
Section titled “2.18.0 的升级入口”从 2.17.0 升级需要 0034 和 0035:前者支持粘性绑定用户明细,后者支持独立 OAuth 访问令牌与请求日志关联。需要先迁移,再更新服务;即使暂不启用 OAuth,也不能跳过结构迁移。
更早版本还涉及双额度、模型配置与 MCP 等变更。完整索引见 迁移与切换索引。
升级后检查什么
Section titled “升级后检查什么”- 原有客户端协议、模型 ID、路由组和用户 Key 可正常调用。
- 新功能按需配置,目录导入没有覆盖已有价格和供应商凭证。
- 计费、额度、故障转移和工具调用符合预期。
- 数据库切换后确认维护状态;切换环境可能同时复制了维护配置。
历史说明保留各版本当时的语义。版本动态用于查看变化,本页用于组织升级过程。