跳转到内容

升级与迁移

升级前记录当前版本和目标版本,阅读目标版本的兼容性变化。跨多个版本升级时,执行全部尚未应用的迁移,不能只运行最后一个版本新增的 SQL。

  1. 备份数据库,确认可恢复路径。
  2. 根据迁移要求安排维护模式,等待在途请求结束。
  3. 按编号应用目标数据库对应的待执行迁移。
  4. 更新匹配版本的 Proxy、Admin 和迁移工具。
  5. 验证健康、登录、真实请求、日志及额度变化,再解除维护。

具体版本可能要求更严格的切换顺序,不要仅根据本摘要执行跨版本生产迁移。

从 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.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.17.0 升级需要 0034 和 0035:前者支持粘性绑定用户明细,后者支持独立 OAuth 访问令牌与请求日志关联。需要先迁移,再更新服务;即使暂不启用 OAuth,也不能跳过结构迁移。

更早版本还涉及双额度、模型配置与 MCP 等变更。完整索引见 迁移与切换索引。

  • 原有客户端协议、模型 ID、路由组和用户 Key 可正常调用。
  • 新功能按需配置,目录导入没有覆盖已有价格和供应商凭证。
  • 计费、额度、故障转移和工具调用符合预期。
  • 数据库切换后确认维护状态;切换环境可能同时复制了维护配置。

历史说明保留各版本当时的语义。版本动态用于查看变化,本页用于组织升级过程。