版本：3.19.0

环境变量

APISIX 支持在配置文件和插件字符串字段中使用环境变量。部分变量有保留用途，你也可以定义用于部署特定值和 Secret 的自定义变量。

保留环境变量

APISIX 目前保留以下环境变量：

变量名	描述
`APISIX_DEPLOYMENT_ETCD_HOST`	etcd 端点 URL 的 JSON 数组，例如 `["http://etcd:2379"]`。
`APISIX_PROFILE`	区分配置文件的部署环境。
`APISIX_WORKER_PROCESSES`	工作进程的数量。

要使用这些配置，请在启动 APISIX 之前为环境变量赋值。

以下示例将保留的 etcd 主机变量设置为带引号的 JSON 数组：

export APISIX_DEPLOYMENT_ETCD_HOST='["http://etcd:2379"]'

APISIX 会将该值解码为 JSON，并在验证配置前替换 deployment.etcd.host。http://etcd:2379 这样的纯 URL 不是有效的 JSON；APISIX 会报告解析失败，并保留 config.yaml 中的 etcd 主机。

自定义环境变量

你可以在配置文件中和某些插件中使用自定义环境变量。

将变量传递给 NGINX Worker 进程

使用 config.yaml 中的 nginx_config.envs 将变量提供给 NGINX Worker 进程。没有等号的名称会继承启动 APISIX 的环境中的值；NAME=value 条目会将配置的值赋给每个 Worker：

config.yaml
nginx_config:
  envs:
    - APP_MODE
    - "GREETING=hello world"

APISIX 会为生成的 NGINX env 指令添加引号，因此赋值可以包含空格。嵌入的引号和反斜杠会在生成的配置中转义。包括换行符在内的控制字符会在配置校验时被拒绝。

更改 nginx_config.envs 后，请重新加载 APISIX，使新的 Worker 收到这些值。插件字段随后可通过 $env://APP_MODE、$env://GREETING 或大写形式 $ENV:// 引用它们。

配置文件

使用 ${{ENV_VAR}} 要求必须提供变量值，或使用 ${{ENV_VAR:=default_value}} 提供回退值。APISIX 确定结果类型的方式取决于配置文件：

在 apisix.yaml 中，APISIX 会先替换原始文件中的占位符，再解析 YAML。因此，未加引号的占位符可能成为数字或布尔值。请为占位符加引号，以将替换值保留为字符串。
在 config.yaml 和 apisix.json 中，APISIX 会先解析文件，再替换占位符。仅由数字组成的替换值或字面值 true、false 会转换为相应原生类型。为占位符加引号不会强制这些文件将替换值保留为字符串。

有关各种行为的示例，请参阅配置文件。

以下示例在环境变量中设置客户端请求和 Admin API 的监听端口：

export APISIX_NODE_LISTEN=8132
export ADMIN_API_PORT=9232

在 config.yaml 中，按如下方式引用环境变量：

config.yaml
apisix:
  node_listen:
    - ${{APISIX_NODE_LISTEN}}
deployment:
  admin:
    admin_listen:
      port: ${{ADMIN_API_PORT}}

启动后，APISIX 将监听端口 8132 用于客户端请求，监听端口 9232 用于 Admin API 请求。

你还可以配置默认值，以便在未设置环境变量时回退，例如：

config.yaml
apisix:
  node_listen:
    - ${{APISIX_NODE_LISTEN:=9080}}
deployment:
  admin:
    admin_listen:
      port: ${{ADMIN_API_PORT:=9180}}

如果 APISIX 无法在环境中解析 APISIX_NODE_LISTEN 和 ADMIN_API_PORT 的值，它将默认监听端口 9080 用于客户端请求，监听端口 9180 用于 Admin API 请求。

插件

APISIX 支持在插件字符串字段中使用 $env://NAME 和 $ENV://NAME 引用，包括 Redis 密码或身份认证密钥等机密值。被引用的变量必须可供 APISIX Worker 进程使用，例如通过 NGINX env 指令或容器环境传入。

以下示例演示了如何配置 key-auth 插件以从环境变量获取用户身份认证密钥。

将密钥的值保存到环境变量：

export JACK_AUTH_KEY=jack-key

提示

如果你在 Docker 中运行 APISIX，你应该在启动容器时使用 -e 标志设置环境变量。

创建消费者 jack：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "jack"
  }'

为消费者配置 key-auth 凭证：

curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-jack-key-auth",
    "plugins": {
      "key-auth": {
        "key": "$env://JACK_AUTH_KEY"
      }
    }
  }'

创建路由并启用 key-auth：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "key-auth-route",
    "uri": "/anything",
    "plugins": {
      "key-auth": {}
    },
    "upstream" : {
      "nodes": {
        "httpbin.org": 1
      }
    }
  }'

使用身份认证密钥向路由发送请求：

curl "http://127.0.0.1:9080/anything" -H 'apikey: jack-key'

你应该收到 HTTP/1.1 200 OK 响应。

有关插件中环境变量支持的更多信息，请参阅插件文档。

保留环境变量​

自定义环境变量​

将变量传递给 NGINX Worker 进程​

配置文件​

插件​

保留环境变量

自定义环境变量

将变量传递给 NGINX Worker 进程

配置文件

插件