环境变量

API7 网关支持使用环境变量配置消费者凭证、SSL 证书和部分插件。某些环境变量有专门用途并已被保留；你也可以创建并引用自定义名称的环境变量。

保留的环境变量

API7 网关目前保留以下环境变量：

变量名	说明
APISIX_DEPLOYMENT_ETCD_HOST	DP Manager 端点 URL 的 JSON 数组。
APISIX_WORKER_PROCESSES	工作进程数量。

请用引号括住端点数组，以便 Shell 保留有效的 JSON 格式：

export APISIX_DEPLOYMENT_ETCD_HOST='["https://your-host-or-ip:7943"]'

生成的网关接入命令还使用以下连接变量：

变量	用途
API7_DP_MANAGER_ENDPOINTS	DP Manager 端点 URL 的 JSON 数组。
API7_DP_MANAGER_CERT	PEM 格式的网关客户端证书；也接受别名 API7_CONTROL_PLANE_CERT。
API7_DP_MANAGER_KEY	配套的 PEM 格式客户端私钥；也接受别名 API7_CONTROL_PLANE_KEY。
API7_DP_MANAGER_CA	连接 DP Manager 所用的 CA 证书；也接受别名 API7_CONTROL_PLANE_CA。
API7_DP_MANAGER_SNI	可选的 TLS 服务器名称；也接受别名 API7_CONTROL_PLANE_SNI。
API7_GATEWAY_GROUP_SHORT_ID	网关组的配置前缀，由接入命令提供。

客户端证书和私钥必须同时提供。如果缺少其中任意一项，连接配置不会应用这组覆盖变量中的证书、私钥或 CA 值。请使用同一网关组和部署生成的材料。

API7_DP_MANAGER_ENDPOINTS 的优先级高于 API7_CONTROL_PLANE_ENDPOINTS，后者又高于 APISIX_DEPLOYMENT_ETCD_HOST。网关会将选中的值解析为 JSON。若格式错误，加载器会输出解析错误，不应用该端点值，也不会尝试优先级较低的端点变量。同一次失败还会跳过证书、私钥、CA 和 SNI 环境变量。即使出错的值来自其他变量，错误消息仍会显示 API7_DP_MANAGER_ENDPOINTS。

启动网关前，请设置所需的连接变量。

自定义环境变量

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

注意

环境变量直接在每个数据面（网关实例）上配置，并在重启后立即生效。控制面无法查看它们的实际值。同一网关组中的不同实例若使用不一致的环境变量配置，可能产生不可预测的行为，甚至导致 API 请求失败。

消费者凭证

通过 NGINX env 指令，消费者凭证中的以下敏感字段可以存储在环境变量中：

• Key Authentication 凭证中的 key
• Basic Authentication 凭证中的 password
• JWT Authentication 凭证中的 secret 和 public key
• HMAC Authentication 凭证中的 secret key

以下示例展示如何让 Key Authentication 凭证从环境变量读取用户认证密钥。

设置环境变量

Docker

部署网关实例时设置环境变量。按照使用 Docker Compose 部署操作，然后将环境变量添加到生成的脚本中。

Docker 示例：在 docker run 命令中添加自定义环境变量：

docker run -d --restart always -e API7_DP_MANAGER_ENDPOINTS='["https://your-host-or-ip:7943"]' \
-e API7_GATEWAY_GROUP_SHORT_ID=default \
-e ALICE_AUTH_KEY=alice-key \
-e API7_DP_MANAGER_CERT="-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----" \
-e API7_DP_MANAGER_KEY="-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----" \
-e API7_DP_MANAGER_CA="-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----" \
-p 9080:9080 \
-p 9443:9443 \
api7/api7-ee-3-gateway:3.10.9

备注

网关实例部署后，修改环境变量需要重启该实例。

Kubernetes

部署网关实例时设置环境变量。按照在 Kubernetes 上部署 API7 企业版操作，然后将环境变量添加到生成的脚本或 YAML 中。

脚本示例：在 helm upgrade 命令中添加自定义环境变量：

helm repo add api7 https://charts.api7.ai
helm repo update
# ... existing setup ...
helm upgrade --install -n test --create-namespace api7-ee-3-gateway api7/gateway \
  --version "~3.10.0" \
  --set "etcd.auth.tls.enabled=true" \
  --set "etcd.auth.tls.existingSecret=api7-ee-3-gateway-tls" \
  --set "etcd.auth.tls.certFilename=tls.crt" \
  --set "etcd.auth.tls.certKeyFilename=tls.key" \
  --set "etcd.auth.tls.verify=true" \
  --set "gateway.tls.existingCASecret=api7-ee-3-gateway-tls" \
  --set "gateway.tls.certCAFilename=ca.crt" \
  --set "apisix.extraEnvVars[0].name=API7_GATEWAY_GROUP_SHORT_ID" \
  --set "apisix.extraEnvVars[0].value=default" \
  --set "apisix.extraEnvVars[1].name=ALICE_AUTH_KEY" \
  --set "apisix.extraEnvVars[1].value=alice-key" \
  --set "etcd.host[0]=https://your-host-or-ip:7943" \
  --set "apisix.replicaCount=1"

