在 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
kubectl -n aisix create secret generic openai-credentials \
  --from-literal=api-key="$OPENAI_API_KEY"
kubectl -n aisix 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 api7/aisix --namespace aisix \
  -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:1.5.0 \
  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:1.5.0 \
  validate --resources /work/resources.yaml

使用现有 Secret

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

kubectl -n aisix create secret generic aisix-resources \
  --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

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 create configmap aisix-resources \
  --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

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 api7/aisix --namespace aisix --version 1.5.0 -f values.yaml

验证部署

等待网关 Deployment 可用：

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

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

kubectl -n aisix port-forward service/aisix 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，并在 /etc/aisix/standalone/config.yaml 渲染只包含以下两个设置的启动配置：

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

其他所有配置都通过环境变量传递给网关，并优先于该文件。Chart 会自行设置代理和指标监听器地址。其他启动配置字段请通过 extraEnvVars 以 AISIX_<SECTION>__<KEY> 的形式提供。例如，以下配置会启用调试日志：

extraEnvVars:
  - name: AISIX_OBSERVABILITY__LOG_LEVEL
    value: debug

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 deploy/<release>-aisix -n <namespace>

Chart 会在安装后说明中输出适用于当前安装的命令。

健康检查

两个探针都指向代理端口。代理监听器绑定后，/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.5.0

Chart 源码和软件包发布在 aisix-1.5.0 Helm Chart Release 中。

启用只读 Admin API

Chart 默认不绑定 Admin API，也不发布 Admin Service。使用文件来源时，该 API 为只读。如果需要临时运维访问，请让监听器保持绑定到 Pod 回环地址，并将其密钥存入 Secret：

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

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

将以下条目添加到 values.yaml 中现有的 extraEnvVars 列表。不要创建第二个顶层 extraEnvVars 键：

values.yaml（Admin API 设置）

extraEnvVars:
  - name: AISIX_ADMIN__ENABLED
    value: "true"
  - name: AISIX_ADMIN__ADDR
    value: "127.0.0.1:9180"
  - name: AISIX_ADMIN__ADMIN_KEYS
    valueFrom:
      secretKeyRef:
        name: aisix-admin-keys
        key: admin-key

应用 values，然后在需要时转发该监听器：

helm upgrade aisix api7/aisix --namespace aisix -f values.yaml
kubectl rollout status deployment/aisix --namespace aisix --timeout=5m
kubectl -n aisix port-forward deployment/aisix 9180:9180

迁移到 AISIX Cloud

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

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