第 7 章 APIcast 环境变量

APIcast 环境变量允许您修改 APIcast 的行为。以下值是受支持的环境变量：

all_proxy,ALL_PROXY

Default: no value: string Example:http://forward-proxy:80

定义要在未指定特定于协议的代理时用于连接服务的 HTTP 代理。不支持身份验证。

APICAST_ACCESS_LOG_FILE

默认 ：stdout

定义将存储访问日志的文件。

APICAST_BACKEND_CACHE_HANDLER

值 ：严格 | 弹性

默认 ： strict

弃用 ：改为使用 缓存 策略。

定义当后端不可用时授权缓存的行为方式。当后端不可用时，请严格删除缓存的应用。弹性仅在从后端获取授权时才会这样做。

APICAST_CACHE_MAX_TIME

默认：1 m

值： 字符串

在系统中选择要缓存的响应时，此变量的值表示要缓存的最长时间。如果未设置 cache-control 标头，则缓存的时间将是定义的标头。

此值的格式由 proxy_cache_valid NGINX 指令 定义。

此参数仅供使用内容缓存策略的 API 使用，并且请求符合缓存条件。

APICAST_CACHE_STATUS_CODES

默认： 200、302

值： 字符串

当上游的响应代码与此环境变量中定义的一个状态代码匹配时，响应内容将缓存在 NGINX 中。缓存时间取决于其中一个值：标头缓存时间值或 APICAST_CACHE_MAX_TIME 环境变量定义的最长时间。

此参数仅供使用内容缓存策略的 API 使用，并且请求符合缓存条件。

APICAST_CONFIGURATION_CACHE

值 ：数字

默认 ：0

指定配置要存储的时间间隔（以秒为单位）。该值应设置为 0（不兼容 APICAST_CONFIGURATION_LOADER的引导值）或超过 60 个。例如，如果 APICAST_CONFIGURATION_CACHE 设为 120，则网关将每 2 分钟从 API 管理器重新加载配置（120 秒）。值 < 0 禁用重新加载。

APICAST_CONFIGURATION_LOADER

值 ：boot | lazy

默认 ： lazy

定义如何加载配置。启动将在网关启动时向 API 管理器请求配置。lazy 将根据每个传入请求按需加载（保证对每个请求 APICAST_CONFIGURATION_CACHE 应该为 0 完全刷新）。

APICAST_CUSTOM_CONFIG

弃用 ：改为使用 策略。

定义实施自定义逻辑的 Lua 模块的名称，覆盖现有的 APIcast 逻辑。

APICAST_ENVIRONMENT

默认 ：

value: string[:]

示例 ：production:cloud-hosted

APIcast 应加载以冒号(:)分隔的环境（或路径）列表。此列表可以替代 CLI 上的 -e 或 --environment 参数，例如，存储在容器镜像中作为默认环境。CLI 上传递的任何值都会覆盖此变量。

APICAST_EXTENDED_METRICS

默认 ：false

值 ：布尔值

示例 ："true"

启用 Prometheus 指标的附加信息。以下指标有 service_id 和 service_system_name 标签，它们提供了有关 APIcast 的更多深入详情：

APICAST_HTTPS_CERTIFICATE

默认值 ：no 值

HTTPS 的 PEM 格式带有 X.509 证书的文件路径。

APICAST_HTTPS_CERTIFICATE_KEY

默认值 ：no 值

使用 PEM 格式的 X.509 证书 secret 密钥的文件路径。

APICAST_HTTPS_PORT

默认值 ：no 值

控制哪些端口 APIcast 应开始侦听 HTTPS 连接。如果此冲突与 HTTP 端口冲突，它将仅用于 HTTPS。

APICAST_HTTPS_VERIFY_DEPTH

默认 ：1

值 ：正整数。

定义客户端证书链的最大长度。如果此参数的值有 1，则可以在客户端证书链中包含额外证书。例如，root 证书认证机构。

APICAST_LOAD_SERVICES_WHEN_NEEDED

值：

默认 ：false

当配置了多个服务时，可以使用此选项。但是，其性能取决于其他因素，例如服务数量、APIcast 和 3scale 管理门户之间的延迟，以及配置的生存时间(TTL)。

默认情况下，APIcast 每次从管理门户下载其配置时加载所有服务。启用这个选项后，配置将使用延迟加载。APIcast 将仅加载为请求的主机标头中指定的主机配置的主机。

APICAST_LOG_FILE

默认 ： stderr

定义包含 OpenResty 错误日志的 文件。文件供 error_log 指令中的 bin/apicast 使用。文件路径可以是绝对的，也可以是相对于 APIcast 前缀目录。请注意，默认前缀目录为 APIcast。如需更多信息，请参阅 NGINX 文档。

