版本：1.6.0

在 OKD 上升级 AISIX

在 OKD 上由 Helm 管理的 AISIX 部署有两种形态：不带控制面的开源网关，或私有化部署的 AISIX Cloud。本流程将这两种部署从 1.4 或 1.5 升级到本版本。每个网关部署都有独立的 Helm Release；私有化部署的 AISIX Cloud 还有一个控制面 Release。

升级顺序遵循这种管理关系。对于开源网关，先用目标网关镜像校验其资源，然后直接升级网关 Release。对于私有化部署的 AISIX Cloud，先升级控制面，确认它与现有网关的连接正常，再逐个升级受管网关的 Release。混合版本和控制面回滚说明，请参阅升级 AISIX。

两条路径使用的 AISIX Chart 都支持 OKD restricted-v2 Security Context Constraint（SCC）分配的随机非 root 用户，因此不要为 AISIX 的 ServiceAccount 授予 anyuid SCC。使用随包 PostgreSQL 的私有化 AISIX Cloud 部署还需要运行 OKD 预检中的覆盖配置。开始任一升级路径之前，请先准备好前提条件中列出的集群访问权限、Release 信息和恢复材料。

前提条件

每种部署都需要准备：

配置 oc，使其能访问包含 AISIX 的 OKD 项目，并安装 Helm 3.15 或更高的 Helm 3 版本、cURL 和 jq。如需在升级前校验开源网关的资源，还需安装 Docker。
确认每个网关部署的 Helm Release 名称和命名空间。
如果从 1.4 升级，请阅读 1.5.0 和 1.6.0 的发布说明，并按顺序完成每一条相关的升级说明。对于私有化部署的 AISIX Cloud，还请阅读从 1.5.x 或更早版本升级：控制台、访问与控制台部署方式的变化，并完成其中适用的升级前准备。
如果从 1.5 升级，请阅读 1.6.0 的发布说明，并完成每一条相关的升级说明。对于私有化部署的 AISIX Cloud，还请阅读从 1.5.x 或更早版本升级：控制台、访问与控制台部署方式的变化，并完成其中适用的升级前准备。
对于现有的多副本网关部署，确认负载均衡器会摘除 /readyz 检查失败的 Pod。如果计划在升级前把单副本部署扩容，而限流计数或缓存条目需要在副本间保持一致，请先配置共享 Redis；否则，请明确接受暂时按副本独立计数的行为。请参阅生产就绪。

对于私有化部署的 AISIX Cloud，还需要：

确认控制面的 Helm Release 名称和命名空间。
创建完整的恢复集，包含 PostgreSQL 备份、匹配的主密钥和 Secret 来源、部署配置以及软件版本，并确认数据库备份可以恢复。数据库迁移会在新版控制面 API 启动时执行。
为控制面规划维护窗口。

准备升级

后续每条命令都通过安装时选定的 Helm Release 名称和命名空间找到网关。下面的值是各网关安装命令（包括控制台生成的命令）使用的默认值。如果安装时选择了其他值，请换成你自己的。要查找它们，请运行 helm list -A，找到 CHART 列为 aisix-<version> 的 Release。

值填错不会在这一步报错，而是在之后暴露：helm upgrade 会以 "<name>" has no deployed releases 失败，按标签查找 Deployment 和 Pod 也会返回空结果。

设置示例中使用的网关 Release 信息：

export GATEWAY_NAMESPACE="aisix-dp"
export GATEWAY_RELEASE="aisix-dp"
export GATEWAY_UPGRADE_TIMEOUT="60m"

60 分钟的网关超时是针对 Chart 默认值的一个保守起始预算，并非预期耗时。这些默认值包括两个副本、每个 Pod 1,230 秒的终止上限，以及五分钟的启动探针预算。

Kubernetes 可以让 Pod 终止过程相互重叠，Helm 也不要求旧 Pod 结束后才认为更新后的 Deployment 已就绪。修改副本数、更新策略、终止宽限期、探针预算，或者镜像拉取和调度变慢时，请重新计算超时。

