跳到主要内容
版本:3.8.x

环境变量

API7 企业版支持在消费者凭据、SSL 证书和某些插件中使用环境变量。一些环境变量保留作特殊用途,其他环境变量则可以使用自定义名称创建并引用。

保留环境变量​

API7 企业版目前保留以下环境变量。

变量名称说明
APISIX_DEPLOYMENT_ETCD_HOSTetcd 主机地址。
APISIX_WORKER_PROCESSESWorker 进程数量。

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

自定义环境变量​

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

注意

环境变量直接在每个数据面(网关实例)上配置,重启后立即生效。由于采用此配置方式,你无法从控制面查看其实际值。同一网关组中不同网关实例的环境变量配置不一致,可能导致不可预测的行为及 API 故障。

消费者凭据​

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

  • Key Authentication 凭据中的 key
  • Basic Authentication 凭据中的 password
  • JWT Authentication 凭据中的 secret、public key
  • HMAC Authentication 凭据中的 secret key

以下示例演示如何配置 Key 身份认证凭据,从环境变量获取用户身份认证 Key。

设置环境变量​

部署网关实例时设置环境变量。按照新增网关实例操作,然后将环境变量添加到生成的脚本中。

例如,在 Docker 的 docker run 命令中添加自定义环境变量。

docker run -d -e API7_CONTROL_PLANE_ENDPOINTS='["https://your-host-or-ip:443"]' \
-e API7_GATEWAY_GROUP_SHORT_ID=default \
-e ALICE_AUTH_KEY=alice-key \
-e API7_CONTROL_PLANE_CERT="-----BEGIN CERTIFICATE-----
MIIBiDCCATqgAwIBAgICBAAwBQYDK2VwMEQxCzAJBgNVBAYTAlVTMRMwEQYDVQQI
EwpDYWxpZm9ybmlhMQ0wCwYDVQQKEwRBUEk3MREwDwYDVQQDEwhBUEk3IEluYzAe
Fw0yNDEwMjkwMzM4NTJaFw0yNTExMjgwMzM4NTJaMDAxDTALBgNVBAoTBEFQSTcx
HzAdBgNVBAMTFmFwaTdlZTMtYXBpc2l4LWdhdGV3YXkwKjAFBgMrZXADIQBpBV0D
YBeCedUrIWvyk2YHORcmzBeCiActHJk3u4ZkyKNkMGIwDgYDVR0PAQH/BAQDAgeA
MBMGA1UdJQQMMAoGCCsGAQUFBwMCMC0GA1UdDgQmBCQyOWEzZmVlZi1hNzM2LTQy
OTEtODlmZS0xOWI4MDFjODNjZWQwDAYDVR0jBAUwA4ABMDAFBgMrZXADQQA0aeIB
5Gy5cVYrRgM+PRduSumjDMyDFNbH01GNQ/5RTeyMaH3lAj64JLOO4sQe7gy3dDxx
b7N9mKGl8iMzSLwF
-----END CERTIFICATE-----" \
-e API7_CONTROL_PLANE_KEY="-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEIJ6hn4EQKXSh4U+2SFPJhBh3RxN/1trnsu2Zjp6hRB5A
-----END PRIVATE KEY-----" \
-e API7_CONTROL_PLANE_CA="-----BEGIN CERTIFICATE-----
MIIBdTCCASegAwIBAgIQVXqTFu/hH4caZptKdGp04zAFBgMrZXAwRDELMAkGA1UE
BhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExDTALBgNVBAoTBEFQSTcxETAPBgNV
BAMTCEFQSTcgSW5jMB4XDTI0MDkwNzA4MTc0NVoXDTM0MDkwNTA4MTc0NVowRDEL
MAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExDTALBgNVBAoTBEFQSTcx
ETAPBgNVBAMTCEFQSTcgSW5jMCowBQYDK2VwAyEAkTj447bpztG1dc0HVW74za+v
NEAhU7mySYSmUSwdRfCjLzAtMA4GA1UdDwEB/wQEAwIChDAPBgNVHRMBAf8EBTAD
AQH/MAoGA1UdDgQDBAEwMAUGAytlcANBAKxxBg/CEnOoxQnVd8ixHKJCgChZ2IZE
BLCHaQTEbmfy8RQ+po0cKOthWFDx8gsx2AjdkLO5PPaHPujIXyfz8QI=
-----END CERTIFICATE-----" \
-p 9080:9080 \
-p 9443:9443 \
api7/api7-ee-3-gateway:dev
备注

部署后,必须重启网关实例,才能修改该实例的环境变量。

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

  1. 在侧边导航栏选择网关组的消费者。
  2. 点击 + 新增消费者。
  3. 在对话框中完成以下操作。
  • 在名称字段中输入 Alice。
  • 点击新增。
  1. 在凭据选项卡中,点击 + 新增 Key Authentication 凭据。
  2. 在对话框中完成以下操作。
  • 在名称字段中输入 primary-key。
  • 在 Key 字段中选择手动输入,然后输入 $env://ALICE_AUTH_KEY。
  • 点击新增。
  1. 验证时,参阅为 API 启用 Key Authentication,在服务级别启用 key-auth 插件,然后按照验证 Key Authentication进行验证。

SSL 证书​

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

以下示例演示如何配置 SSL 证书,从环境变量获取敏感数据。

设置环境变量​

