版本：1.7.1

在 Kubernetes 上部署 AISIX OSS

api7/aisix Helm Chart 用于在 Kubernetes 上部署开源 AISIX 网关。将 controlPlane.enabled 设为 false，无需控制面或网关证书包即可运行网关，并从声明式 resources.yaml 文件加载资源。

服务提供方密钥、模型、调用方 API Key、安全护栏、MCP 服务器和限流策略均来自该文件；Kubernetes 则管理网关 Pod、Service、健康检查和滚动更新。要部署连接 AISIX Enterprise 或 AISIX Cloud 的网关，请按照连接控制面的安装流程操作。在 OpenShift 或 OKD 上部署时，请改用在 OpenShift 或 OKD 上部署 AISIX OSS。

前置条件

一个已配置 kubectl 访问权限的 Kubernetes 集群。
Helm 3 和 Docker。
一个上游服务提供方密钥和一个调用方 API Key。示例使用 OpenAI 和模型别名 gpt-4o-mini。

准备集群和凭据

导出示例使用的服务提供方凭据和调用方凭据：

# 替换为你的 OpenAI API Key。
export OPENAI_API_KEY="YOUR_PROVIDER_API_KEY"

# 选择一个调用 AISIX 时使用的 API Key。
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

添加 Chart 仓库、创建命名空间，并将两个凭据存储为 Kubernetes Secret：

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

kubectl create namespace aisix-dp
kubectl -n aisix-dp create secret generic openai-credentials \
  --from-literal=api-key="$OPENAI_API_KEY"
kubectl -n aisix-dp create secret generic aisix-caller-keys \
  --from-literal=my-caller="$CALLER_API_KEY"

选择资源来源

controlPlane.enabled 默认为 true。下方每个完整的 values.yaml 都将其设为 false，并从三种来源中的一种提供 resources.yaml。省略来源或同时设置多个来源都会导致 Helm 渲染失败。

配置值	文件位置	适用场景
`standalone.resources`	作为 YAML Map 内联在 values 中。Chart 将其渲染到自己管理的 Secret。	文件与 Release 一同管理。
`standalone.existingSecret`	位于你创建的 Secret 中，键名为 `resources.yaml`。	文件包含明文凭据，或由其他系统管理其生命周期。
`standalone.existingConfigMap`	位于你创建的 ConfigMap 中，键名为 `resources.yaml`。	文件中的每个凭据都是 `${VAR}` 引用，而非明文值。

每个安装示例都只启动一个网关副本，因为限流计数器默认使用每个副本自己的内存。增加副本数前，请先配置共享 Redis。

Chart 会将 standalone.resources 渲染到 Secret 而非 ConfigMap，因为服务提供方密钥属于凭据。凭据仍无需直接写入 values 文件：文件加载时会从容器环境解析 ${VAR} 引用，因此可通过 extraEnvVars 提供取值。参见环境变量插值。

选择下方一种方式。Secret 和 ConfigMap 方式都从相同的文件准备步骤开始。每种方式都会提供完整的 values.yaml，随后继续执行安装网关。

使用内联资源

将以下 Chart 配置保存为 values.yaml。Chart 会把内联资源文档存储到 Secret，而两个凭据值仍保存在前面创建的独立 Secret 中：

values.yaml
replicaCount: 1

image:
  repository: ghcr.io/api7/aisix
  tag: "1.7.1"

controlPlane:
  enabled: false

standalone:
  resources:
    _format_version: "1"
    provider_keys:
      - display_name: openai-main
        provider: openai
        adapter: openai
        api_key: ${OPENAI_API_KEY}
        api_base: https://api.openai.com/v1
    models:
      - display_name: gpt-4o-mini
        provider: openai
        model_name: gpt-4o-mini
        provider_key: openai-main
    api_keys:
      - display_name: my-caller
        key_env: CALLER_API_KEY
        allowed_models:
          - gpt-4o-mini

