升级 AISIX

AISIX 部署分两部分升级：AISIX Cloud 控制面，以及承载流量的 AISIX 网关。两者独立升级，顺序固定；在你逐台升级网关的过程中，它们运行的版本可以不同。

本页说明哪些升级路径受支持、应遵循的顺序，以及各安装方式的升级步骤。各版本的具体变更请参见发布说明。

变更控制面之前，请把数据库、Secret、部署配置和匹配的软件准备为同一个恢复集。请参阅备份与恢复。对于 OKD 上的 Helm 部署，在 OKD 上升级 AISIX 提供了从 1.4 或 1.5 升级到本版本所需的 oc 命令、SCC 检查和分阶段验证。

支持的升级路径

支持的升级下限是 0.12.0。运行 0.12.0 或更高版本的部署可以直接升级到任意更新的版本，包括当前版本。

版本可以跳过。从 0.12.0 直接升级到当前版本是受支持的，不需要逐个经过中间版本。决定升级是否受支持的是下限，而不是跨度：只要来源版本不低于 0.12.0，就可以一步升级到任意更新的目标版本。

升级下限只有在某个版本明确宣布上调时才会变化，不会随着新版本发布而静默抬高，因此今天受支持的部署会一直受支持，直到有版本公告说明为止。从较旧的部署规划跨版本升级前，请先查看目标版本的发布说明。

低于 0.12.0 的部署需要分两步升级：先升级到 0.12.0 与目标版本之间的某个版本，让它启动并完成数据库迁移，然后再升级到目标版本。

兼容性例外是按功能划分的，而不是按版本划分：升级过程中可能出现差异的，始终是某一项具体配置，而不是版本组合本身。这里有两种不同的差异。一种是网关版本无法加载的配置，它会让该网关丢掉整个资源——在 0.12.0 与当前版本之间不存在这样的配置，因此控制面能够保存的每一份配置，都能作为完整资源在下限以上的每个网关版本上加载。另一种是网关版本不认识的配置，这是升级期间的常见情况：资源照常加载并生效，只是这一项配置在该网关上不起作用，直到它被升级。

升级顺序与混合版本窗口

先升级控制面，再升级网关。 控制面能够理解下限以上的每个网关版本，而网关不一定能理解比自己更新的控制面。

在这两步之间，部署处于混合版本状态：控制面已是新版本，网关仍是旧版本。这个窗口由升级下限限定，而不是由时间限定。只要每台网关都不低于 0.12.0，这个窗口可以持续到你需要的任何时长——分批推进的机群升级、刻意滞后一周的灰度环境、按自己维护窗口升级的网关，都可以。整个期间网关照常承载流量。

各网关实例的版本单独显示在环境的 Data planes 视图中，因此可以看出哪些实例尚未升级。控制面版本显示在控制台左侧导航底部，也可以通过 GET /api/config/public 获取，参见 On-Premises 安装中的「验证安装」一节。

保存作用域内某些网关不认识的配置项是允许的。响应会给出字段名、第一个能够识别该字段的受支持网关版本，以及有多少台网关会忽略它。如果当前没有任何受支持版本能够识别该字段，响应也会明确说明。控制台会在保存后显示同一条警告。在依赖该配置项之前请先阅读警告：被忽略的限制类配置在这些网关上并不生效。

配置到达网关后，控制台还会显示各网关上报的信息。环境概览会区分被忽略的字段和整个资源被拒绝的情况，Data planes 则把受影响节点标记为 Limitations 或 Incompatible。这些运行时信号能够发现最初保存配置后才注册或发生回滚的网关。验证流程参见资源投射。

在网关侧，aisix_config_partially_compatible_resources 统计的是携带了本网关版本不认识的字段的资源数量。在窗口期内它可能不为零，网关升级完成后应回落到零。配置健康类指标参见指标参考。

跳过的每个版本，其升级说明依然适用

跳过一个版本，跳过的是它的发布说明，而不是它带来的行为变化。一次跨越多个版本的升级，其间每个版本的升级说明都对你适用，并且要按顺序阅读——从你当前版本的下一个版本开始，一直读到目标版本，由旧到新。

