版本：Dev

在 Kubernetes 上部署开源 AISIX 网关

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

服务提供方密钥、模型、调用方 API Key、护栏、MCP 服务器和限流策略均来自该文件；Kubernetes 则管理网关 Pod、Service、健康检查和滚动更新。如果要为 AISIX Cloud 部署网关，请参阅在 Kubernetes 上部署 AISIX 网关。

前置条件

一个已配置 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: dev

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 \
  -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 -v "$(pwd):/work:ro" \
  -e OPENAI_API_KEY -e CALLER_API_KEY \
  --entrypoint /usr/local/bin/aisix ghcr.io/api7/aisix:dev \
  validate --resources /work/rendered-resources.yaml

准备资源文件

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

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

docker run --rm -v "$(pwd):/work:ro" \
  -e OPENAI_API_KEY -e CALLER_API_KEY \
  --entrypoint /usr/local/bin/aisix ghcr.io/api7/aisix:dev \
  validate --resources /work/resources.yaml

使用现有 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: dev

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: dev

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 -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

Chart 源码发布在 api7/api7-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 -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 Cloud

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

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

前置条件​

准备集群和凭据​

选择资源来源​

使用内联资源​

准备资源文件​

使用现有 Secret​

使用现有 ConfigMap​

安装网关​

验证部署​

Chart 配置内容​

应用资源文件变更​

健康检查​

暴露、扩缩容和运维​

启用 Admin API​

迁移到 AISIX Cloud​