APICAST_LOG_LEVEL

值 ：debug | info | notice | warn | error | crit | alert | emerg

默认 ：warn

指定 OpenResty 日志的日志级别。

APICAST_MANAGEMENT_API

值：

管理 API 功能强大，可以控制 APIcast 配置。您应该只为调试启用 debug 级别。

APICAST_MODULE

默认 ：apicast

弃用 ：改为使用 策略。

指定实施 API 网关逻辑的主 Lua 模块的名称。自定义模块可以覆盖默认 apicast.lua 模块的功能。请参阅 有关 如何使用模块的示例。

APICAST_OIDC_LOG_LEVEL

值 ：debug | info | notice | warn | error | crit | alert | emerg

默认 ：err

允许为与 OpenID Connect 集成相关的日志设置日志级别。

APICAST_PATH_ROUTING

值 ：

当此参数设置为 true 时，除了基于主机的默认路由外，网关还将使用基于路径的路由。API 请求将从请求 的主机 标头值 与公共基础 URL 匹配的服务列表中路由到具有匹配映射规则的第一个服务。

APICAST_PATH_ROUTING_ONLY

值 ：

当此参数设置为 true 时，网关将使用基于路径的路由，并且不会回退到基于主机的默认路由。API 请求路由到具有匹配映射规则的第一个服务，其从请求 的主机 标头值 与公共基础 URL 的值匹配的服务列表中。

此参数的优先级高于 APICAST_PATH_ROUTING。如果启用了 APICAST_PATH_ROUTING_ONLY，APIcast 将只执行基于路径的路由，无论 APICAST_PATH_ROUTING 的值为何。

APICAST_POLICY_LOAD_PATH

默认 ：APICAST_DIR/policies

value: string[:]

示例 ：~/apicast/policies:$PWD/policies

冒号(:)分隔的路径列表，APIcast 应该在其中查找策略。它可用于首先从开发目录加载策略或加载示例。

APICAST_PROXY_HTTPS_CERTIFICATE

默认 ：

值 ：字符串

示例 ：/home/apicast/my_certificate.crt

APIcast 与上游连接时将使用的客户端 SSL 证书的路径。请注意，此证书将用于配置中的所有服务。

APICAST_PROXY_HTTPS_CERTIFICATE_KEY

默认 ：

值 ：字符串

示例 ：/home/apicast/my_certificate.key

客户端 SSL 证书密钥的路径。

APICAST_PROXY_HTTPS_PASSWORD_FILE

默认 ：

值 ：字符串

示例 ：/home/apicast/passwords.txt

使用 APICAST_PROXY_HTTPS_CERTIFICATE_KEY 指定 SSL 证书密钥的密语文件的路径。

APICAST_PROXY_HTTPS_SESSION_REUSE

默认 ： on

值 ：

APICAST_REPORTING_THREADS

默认 ：0

值 ：整数 >= 0

试验性 ：了解高负载可能具有无法预计的性能并丢失报告。

大于 0 的值将启用对后端的带外报告。这是一个全新的 实验 功能，用于提高性能。客户端不会看到后端延迟，一切都将异步处理。这个值决定了在客户端因增加延迟而节流前可以同时运行多少异步报告。

APICAST_RESPONSE_CODES

值 ：

默认 ：<empty>(false)

当设置为 true 时，APIcast 会在 3scale 中记录 API 后端返回的响应代码。在一些计划中，以后可以从 3scale 管理门户查看此信息。如需更多信息，请参阅 为您的 API 设置和评估 3scale 响应代码日志。

APICAST_SERVICE_CACHE_SIZE

值 ：整数 >= 0

默认 ： 1000

指定 APIcast 可存储在内部缓存中的服务数量。高值会影响性能，因为 Lua 的 lru 缓存将初始化所有条目。

APICAST_SERVICE_${ID}_CONFIGURATION_VERSION

将 ${ID} 替换为实际的服务 ID。该值应当是您可以在管理门户的配置历史记录中看到的配置版本。将它设置为特定版本将阻止它自动更新，并且始终使用该版本。

APICAST_SERVICES_LIST

value ：以逗号分隔的服务 ID 列表

用于过滤 3scale API Manager 中配置的服务，并且仅对网关中的特定服务使用配置，丢弃未在列表中指定的服务 ID。您可以在管理门户中找到服务 ID： Dashboard > [Your_API_name]，标记为 API 调用的 ID。

APICAST_SERVICES_FILTER_BY_URL

值 ：PCRE（Perl 兼容正则表达式），如 *.example.com。

过滤 3scale API Manager 中配置的服务。

此过滤器 与公共基本 URL 匹配，可以是暂存或生产。与过滤器不匹配的服务将被丢弃。如果无法编译正则表达式，则不会加载任何服务。