升级说明记录的是升级前需要做的事：含义发生变化的配置项、开始生效的 Helm 取值、需要复核的告警表达式。被跳过版本中的说明，不会因为后续版本的说明而失效。

从更早的版本升级到 1.0.0 之前，还要完成升级到 1.0.0 时复核已有安全护栏。它不是一条升级说明，而是一份升级前检查清单：它要求你在控制面以新版本启动之前，先找出并停用受影响的语义安全护栏。

从 1.5.x 或更早版本升级：控制台、访问与控制台部署方式的变化

1.5.x 之后的版本将控制台登录移入 cp-api，由 cp-api 直接提供控制台，不再使用单独的控制台服务，并以 on-premises 部署模式运行控制面。从 1.5.x 或更早版本升级控制面之前，请先了解以下变化。

危险

如果待升级的控制面中有多个组织，升级后控制台会一直被锁定，直到某个 Owner 保留一个组织并永久删除其他所有组织。开始前请先阅读将多个组织合并为一个，并备份数据库。

现有会话失效

升级前版本的会话不会保留，因此升级后所有用户都需要重新登录一次。账号和密码保持不变，使用原来的邮箱地址和密码即可登录。回滚到升级前的版本同样会让所有用户退出登录。

移除 Google 和 GitHub 登录

控制台只提供邮箱和密码登录。只使用过 Google 或 GitHub 登录的用户没有密码，升级后无法登录。目前这类用户无法自助恢复访问：密码重置邮件只会发送给已有密码的账号。请在升级前确认有哪些这样的用户。

社交登录相关设置不再生效：Helm Chart 中的 api.oauthEnabled 和 secrets.oauth.*，以及 AISIX_CLOUD_OAUTH_ENABLED、AISIX_GOOGLE_OAUTH_* 和 AISIX_GITHUB_OAUTH_* 变量。

已移除的设置

以下设置不再被读取。仍设置了它们的 values 文件或 .env 可以正常安装和启动，你可以将其删除：

Helm 配置项	变量	说明
secrets.betterAuthSecret	BETTER_AUTH_SECRET、BETTER_AUTH_URL	会话不再使用共享密钥签名。只要仍可能回滚到升级前的版本，就请保留该值，因为 1.5.x 及更早版本启动时需要它。
api.jwtAudience	AISIX_CLOUD_JWT_AUDIENCE	控制台不再使用会话 JWT。
—	AISIX_AUTH_REQUIRE_EMAIL_VERIFICATION	已移除。
ui.image.*、ui.replicaCount、ui.resources 及其他 ui 工作负载配置项	AISIX_UI_IMAGE	不再有控制台镜像或工作负载。
—	AISIX_CLOUD_DASHBOARD_URL	cp-api 直接从自己的镜像中提供控制台文件。

控制台由 cp-api 提供

不再有 aisix-cp-ui 镜像、控制台 Pod 或控制台容器。控制台文件随 cp-api 镜像发布，因此请从镜像同步列表和允许列表中移除 aisix-cp-ui。

• Helm。 helm upgrade 会删除控制台 Deployment。<release>-ui Service 会保留，名称、类型、端口和 nodePort 都不变，但现在转发到 cp-api，因此仍指向它的反向代理或 NodePort 可以继续工作。新的配置请指向 cp-api Service。
• Docker Compose。 Compose 文件中移除了 ui 服务，run.sh 会在升级时删除旧的 ui 容器。
• 可信源站。 额外的登录源站现在使用 api.trustedOrigins。1.5.0 安装说明中放在 ui.extraEnvVars 里的 AISIX_TRUSTED_ORIGINS 条目仍会传给 cp-api；方便时请将其迁移到 api.trustedOrigins。
• 语言。 Helm 中的 ui.defaultLocale 和 Docker Compose 中的 AISIX_DASHBOARD_LOCALE 仍然设置控制台语言，现在也决定邮件语言。如果你是直接在 1.5.x 的控制台容器上设置 AISIX_DASHBOARD_LOCALE，请改为在 cp-api 上设置 ui.defaultLocale 或 AISIX_CLOUD_DEFAULT_LOCALE。
• 私有数据库 CA。 控制台不再连接数据库，因此 1.5.x 中为私有 PostgreSQL CA 配置的 ui.extraVolumes、ui.extraVolumeMounts 和 NODE_EXTRA_CA_CERTS 不再适用。请改用 externalDatabase.sslRootCert 把 CA 提供给 cp-api 和 dp-manager，参见信任私有数据库 CA。