extraEnvVars:
  - name: OPENAI_API_KEY
    valueFrom:
      secretKeyRef:
        name: openai-credentials
        key: api-key
  - name: CALLER_API_KEY
    valueFrom:
      secretKeyRef:
        name: aisix-caller-keys
        key: my-caller

内联资源并不存在可单独验证的文件。安装前，渲染由 Chart 管理的 Secret，并提取从 values.yaml 组装出的确切资源文档：

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

使用文档引用的凭据验证渲染结果：

docker run --rm -i \
  -e OPENAI_API_KEY -e CALLER_API_KEY \
  --entrypoint /bin/sh ghcr.io/api7/aisix:1.7.1 \
  -c 'umask 077; cat > /tmp/resources.yaml && exec /usr/local/bin/aisix validate --resources /tmp/resources.yaml' \
  < rendered-resources.yaml

流式传入文档可避免修改其宿主机权限或 SELinux 标签。

准备资源文件

Secret 和 ConfigMap 方式都从本地文件开始。按照开源 AISIX 网关快速入门创建可用的 resources.yaml；完整 schema 请参阅资源文件参考。保留快速入门中的 ${OPENAI_API_KEY} 和 key_env: CALLER_API_KEY 引用。

使用与网关将接收的环境变量相同的环境变量验证文件。validate 子命令会解析文件，但不会绑定监听器：

docker run --rm -i \
  -e OPENAI_API_KEY -e CALLER_API_KEY \
  --entrypoint /bin/sh ghcr.io/api7/aisix:1.7.1 \
  -c 'umask 077; cat > /tmp/resources.yaml && exec /usr/local/bin/aisix validate --resources /tmp/resources.yaml' \
  < resources.yaml

流式传入文件可避免修改其宿主机权限或 SELinux 标签。

使用现有 Secret

将经过验证的文件存入 Secret：

kubectl -n aisix-dp create secret generic aisix-resources-file \
  --from-file=resources.yaml=./resources.yaml

将以下 Chart 配置保存为 values.yaml。extraEnvVars 会让 resources.yaml 引用的凭据变量在网关容器中可用：

values.yaml
replicaCount: 1

image:
  repository: ghcr.io/api7/aisix
  tag: "1.7.1"

controlPlane:
  enabled: false

standalone:
  existingSecret: aisix-resources-file

extraEnvVars:
  - name: OPENAI_API_KEY
    valueFrom:
      secretKeyRef:
        name: openai-credentials
        key: api-key
  - name: CALLER_API_KEY
    valueFrom:
      secretKeyRef:
        name: aisix-caller-keys
        key: my-caller

使用现有 ConfigMap

只有经过验证的 resources.yaml 文件中的每个凭据都是环境变量引用时，才使用 ConfigMap。创建 ConfigMap：

kubectl -n aisix-dp create configmap aisix-resources-file \
  --from-file=resources.yaml=./resources.yaml

将以下 Chart 配置保存为 values.yaml：

values.yaml
replicaCount: 1

image:
  repository: ghcr.io/api7/aisix
  tag: "1.7.1"

controlPlane:
  enabled: false

standalone:
  existingConfigMap: aisix-resources-file

extraEnvVars:
  - name: OPENAI_API_KEY
    valueFrom:
      secretKeyRef:
        name: openai-credentials
        key: api-key
  - name: CALLER_API_KEY
    valueFrom:
      secretKeyRef:
        name: aisix-caller-keys
        key: my-caller

部署网关

从 values.yaml 安装网关：

helm install aisix-dp api7/aisix --namespace aisix-dp --version 1.7.1 -f values.yaml

验证部署

等待网关 Deployment 可用：

kubectl rollout status deployment/aisix-dp --namespace aisix-dp --timeout=5m

在另一个终端中，将代理 Service 端口转发到工作站：

kubectl -n aisix-dp port-forward service/aisix-dp 3000:80

回到原来的终端，检查就绪状态，并列出该调用方密钥可用的模型：

export AISIX_PROXY="http://127.0.0.1:3000"

curl -sS "$AISIX_PROXY/readyz"
curl -sS "$AISIX_PROXY/v1/models" \
  -H "Authorization: Bearer $CALLER_API_KEY"

