版本：1.5.0

环境变量

AISIX AI 网关使用环境变量选择启动配置文件、覆盖启动配置字段，并提供 AISIX 网关证书材料等部署相关值。

大多数运行时网关资源不直接通过环境变量配置。对于开源 AISIX 网关，请在 resources.yaml 文件中声明模型、调用方 API Key、服务提供方密钥、安全护栏、缓存策略和可观测性导出器。该文件支持对 ${OPENAI_API_KEY} 等值进行环境变量插值。

对于连接到 AISIX Cloud 的 AISIX 网关，这些资源由控制面下发。

保留环境变量

AISIX 保留以下环境变量：

变量	说明
`AISIX_CONFIG`	AISIX 二进制程序使用的启动配置文件路径，等同于传递 `--config`。仅在直接运行二进制程序时读取。
`AISIX_CONFIG_PATH`	官方容器入口使用的配置文件路径，默认值为 `/etc/aisix/config.yaml`。
`AISIX_DP_BUDGET_STALE_MAX_SECONDS`	控制面不可达时，连接到 AISIX Cloud 的网关继续接受缓存预算决策的最长时间（秒）。默认值为 `600`。
`RUST_LOG`	进程日志指令。未设置时，AISIX 使用 `observability.log_level`。

这些是 AISIX 中不指向启动配置字段的变量。AISIX 按名称读取每一个，绝不会把它们当作启动配置覆盖项。

直接运行二进制文件时，请使用 --config 选项选择启动配置：

aisix --config /etc/aisix/config.yaml

仅在使用官方容器入口时使用 AISIX_CONFIG_PATH：

docker run \
  -v "$(pwd)/config.prod.yaml:/etc/aisix/config.prod.yaml:ro" \
  -e AISIX_CONFIG_PATH="/etc/aisix/config.prod.yaml" \
  ghcr.io/api7/aisix:1.5.0

启动配置覆盖

AISIX 加载配置文件后，会应用以 AISIX_ 为前缀的环境变量覆盖项。前缀后使用单下划线，嵌套字段之间使用双下划线。

以下示例覆盖代理监听地址：

export AISIX_PROXY__ADDR="0.0.0.0:3000"

常见覆盖变量包括：

变量	覆盖字段
`AISIX_PROXY__ADDR`	`proxy.addr`
`AISIX_PROXY__THREAD_PER_CORE`	`proxy.thread_per_core`
`AISIX_PROXY__WORKERS`	`proxy.workers`
`AISIX_ETCD__ENDPOINTS`	`etcd.endpoints`
`AISIX_ETCD__PREFIX`	`etcd.prefix`
`AISIX_OBSERVABILITY__LOG_LEVEL`	`observability.log_level`
`AISIX_CACHE__REDIS__MODE`	`cache.redis.mode`
`AISIX_CACHE__REDIS__URL`	`cache.redis.url`
`AISIX_CACHE__REDIS__MASTER_NAME`	`cache.redis.master_name`
`AISIX_CACHE__REDIS__USERNAME`	`cache.redis.username`
`AISIX_CACHE__REDIS__PASSWORD`	`cache.redis.password`
`AISIX_CACHE__REDIS__DATABASE`	`cache.redis.database`
`AISIX_CACHE__REDIS__TIMEOUT_SECS`	`cache.redis.timeout_secs`
`AISIX_RATELIMIT__BACKEND`	`ratelimit.backend`
`AISIX_RATELIMIT__REDIS__MODE`	`ratelimit.redis.mode`
`AISIX_RATELIMIT__REDIS__URL`	`ratelimit.redis.url`
`AISIX_RATELIMIT__REDIS__MASTER_NAME`	`ratelimit.redis.master_name`
`AISIX_RATELIMIT__REDIS__USERNAME`	`ratelimit.redis.username`
`AISIX_RATELIMIT__REDIS__PASSWORD`	`ratelimit.redis.password`
`AISIX_RATELIMIT__REDIS__DATABASE`	`ratelimit.redis.database`
`AISIX_RATELIMIT__REDIS__TIMEOUT_SECS`	`ratelimit.redis.timeout_secs`
`AISIX_RATELIMIT__CONCURRENCY_TTL_SECS`	`ratelimit.concurrency_ttl_secs`
`AISIX_BEDROCK_ENDPOINT_URL`	顶层 `bedrock_endpoint_url`。

列表字段在环境变量中取逗号分隔的值，例如 AISIX_ETCD__ENDPOINTS="http://etcd-0:2379,http://etcd-1:2379"。以下字段接受这种写法：

变量	覆盖字段
`AISIX_ETCD__ENDPOINTS`	`etcd.endpoints`
`AISIX_ADMIN__ADMIN_KEYS`	`admin.admin_keys`
`AISIX_PROXY__REAL_IP__TRUSTED_PROXIES`	`proxy.real_ip.trusted_proxies`
`AISIX_PROXY__REQUEST_ID__ACCEPT_HEADERS`	`proxy.request_id.accept_headers`
`AISIX_OBSERVABILITY__METRICS__BUCKETS__REQUEST_E2E_LATENCY`	`observability.metrics.buckets.request_e2e_latency`
`AISIX_OBSERVABILITY__METRICS__BUCKETS__REQUEST_TTFT`	`observability.metrics.buckets.request_ttft`
`AISIX_OBSERVABILITY__METRICS__BUCKETS__GUARDRAIL_LATENCY`	`observability.metrics.buckets.guardrail_latency`
`AISIX_OBSERVABILITY__METRICS__BUCKETS__A2A_TTFB`	`observability.metrics.buckets.a2a_ttfb`