控制台链接格式变化

原先在路径中携带 ID 的页面，现在改为通过查询参数传递 ID，例如 /environments/<page>?env=<id> 取代 /environments/<id>/<page>。团队、MCP 服务器工具和邀请页面也以同样方式变化。cp-api 会将旧链接（包括升级前已发出的邀请链接）重定向到新格式。

可以发送邮件

控制面现在可以通过 SMTP 中继发送邀请邮件和密码重置邮件。在配置中继之前，邮件功能保持关闭，参见配置邮件（SMTP）。未配置时，邀请卡片不再提示邮件已发送，而是显示链接，由你转交给受邀者。

仅能通过邀请注册

任何人都不能再自行注册。尚无账号的人需要管理员发出邀请，并通过邀请中的链接注册，参见邀请成员。已有账号及其密码不变。如果控制台以外的客户端过去只凭邮箱地址为受邀者注册，现在必须以 invitationToken 发送邀请 Token。

不能再创建组织

任何人都无法通过控制台或 API 创建新组织。Owner 现在可以删除组织，但部署中的最后一个组织除外。包含多个组织的控制面必须先缩减为一个组织，控制台才能重新使用，参见将多个组织合并为一个。

将多个组织合并为一个

On-Premises 控制面只服务一个组织，但 1.5.x 及更早版本允许任何人创建组织，因此升级后的控制面中可能有多个组织。在这种情况下，控制台对所有用户锁定：控制台的每个页面都会跳转到 /consolidate，控制台请求返回 403，错误码为 ORG_CONSOLIDATION_REQUIRED。Admin Token 仍可正常使用，网关流量也不受影响。

危险

合并会永久删除除保留组织之外的所有组织（包括你不是成员的组织）及其中的全部内容：它们的环境及其中的模型、调用方 API Key 和其他资源，其成员的组织成员关系，以及用量和审计记录。连接到这些环境的所有网关证书都会被吊销，这些网关将与控制面断开。此操作无法撤销。如果有人需要这些组织中的数据，请在合并之前备份数据库。

任何至少是一个组织 Owner 的用户，都可以使用密码登录后执行合并：

1. 使用密码登录。控制台会打开 保留一个组织 页面。
2. 选择要保留的组织。只有你是 Owner 的组织可供选择。
3. 核对将被删除的组织。页面会按名称和标识列出控制面上的其他所有组织。
4. 输入要保留组织的标识，然后选择 删除。按钮上会显示将被删除的组织数量。

每个被删除的组织都与 Owner 删除组织时的处理方式相同：对它的访问立即终止，其存储的数据（如用量和审计记录）随后在后台移除。

当只剩一个组织时，锁定立即解除，控制台会打开你保留的组织。本次合并会记录在该组织的审计日志中，资源类型为 organization，操作为 consolidate。

不是任何组织 Owner 的用户会看到一个页面，提示需由组织 Owner 登录并完成合并。

有密码的用户账号会保留。没有密码且只属于被删除组织的账号（例如直接创建或通过 SCIM 预配的成员）会随这些组织一起删除。有密码且只属于被删除组织的用户仍可登录，但不再属于任何组织，会看到联系管理员的提示，直到被邀请加入剩下的组织。系统不会自动把任何人加入保留的组织。

如果合并中途停止，已删除的组织不会恢复，控制台仍保持锁定。再次执行合并即可删除剩余的组织。

计费功能消失

计费页面、组织套餐以及角色目录中的 billing 权限都已移除。

管理员保持不变