请确认集群能够调度滚动更新多出的那个 Pod；超时设得再长也解决不了配额或容量拒绝。原子升级失败时，Helm 回滚可能再用掉一整个超时周期，因此请在维护窗口中预留这段时间。

对于私有化部署的 AISIX Cloud，还需要设置控制面 Release 信息。查找方式相同：在 helm list -A 中，控制面 Release 的 CHART 列为 aisix-cp-<version>。私有化安装中的安装命令把 Release 命名为 aisix-cp，并安装到运行命令时的当前项目中；如果你的值不同，请换成自己的。值填错时的失败方式与上面相同：

export CP_NAMESPACE="aisix"
export CP_RELEASE="aisix-cp"
export CP_UPGRADE_TIMEOUT="35m"

35 分钟的控制面超时覆盖了 Chart 默认 30 分钟的 API 启动探针预算，并留有运维余量。如果数据库迁移可能耗时更长，请调大该值。

刷新 API7 Chart 仓库，并确认每个适用的 1.6.0 Chart 均可用：

helm repo add api7 https://charts.api7.ai
helm repo update

helm show chart api7/aisix --version 1.6.0

# On-premises AISIX Cloud only
helm show chart api7/aisix-cp --version 1.6.0

记录当前部署

记录已安装的 Chart 版本和应用版本：

helm list -n "$GATEWAY_NAMESPACE"

oc get pods -n "$GATEWAY_NAMESPACE"
# If this deployment uses OpenShift Routes
oc get routes -n "$GATEWAY_NAMESPACE"

# On-premises AISIX Cloud only
helm list -n "$CP_NAMESPACE"
oc get pods -n "$CP_NAMESPACE"
# If this deployment uses OpenShift Routes
oc get routes -n "$CP_NAMESPACE"

根据 Helm Release 标签解析 Deployment 名称：

export GATEWAY_DEPLOYMENT="$(oc get deployment -n "$GATEWAY_NAMESPACE" \
  -l "app.kubernetes.io/instance=$GATEWAY_RELEASE,app.kubernetes.io/component=gateway" \
  -o jsonpath='{.items[0].metadata.name}')"

printf 'Gateway: %s\n' "$GATEWAY_DEPLOYMENT"

对于私有化部署的 AISIX Cloud，还需要解析控制面 API 的 Deployment：

export CP_API_DEPLOYMENT="$(oc get deployment -n "$CP_NAMESPACE" \
  -l "app.kubernetes.io/instance=$CP_RELEASE,app.kubernetes.io/component=api" \
  -o jsonpath='{.items[0].metadata.name}')"

printf 'Control-plane API: %s\n' "$CP_API_DEPLOYMENT"

如果预期的 Deployment 名称为空，请停下来检查 Release 名称和命名空间。

只保存由用户提供的 values。导出的 values 可能包含凭据，因此请先设置严格的文件创建掩码。不要使用 helm get values --all；把源 Chart 的默认值带到新版本，会让目标 Chart 的默认值无法生效。

umask 077
touch gateway-values.yaml
chmod 600 gateway-values.yaml
helm get values "$GATEWAY_RELEASE" -n "$GATEWAY_NAMESPACE" -o yaml > gateway-values.yaml

# On-premises AISIX Cloud only
touch cp-values.yaml
chmod 600 cp-values.yaml
helm get values "$CP_RELEASE" -n "$CP_NAMESPACE" -o yaml > cp-values.yaml

请将这些文件视为敏感文件。部署未使用已有 Secret 时，其中可能包含凭据。请把它们与升级记录以及恢复集的其余部分（如适用）一起保存，并在升级后删除本地副本。

检查保存的 values 是否显式固定了 AISIX 组件镜像：

helm get values "$GATEWAY_RELEASE" -n "$GATEWAY_NAMESPACE" -o json \
  | jq '{gateway_image_tag: (.image.tag // "")}'