对于 Redis Cluster 和 Sentinel 节点列表以及堆 profile 阈值，请在启动配置文件中配置 cache.redis.nodes、cache.redis.sentinels、ratelimit.redis.nodes、ratelimit.redis.sentinels 或 observability.heap_profiling.auto_dump.thresholds。通过环境变量设置其中任一字段会导致网关无法启动。

配置文件字段请参见启动配置参考。

无法识别的 AISIX 变量

AISIX 依据首段判断一个以 AISIX_ 为前缀的变量。它先把变量名转为小写、去掉前缀，再按 __ 或 . 切分剩余部分。如果首段是启动配置的顶层配置块之一——admin、bedrock_endpoint_url、cache、downstream、etcd、managed、observability、proxy、ratelimit、resources_file、shutdown、upstream——该变量会作为覆盖项生效。否则它会被忽略，AISIX 在启动时为每个这样的变量打印一条警告：

AISIX_OSS_PORT_9090_TCP_PROTO was not applied as a configuration override: it names no gateway setting, and a nested setting is spelled AISIX_<SECTION>__<KEY>. If the configuration reads it by name (etcd.password_env, a resources-file interpolation) it still applies; otherwise nothing reads it — Kubernetes injects variables of this shape for every Service named aisix or aisix-*, which enableServiceLinks: false on the pod spec turns off.

「被忽略」不等于「没有任何地方读取它」。如果配置按名称引用了该变量——例如 etcd.password_env，或 resources.yaml 插值——它仍然生效，因为这类引用是在配置解析完成之后按名称解析的。而这条警告是在两者都还不可知时打印的。

真实配置块下面的拼写错误则是另一回事，不会被容忍。AISIX_PROXY__TIMEOTU 的首段是 proxy，因此它会进入配置解析器，并以未知字段错误导致启动失败。这是有意为之：你本想设置某项配置却拼错了，应当让网关停下来，而不是被静默丢弃。

保留环境变量会被跳过且不打印警告，因为 AISIX 按名称读取它们。

Kubernetes Service 链接变量

Kubernetes 会为命名空间中的每个 Service，向每个容器注入一组以该 Service 命名的 Docker 风格链接变量。因此，名为 aisix 或 aisix-xxx 的 Service 会在网关容器中产生 AISIX_PORT_80_TCP_ADDR、AISIX_OSS_SERVICE_HOST 之类的变量——其中既包括发布这个网关自身的 Service，也包括安装在同一命名空间中的 AISIX Cloud 控制面。

它们都不指向任何网关配置项，因此每个都会产生一条启动警告。请在 Pod spec 上关闭该行为：

spec:
  template:
    spec:
      enableServiceLinks: false

官方 api7/aisix Helm chart 已经在网关 Pod 上设置了该字段。如果你使用手写 manifest 部署网关，请自行设置。

AISIX Cloud 连接变量

AISIX 网关同样使用 AISIX_ 覆盖机制设置 managed.* 启动配置。

变量	说明
`AISIX_MANAGED__ENABLED`	设置为 `true` 时将网关连接到 AISIX Cloud。
`AISIX_MANAGED__CP_BASE_URL`	AISIX Cloud 控制面源地址，用于心跳、遥测、证书轮换和预算检查。需为 `https://` URL，例如 `https://dpm.example.com:7944`。
`AISIX_MANAGED__CP_ETCD_ENDPOINT`	网关启动时使用的控制面 etcd 端点。为不带 URL scheme 的 `host:port`。
`AISIX_MANAGED__CP_CA_CERT_FILE`	可选 CA bundle 文件，用于信任控制面和 etcd 的 TLS 连接。
`AISIX_MANAGED__CP_CERT_PEM`	用于与 AISIX Cloud 控制面建立 mTLS 的内联客户端证书 PEM。
`AISIX_MANAGED__CP_KEY_PEM`	与客户端证书配对的内联私钥 PEM。
`AISIX_MANAGED__CP_CA_PEM`	作为信任锚的内联 CA 证书 PEM。
`AISIX_MANAGED__CP_CERT_FILE`	客户端证书 PEM 文件路径。
`AISIX_MANAGED__CP_KEY_FILE`	私钥 PEM 文件路径。
`AISIX_MANAGED__CP_CA_FILE`	CA 证书 PEM 文件路径。
`AISIX_MANAGED__MTLS_DIR`	网关持久化已生成 mTLS bundle 的目录。
`AISIX_MANAGED__DP_ID_FILE`	网关持久化 AISIX 网关 ID 的文件。
`AISIX_MANAGED__SNAPSHOT_CACHE_ENABLED`	启用磁盘配置快照缓存，默认为 `false`。
`AISIX_MANAGED__SNAPSHOT_CACHE_PATH`	`AISIX_MANAGED__SNAPSHOT_CACHE_ENABLED` 为 `true` 时使用的磁盘快照缓存文件路径。仅配置路径不会启用缓存。
`AISIX_MANAGED__HEARTBEAT_INTERVAL_SECS`	AISIX 网关心跳间隔（秒）。默认值为 `15`；取值会被限制在 `5` 到 `300` 之间。

证书、私钥和 CA bundle 应选择内联 PEM 变量或文件路径变量之一。同一个 bundle 不要混用内联和文件形式。

AISIX Cloud 连接设置请参见连接 AISIX 网关。

保留环境变量​

启动配置覆盖​

无法识别的 AISIX 变量​

Kubernetes Service 链接变量​

AISIX Cloud 连接变量​

保留环境变量

启动配置覆盖

无法识别的 AISIX 变量

Kubernetes Service 链接变量

AISIX Cloud 连接变量