部署网关实例时设置环境变量。按照新增网关实例操作,然后将环境变量添加到生成的脚本中。

例如,在 Docker 的 docker run 命令中添加自定义环境变量。

docker run -d -e API7_CONTROL_PLANE_ENDPOINTS='["https://your-host-or-ip:443"]' \
-e API7_GATEWAY_GROUP_SHORT_ID=default \
-e SSL_CERTIFICATE="-----BEGIN CERTIFICATE-----
MIIBiDCCATqgAwIBAgICBAAwBQYDK2VwMEQxCzAJBgNVBAYTAlVTMRMwEQYDVQQI
EwpDYWxpZm9ybmlhMQ0wCwYDVQQKEwRBUEk3MREwDwYDVQQDEwhBUEk3IEluYzAe
Fw0yNDEwMjkwMzM4NTJaFw0yNTExMjgwMzM4NTJaMDAxDTALBgNVBAoTBEFQSTcx
HzAdBgNVBAMTFmFwaTdlZTMtYXBpc2l4LWdhdGV3YXkwKjAFBgMrZXADIQBpBV0D
YBeCedUrIWvyk2YHORcmzBeCiActHJk3u4ZkyKNkMGIwDgYDVR0PAQH/BAQDAgeA
MBMGA1UdJQQMMAoGCCsGAQUFBwMCMC0GA1UdDgQmBCQyOWEzZmVlZi1hNzM2LTQy
OTEtODlmZS0xOWI4MDFjODNjZWQwDAYDVR0jBAUwA4ABMDAFBgMrZXADQQA0aeIB
5Gy5cVYrRgM+PRduSumjDMyDFNbH01GNQ/5RTeyMaH3lAj64JLOO4sQe7gy3dDxx
b7N9mKGl8iMzSLwF
-----END CERTIFICATE-----" \
-e SSL_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEIJ6hn4EQKXSh4U+2SFPJhBh3RxN/1trnsu2Zjp6hRB5A
-----END PRIVATE KEY-----" \
-e API7_CONTROL_PLANE_CERT="-----BEGIN CERTIFICATE-----
MIIBiDCCATqgAwIBAgICBAAwBQYDK2VwMEQxCzAJBgNVBAYTAlVTMRMwEQYDVQQI
EwpDYWxpZm9ybmlhMQ0wCwYDVQQKEwRBUEk3MREwDwYDVQQDEwhBUEk3IEluYzAe
Fw0yNDEwMjkwMzM4NTJaFw0yNTExMjgwMzM4NTJaMDAxDTALBgNVBAoTBEFQSTcx
HzAdBgNVBAMTFmFwaTdlZTMtYXBpc2l4LWdhdGV3YXkwKjAFBgMrZXADIQBpBV0D
YBeCedUrIWvyk2YHORcmzBeCiActHJk3u4ZkyKNkMGIwDgYDVR0PAQH/BAQDAgeA
MBMGA1UdJQQMMAoGCCsGAQUFBwMCMC0GA1UdDgQmBCQyOWEzZmVlZi1hNzM2LTQy
OTEtODlmZS0xOWI4MDFjODNjZWQwDAYDVR0jBAUwA4ABMDAFBgMrZXADQQA0aeIB
5Gy5cVYrRgM+PRduSumjDMyDFNbH01GNQ/5RTeyMaH3lAj64JLOO4sQe7gy3dDxx
b7N9mKGl8iMzSLwF
-----END CERTIFICATE-----" \
-e API7_CONTROL_PLANE_KEY="-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEIJ6hn4EQKXSh4U+2SFPJhBh3RxN/1trnsu2Zjp6hRB5A
-----END PRIVATE KEY-----" \
-e API7_CONTROL_PLANE_CA="-----BEGIN CERTIFICATE-----
MIIBdTCCASegAwIBAgIQVXqTFu/hH4caZptKdGp04zAFBgMrZXAwRDELMAkGA1UE
BhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExDTALBgNVBAoTBEFQSTcxETAPBgNV
BAMTCEFQSTcgSW5jMB4XDTI0MDkwNzA4MTc0NVoXDTM0MDkwNTA4MTc0NVowRDEL
MAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExDTALBgNVBAoTBEFQSTcx
ETAPBgNVBAMTCEFQSTcgSW5jMCowBQYDK2VwAyEAkTj447bpztG1dc0HVW74za+v
NEAhU7mySYSmUSwdRfCjLzAtMA4GA1UdDwEB/wQEAwIChDAPBgNVHRMBAf8EBTAD
AQH/MAoGA1UdDgQDBAEwMAUGAytlcANBAKxxBg/CEnOoxQnVd8ixHKJCgChZ2IZE
BLCHaQTEbmfy8RQ+po0cKOthWFDx8gsx2AjdkLO5PPaHPujIXyfz8QI=
-----END CERTIFICATE-----" \
-p 9080:9080 \
-p 9443:9443 \
api7/api7-ee-3-gateway:dev
备注

部署后,必须重启网关实例,才能修改该实例的环境变量。

使用环境变量配置 SSL 证书​

  1. 在侧边导航栏选择网关组的 SSL 证书。
  2. 点击 + 新增 SSL 证书。
  3. 在对话框中完成以下操作。
  • 在证书字段中输入 $env://SSL_CERTIFICATE。
  • 在私钥字段中输入 $env://SSL_PRIVATE_KEY。
  • 点击新增。