# On-premises AISIX Cloud only
helm get values "$CP_RELEASE" -n "$CP_NAMESPACE" -o json \
  | jq '{api_image_tag: (.api.image.tag // ""), dpm_image_tag: (.dpm.image.tag // ""), generated_gateway_image: (.api.dpImage // "")}'

tag 为空时使用目标 Chart 的应用版本。如果有 tag 固定在较旧的 AISIX 镜像上，请从保存的 values 中删除它，或改为目标版本。请保留有意设置的自定义镜像仓库；对于自定义构建，请使用与目标版本兼容的 tag。

对于私有化部署的 AISIX Cloud，generated_gateway_image 是控制台在生成的网关安装说明中填入的镜像。值为空时跟随控制面 Release。请清除或更新较旧的固定值，以免升级后新增的网关以旧镜像启动；只有在有意使用与目标版本兼容的自定义构建时才保留它。

运行 OKD 预检

AISIX 应用容器不固定 runAsUser、runAsGroup 或 fsGroup，因此 OKD 可以分配允许的 UID。请保持 runAsNonRoot 开启；除非集群管理员已将固定 ID 分配给该项目，否则请删除固定 ID。

如果控制面使用随包 PostgreSQL 实例，请在 cp-values.yaml 中加入以下 values。否则 PostgreSQL 依赖会固定 UID 和组，可能被 restricted-v2 拒绝：

cp-values.yaml
postgresql:
  primary:
    podSecurityContext:
      enabled: false
    containerSecurityContext:
      enabled: false

生产环境建议使用外部高可用 PostgreSQL 数据库。请参阅外部数据库。

让 Helm 针对在线集群渲染每个适用的升级。--dry-run=server 允许集群查询和 OpenAPI 校验，--hide-secret 则防止 Helm 把渲染出的 Secret 打印到终端或 CI 日志：

helm upgrade "$GATEWAY_RELEASE" api7/aisix \
  --namespace "$GATEWAY_NAMESPACE" \
  --version 1.6.0 \
  --values gateway-values.yaml \
  --dry-run=server \
  --hide-secret

# On-premises AISIX Cloud only
helm upgrade "$CP_RELEASE" api7/aisix-cp \
  --namespace "$CP_NAMESPACE" \
  --version 1.6.0 \
  --values cp-values.yaml \
  --dry-run=server \
  --hide-secret

这些命令不会把渲染出的对象提交给 Kubernetes 准入控制。请把它们视为渲染和 OpenAPI 检查，而不是对 SCC、配额或准入策略的校验。新 Pod 实际分配到的 SCC，只有在 OKD 创建该 Pod 时才能确认。继续之前，请解决所有报告的错误。

渲染目标网关 Deployment，并获取 Helm 将要应用的确切网关镜像。这样可以保留 Chart 的镜像仓库地址，以及任何有意设置的仓库或 tag 覆盖：