升级后的控制面保留现有的账号、组织、Owner 和 Admin，他们照常登录。由于数据库中已有用户，即使部署包的 .env 或 Chart 现在可能带有首个管理员设置，cp-api 也不会创建首个管理员。现有的 Owner 和 Admin 负责邀请新成员，并可以为成员启用登录或重置密码。

默认允许访问私有地址的出站连接

Playground、预算通知、MCP spec_url 获取以及护栏连接测试，现在默认可以访问私有、内部和回环地址。如需继续拒绝，请将对应的设置设为 false，参见私有网络访问。

使用 helm upgrade --reuse-values 从 Chart 1.5.0 升级的 Helm Release，仍会把该 Chart 中 api.playgroundAllowPrivateIPs 和 api.notifyAllowPrivateURLs 的默认值 false 作为显式值保留。在清除这两项之前（例如按使用 Helm 升级所述使用你自己的 values 文件升级），它们仍会拒绝私有地址。

组织恢复需要全新安装

向空数据库执行未鉴权导入的方式已移除，向已在使用中的部署导入的方式也已移除。备份文件现在只能恢复到全新安装的控制面，并由其首个管理员在修改初始密码之后执行。脱敏恢复也不再为恢复出的账号设置密码 aisix-repro，aisix-repro-<api_key_id> 也不再能通过鉴权：请改为为账号启用登录，并轮换调用方 API Key。参见组织备份与恢复。

升级部署包安装

Docker Compose 部署包——在线快速安装包和离线包——升级方式相同：把新版本部署包解压覆盖到现有安装目录上，然后重新运行 run.sh。

请先备份数据库。cp-api 会在新版本下首次启动时迁移数据库结构，而回滚依赖的正是这份备份。

在线安装的升级方式是在包含安装目录的上级目录中重新运行一键脚本——它会拉取当前版本的部署包，解压覆盖到 aisix-self-hosted，然后执行 run.sh：

curl -sL "https://run.api7.ai/aisix-self-hosted/quickstart" | bash

内网隔离环境需要把离线包带进去，而离线包按 CPU 架构分别发布。请在能联网的机器上下载与离线主机匹配的版本固定软件包：

curl -fSL "https://run.api7.ai/aisix-self-hosted/aisix-self-hosted-offline-1.6.0-linux-amd64.tar.gz" \
  -o aisix-self-hosted-offline-1.6.0-linux-amd64.tar.gz

AArch64 主机请把 amd64 换成 arm64。不带架构后缀的 aisix-self-hosted-offline-1.6.0.tar.gz 仍然继续发布，内容就是 linux/amd64 包。升级时请使用与该主机架构一致的部署包：run.sh 会在加载任何镜像之前拒绝架构不匹配的包，并打印正确的下载 URL。

在包含安装目录的上级目录中解压覆盖，而不是在安装目录内部：

cd /path/that/contains/aisix-self-hosted
tar -xzf aisix-self-hosted-offline-1.6.0-linux-amd64.tar.gz
cd aisix-self-hosted
./run.sh

在 aisix-self-hosted 内部执行 tar 会解压出一个嵌套副本，原安装目录不会有任何变化。

部署包中不含 .env，因此这一步只替换 Compose 文件和脚本，你的密钥和数据卷保持原样。.env 中唯一属于部署包的取值是 AISIX_VERSION，它固定了所有镜像版本——包括控制台在生成网关安装命令时使用的网关镜像。run.sh 会把它调整为与部署包一致，并打印所做的操作：

==> Upgrading AISIX 1.0.0 -> 1.1.0.
    AISIX_VERSION in .env now matches this package; your secrets are untouched.

run.sh 在这里会打印两种行之一。上面这种是常规情况；如果 .env 中原本完全没有 AISIX_VERSION，打印的会是 ==> Added AISIX_VERSION=<version> to .env (it had none).，这种情况同样完成了升级。两种行都没有出现，才说明没有发生升级。确认实际运行的版本：

COMPOSE_PROJECT_NAME=aisix-self-hosted docker compose images

单个镜像覆盖项——AISIX_API_IMAGE、AISIX_DPM_IMAGE 和 AISIX_CLOUD_DP_IMAGE——run.sh 从不改写，并且它们的优先级高于 AISIX_VERSION。如果希望某个组件跟随部署包，请在升级前移除对应的覆盖项。参见 On-Premises 配置中的「镜像和发布版本」。