YAML 示例：

apiVersion: v1
kind: Secret
metadata:
  namespace: test
  name: api7-ee-3-gateway-tls
type: kubernetes.io/tls
# ...
---
apisix:
  replicaCount: 1
  extraEnvVars:
  - name: API7_GATEWAY_GROUP_SHORT_ID
    value: "default"
  - name: ALICE_AUTH_KEY
    value: "alice-key"
etcd:
  host:
  - "https://your-host-or-ip:7943"
  auth:
    tls:
      enabled: true
      existingSecret: api7-ee-3-gateway-tls
      certFilename: tls.crt
      certKeyFilename: tls.key
      verify: true
gateway:
  tls:
    existingCASecret: api7-ee-3-gateway-tls
    certCAFilename: ca.crt

备注

网关实例部署后，修改环境变量需要重启该实例。

使用环境变量配置消费者凭证

1. 在侧边导航栏中选择网关组的Consumers（消费者）。
2. 点击**+ Add Consumer（添加消费者）**。
3. 在对话框中执行以下操作：
   • 在**Name（名称）**字段中输入 Alice。
   • 点击Add（添加）。
4. 在Credentials（凭证）标签页中点击+ Add Key Authentication Credential（添加 Key Authentication 凭证）。
5. 在对话框中执行以下操作：
   • 在**Name（名称）**字段中输入 primary-key。
   • 在 Key 字段中选择Manually Input（手动输入），然后输入 $env://ALICE_AUTH_KEY。
   • 点击Add（添加）。
6. 如需验证，请在服务级别启用 key-auth 插件（参阅消费者和凭证），然后携带 API Key 发送请求，确认认证成功。

SSL 证书

通过 NGINX env 指令，SSL 证书的 private key 和 certificate 敏感字段可以存储在环境变量中。

以下示例展示如何让 SSL 证书从环境变量读取敏感数据。

设置环境变量

Docker

部署网关实例时设置环境变量。按照使用 Docker Compose 部署操作，然后将环境变量添加到生成的脚本中。

Docker 示例：在 docker run 命令中添加自定义环境变量：

docker run -d --restart always -e API7_DP_MANAGER_ENDPOINTS='["https://your-host-or-ip:7943"]' \
-e API7_GATEWAY_GROUP_SHORT_ID=default \
-e SSL_CERTIFICATE="-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----" \
-e SSL_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----" \
-e API7_DP_MANAGER_CERT="..." \
-e API7_DP_MANAGER_KEY="..." \
-e API7_DP_MANAGER_CA="..." \
-p 9080:9080 \
-p 9443:9443 \
api7/api7-ee-3-gateway:3.10.9

备注

网关实例部署后，修改环境变量需要重启该实例。

Kubernetes

部署网关实例时设置环境变量。按照在 Kubernetes 上部署 API7 企业版操作，然后以 Kubernetes Secret 的形式将环境变量加入生成的脚本或 YAML 文件。

脚本示例：

# ... existing setup ...
kubectl apply -n demo -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  namespace: demo
  name: env-secrets
type: Opaque
data:
  SSL_CERTIFICATE: <base64-encoded-cert>
  SSL_PRIVATE_KEY: <base64-encoded-key>
EOF
helm upgrade --install -n demo --create-namespace api7-ee-3-gateway api7/gateway \
  --version "~3.10.0" \
  --set "apisix.extraEnvVarsSecret=env-secrets" \
  # ... other settings ...

YAML 示例：

apiVersion: v1
kind: Secret
metadata:
  name: env-secrets
  namespace: demo
type: Opaque
data:
  SSL_CERTIFICATE: <base64-encoded-cert>
  SSL_PRIVATE_KEY: <base64-encoded-key>
---
apisix:
  replicaCount: 1
  extraEnvVarsSecret: env-secrets
# ...

备注

网关实例部署后，修改环境变量需要重启该实例。

使用环境变量配置 SSL 证书

1. 在侧边导航栏中选择网关组的 SSL Certificates（SSL 证书）。
2. 点击**+ Add SSL Certificate（添加 SSL 证书）**。
3. 在对话框中执行以下操作：
   • 在**Certificate（证书）**字段中输入 $env://SSL_CERTIFICATE。
   • 在**Key（私钥）**字段中输入 $env://SSL_PRIVATE_KEY。
   • 点击Add（添加）。