升级 AISIX

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

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

变更控制面之前，请把数据库、Secret、部署配置和匹配的软件准备为同一个恢复集。请参阅备份与恢复。

支持的升级路径

支持的升级下限是 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 时复核已有安全护栏。它不是一条升级说明，而是一份升级前检查清单：它要求你在控制面以新版本启动之前，先找出并停用受影响的语义安全护栏。

升级部署包安装

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

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

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

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

内网隔离环境需要把离线包带进去，而离线包按 CPU 架构分别发布。请在能联网的机器上下载与离线主机匹配的那一个——下面的 URL 已固定到本版本，同时还发布有 aisix-self-hosted-offline-latest-linux-<arch>.tar.gz 形式的 latest URL，它会解析到当前版本：

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

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

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

cd /path/that/contains/aisix-self-hosted
tar -xzf aisix-self-hosted-offline-1.4.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_UI_IMAGE 和 AISIX_CLOUD_DP_IMAGE——run.sh 从不改写，并且它们的优先级高于 AISIX_VERSION。如果希望某个组件跟随部署包，请在升级前移除对应的覆盖项。参见 On-Premises 配置中的「镜像和发布版本」。

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

使用 Helm 升级

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

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

helm repo update

helm upgrade aisix-cp api7/aisix-cp -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 就绪——数据库迁移在新版本下首次启动时执行——之后再继续。

然后升级网关，可以逐批升级，也可以一次全部升级，取决于你的机群推进方式：

helm upgrade aisix api7/aisix -f your-gateway-values.yaml

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

开始之前有一项取值值得检查：控制面 Chart 的 api.dpImage 固定了控制台在生成安装命令时使用的网关镜像，作用与部署包安装中的 AISIX_CLOUD_DP_IMAGE 完全相同。如果你显式设置过它，它会在历次升级中一直保留，升级之后新加的网关仍会以旧镜像启动。留空即可跟随 Chart 的 appVersion。

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

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

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

如果其中一台网关无法加载某份配置，保存请求会以 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.extraEnvVars 传给 cp-api：

values.yaml

api:
  extraEnvVars:
    - name: AISIX_ALLOW_UNSUPPORTED_UPGRADE
      value: "1"

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

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

cp-api 和部署包的 run.sh 都读取这个开关，因此两条升级路径使用同一个名字。升级完成后请把它移除，以免后续某次不受支持的升级被静默放行。

回滚

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

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

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

AISIX_ALLOW_DOWNGRADE=1 ./run.sh

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

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

不受支持的情况

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