离线部署包还带有镜像。解压新部署包会把新版本的镜像归档加入 images/，但先前版本的归档也仍留在那里，而 run.sh 每次启动这套栈时都会对 images/ 中的每个归档执行 docker load。升级成功启动后，请从 images/ 中删除先前版本的归档，这样之后的启动只会加载当前版本的镜像。在此之前请先保留它们：在离线主机上回滚时要加载的正是这些归档。

唯一需要避免的做法，是把新部署包解压到另一个目录。Compose 项目名属于部署包，因此新目录会接管同一个数据卷，而它旁边的 .env 却是全新生成的。此时 run.sh 会停下来而不是启动：只要发现这套栈的容器正运行在另一个目录下，它就会拒绝，与新目录的 .env 内容无关。请回到原目录升级；如果确实要迁移安装位置，请先在原目录执行 ./run.sh down，再把它的 .env 复制过去，然后运行新目录中的脚本。

使用 Helm 升级

控制面 Chart 与网关 Chart 每个版本都使用相同的 version 和 appVersion，因此两者升级到同一个版本号。先升级控制面 Chart。

升级控制面 Chart 前请备份数据库，无论使用的是随 Chart 部署的数据库还是外部数据库。

以下命令中的 Helm Release 名称和命名空间，都是安装时选定的值。控制面命令使用 aisix-cp，即私有化安装中的 Release 名称；那里的安装命令会装到执行时的当前命名空间中，如果它不是你现在的当前命名空间，请加上 --namespace <namespace>；如果安装时用了其他 Release 名称，请换成你自己的。helm list -A 会列出所有 Release 及其命名空间：控制面的 CHART 列为 aisix-cp-<version>，网关的为 aisix-<version>。Release 名称或命名空间填错时，helm upgrade 会报错 "<name>" has no deployed releases。

helm repo update

helm upgrade aisix-cp api7/aisix-cp --version 1.6.0 -f your-cp-values.yaml

请用你自己的 values 文件升级，不要用 --reuse-values。--reuse-values 会重放上一个 release 完全解析后的取值，其中包含 Chart 默认值，因此新 Chart 改动过的默认值不会被采用。Chart 中的探针预算就属于会随版本变化的默认值，而使用新镜像、却沿用上一版 Chart 预算启动的工作负载，可能被自己的探针重启。如果你此前没有维护 values 文件，可以用 helm get values aisix-cp 打印安装时使用的覆盖项，保存下来再用 -f 传入。

等待 cp-api Pod 就绪——数据库迁移在新版本下首次启动时执行——之后再继续。Pod 就绪后，大表上的索引构建仍会在后台继续，参见控制面升级后的索引构建。

然后升级网关，可以逐批升级，也可以一次全部升级，取决于你的机群推进方式。下面的命令使用各安装命令（包括控制台生成的命令）默认的网关 Release 名称和命名空间，即命名空间 aisix-dp 中的 aisix-dp。如果安装网关时用了其他 Release 名称或命名空间，请换成你自己的：

helm upgrade aisix-dp api7/aisix --namespace aisix-dp --version 1.6.0 -f your-gateway-values.yaml

网关由 Deployment 的滚动更新替换。除非你在 Chart 上设置 updateStrategy，否则用的是 Kubernetes 的默认策略，因此在规模较大的部署中会同时替换多个 Pod。新 Pod 在能够提供服务之前不会接到流量：在网关从控制面拿到并应用配置之前，Kubernetes 不会把它加入 Service 端点。滚动过程涉及的探针预算和排空设置参见在 Kubernetes 上部署网关。

开始之前有一项取值值得检查：控制面 Chart 的 api.dpImage 固定了控制台在生成安装命令时使用的网关镜像，作用与部署包安装中的 AISIX_CLOUD_DP_IMAGE 完全相同。如果你显式设置过它，它会在历次升级中一直保留，升级之后新加的网关仍会以旧镜像启动。留空时，cp-api 会下发其自身版本的网关 docker.io/api7/aisix:<version>。使用 --reuse-values 升级的 Release 会保留其之前 values 中的镜像。