TARGET_GATEWAY_IMAGE="$(
  helm template "$GATEWAY_RELEASE" api7/aisix \
    --namespace "$GATEWAY_NAMESPACE" \
    --version 1.6.0 \
    --values gateway-values.yaml \
    --show-only templates/deployment.yaml \
    | awk '
      $1 == "-" && $2 == "name:" && $3 == "aisix" { in_gateway = 1; next }
      in_gateway && $1 == "image:" { gsub(/"/, "", $2); print $2; exit }
    '
)"
export TARGET_GATEWAY_IMAGE

if [ -z "$TARGET_GATEWAY_IMAGE" ]; then
  echo "Target gateway image was not rendered" >&2
else
  printf 'Target gateway image: %s\n' "$TARGET_GATEWAY_IMAGE"
fi

如果没有渲染出目标网关镜像，请不要继续。

对于私有化部署的 AISIX Cloud，还需要检查目标控制面渲染结果中的每个镜像：

helm template "$CP_RELEASE" api7/aisix-cp \
  --namespace "$CP_NAMESPACE" \
  --version 1.6.0 \
  --values cp-values.yaml \
  | grep -E '^[[:space:]]+image:'

aisix-cp-api 和 aisix-cp-dpm 镜像应使用 1.6.0 版本，或有意设置的、与目标版本兼容的自定义 tag。PostgreSQL 是独立版本化的 Chart 依赖。除非另有经过单独测试的数据库镜像方案要求使用其他 tag，否则请保留 1.6.0 Chart 渲染出的 PostgreSQL 镜像 tag。

按你的部署形态继续相应的升级路径：

私有化部署的 AISIX Cloud，请继续升级私有化部署的 AISIX Cloud。
开源 AISIX 网关，请跳过 AISIX Cloud 流程，继续升级开源 AISIX 网关。

升级私有化部署的 AISIX Cloud

升级控制面

升级控制面时不要使用 --atomic，并且只有在它通过验证后才继续升级受管网关。新版 API 会在启动时迁移数据库，而 Helm 的自动回滚只会还原 Kubernetes 对象，不会恢复数据库备份。

helm upgrade "$CP_RELEASE" api7/aisix-cp \
  --namespace "$CP_NAMESPACE" \
  --version 1.6.0 \
  --values cp-values.yaml \
  --wait \
  --timeout "$CP_UPGRADE_TIMEOUT"

控制面 API 执行数据库迁移期间，数据面管理器可能短暂记录缺表错误，它会自动重试。如果控制面 API 就绪后这些错误仍在持续，请进行排查。

观察滚动更新。如果 API Pod 未就绪，请先 describe 它；如果容器已经启动，再查看它的日志：

oc rollout status -n "$CP_NAMESPACE" \
  "deployment/$CP_API_DEPLOYMENT" \
  --timeout="$CP_UPGRADE_TIMEOUT"

oc get pods -n "$CP_NAMESPACE" \
  -l "app.kubernetes.io/instance=$CP_RELEASE,app.kubernetes.io/component=api"

oc describe pod -n "$CP_NAMESPACE" <non-ready-cp-api-pod>

oc logs -n "$CP_NAMESPACE" \
  <non-ready-cp-api-pod> \
  --all-containers \
  --tail=300

通过公开端点确认控制面版本。将 AISIX_CP 设置为现有端点加上 /api，末尾不带斜杠。对于使用 OpenShift Route 的部署，请使用 Route 的源站地址：

export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"

curl -fsS "$AISIX_CP/config/public" | jq '{cp_version, cp_commit}'

登录控制台并确认：

组织、环境、模型、Provider Key 和调用方 API Key 都在；
原有网关在环境的 Data planes 视图中保持健康；
控制面和数据面管理器的 Route（如有）仍指向原来的 Service。

升级受管网关

AISIX Cloud 控制面通过验证后，再逐个升级受管网关的 Release。

运行 Helm 之前，先打开第二个终端观察网关 Pod，并让它一直运行到 Helm 返回：

oc get pods -n "$GATEWAY_NAMESPACE" \
  -l "app.kubernetes.io/instance=$GATEWAY_RELEASE,app.kubernetes.io/component=gateway" \
  --watch

如果新 Pod 卡住或反复重启，按 Ctrl+C 停止观察，或者打开第三个终端。趁原终端中的 Helm 仍在等待时，记录该 Pod 的 describe 输出和日志。原子回滚可能在 Helm 命令返回之前就删除失败的目标 Pod；请参阅网关未就绪。

在原终端中运行升级：

helm upgrade "$GATEWAY_RELEASE" api7/aisix \
  --namespace "$GATEWAY_NAMESPACE" \
  --version 1.6.0 \
  --values gateway-values.yaml \
  --atomic \
  --timeout "$GATEWAY_UPGRADE_TIMEOUT"

--atomic 会一直阻塞，直到 1.6.0 版本就绪，或 Helm 在失败后完成回滚。如果命令以非零状态退出，不要把之后 oc rollout status 的成功当作 1.6.0 版本升级成功的证据，它报告的可能是已恢复的修订版本。请保留 Helm 运行期间记录的诊断信息，然后查看 Release 历史并确认恢复后的网关 Release：

helm history "$GATEWAY_RELEASE" -n "$GATEWAY_NAMESPACE"

在 Chart 默认的滚动更新策略和就绪探针下，新网关加载到可用配置之前，就绪状态一直为 false。因此 OKD 会把该 Pod 排除在 Service 端点之外，直到它能处理流量。如果升级必须避免流量中断，请确认 gateway-values.yaml 没有选择 Recreate 更新策略，并且 readinessProbe.enabled 保持为 true。单副本部署在替换唯一的 Pod 时仍可能中断。

如果 Helm 命令成功，请确认 1.6.0 的滚动更新已完成，且每个网关 Pod 都已就绪：

oc rollout status -n "$GATEWAY_NAMESPACE" \
  "deployment/$GATEWAY_DEPLOYMENT" \
  --timeout="$GATEWAY_UPGRADE_TIMEOUT"

oc get pods -n "$GATEWAY_NAMESPACE"

验证部署

在 Data planes 视图中确认每个网关都报告 1.6.0 版本且状态健康。将 AISIX_PROXY 设置为现有网关端点，末尾不带斜杠。对于使用 OpenShift Route 的部署，请使用 Route 的源站地址。然后列出调用方可用的模型：

export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
export AISIX_API_KEY="<caller-api-key>"

curl -fsS "$AISIX_PROXY/v1/models" \
  -H "Authorization: Bearer $AISIX_API_KEY"

发送一个有代表性的推理请求，并检查该部署所依赖的访问日志、指标和用量上报。在变更策略规定的观察期结束之前，请保留保存的 values。对于私有化部署的 AISIX Cloud，请在同一期间内保留完整的恢复集。

升级开源 AISIX 网关

如果你运行的是不带控制面的开源 AISIX 网关，请先完成前提条件、准备升级、记录当前部署和运行 OKD 预检，再按本路径操作。

校验网关资源

升级之前，用目标网关镜像校验网关的完整资源。首先在不打印内联资源文档的前提下，确认该 Release 使用哪种资源来源：

helm get values "$GATEWAY_RELEASE" -n "$GATEWAY_NAMESPACE" -o json \
  | jq '{inline_resources: (((.standalone.resources // {}) | length) > 0), existing_secret: (.standalone.existingSecret // ""), existing_config_map: (.standalone.existingConfigMap // "")}'

export TARGET_RESOURCES_FILE="$(mktemp "$PWD/aisix-resources.XXXXXX")"
chmod 600 "$TARGET_RESOURCES_FILE"

使用与该来源对应的命令。对于内联资源，渲染目标 Chart 管理的 Secret 并提取完整文档：

helm template "$GATEWAY_RELEASE" api7/aisix \
  --namespace "$GATEWAY_NAMESPACE" \
  --version 1.6.0 \
  --values gateway-values.yaml \
  --show-only templates/secret.yaml \
  | awk '
    /^  resources\.yaml: \|$/ { in_resources = 1; next }
    in_resources && /^---$/ { exit }
    in_resources { sub(/^    /, ""); print }
  ' > "$TARGET_RESOURCES_FILE"

对于已有的 Secret 或 ConfigMap，请把占位符替换为上一条 jq 命令报告的名称：

# Choose one command.
oc extract -n "$GATEWAY_NAMESPACE" \
  'secret/<existing-secret-name>' \
  --keys=resources.yaml --to=- > "$TARGET_RESOURCES_FILE"

oc extract -n "$GATEWAY_NAMESPACE" \
  'configmap/<existing-config-map-name>' \
  --keys=resources.yaml --to=- > "$TARGET_RESOURCES_FILE"

使用从目标 Deployment 渲染结果中获取的 TARGET_GATEWAY_IMAGE 校验提取出的文档。导出资源文件引用的每个环境变量，并为每个变量添加一个 -e 选项。示例使用 OPENAI_API_KEY 和 CALLER_API_KEY，请替换为你资源文件中的变量名。

该命令把文档以流的方式传入短生命周期的容器，而不是把主机文件 bind mount 进去。这样网关镜像就能读取该文档，而无需放宽主机文件权限或修改其 SELinux 标签。

docker run --rm -i \
  -e OPENAI_API_KEY \
  -e CALLER_API_KEY \
  --entrypoint /bin/sh "$TARGET_GATEWAY_IMAGE" \
  -c 'umask 077; cat > /tmp/resources.yaml && exec /usr/local/bin/aisix validate --resources /tmp/resources.yaml' \
  < "$TARGET_RESOURCES_FILE" && {
    rm -f "$TARGET_RESOURCES_FILE" &&
    unset TARGET_RESOURCES_FILE
  }

继续之前，请解决所有校验错误。校验失败时会保留提取出的文件以供检查，并返回非零状态。如果资源文件不引用环境变量，请省略 -e 选项。

升级网关

完成共同的准备工作和资源校验后，再升级开源网关。

运行 Helm 之前，先打开第二个终端观察网关 Pod，并让它一直运行到 Helm 返回：

oc get pods -n "$GATEWAY_NAMESPACE" \
  -l "app.kubernetes.io/instance=$GATEWAY_RELEASE,app.kubernetes.io/component=gateway" \
  --watch

在原终端中运行升级：

helm upgrade "$GATEWAY_RELEASE" api7/aisix \
  --namespace "$GATEWAY_NAMESPACE" \
  --version 1.6.0 \
  --values gateway-values.yaml \
  --atomic \
  --timeout "$GATEWAY_UPGRADE_TIMEOUT"

helm history "$GATEWAY_RELEASE" -n "$GATEWAY_NAMESPACE"

如果 Helm 命令成功，请确认 1.6.0 的滚动更新已完成，且每个网关 Pod 都已就绪：

oc rollout status -n "$GATEWAY_NAMESPACE" \
  "deployment/$GATEWAY_DEPLOYMENT" \
  --timeout="$GATEWAY_UPGRADE_TIMEOUT"

oc get pods -n "$GATEWAY_NAMESPACE"

验证网关

将 AISIX_PROXY 设置为现有网关端点，末尾不带斜杠。对于使用 OpenShift Route 的部署，请使用 Route 的源站地址。然后列出调用方可用的模型：

export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
export AISIX_API_KEY="<caller-api-key>"

curl -fsS "$AISIX_PROXY/v1/models" \
  -H "Authorization: Bearer $AISIX_API_KEY"

发送一个有代表性的推理请求，并检查该部署所依赖的访问日志、指标和用量上报。在变更策略规定的观察期结束之前，请保留保存的 values。

升级故障排查

如果升级后的工作负载未就绪或未重新连接，请从下面对应的症状开始排查。

Web 控制台报告缺少 PostgreSQL 依赖

最初用 Helm CLI 安装的控制面 Release，可能无法在 OKD Web 控制台中升级。如果控制台报告以下错误，请改用升级控制面中的 Helm CLI 流程：

found in Chart.yaml, but missing in charts/ directory: postgresql

已发布的控制面 Chart 已经包含 PostgreSQL 依赖，因此不要单独下载该依赖，也不要重新构建 Chart。

Pod 被 SCC 拒绝

把命名空间设置为包含被拒绝工作负载的项目。找到 FailedCreate 事件，然后 describe 该事件报告的控制器类型和名称。网关或控制面 API 的 Pod 归 ReplicaSet 所有，随包 PostgreSQL 则归 StatefulSet 所有：

export FAILED_NAMESPACE="<project-containing-rejected-workload>"

oc get events -n "$FAILED_NAMESPACE" --sort-by=.lastTimestamp
oc describe -n "$FAILED_NAMESPACE" <controller-kind>/<controller-name>

从 AISIX 应用 Pod 中删除固定的 runAsUser、runAsGroup 和 fsGroup 值。对于随包 PostgreSQL，按运行 OKD 预检中的说明关闭 Pod 和容器安全上下文。

控制面未就绪

找到未就绪的控制面 API Pod 并 describe 它。数据库迁移失败、数据库无法连接或缺少 Secret，都会导致其无法就绪。如果容器已经启动，请查看 Pod 日志：

oc get pods -n "$CP_NAMESPACE" \
  -l "app.kubernetes.io/instance=$CP_RELEASE,app.kubernetes.io/component=api"

oc describe pod -n "$CP_NAMESPACE" <non-ready-cp-api-pod>

oc logs -n "$CP_NAMESPACE" \
  <non-ready-cp-api-pod> \
  --all-containers \
  --tail=300

不要反复重新运行升级。如果迁移无法完成，请按批准的回滚流程恢复完整的升级前恢复集。

网关未就绪

停止观察后，趁 Helm 仍在等待，针对观察中报告的新目标 Pod 运行以下诊断命令；也可以在第三个终端中运行。原子升级失败返回后，失败的 Pod 可能已经不存在；这时请使用已记录的输出和事件，再用上面的 Release 历史命令确认恢复后的修订版本。

oc get events -n "$GATEWAY_NAMESPACE" --sort-by=.lastTimestamp

oc get pods -n "$GATEWAY_NAMESPACE" \
  -l "app.kubernetes.io/instance=$GATEWAY_RELEASE,app.kubernetes.io/component=gateway"

oc describe pod -n "$GATEWAY_NAMESPACE" <non-ready-gateway-pod>

oc logs -n "$GATEWAY_NAMESPACE" \
  <non-ready-gateway-pod> \
  --all-containers \
  --tail=300

如果有容器重启过，请用 oc describe pod 找到它的名称，然后不带 --all-containers 查看该容器上一次运行的日志：

oc describe pod -n "$GATEWAY_NAMESPACE" <non-ready-gateway-pod>

oc logs -n "$GATEWAY_NAMESPACE" \
  <non-ready-gateway-pod> \
  -c <restarted-container-name> \
  --previous \
  --tail=300

对于私有化部署的 AISIX Cloud，请确认该 Pod 能通过双向 TLS 访问现有的数据面管理器端点。如果端点使用 OpenShift Route，请确认该 Route 使用 TLS 透传（passthrough）。无论哪种情况，都请确认端点主机名仍与网关配置中的地址一致。

对于开源 AISIX 网关，请检查日志中的资源校验错误。确认保存的 standalone values 仍指向完整的资源文件，并且网关能访问每个已配置的上游端点。

滚动更新后网关验证失败

如果滚动更新已就绪，但模型列表、推理、日志、指标或用量检查失败，请检查网关日志和 Helm Release 历史。如果无法在本版本上安全地修复故障，请把网关回滚到升级前的修订版本：

helm history "$GATEWAY_RELEASE" -n "$GATEWAY_NAMESPACE"

helm rollback "$GATEWAY_RELEASE" <pre-upgrade-revision> \
  --namespace "$GATEWAY_NAMESPACE" \
  --wait \
  --timeout "$GATEWAY_UPGRADE_TIMEOUT"

等回滚完成后，按情况重新执行验证部署或验证网关。对于私有化部署的 AISIX Cloud，请让已通过验证的控制面保持在本版本。受支持的混合版本窗口允许上一版网关在你排查期间保持连接。

前提条件​

准备升级​

记录当前部署​

运行 OKD 预检​

升级私有化部署的 AISIX Cloud​

升级控制面​

升级受管网关​

验证部署​

升级开源 AISIX 网关​

校验网关资源​

升级网关​

验证网关​

升级故障排查​

Web 控制台报告缺少 PostgreSQL 依赖​

Pod 被 SCC 拒绝​

控制面未就绪​

网关未就绪​

滚动更新后网关验证失败​