APICAST_UPSTREAM_RETRY_CASES

值 ： error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | non_idempotent | off

APICAST_WORKERS

默认 ：auto

值 ：数字 | auto

这是 nginx worker_processes 指令 中使用的值。默认情况下，APIcast 使用 auto，但使用 1 的开发环境 除外。

BACKEND_ENDPOINT_OVERRIDE

从配置覆盖后端端点的 URI。在 OpenShift 外部部署 AMP 时非常有用.示例 ：https://backend.example.com.

HTTP_KEEPALIVE_TIMEOUT

默认 ： 75 值 ：正整数 示例 ：1

此参数设置一个超时，期间 keep-alive 客户端连接将在服务器端保持打开状态。零值禁用 keep-alive 客户端连接。

默认情况下，网关会禁用 HTTP_KEEPALIVE_TIMEOUT。此配置允许使用默认值为 75 秒 的 NGINX 中保留超时。

HTTP_PROXY,HTTP_PROXY

Default: no value: string Example:http://forward-proxy:80

定义用于连接 HTTP 服务的 HTTP 代理。不支持身份验证。

HTTPS_PROXY,HTTPS_PROXY

Default: no value: string Example:https://forward-proxy:443

定义用于连接 HTTPS 服务的 HTTP 代理。不支持身份验证。

NO_PROXY,NO_PROXY

default: no value : string\[,<string>\]; *Example:foo,bar.com,.extra.dot.com

定义不应代理请求的主机名和域名的逗号分隔列表。将 设置为单个 * 字符（匹配所有主机）有效禁用代理。

OPENSSL_VERIFY

值 ：

控制 OpenSSL 对等验证.它默认为 off，因为 OpenSSL 无法使用系统证书存储。它需要自定义证书捆绑包并将其添加到可信证书中。

建议您使用 https://github.com/openresty/lua-nginx-module#lua_ssl_trusted_certificate 并指向由 export-builtin-trusted-certs 生成的证书捆绑包。

OPENTRACING_CONFIG

此环境变量用于决定 opentracing tracer 的配置文件，如果未设置 OPENTRACING_TRACER，则忽略此变量。

每个 tracer 都有一个默认配置文件：* jaeger: conf.d/opentracing/jaeger.example.json

通过使用此变量设置文件路径，您可以选择挂载与默认情况下提供的不同的配置。

示例 ：/tmp/jaeger/jaeger.json

OPENTRACING_HEADER_FORWARD

默认 ：uber-trace-id

此环境变量控制用于转发 Opentracing 信息的 HTTP 标头，此 HTTP 标头将转发到上游服务器。

OPENTRACING_TRACER

示例 ：jaeger

此环境变量控制将加载的追踪库，现在只有一个打开追踪器可用，即 jaeger。

如果为空，将禁用 opentracing 支持。

解析器

允许指定将由 OpenResty 使用的自定义 DNS 解析器。如果 RESOLVER 参数为空，则会自动发现 DNS 解析器。

THREESCALE_CONFIG_FILE

带有网关配置的 JSON 文件的路径。您必须提供 THREESCALE_PORTAL_ENDPOINT 或 THREESCALE_CONFIG_FILE 才能成功运行网关。从这两个环境变量中，THREESCALE_CONFIG_FILE 优先

要使用网关配置来构建文件，根据服务数量，有两个替代方案：

当使用容器镜像部署网关时：

您可以在 Example 文件夹中找到 示例 配置文件。

THREESCALE_DEPLOYMENT_ENV

值 ： stage | production

默认 ：production

环境变量的值定义特定配置的环境。使用新 APIcast 时，将从 3scale（标记或生产）下载该环境的配置。

X-3scale-User-Agent 标头中也使用 THREESCALE_DEPLOYMENT_ENV 的值来授权并报告向 3scale 服务管理 API 发出的请求。标头值供 3scale 用于统计。

THREESCALE_PORTAL_ENDPOINT

以以下格式包含密码和门户端点的 URI：& lt;schema>://<password>@<admin-portal-domain>。<password> 可以是 3scale 帐户管理 API 的供应商密钥或访问令牌。<admin-portal-domain> 是登录管理门户的 URL。

示例 ：https://access-token@account-admin.3scale.net。

提供了 When THREESCALE_PORTAL_ENDPOINT 环境变量，网关会在初始化时从 3scale 下载配置。配置包括 API 集成页面中提供的所有设置。

您还可以使用此环境变量 创建具有主管理门户的单一网关。

需要为 网关提供成功运行的 THREESCALE_PORTAL_ENDPOINT 或 THREESCALE_CONFIG_FILE （优先）。