部署中的每一批网关都要重复这一步。在此之前，这些网关处于上文所述的混合版本窗口中，这是受支持的状态。

将应用设置迁移到 Chart values

两个 Chart 都把每项应用设置声明为显式的 value，并将其渲染成组件从 ConfigMap 读取的配置文件。密钥保留在 Kubernetes Secret 中，永远不会写入该文件。extraEnvVars 只用于系统级变量，例如 TZ。

如果某个 Chart 的早期版本通过 extraEnvVars 接收应用设置，这些设置在升级后仍然有效，因为环境变量会覆盖配置文件。但它同样会覆盖现在用于配置同一设置的 value，因此请把每项设置迁移到对应的 value，并删除该环境变量：

• 控制面 Chart。 例如，AISIX_TRUSTED_ORIGINS 改为 api.trustedOrigins，AISIX_CLOUD_MCP_SPEC_ALLOW_PRIVATE_URLS 改为 api.mcpSpecAllowPrivateURLs。完整列表参见 Helm 配置值。
• 网关 Chart。 AISIX_<SECTION>__<KEY> 变量改为 config 下的同名键，例如 AISIX_OBSERVABILITY__LOG_LEVEL 对应 config.observability.log_level。由 Chart 根据自身 value 设置的键（例如监听器地址和控制面连接）在 config 下会被拒绝。Redis 的 URL、用户名和密码改为通过 configSecrets 或 rateLimit.redis 从 Secret 读取。参见设置其他网关配置。

覆盖 Chart 自身设置的变量（而不只是覆盖配置文件的变量）同样仍然有效，但这只是兼容途径。对于 1.5.0 版 Chart 已渲染的变量名，Chart 会把自己的条目保留在你的条目之前，因此容器中会出现两个同名条目。Helm 4 的 server-side apply 会拒绝重复的变量名，因此新安装要在 values.yaml 中通过对应的 value 或在 config 下设置该值，而不要使用 extraEnvVars。现有的这类覆盖也请迁移到 values。

删除 Chart 仍在渲染的变量名的覆盖需要运行两次 helm upgrade。已部署的 Pod 规格中该变量名出现两次，而新规格中只出现一次，因此第一次 Helm 3 升级会把两个条目都删除，第二次升级才会重新加上 Chart 自己的条目。这一限制从 1.5.0 版 Chart 起就存在。

第一次升级到会渲染配置文件的网关 Chart 时，即使没有修改任何 value，也会把每个网关 Pod 替换一次，因为 Pod 规格发生了变化：网关改为读取渲染出的文件，来自控制面的证书包改为以文件形式挂载。如果某个 release 的 extraEnvVars 设置了 AISIX_MANAGED__CP_CERT_PEM、AISIX_MANAGED__CP_KEY_PEM 或 AISIX_MANAGED__CP_CA_PEM，它会继续以环境变量形式接收证书包。

控制面升级后的索引构建

一个版本可能会为控制面的大表添加索引，尤其是存放用量记录的 dpmgr_usage_events。cp-api 在数据库迁移完成后立即开始提供服务，之后在后台构建这些索引，因此构建期间控制台和向网关下发配置都可用。在控制面数据库角色上设置的 PostgreSQL statement_timeout 不会中断构建。

构建耗时与用量表的大小成正比。按测试部署的粗略参考，5000 万到 6000 万行的用量表大约需要 15 分钟，实际耗时取决于磁盘、缓存和数据库负载。新安装时表是空的，构建几乎立即完成。

cp-api 会逐个索引记录日志：先是 building index，然后是周期性的 index build progress，最后是 index built。全部完成后记录 background index build: every index is in place。在它们所依赖的索引建好之前，预算支出统计、用量与数据保留清理以及组织删除清理会等待。这期间请求仍会被记录，构建结束后预算支出会一次性补齐。