就绪请求应返回 ok，模型列表应包含 gpt-4o-mini。通过网关发送请求，验证服务提供方凭据和上游连接：

curl -sS "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer $CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Reply with: AISIX is ready"
      }
    ]
  }'

成功响应应包含助手消息 AISIX is ready。这表示网关已加载资源和凭据、验证调用方身份，并能够访问上游服务提供方。

Chart 配置内容

Chart 会将资源文件以只读方式挂载到 /etc/aisix/resources/resources.yaml。它会根据 config value 把网关的启动配置渲染到 ConfigMap 中，以只读方式挂载到 /etc/aisix/chart/config.yaml，并为独立模式填入由它负责的键：

resources_file: /etc/aisix/resources/resources.yaml
admin:
  enabled: false

设置 admin.enabled: true 后，Chart 会改为渲染 admin.enabled: true，以及绑定 containerPorts.admin 的 admin.addr。参见启用 Admin API。

Chart 还会根据自身的 value 设置代理和指标监听器地址以及限流后端。其他启动配置字段请写在 config 下，节名和键名与配置文件相同。例如，以下配置会启用调试日志：

config:
  observability:
    log_level: debug

修改 config 后，helm upgrade 会滚动更新 Pod。包含凭据的设置（例如 Redis 密码）请改为通过 configSecrets 从 Secret 读取。Chart 在 config 下拒绝的键以及 configSecrets 的用法，请参阅设置其他网关配置。

extraEnvVars 用于系统级环境变量以及资源文件引用的变量。覆盖 Chart 自身设置的变量只是为现有部署保留的兼容途径，参见设置其他网关配置。

Chart 还会在网关 Pod 上设置 enableServiceLinks: false。否则 Kubernetes 会为命名空间中的每个 Service 注入 Docker 风格的链接变量。名为 aisix 或 aisix-something 的 Service 会生成带 AISIX_ 前缀的变量，而网关会读取这些变量。参见 Kubernetes Service Link。

应用资源文件变更

网关只会在收到 SIGHUP 时重新读取 resources.yaml，而 Chart 不会发送该信号。必须滚动更新 Pod 才会应用变更。

内联资源。 编辑 standalone.resources 并运行 helm upgrade。Pod 模板带有渲染文件的校验和，因此变更会自动滚动更新 Pod。
现有 Secret 或 ConfigMap。 在 Helm 之外编辑对象不会触发滚动更新：Kubernetes 会就地更新挂载文件，但不会通知网关。请显式应用：
```
kubectl rollout restart deployment/aisix-dp -n aisix-dp
```

对于本指南使用的 Release 和 Namespace，Deployment 名称为 aisix-dp。使用其他 Release 名、Namespace 或名称覆盖时，请使用 Chart 安装后说明中输出的 Deployment。Chart 并不总会在 Release 名后追加 -aisix。

健康检查

两个探针都指向代理端口。代理监听器绑定后，/livez 即可响应。当实例能够提供服务时，/readyz 返回 200；实例排空期间返回 503。使用文件来源时，只要文件解析成功就会绑定监听器，网关无需等待配置拉取。参见健康检查。

暴露、扩缩容和运维

Service 暴露、自动扩缩容、Redis 限流计数器、Pod 中断预算、终止和排空不依赖网关获取资源的方式。在 Kubernetes 上部署 AISIX 网关介绍了这些通用的 Kubernetes 运维操作。

运行多个副本前，请配置共享 Redis 后端。限流计数器默认按副本保存，因此 N 个副本会把每项配置的限制放大为 N 倍。

listeners 配置值的用法也相同。开源网关可以同时提供 HTTPS 和纯 HTTP；参见同时提供 HTTPS 和纯 HTTP。

查看 Chart 支持的所有配置值：

helm show values api7/aisix --version 1.7.1

Chart 源码和发布包见 aisix-1.7.1 Helm Chart 发布版本。

启用 Admin API