每个索引的构建都要扫描两遍表并写入预写日志（WAL），因此构建期间数据库的 I/O 和 CPU 负载会明显升高。在一次实测中，重建最大的用量索引约耗时 23 秒，写入约 180 MB 预写日志，PostgreSQL 的 CPU 接近上限，而用量写入和 Usage 页面的延迟没有可测量的变化。即便如此，用量表较大的部署仍建议在业务低峰期升级。

开始下一次升级之前，请等待日志中出现 background index build: every index is in place。如果更新的版本需要修改同一张表，它的迁移会一直等到上一次构建结束才能完成。

部署包安装

./run.sh 会逐层启动整个栈，并自己等待每一层就绪，因此能说明是哪一步耗时较长。它首先停止新部署包要替换的所有容器，包括上一个版本的 dp-manager，确保新的 cp-api 迁移期间没有任何组件写数据库。然后启动 PostgreSQL 并等待它就绪，再启动 cp-api 并等待它就绪，最后启动 dp-manager 和其余服务。

正常启动不会额外打印任何内容。某一层耗时超过约 10 秒后，run.sh 每 30 秒打印一行：

• cp-api is still migrating the database (…)。迁移耗时较长时，可能附带 It is waiting for a table lock another database session holds，./run.sh logs api 会给出该会话。
• cp-api is still starting (…)：迁移已完成，但升级后的首次启动仍在启动其余部分。
• PostgreSQL is recovering from an unclean shutdown (…)。参见中断停止后的 PostgreSQL 恢复。

请让它继续运行。按 Ctrl-C 不会停止迁移，迁移会在容器内继续进行，但 dp-manager 只由 run.sh 启动，因此迁移完成后请再运行一次 ./run.sh。之后如需跟踪后台索引构建，请运行 ./run.sh logs api。

被其他会话持有的表锁

每个迁移步骤最多等待 5 秒获取表锁，然后重试，而不是让该表上的所有读写排在一个长时间运行的事务之后。重试期间，cp-api 会记录 database migration is waiting for a table lock held by another session; retrying，并附上阻塞会话的进程 ID、应用名称、状态、事务开始时间和查询。常见原因是长时间运行的事务，或仍在运行上一个版本的控制面副本。结束该会话或等待它完成后，迁移会继续。

中断停止后的 PostgreSQL 恢复

./run.sh stop 和 ./run.sh down 会给每个容器最多 2 分钟关闭，因为在大量写入之后，PostgreSQL 关闭时的检查点可能超过 Docker Compose 默认的 10 秒。用上一个部署包的 run.sh 执行的停止仍然只有 10 秒。

如果 PostgreSQL 的关闭被中断，下次启动时它会先重放日志，之后才接受连接；对于近期写入很多的数据库，这可能需要几分钟。数据不会丢失。run.sh 最多等待 30 分钟，恢复期间会打印 PostgreSQL is recovering from an unclean shutdown。如果恢复超过了这个等待时间，run.sh 会指出启动失败是由恢复导致的：请等待 ./run.sh logs postgres 显示 database system is ready to accept connections，然后再运行一次 ./run.sh。

窗口期内控制面会做哪些检查

在网关尚未升级期间，控制面会依据其内置的已发布兼容性契约，检查你保存后将投射给近期有上报且已注册网关的每一份配置。

如果其中一台网关无法加载某份配置，保存请求会以 HTTP 422 失败，错误码为 DP_INCOMPATIBLE。响应中会指出网关版本、受影响的网关、字段路径以及 schema 给出的原因。此时不会写入任何内容，资源会保留之前的配置。这项检查由具体配置项触发，而不是由版本差异本身触发。请升级受影响的网关，或者在它们升级完成前先不要使用该配置项。

网关刚升级完成时，重启后的网关此前的注册记录最长还会被计入 5 分钟。如果在这段时间内保存被拒绝，而它指出的版本你已经升级过了，通常就是这条过期注册记录导致的；稍等片刻重试即可。

低于升级下限的网关完全不做检查。没有受支持的契约可供比对，因此保存会成功，响应中携带一条 below_floor 警告，给出受影响的网关数量、它们上报的版本，以及升级下限。请如实理解这条警告：这些网关已不在支持范围内，控制面无法告诉你它们能否加载你刚刚保存的内容。请把它们升级到 0.12.0 或更高版本。

如果网关上报的版本无法映射到控制面内置的兼容性契约，控制面也会跳过该网关。这包括自定义或本地构建，以及比控制面已知契约更新的网关版本。请直接验证这些网关，不要把未出现保存时警告当作兼容性证明。

升级下限闸门

从低于下限的版本升级，会被直接拒绝而不是尝试执行，因为一个迁移到一半的数据库，比多做一步升级难恢复得多。

当数据库上一次由低于下限的版本运行时，cp-api 拒绝启动。错误信息会给出数据库中记录的版本、本版本能够升级的最低来源版本，以及覆盖开关。这项检查在任何迁移动作之前执行，因此被拒绝的启动不会改动数据库，它保持上一个版本留下的样子。正确做法是先升级到一个受支持的版本。

这项检查读取的是控制面从本版本起才写入的版本记录，因此它只能判断已经被带有该记录的版本运行过的数据库。被更早版本运行过的数据库没有这条记录，无从判断，因此不会被拒绝——在这一次升级中，只有部署包安装的 .env 检查能拦住你，而 Helm 安装完全没有闸门。请自行确认你是从哪个版本升上来的。

离线包和在线包在 run.sh 中拒绝同样的升级，并且发生在任何容器启动之前，同时给出两步做法：取一个介于 0.12.0 与目标版本之间的部署包，解压覆盖到安装目录并运行，等它完成迁移，然后再解压目标部署包并再次运行。

如果确实要继续，请设置 AISIX_ALLOW_UNSUPPORTED_UPGRADE=1，取值必须正好是 1。请先备份数据库——这会执行从那么早的版本起从未被验证过的迁移路径，而这份备份是唯一的退路。

部署包安装在命令上设置：

AISIX_ALLOW_UNSUPPORTED_UPGRADE=1 ./run.sh

Helm 安装设置 api.allowUnsupportedUpgrade：

values.yaml

api:
  allowUnsupportedUpgrade: true

把它加进你升级时使用的 values 文件，这样它才会真正生效：

helm upgrade aisix-cp api7/aisix-cp --version 1.6.0 -f your-cp-values.yaml

cp-api 和部署包的 run.sh 都读取这个环境变量，因此两条部署包升级路径使用同一个名字，而 Chart value 设置的是 cp-api 的同一项配置。升级完成后请把这个覆盖开关移除，以免后续某次不受支持的升级被静默放行。

回滚

回滚按相反顺序进行：先网关，后控制面。

控制面回滚是一次数据库恢复，而不只是换个镜像。新版本已经迁移过数据库结构，把旧版本直接跑在上面，等于让旧代码运行在它不认识的数据库上。请先恢复升级前的备份，再用旧版本对接恢复后的数据库启动。

对于部署包安装，当目录中的部署包版本低于 .env 中记录的版本时，run.sh 会拒绝启动，因为这几乎总是意外——重新下载了旧的 tarball，或者把 latest 的 URL 取到了更新的安装上。有意为之的回滚，在恢复数据库备份之后，需要显式确认：

AISIX_ALLOW_DOWNGRADE=1 ./run.sh

run.sh 结束时会打印部署的版本号。请核对这一行是否是你要回滚到的版本。

对于 Helm 安装，helm rollback 可以把工作负载恢复到上一个 revision；数据库恢复仍然需要你先自行完成。

不受支持的情况

• 从低于升级下限的版本一步升级。 请先升级到 0.12.0 与目标版本之间的某个版本，让它完成迁移，然后再升级一次。
• 接入的网关版本，低于环境现有配置已经要求的版本。 混合版本窗口覆盖的是向前升级中的网关。把一台较旧版本的网关接入一个现有配置已经依赖更新版本的环境，是不受支持的——这台网关无法加载分发给它的配置。
• 让低于 0.12.0 的网关对接当前版本的控制面。 这类网关不在支持范围内，控制面无法判断它会加载到什么。
• 先升级网关再升级控制面。 在所有部署方式中，顺序都是控制面优先。