Chart 默认关闭网关的 Admin API。设置 admin.enabled: true 后，Chart 会在 containerPorts.admin（默认 3001）上绑定 Admin API，并通过单独的 ClusterIP Service <fullname>-admin 发布它；release 名为 aisix-dp 时，该 Service 名为 aisix-dp-admin。代理 Service 永远不会承载它。

针对资源文件，/admin/v1/* 是只读的：它列出和获取网关已加载的内容，包括模型状态。对这些路径的每个请求都需要携带一个 Admin Key，形式为 Authorization: Bearer <key> 或 x-api-key: <key>。

同一个监听器还提供 Playground，即 POST /playground/chat/completions。它与代理一样使用调用方 API Key 认证，并会向你的上游提供商发送真实请求。只读仅适用于 /admin/v1/*，因此请把 Admin Service 的访问权限视同代理的访问权限。

将 Admin Key 存入你自己管理的 Secret，避免写进 values 文件：

# 选择一个 Admin API Key。
export AISIX_ADMIN_KEY="YOUR_ADMIN_API_KEY"

kubectl -n aisix-dp create secret generic aisix-admin-keys \
  --from-literal=admin-keys="$AISIX_ADMIN_KEY"

在 values.yaml 中添加以下内容：

values.yaml（Admin API）
admin:
  enabled: true
  existingSecret: aisix-admin-keys

Value	默认值	说明
`admin.enabled`	`false`	绑定 Admin API 并创建 Admin Service。
`admin.keys`	`[]`	Admin Key，渲染到由 Chart 管理的 Secret 中。
`admin.existingSecret`	`""`	改为从现有 Secret 读取 Admin Key。
`admin.existingSecretKey`	`admin-keys`	`admin.existingSecret` 中保存 Admin Key 的键。多个 Key 用逗号分隔。
`containerPorts.admin`	`3001`	Admin API 在容器内绑定的端口。
`admin.service.port`	`3001`	Admin Service 的端口。
`admin.service.annotations`	`{}`	Admin Service 的额外注解。

无论采用哪种方式，Admin Key 都会以 AISIX_ADMIN__ADMIN_KEYS 环境变量的形式从 Secret 传给网关，永远不会写入配置 ConfigMap。网关按逗号分隔读取该变量，因此 Admin Key 中不能包含逗号。

如果 admin.enabled 为 true，但 admin.keys 和 admin.existingSecret 都没有提供 Key，渲染会失败。如果同时设置了 controlPlane.enabled: true，渲染也会失败：Admin API 只适用于独立模式，因为连接到控制面的网关没有 Admin API。

应用 values，然后在需要时转发 Admin Service：

helm upgrade aisix-dp api7/aisix --namespace aisix-dp --version 1.7.1 -f values.yaml
kubectl rollout status deployment/aisix-dp --namespace aisix-dp --timeout=5m
kubectl -n aisix-dp port-forward svc/aisix-dp-admin 3001:3001

在另一个终端中列出网关已加载的模型：

curl "http://127.0.0.1:3001/admin/v1/models" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}"

已经通过 extraEnvVars 中的 AISIX_ADMIN__* 变量绑定 Admin API 的 release 仍可继续工作，因为环境变量会覆盖配置文件。把这些设置迁移到 admin 后，API 还会获得自己的 Service。

迁移到 AISIX Enterprise 或 AISIX Cloud

AISIX OSS 不包含控制面控制台、组织和环境、集中式用量与成本报告、预算或按环境交付配置的功能。请改为将日志和指标导出到自己运维的系统；参见导出器。

通过 AISIX Enterprise 或 AISIX Cloud 部署网关，并由控制面签发网关证书。资源不会自动迁移；请按照规划迁移在所选产品中重新创建。

前置条件​

准备集群和凭据​

选择资源来源​

使用内联资源​

准备资源文件​

使用现有 Secret​

使用现有 ConfigMap​

部署网关​

验证部署​

Chart 配置内容​

应用资源文件变更​

健康检查​

暴露、扩缩容和运维​

启用 Admin API​

迁移到 AISIX Enterprise 或 AISIX Cloud​