红帽全球峰会管理 API 网关
中等到高级目标，以管理您的安装。
摘要
前言
本指南将帮助您将中间功能应用到您的 3scale 安装中。有关安装的基本详情，请参阅安装 3scale。
第 1 章 操作 APIcast
本节介绍了使用高级 APIcast 配置时需要考虑的概念。
1.1. 映射规则
映射规则定义了您要报告的指标或方法，具体取决于您的 API 请求。以下是映射规则示例：
这个规则表示，任何以 / 开头的 GET 请求都将按 1 增加指标 命中。此规则将与您的 API 的任何请求匹配。但很可能会更改此规则，因为它过于通用。
Echo API 的以下规则显示更具体的示例：
1.1.1. 映射规则的匹配
映射规则的匹配通过前缀来执行，并可任意复杂（标记遵循 OpenAPI 和 ActiveDocs 规格）：
-
映射规则必须以正斜杠(
/)开头。 -
您可以在字面字符串的路径上执行匹配项（例如：
/hello）。 映射规则可以包含查询字符串或正文上的参数（例如：
/{word}?value={value}）。APIcast 获取参数的方式如下：-
GET方法：来自查询字符串。 -
POST、DELETE或PUT方法：来自正文。
-
-
映射规则可以包含命名通配符（例如：
/{word}）。此规则将匹配占位符{word}中的任何内容，使请求（如/morning）与规则匹配。通配符可以在斜杠或斜杠与点之间出现。参数也可以包含通配符。 -
默认情况下，根据您指定的排序，从第一个到最后一个到最后一个映射规则评估所有映射规则。如果您添加规则
/v1/v1/word或/v1/sentence）。 -
您可以在模式的末尾添加一个美元符号(
$)来指定完全匹配项。例如，/v1/word$将仅匹配/v1/wordrequests，并且不匹配/v1/word/hello请求。要完全匹配，还必须确保禁用了与所有(/)匹配的默认映射规则。 - 多个映射规则可以匹配请求路径，但如果都不匹配，则会使用 HTTP 404 状态代码丢弃该请求。
1.1.2. 映射规则工作流
映射规则有以下工作流：
- 您可以定义一个新的映射规则（请参阅 添加映射规则）。
- 下一次重新加载时，映射规则会灰显，以防止意外修改。
- 要编辑现有的映射规则，您必须首先通过单击右侧的铅笔图标启用它。
- 若要删除规则，可单击回收站图标。
- 点 Update & Test Staging Configuration 时会保存所有修改和删除。
添加映射规则
要添加新映射规则，请执行以下步骤：
- 点 Add Mapping Rule。
指定以下设置：
-
动词 ：HTTP 请求动词（
GET、POST、DELE 或PUT）。 -
Pattern ：要匹配的模式（例如，
/hello）。 -
+ ：指标递增号（例如
1）。 -
指标（或方法 ）：指标或方法名称（如
gethello）。
-
动词 ：HTTP 请求动词（
- 点击 Update & Test Test Staging Configuration 以应用更改。
停止其他映射规则
要停止处理其他映射规则，您可以选择 Last?。例如，如果您在 API Integration Settings 中定义以下映射规则，并且具有与每个规则关联的不同指标：
(get) /path/to/example/search
(get) /path/to/example/{id}
(get) /path/to/example/search
(get) /path/to/example/{id}
在使用 (get)/path/to/example/search 调用时，APIcast 将停止处理剩余的映射规则，并在规则匹配后递增其指标。
排序映射规则
要对映射规则进行排序，您可以为 Last? 设置旁的每个映射规则使用绿色箭头来拖放它们。指定的排序保存在数据库中，并在点 Update & test in Staging Environment 后保存在代理配置中。
如需了解更多配置选项，请参阅 APIcast 高级配置。
1.2. 主机标头
这个选项只适用于那些拒绝流量的 API 后端，除非 Host 标头与预期匹配。在这些情况下，您的 API 后端前有一个网关会导致问题，因为 主机 将是网关之一，例如 xxx-yyy.staging.apicast.io
为了避免这个问题，您可以在 Authentication Settings 中的 Host Header 字段中定义 API 后端需要的主机，托管 APIcast 实例将重写主机。
1.3. 产品部署
在配置了 API 集成并验证其在 Staging 环境中工作后，您便可以继续使用 APIcast 生产部署。
在 Integration 页面的底部，您将找到 Production 部分。您可以在此处找到两个字段： 专用基本 URL，其与您在 Staging 部分中配置的相同，以及 公共基本 URL。
1.4. 公共基本 URL
Public Base URL 是您的开发人员用来向 API 发出请求的 URL，并由 3scale 保护。这将是您的 APIcast 实例的 URL。
如果您使用的是由管理的部署选项之一，您可以在要管理的域名上为每个环境（镜像和生产）选择您自己的公共基本 URL。请注意，这个 URL 应与其中一个 API 后端不同，可能类似于 https://api.yourdomain.com:443，其中 您的domain.com 是您所属的域。设置公共基本 URL 后，请确保保存更改，如有必要，将暂存中的更改提升到生产环境。
请注意，APIcast 将仅接受对在公共基本 URL 中指定的主机名的调用。例如，对于上面使用的 Echo API 示例，如果我们指定了 https://echo-api.3scale.net:443 作为公共基本 URL，则正确的调用是：
curl "https://echo-api.3scale.net:443/hello?user_key=YOUR_USER_KEY"
curl "https://echo-api.3scale.net:443/hello?user_key=YOUR_USER_KEY"如果您还没有 API 的公共域，您也可以在请求中使用 APIcast IP，但您仍需要在公共基本 URL 字段中指定一个值（即使域不真实），在这种情况下，请确定您在 Host 标头中提供主机，例如：
curl "http://192.0.2.12:80/hello?user_key=YOUR_USER_KEY" -H "Host: echo-api.3scale.net"
curl "http://192.0.2.12:80/hello?user_key=YOUR_USER_KEY" -H "Host: echo-api.3scale.net"
如果您在本地机器上部署，您也可以只使用"localhost"作为域，因此公共基本 URL 类似如下，然后您可以按照以下方式发出请求：http://localhost:80
curl "http://localhost:80/hello?user_key=YOUR_USER_KEY"
curl "http://localhost:80/hello?user_key=YOUR_USER_KEY"如果您有多个 API 服务，则需要为每个服务正确设置此公共基本 URL。APIcast 将基于主机名路由请求。
1.5. 保护 API 后端
在生产环境中工作 APIcast 后，您可能想限制在没有凭证的情况下对 API 后端的直接访问。执行此操作的最简单方法是使用 APIcast 设置的 Secret Token。有关如何设置它的信息，请参阅高级 APIcast 配置。
1.6. 将 APIcast 与私有 API 搭配使用
通过 APIcast，可以保护不能在互联网上公开访问的 API。必须满足的要求有：
- 自我管理的 APIcast 必须用作部署选项。
- APIcast 需要能够从公共互联网访问，并且能够向 3scale 服务管理 API 发出出站调用。
- API 后端应该可通过 APIcast 访问。
在这种情况下，您可以在 Private Base URL 字段中设置 API 的内部域名或 IP 地址，并像平常一样遵循其余步骤。但请注意，您无法利用 Staging 环境，测试调用将无法成功，因为登台 APIcast 实例由 3scale 托管，并且无法访问您的私有 API 后端。但是，在生产环境中部署 APIcast 后，如果配置正确，APIcast 将按预期工作。
1.7. 使用 OpenTracing 配置 APIcast
OpenTracing 是一种 API 规范和方法，用于配置文件和监控微服务。从版本 3.3 开始，APIcast 包括 OpenTracing Libraries 和 Jaeger Tracer 库。
1.7.1. 先决条件
要在 APIcast 部署中添加分布式追踪，您需要确保以下先决条件：
- 每个外部请求都应附加唯一的请求 ID，通常是通过 HTTP 标头连接。
- 每个服务都应该将请求 ID 转发到其他服务。
- 每个服务都应该在日志中输出请求 ID。
- 每个服务均应记录其他信息，如请求的开始和结束时间。
- 日志需要聚合，并提供通过 HTTP 请求 ID 解析的方式。
1.7.2. 流程
要配置 OpenTracing，请使用以下环境变量：
- OPENTRACING_MERGER：定义要使用哪个 tracer 实现。目前，只有 Jaeger 可用。
- OPENTRACING_CONFIG：要指定 tracer 的默认配置文件。您可以在此处看到一个 示例。
- OPENTRACING_HEADER_FORWARD：可选.您可以根据 OpenTracing 配置来设置此环境变量。
有关这些变量的更多信息，请参阅 APIcast 环境变量。
要测试集成是否正常工作，您需要检查 Jaeger 追踪界面中是否报告 trace。
1.7.3. 附加信息
OpenTracing 和 Jaeger 集成在上游项目中找到 ：https://github.com/3scale/apicast
1.7.4. 在 OpenShift 实例上安装 Jaeger
本节提供有关在运行的 OpenShift 实例上安装 Jaeger 的信息。
Jaeger 是一个第三方组件，3scale 不提供支持，但 APIcast 的使用除外。以下说明仅作为参考示例提供，不适用于生产用途。
在当前命名空间中安装 Jaeger all-in-one：
oc process -f https://raw.githubusercontent.com/jaegertracing/jaeger-openshift/master/all-in-one/jaeger-all-in-one-template.yml | oc create -f -
oc process -f https://raw.githubusercontent.com/jaegertracing/jaeger-openshift/master/all-in-one/jaeger-all-in-one-template.yml | oc create -f -Copy to Clipboard Copied! Toggle word wrap Toggle overflow 创建 Jaeger 配置文件
jaeger_config.json并添加以下内容：Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
设置 1 的样本常数以对所有请求进行抽样
-
设置
报告器的位置和队列大小 -
设置标头，包括我们将用来跟踪请求的TraceContextHeaderName
-
设置 1 的样本常数以对所有请求进行抽样
从 Jaeger 配置文件创建 ConfigMap，并将其挂载到 APIcast 中：
oc create configmap jaeger-config --from-file=jaeger_config.json oc volume dc/apicast --add -m /tmp/jaeger/ --configmap-name jaeger-config
oc create configmap jaeger-config --from-file=jaeger_config.json oc volume dc/apicast --add -m /tmp/jaeger/ --configmap-name jaeger-configCopy to Clipboard Copied! Toggle word wrap Toggle overflow 使用刚添加的配置启用 OpenTracing 和 Jaeger：
oc set env deploymentConfig/apicast OPENTRACING_TRACER=jaeger OPENTRACING_CONFIG=/tmp/jaeger/jaeger_config.json
oc set env deploymentConfig/apicast OPENTRACING_TRACER=jaeger OPENTRACING_CONFIG=/tmp/jaeger/jaeger_config.jsonCopy to Clipboard Copied! Toggle word wrap Toggle overflow 查找运行 Jaeger 接口的 URL：
oc get route (…) jaeger-query-myproject.127.0.0.1.nip.io
oc get route (…) jaeger-query-myproject.127.0.0.1.nip.ioCopy to Clipboard Copied! Toggle word wrap Toggle overflow - 打开上一步中的 Jaeger 接口，它显示来自 Openshift Health 检查的数据。
- 最后一步是将 OpenTracing 和 Jaeger 支持添加到您的后端 API，以便您可以查看完整的请求追踪。根据所用的框架和语言，每个后端都有所不同。作为参考示例，您可以使用 OpenTracing 与 Jaeger 来收集 Kubernetes 中的应用指标。
有关配置 Jaeger 的更多信息，请参阅：
第 2 章 操作 Docker 容器化环境
2.1. 对 Docker 容器化环境的 APIcast 进行故障排除
本节介绍了在 Docker 容器化环境中使用 APIcast 时最常发现的问题。
2.1.1. 无法连接到 Docker 守护进程错误
docker：无法连接到 Docker 守护进程。Is the docker daemon running on this host? 错误消息可能是 Docker 服务尚未启动。您可以通过运行 sudo systemctl status docker.service 命令来检查 Docker 守护进程的状态。
确保您以 root 用户身份运行此命令，因为 Docker 容器化环境默认需要在 RHEL 中具有 root 权限。有关详细信息，请参阅 此处。
2.1.2. 基本 Docker 命令行界面命令
如果您以分离模式启动容器（-d 选项），并希望检查正在运行的 APIcast 实例的日志，您可以使用 log 命令： sudo docker logs <container>。其中，<container> 是容器名称（上例中的 "apicast"）或容器 ID。您可以使用 sudo docker ps 命令获取正在运行的容器及其 ID 和名称的列表。
要停止容器，请运行 sudo docker stop <container> 命令。您还可以运行 sudo docker rm <container> 命令删除容器。
有关可用命令的更多信息，请参阅 Docker 命令参考。
第 3 章 高级 APIcast 配置
本节介绍 3scale 在暂存环境中的 API 网关的高级设置选项。
3.1. 定义 secret 令牌
出于安全考虑，从 3scale 网关到 API 后端的任何请求都包含名为 X-3scale-proxy-secret-token 的标头。您可以在 Integration 页面的 Authentication Settings 中设置此标头的值。
将 secret 令牌设置为代理和 API 之间的共享机密，以便您可以阻断所有来自网关的 API 请求（如果不希望它们）。当您使用沙盒网关设置流量管理策略时，这会添加额外的安全层来保护您的公共端点。
您的 API 后端必须具有公共可解析域才能使网关正常工作，因此知道您的 API 后端的任何人都可以绕过凭证检查。这不应该成为问题，因为暂存环境中的 API 网关并不适用于生产环境，但始终最好有一个可用的隔离。
3.2. 凭证
3scale 中的 API 凭证是 user_key 或 app_id/app_key，具体取决于您使用的身份验证模式。OpenID Connect 对暂存环境中的 API 网关有效，但它无法在 Integration 页面中进行测试。
但是，您可能想要在 API 中使用不同的凭证名称。在这种情况下，如果使用 API 密钥模式，您需要为 user_key 设置自定义名称：
另外，对于 app_id 和 app_key ：
例如，如果这更适合您的 API，您可以将 app_id 重命名为 key。网关将使用名称 key，并将其转换为 app_id，然后向 3scale 后端执行授权调用。请注意，新凭证名称必须是字母数字。
您可以决定您的 API 是否在查询字符串（或者正文（如果不是 GET）或标头中传递凭证。
APIcast 在提取凭据时规范化标头名称。这意味着它们不区分大小写，下划线和连字符可以平等对待。例如，如果您将 App Key 参数设置为 App_Key，其他值（如 app-key） 也被接受，作为有效的 app 键标头。
3.3. 错误信息
完整的配置的另一个重要元素是定义您自己的自定义错误消息。
务必要注意，暂存环境中的 3scale API 网关将通过您的 API 生成的错误消息。但是，由于 API 的管理层现在由网关执行，因此您的 API 不会看到的一些错误，因为一些请求将由网关终止。
以下是一些错误：
- 身份验证缺失： 每当 API 请求不包含任何凭证时，都会生成这个错误。当用户没有将其凭证添加到 API 请求时会出现这种情况。
- 身份验证失败： 每当 API 请求不包含有效凭证时，都会生成这个错误。这可能是因为凭证是 fake，或者应用程序已被临时暂停。
- no match：这个错误表示请求与任何映射规则不匹配，因此没有更新指标。这不一定是错误，但意味着用户正在尝试随机路径，或者您的映射规则无法涵盖合法情况。
- 重试：当 API 请求超过速率限制时，会触发这个错误。返回 Retry-After 标头，状态代码为 429，以秒为单位，直到限制过期为止。
3.4. 配置历史记录
每次点击 Update & Test Staging Configuration 按钮时，当前配置都会保存在 JSON 文件中。暂存网关将利用每个新请求拉取最新的配置。对于每个环境（ staging 或 production），您可以看到所有之前的配置文件的历史记录。
请注意，无法自动回滚到以前的版本。而是提供您的所有配置版本的历史记录及其相关的 JSON 文件。使用这些文件来检查您在任何时间点上部署的配置。如果需要，可以手动重新创建任何部署。
3.5. 调试
设置网关配置很容易，但您可能仍会遇到错误。在这种情况下，网关可以返回有用的调试信息来跟踪错误。
要从 APIcast 获取调试信息，您必须将以下标头添加到 API 请求中： X-3scale-debug: {SERVICE_TOKEN}，其服务帐户令牌与您要访问的 API 服务对应的服务令牌对应。
当找到标头且服务令牌有效时，网关会将以下信息添加到响应标头中：
X-3scale-matched-rules: /v1/word/{word}.json, /v1
X-3scale-credentials: app_key=APP_KEY&app_id=APP_ID
X-3scale-usage: usage%5Bversion_1%5D=1&usage%5Bword%5D=1
X-3scale-matched-rules: /v1/word/{word}.json, /v1
X-3scale-credentials: app_key=APP_KEY&app_id=APP_ID
X-3scale-usage: usage%5Bversion_1%5D=1&usage%5Bword%5D=1
X-3scale-matched-rules 表示在用逗号分开的列表中为请求匹配了哪些映射规则。
标头 X-3scale-credentials 返回传递给 3scale 后端的凭证。
x-3scale-usage 表示报告到 3scale 后端的使用情况。usage%5Bversion_1%5D=1&usage%5Bword%5D=1 是一个 URL 编码的 usage[version_1]=1&usage[word]=1，显示 API 请求递增方法(metrics) version_1，并按 1 按 单词。
3.6. 路径路由
如果配置了 APICAST_SERVICES_LIST 环境变量，APIcast 处理 3scale 帐户上配置的所有 API 服务（或服务子集）。通常，APIcast 会根据请求的主机名将 API 请求路由到适当的 API 服务，方法是将它与 公共基础 URL 匹配。找到匹配项的第一个服务用于授权。
路径路由功能允许在多个服务上使用相同的 公共基础 URL，并使用请求的路径路由请求。要启用该功能，请将 APICAST_PATH_ROUTING 环境变量设置为 true 或 1。启用后，APIcast 将根据主机名和路径将传入的请求映射到服务。
如果要使用同一 公共基本 URL 通过不同的网关公开托管的多个后端服务，可使用此功能。要达到此目的，您可以为每个 API 后端（即 私有基本 URL）配置多个 API 服务并启用路径路由功能。
例如，您使用以下方式配置了 3 个服务：
-
Service A Public Base URL:
api.example.com映射规则：/a -
Service B Public Base URL:
api2.example.com映射规则：/b -
Service C Public Base URL:
api.example.com映射规则：/c
如果路径路由为 disabled (APICAST_PATH_ROUTING=false)，对 api.example.com 的所有调用都将尝试匹配 Service A。因此，调用 api.example.com/c 和 api.example.com/b 将失败，并显示 "No Mapping Rule match" 错误。
如果路径路由为 enabled (APICAST_PATH_ROUTING=true)，则调用将由主机和路径匹配。因此：
-
api.example.com/a将路由到 Service A -
api.example.com/c将路由到 Service C -
api.example.com/b将失败，显示"No Mapping Rule match"错误，即它不匹配 Service B，因为 公共基础 URL 不匹配。
如果使用路径路由，您必须确保使用相同 公共基本 URL 的不同服务中的映射规则之间没有冲突，例如，仅在一个服务中使用方法 + 路径模式的组合。
第 4 章 APIcast 策略
APIcast 策略是修改 APIcast 操作方式的功能单元。可以启用、禁用和配置策略，以控制它们如何修改 APIcast。使用策略添加默认 APIcast 部署中不可用的功能。您可以创建自己的策略，或使用 Red Hat 3scale 提供的标准策略。
以下主题提供有关标准 APIcast 策略的信息，创建您自己的自定义 APIcast 策略并创建策略链。
使用策略链控制服务策略。策略链执行以下操作：
- 指定 APIcast 使用的策略
- 为策略 3scale 提供配置信息
- 指定 3scale 加载策略的顺序
红帽 3scale 提供了一种添加自定义策略的方法，但不支持自定义策略。
要使用自定义策略修改 APIcast 的行为，您必须执行以下操作：
- 在 APIcast 中添加自定义策略
- 定义配置 APIcast 策略的策略链
- 将策略链添加到 APIcast
4.1. APIcast 标准策略
3scale 提供以下标准策略：
- 第 4.1.1 节 “3scale Auth 缓存策略”
- 第 4.1.2 节 “3scale 批处理器策略”
- 第 4.1.3 节 “匿名访问策略”
- 第 4.1.4 节 “CORS 请求处理策略”
- 第 4.1.5 节 “echo policy”
- 第 4.1.6 节 “边缘限制策略”
- 第 4.1.7 节 “标头修改策略”
- 第 4.1.8 节 “IP 检查策略”
- 第 4.1.9 节 “liquid Context Debug 策略”
- 第 4.1.10 节 “日志记录策略”
- 第 4.1.15 节 “Prometheus Metrics”
- 第 4.1.11 节 “OAuth 2.0 令牌 Introspection 策略”
- 第 4.1.12 节 “推荐策略”
- 第 4.1.13 节 “RH-SSO/Keycloak 角色检查策略”
- 第 4.1.14 节 “路由策略”
- 第 4.1.16 节 “SOAP 策略”
- 第 4.1.17 节 “TLS 客户端证书验证策略”
- 第 4.1.18 节 “上游策略”
- 第 4.1.19 节 “URL 重写策略”
- 第 4.1.20 节 “使用 Captures 策略的 URL 重写”
您可以在 3scale API Management 中 启用和配置 标准策略。
4.1.1. 3scale Auth 缓存策略
3scale 身份验证缓存策略会缓存对 APIcast 发出的身份验证调用。您可以选择操作模式来配置缓存操作。
3scale Auth 缓存在以下模式中可用：
1.Strict - Cache only authorized calls.
"strict"模式仅缓存授权的调用。如果策略在"strict"模式下运行，并且调用失败或被拒绝，策略会使缓存条目失效。如果后端无法访问，则所有缓存的调用都会被拒绝，无论它们缓存的状态如何。
2.Resilient – Authorize according to last request when backend is down.
"弹性"模式会缓存授权和拒绝调用。如果策略在"弹性"模式下运行，则失败的调用不会使现有的缓存条目无效。如果后端变得不可访问，则命中缓存的调用仍会根据缓存的状态继续获得授权或拒绝。
3.Allow - When backend is down, allow everything unless seen before and denied.
"Allow"模式会缓存授权和被拒绝的调用。如果策略在"allow"模式下运行，则缓存的调用根据缓存的状态继续被拒绝或允许。但是，任何新调用都将缓存为授权。
在"允许"模式下操作存在安全隐患。在使用"allow"模式时，请考虑以上问题并进行练习。
4.none - 禁用缓存。
"None"模式禁用缓存。如果您希望策略保持活动状态，但不想使用缓存，则此模式非常有用。
配置属性
| 属性 | 描述 | 值 | 必需？ |
|---|---|---|---|
| caching_type |
| 数据类型：枚举的字符串 [resilient, strict, allow, none] | 是 |
策略对象示例
有关如何配置策略的详情，请参考文档中的创建策略链 部分。
4.1.2. 3scale 批处理器策略
3scale Batcher 策略为标准 APIcast 授权机制提供了一个替代方法，其中每个 API 请求 APIcast 都会进行对 3scale 后端(Service Management API)的调用。
3scale Batcher 策略通过显著减少到 3scale 后端的请求数量来减少延迟并增加吞吐量。为了达到此目的，此策略会缓存授权状态和批处理使用情况报告。
当 3scale Batcher 策略被启用时，APIcast 会使用以下授权流：
在每个请求中，策略检查是否缓存凭证：
- 如果缓存了凭据，策略将使用缓存的授权状态，而不是调用 3scale 后端。
- 如果没有缓存凭据，策略会调用后端，并使用可配置的生存时间(TTL)来缓存授权状态。
- 策略不立即向 3scale 后端报告与请求对应的使用量，而是累计使用计数器将它们报告到批处理中的后端。单独的线程在单个调用中报告 3scale 后端的总用量计数器，具有可配置的频率。
3scale Batcher 策略提高了吞吐量，但准确性较低。使用限制和当前利用率存储在 3scale 中，APIcast 只能在向 3scale 后端发出调用时获取正确的授权状态。当 3scale Batcher 策略被启用时，chrony APIcast 不会发送调用 3scale。在此窗口中，调用的应用程序可能会超过定义的限值。
如果吞吐量比速率限制的准确性更重要，则将此策略用于高负载 API。当报告频率和授权 TTL 低于速率限制周期时，3scale Batcher 策略可以带来更好的准确性。例如，如果限制是每天的，并且报告频率和授权 TTL 被配置为几分钟。
3scale Batcher 策略支持以下配置设置：
auths_ttl：当授权缓存过期时，以秒为单位设置 TTL。当缓存当前调用的授权时，APIcast 将使用缓存的值。在
auths_ttl参数中设置的时间后，APIcast 会移除缓存并调用 3scale 后端来检索授权状态。-
batch_report_seconds：设置批处理报告的频率发送到 3scale 后端。默认值为10秒。
要使用此策略，请在策略链中同时启用 3scale APIcast 和 3scale 批处理器策略。
4.1.3. 匿名访问策略
匿名访问策略会公开一项服务，无需身份验证。例如，这对无法适应发送身份验证参数的传统应用程序很有用。匿名策略只支持使用 API Key 和 App Id / App Key 身份验证选项的服务。当为未提供任何凭证的 API 请求启用策略时，APIcast 将授权调用使用策略中配置的默认凭据。若要授权 API 调用，配置有凭据的应用必须存在并且处于活动状态。
使用 Application Plans，您可以配置用于默认凭证的应用程序的速率限值。
在策略链中同时使用这些策略时，您需要将匿名访问策略放在 APIcast 策略的前面。
以下是策略所需的配置属性：
auth_type ：从以下备选之一选择一个值，并确保属性与为 API 配置的身份验证选项对应：
- app_id_and_app_key ：用于 App ID / App Key 身份验证选项。
- user_key: 用于 API 密钥身份验证选项。
- app_id （仅适用于 app_id_and_app_key auth 类型）：如果没有通过 API 调用提供凭证，则将用于授权的应用程序 Id。
- app_key （仅适用于 app_id_and_app_key auth 类型）：如果没有通过 API 调用提供凭据，则应用程序的 App Key 用于授权。
- user_key （仅适用于 user_key auth_type）：如果没有通过 API 调用提供凭据，应用程序使用的 API 密钥将用于授权。
图 4.1. 匿名访问策略
4.1.4. CORS 请求处理策略
通过跨原始资源共享(CORS)请求处理策略，您可以通过指定以下内容来控制 CORS 行为：
- 允许的标头
- 允许的方法
- 允许凭证
- 允许的源标头
CORS 请求处理策略将阻止所有未指定的 CORS 请求。
当在策略链中使用这两个策略时，您需要将 CORS Request 处理策略放在 APIcast 策略的前面。
配置属性
| 属性 | 描述 | 值 | 必需？ |
|---|---|---|---|
| allow_headers |
| data type：字符串数组，必须是 CORS 标头 | 否 |
| allow_methods |
| data type：枚举字符串的数组 [GET, HEAD, POST, PUT, DELETE, PATCH, OPTIONS, TRACE, CONNECT] | 否 |
| allow_origin |
| 数据类型：字符串 | 否 |
| allow_credentials |
| 数据类型：布尔值 | 否 |
策略对象示例
有关如何配置策略的详情，请参考文档的创建策略链部分。
4.1.5. echo policy
Echo 策略将传入请求打印回客户端，以及可选的 HTTP 状态代码。
配置属性
| 属性 | 描述 | 值 | 必需？ |
|---|---|---|---|
| status | 回显策略将返回到客户端的 HTTP 状态代码 | 数据类型：整数 | 否 |
| exit |
指定回显策略将使用的退出模式。 | data type：枚举字符串 [request, set] | 是 |
策略对象示例
有关如何配置策略的详情，请参考文档的创建策略链部分。
4.1.6. 边缘限制策略
Edge Limiting 策略旨在为发送到后端 API 的流量提供灵活的速率限制，并可与默认的 3scale 授权一起使用。策略支持的用例的一些示例包括：
-
最终用户速率限制： Rate limits by the "sub"(subject)声明在请求的 Authorization 标头中传递的 JWT 令牌的值（配置为
{{ jwt.sub }}）。 - 请求每秒(RPS)速率限制.
- 每个服务的全球速率限值：每个服务应用限制而不是每个应用程序。
- 并发连接限制：设置允许的并发连接数。
4.1.6.1. 限制类型
该策略支持 lua-resty-limit-traffic 库提供的以下类型的限制：
-
leaky_bucket_limiters：基于基于基于平均请求数和最大突发大小的"leaky_bucket"算法。 -
fixed_window_limiters: 基于固定的时间窗口（最后 X 秒）。 -
connection_limiters：基于并发连接数。
您可以通过服务或全局限制来限制任何限制。
4.1.6.2. 限制定义
限制具有一个键，用于对用来定义限制（IP、服务、端点、ID、特定标头等）的实体进行编码。Key 在限制者的 key 参数中指定。
key 是由以下属性定义的对象：
-
名称：它是密钥的名称。它在范围内必须是唯一的。 Scope：它定义密钥的范围。支持的范围有：-
每个影响一个服务（
service）的服务范围。 -
影响所有服务（
global）的全局范围。
-
每个影响一个服务（
name_type: 它定义如何评估"name"值：-
纯文本（
plain） -
Liquid（
liquid）
-
纯文本（
每个限制也有一些参数因类型而异：
leaky_bucket_limiters:rate,burst.-
速率：它定义每秒可进行的请求数量，而没有延迟。 -
burst：它定义每秒可以超过允许的速率的请求数。对于超过允许率（根据速率指定）的请求引入人工延迟。在超过burst中定义的每秒请求数后，请求将被拒绝。
-
-
fixed_window_limiters:count,window.计数定义了在窗口中定义的每秒数发出的请求数量。 connection_limiters：conn、burst、delay.-
conn：定义允许的最大并发连接数。它允许通过每秒burst连接超过该数量。 -
delay：这是延迟超过限制的连接的秒数。
-
例子
每分钟允许 10 个请求到 service_A：
{ "key": { "name": "service_A" }, "count": 10, "window": 60 }{ "key": { "name": "service_A" }, "count": 10, "window": 60 }Copy to Clipboard Copied! Toggle word wrap Toggle overflow 允许延迟 1 到 10 的 100 个连接，延迟为 10：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
您可以为每个服务定义多个限制。如果定义了多个限制，则在至少达到一个限值时请求可以被拒绝或延迟。
4.1.6.3. 移动模板
Edge Limiting 策略允许通过在键中支持 Liquid 变量来指定动态密钥的限制。为此，键的 name_type 参数必须设置为 "liquid"，而 name 参数则可使用 Liquid 变量。示例：{ { remote_addr }} 用于客户端 IP 地址，或者 {{ jwt.sub }} 用于 JWT 令牌的"sub"声明。
例如：
{
"key": { "name": "{{ jwt.sub }}", "name_type": "liquid" },
"count": 10,
"window": 60
}
{
"key": { "name": "{{ jwt.sub }}", "name_type": "liquid" },
"count": 10,
"window": 60
}有关 Liquid 支持的详情请参考 第 5.1 节 “在策略中使用变量和过滤器”。
4.1.6.4. 应用条件
该条件定义 API 网关何时应用限制器。您必须在每个限制器的 condition 属性中至少指定一个操作。
condition 由以下属性定义：
-
combine_op.它是应用于操作列表的布尔值运算符。支持以下两个值：或和。 操作。它是需要评估的条件列表。每个操作都由一个具有以下属性的对象表示：-
left：操作的左侧。 -
left_type：如何评估左属性（解释或静止）。 -
正确：操作的正确部分。 -
right_type：如何评估正确的属性（解释或查询）。 -
op：在左侧和右部分之间应用的 Operator。支持以下两个值：==(等于)和!=（不等于）。
-
例如：
4.1.6.5. 配置存储
默认情况下，Edge 限制策略将 OpenResty 共享字典用于速率限制计数器。但是，可以使用外部 Redis 服务器而不是共享字典。这在使用多个 APIcast 实例时很有用。Redis 服务器可以使用 redis_url 参数进行配置。
4.1.6.6. 错误处理
限制器支持以下参数来配置错误的处理方式：
limits_exceeded_error允许配置在超过配置的限制时返回到客户端的错误状态代码和消息。应配置以下参数：-
status_code：超过限制时请求的状态代码。默认：429。 error_handling：如何处理错误。-
退出: "Respond with an error"。 -
日志："记录请求通过，仅输出日志"
-
-
configuration_error允许配置错误状态代码，并在配置错误时返回到客户端的消息。应配置以下参数：-
status_code：配置问题时的状态代码。默认：500。 error_handling：如何处理错误。-
退出: "Respond with an error"。 -
日志："记录请求通过且仅输出日志"。
-
-
4.1.7. 标头修改策略
标头修改策略允许您修改现有标头，或者定义额外的标头以添加到或从传入的请求或响应中删除。您可以修改响应和请求标头。
Header 修改策略支持以下配置参数：
-
request: 应用到请求标头的操作列表 -
响应：应用到响应标头的操作列表
每个操作都由以下参数组成：
-
op：指定要应用的操作。add操作会为现有标头添加一个值。这个set操作会创建一个标头和值，如果已存在该标头的值，则会覆盖现有的标头值。push操作会创建一个标头和值，但如果已存在，则不会覆盖现有的标头值。相反，push会将值添加到现有标头中。delete操作会删除标头。 -
标题：指定要创建的标头或修改，并且可以用作标头名称（如Custom-Header）的任何字符串。 -
value_type：定义如何评估标题值，可以是纯文本的纯文本或作为 Liquid 模板进行评估。更多信息请参阅 第 5.1 节 “在策略中使用变量和过滤器”。 -
值：指定将用于标头的值。对于值类型"liquid"，值应当采用{{ variable_from_context }}格式。删除时不需要.
策略对象示例
有关如何配置策略的详情，请参考文档中的创建策略链 部分。
4.1.8. IP 检查策略
IP 检查策略用于根据 IP 列表拒绝或允许请求。
配置属性
| 属性 | 描述 | 数据类型 | 必需？ |
|---|---|---|---|
| check_type |
|
字符串，必须是 | 是 |
| ips |
| 字符串数组，必须是有效的 IP 地址 | 是 |
| error_msg |
| 字符串 | 否 |
| client_ip_sources |
|
字符串数组，有效选项为 | 否 |
策略对象示例
有关如何配置策略的详情，请参考文档的创建策略链部分。
4.1.9. liquid Context Debug 策略
Liquid Context Debug 策略仅用于开发环境中而不是生产环境中的调试用途。
此策略使用 JSON 响应 API 请求，其包含上下文中可用的对象和值，并可用于评估 Liquid 模板。当与 3scale APIcast 或 Upstream 策略结合使用时，必须在策略链中放置 Liquid Context Debug 才能正常工作。为避免循环引用，该策略仅包含重复的对象，并将其替换为 stub 值。
启用策略时 APIcast 返回的值示例：
4.1.10. 日志记录策略
Logging 策略允许单独启用或禁用 APIcast(NGINX)访问日志。默认情况下，策略链中不启用此策略。
此策略仅支持 enable_access_logs 配置参数。要禁用服务的访问日志记录，启用策略，取消选择 enable_access_logs 参数，然后单击 Submit 按钮。要启用访问日志，请选择 enable_access_logs 参数或禁用 Logging 策略。
您可以将 Logging 策略与访问日志位置的全局设置合并。设置 APICAST_ACCESS_LOG_FILE 环境变量，以配置 APIcast 访问日志的位置。默认情况下，此变量设置为 /dev/stdout，这是标准输出设备。有关全局 APIcast 参数的详情，请参考 ???。
4.1.11. OAuth 2.0 令牌 Introspection 策略
OAuth 2.0 Token Introspection 策略允许使用令牌签发者(Red Hat Single Sign-On)的 Token Introspection Endpoint(Red Hat Single Sign-On)验证用于带有 OpenID Connect 身份验证选项的服务的 JSON Web Token(JWT)令牌。
APIcast 支持 auth_type 字段中的以下身份验证类型，以确定 Token Introspection Endpoint 和调用此端点时使用的凭证 APIcast：
use_3scale_oidc_issuer_endpoint使用这个设置，APIcast 使用在 Service Integration 页面中配置的 OpenID Connect Issuer 设置中的客户端凭证（客户端 ID 和客户端 Secret）和令牌内省端点。
APIcast 从
token_introspection_endpoint字段发现 Token Introspection 端点，.well-known/openid-configuration端点返回。例 4.1. 身份验证类型设置为
use_3scale_oidc_issuer_endpoint如果身份验证类型被设置为
use_3scale_oidc_issuer_endpoint，则是一个配置示例：Copy to Clipboard Copied! Toggle word wrap Toggle overflow client_id+client_secret这个选项允许您指定不同的令牌内省端点，以及客户端 ID 和客户端 Secret APIcast 用来请求令牌信息。
使用这个选项时，请设置以下配置参数：
-
client_id：为令牌内省端点设置客户端 ID。 -
client_secret：为令牌内省端点设置客户端 Secret。 introspection_url：设置 Introspection Endpoint URL。例 4.2. 身份验证类型设置为
client_id+client_secret如果身份验证类型被设置为
client_id+client_secret，则如下是配置示例：Copy to Clipboard Copied! Toggle word wrap Toggle overflow
-
无论 auth_type 字段中的设置是什么，APIcast 使用 Basic Authentication 来授权 Token Introspection 调用（Authorization: Basic <token> 标头，其中 <token > ; 是 Base64 编码的 < client_id>:<client_secret>）。
Token Introspection Endpoint 的响应中包含 active 属性。APIcast 检查此属性的值。根据属性的值，APIcast 授权或拒绝调用：
-
true：调用已被授权 -
false: 调用被拒绝，且Authentication Failed错误
该策略允许缓存令牌，以避免在相同 JWT 令牌的每个调用中调用 Token Introspection Endpoint。要为 Token Introspection Policy 启用令牌缓存，请将 max_cached_tokens 字段设置为从 0 （禁用该功能）到 10000 直接的值。另外，您可以在 max_ttl_tokens 字段中将令牌的值从 1 设置为 3600 秒。
4.1.12. 推荐策略
请参阅 请参阅 请参阅 请参阅 请参阅器过滤功能。当在服务策略链中启用策略时，APIcast 会在 引用 参数中将后续请求的引用策略发送到 Service Management API（AuthRep 调用）。有关如何过滤工作的更多信息，请参阅 身份验证模式 中的" 引用器过滤 "部分。
器
4.1.13. RH-SSO/Keycloak 角色检查策略
此策略在与 OpenID Connect 身份验证选项一起使用时添加角色检查。此策略会验证红帽单点登录发布的访问令牌中的 realm 角色和客户端角色。当您要为每一个客户端的资源或 3Scale 添加角色检查时，会指定 realm 角色。
以下是两种角色类型，用于检查 类型 属性是否在策略配置中指定：
- 白名单 （默认）：当使用 白名单 时，APIcast 将检查 JWT 令牌中是否存在指定的范围，并在 JWT 中没有范围时拒绝调用。
- blacklist ：当使用 黑名单 时，如果 JWT 令牌包含黑名单范围，APIcast 将拒绝调用。
无法同时配置检查 - 在同一 策略中的黑名单 和 白名单，但您可以在 APIcast 策略链中添加多个 RH-SSO/Keycloak 角色检查 策略的实例。
您可以通过策略配置的 scopes 属性配置范围列表。
每个 scope 对象具有以下属性：
- 资源 ：角色控制的资源（端点）。这个格式与映射规则相同。模式从字符串开头匹配，若要完全匹配，您必须在末尾附加 $。
resource_type ：这定义了 资源 值的评估方式。
- 以纯文本(plain)形式：以纯文本形式评估 资源 值。示例： /api/v1/products$.
- 作为 Liquid 文本(liquid)：允许在 资源 值中使用 Liquid。示例： /resource_{{ jwt.aud }} 管理对资源的访问，包括客户端 ID（包含在 JWT 仲裁 声明中）。
realm_roles ：使用它来检查 realm 角色（请参阅 Red Hat Single Sign-On 文档中的 Realm Roles ）。
域角色存在于红帽单点登录发布的 JWT 中。
"realm_access": { "roles": [ "<realm_role_A>", "<realm_role_B>" ] }"realm_access": { "roles": [ "<realm_role_A>", "<realm_role_B>" ] }Copy to Clipboard Copied! Toggle word wrap Toggle overflow 策略中必须指定实际角色。
"realm_roles": [ { "name": "<realm_role_A>" }, { "name": "<realm_role_B>" } ]"realm_roles": [ { "name": "<realm_role_A>" }, { "name": "<realm_role_B>" } ]Copy to Clipboard Copied! Toggle word wrap Toggle overflow 以下是 realm_roles 数组中每个对象的可用属性：
- name ：指定角色的名称。
- name_type ：定义必须如何评估名称；它可以是 纯 的 或 liquid （与 resource_type的相同）。
client_roles ：使用 client_roles 检查客户端命名空间中的特定访问角色（请参阅 Red Hat Single Sign-On 文档中的客户端角色 ）。
客户端角色存在于 JWT 中的 resource_access 声明下。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 指定策略中的客户端角色。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 以下是 client_roles 数组中每个对象的可用属性：
- name ：指定角色的名称。
- name_type ：定义必须如何评估 name 值；它可以是 纯 的 或 liquid （与 resource_type的相同）。
- client ：指定角色的客户端。如果未定义，此策略将 aud 声明用作客户端。
- client_type ：定义必须如何评估 客户端 值；它可以是 纯 的或禁止（与 resource_type的作用相同）。
4.1.14. 路由策略
Routing 策略允许您将请求路由到不同的目标端点。您可以定义目标端点，然后将从 UI 传入的请求路由到使用正则表达式的请求。
路由基于以下规则：
与 APIcast 策略组合时，路由策略应放在链中的 APIcast 之前，因为首先将内容输出到响应的两个策略。当第二个进程获得更改以运行其内容阶段时，该请求已发送到客户端，因此不会输出到响应。
4.1.14.1. 路由规则
- 如果存在多个规则，它将应用第一个匹配项。规则将排序。
- 如果没有任何规则，它将应用上游，因此策略将与 APIcast 策略结合使用，该策略可从服务配置中获取上游（一个私有基本 URL）。
4.1.14.2. 请求路径规则
这是当路径为 /accounts 时路由到 http://example.com 的配置：
4.1.14.3. 标头规则
这是当标头 Test-Header 的值为 123 时路由到 http://example.com 的配置：
4.1.14.4. 查询参数规则
这是当查询参数 test_query_arg 为 123 时路由到 http://example.com 的配置 ：
4.1.14.5. JWT 声明规则
若要基于 JWT 声明的值进行路由，链中需要有一个策略来验证 JWT 并将其存储在策略共享的上下文中。
这是当 JWT 声明 test_claim 的值为 123 时路由到 http://example.com 的配置 ：
4.1.14.6. 多操作规则
规则可以有多个操作，只有当所有上游评估为 true 时（使用 'and' combine_op）或至少被评估为 true （使用 'or' combine_op）指向给定上游的操作。combine_op 的默认值为 'and'。
这是在请求的路径为 /accounts 以及标头 Test-Header 的值为 123 时路由到 http://example.com 的配置：
这是在请求的路径为 /accounts 或者标头 Test-Header 的值为 123 时路由到 http://example.com 的配置 ：
4.1.14.7. 组合规则
规则可以组合在一起使用。当有多个规则时，上游选择是首批评估为 true 的规则之一。
这是包含多个规则的配置：
4.1.14.8. catch-all 规则
没有操作的规则始终匹配。这对于定义概括性规则非常有用。
如果路径为 /abc，则此配置将请求路由到 http://some_upstream.com，如果路径是 /def，将请求路由到 http://another_upstream.com，最后，如果之前的规则没有评估为 true，则会将请求路由到 http://default_upstream.com ：
4.1.14.9. 支持的操作
支持的操作有 ==, != 和 matches。后者将字符串与正则表达式匹配，并使用 ngx.re.match来实施
这是使用 != 的配置。当路径不是 /accounts 时，它会路由到 http://example.com:
4.1.14.10. 移动模板
可以将弹性模板用于配置的值。如果链中的策略将键 my_var 存储在上下文中，则可以使用动态值定义规则。
这是使用该值路由请求的配置：
4.1.14.11. 设置 Host 标头中使用的主机
默认情况下，当路由请求时，策略使用匹配的规则的 URL 主机设置 Host 标头。可以通过 host_header 属性指定不同的主机。
这是将 some_host.com 指定为 Host 标头主机的配置：
4.1.15. Prometheus Metrics
Prometheus是一个独立的开源系统监视和警报工具包。
在这个 Red Hat 3scale 版本中，不支持 Prometheus 安装和配置。另外，您可以使用 Prometheus 的社区版本 视觉化 API 服务的指标和警报。
Prometheus 指标可用性
以下部署选项提供了与 Prometheus 的 APIcast 集成：
- 自我管理的 APIcast（包括托管或内部 API 管理器）
- 内置 APIcast 内部
托管 API Manager 和托管的 APIcast 不提供与 Prometheus 的 APIcast 集成。
Prometheus metrics 列表
以下指标始终可用：
| 指标 | 描述 | 类型 | 标签 |
|---|---|---|---|
| nginx_http_connections | HTTP 连接数 | gauge | state(accepted,active,handled,reading,total,waiting,writing) |
| nginx_error_log | APIcast 错误 | 计数 | level(debug,info,notice,warn,error,crit,alert,emerg) |
| openresty_shdict_capacity | worker 共享字典的能力 | gauge | dict(one for every dictionary) |
| openresty_shdict_free_space | worker 共享字典的可用空间 | gauge | dict(one for every dictionary) |
| nginx_metric_errors_total | 管理指标的 Lua 库错误数 | 计数 | - |
| total_response_time_seconds | 发送响应客户端所需时间（以秒为单位） | histogram | - |
| upstream_response_time_seconds | 来自上游服务器的响应时间（以秒为单位） | histogram | - |
| upstream_status | 来自上游服务器的 HTTP 状态 | 计数 | status |
| threescale_backend_calls | 授权并报告请求到 3scale 后端(Apisonator) | 计数 | endpoint(authrep, auth, report), status(2xx, 4xx, 5xx) |
只有在使用 3scale Batcher 策略时，以下指标才可用：
| 指标 | 描述 | 类型 | 标签 |
|---|---|---|---|
| batching_policy_auths_cache_hits | 按 3scale 批处理策略的 auths 缓存中的内容 | 计数 | - |
| batching_policy_auths_cache_misses | 3scale 批处理策略的 auths 缓存中丢失 | 计数 | - |
没有值的指标
如果指标没有值，则指标会被隐藏。例如，如果 nginx_error_log 没有报告错误，则不会显示 nginx_error_log 指标。只有当它的值有值后才可见。
4.1.16. SOAP 策略
SOAP 策略与 HTTP 请求的 SOAPAction 或 Content-Type 标头中提供的 SOAP 操作 URI 匹配策略中指定的映射规则。
配置属性
| 属性 | 描述 | 值 | 必需？ |
|---|---|---|---|
| pattern |
此 | 数据类型：字符串 | 是 |
| metric_system_name |
| 数据类型：字符串，必须是一个有效的 metric | 是 |
策略对象示例
有关如何配置策略的详情，请参考文档的创建策略链部分。
4.1.17. TLS 客户端证书验证策略
4.1.17.1. 关于 TLS 客户端证书验证策略
借助 TLS 客户端证书验证策略，APIcast 实施 TLS 握手，并根据白名单验证客户端证书。白名单包含由认证机构(CA)或纯客户端证书签名的证书。如果证书过期或无效，请求将被拒绝，且不会处理其他策略。
客户端连接到 APIcast 以发送请求并提供客户端证书。APIcast 根据策略配置验证传入请求中提供的证书的真实性。APIcast 也可以配置为使用自己的客户端证书，以在连接到上游时使用它。
4.1.17.2. 设置 APIcast 以使用 TLS 客户端证书验证
APIcast 需要配置为终止 TLS。按照以下步骤配置用户在 APIcast 上提供的客户端证书验证策略。
4.1.17.2.1. 先决条件：
- 您需要有权访问 3scale 安装。
- 您需要等待所有部署完成。
4.1.17.2.2. 设置 APIcast 以使用策略
要设置 APIcast 并将其配置为终止 TLS，请按照以下步骤操作：
您需要获取访问令牌并部署 APIcast 自我管理，如 使用 OpenShift 模板部署 APIcast 中所述。
注意需要 APIcast 自我管理的部署，因为 APIcast 实例需要重新配置，才能将一些证书用于整个网关。
仅用于测试目的，您可以使用没有缓存和暂存环境以及
--param标志的 lazy 加载器来进行测试。oc new-app -f https://raw.githubusercontent.com/3scale/3scale-amp-openshift-templates/2.5.0.GA/apicast-gateway/apicast.yml --param CONFIGURATION_LOADER=lazy --param DEPLOYMENT_ENVIRONMENT=staging --param CONFIGURATION_CACHE=0
oc new-app -f https://raw.githubusercontent.com/3scale/3scale-amp-openshift-templates/2.5.0.GA/apicast-gateway/apicast.yml --param CONFIGURATION_LOADER=lazy --param DEPLOYMENT_ENVIRONMENT=staging --param CONFIGURATION_CACHE=0Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 生成证书用于测试目的。另外，对于生产部署，您可以使用证书颁发机构提供的证书。
使用 TLS 证书创建 Secret
oc create secret tls apicast-tls --cert=ca/certs/server.crt --key=ca/keys/server.key
oc create secret tls apicast-tls --cert=ca/certs/server.crt --key=ca/keys/server.keyCopy to Clipboard Copied! Toggle word wrap Toggle overflow 在 APIcast 部署中挂载 Secret
oc set volume dc/apicast --add --name=certificates --mount-path=/var/run/secrets/apicast --secret-name=apicast-tls
oc set volume dc/apicast --add --name=certificates --mount-path=/var/run/secrets/apicast --secret-name=apicast-tlsCopy to Clipboard Copied! Toggle word wrap Toggle overflow 将 APIcast 配置为为 HTTPS 开始侦听端口 8443
oc set env dc/apicast APICAST_HTTPS_PORT=8443 APICAST_HTTPS_CERTIFICATE=/var/run/secrets/apicast/tls.crt APICAST_HTTPS_CERTIFICATE_KEY=/var/run/secrets/apicast/tls.key
oc set env dc/apicast APICAST_HTTPS_PORT=8443 APICAST_HTTPS_CERTIFICATE=/var/run/secrets/apicast/tls.crt APICAST_HTTPS_CERTIFICATE_KEY=/var/run/secrets/apicast/tls.keyCopy to Clipboard Copied! Toggle word wrap Toggle overflow 在服务中公开 8443
oc patch service apicast -p '{"spec":{"ports":[{"name":"https","port":8443,"protocol":"TCP"}]}}'oc patch service apicast -p '{"spec":{"ports":[{"name":"https","port":8443,"protocol":"TCP"}]}}'Copy to Clipboard Copied! Toggle word wrap Toggle overflow 删除默认路由
oc delete route api-apicast-staging
oc delete route api-apicast-stagingCopy to Clipboard Copied! Toggle word wrap Toggle overflow 将
apicast服务作为路由公开oc create route passthrough --service=apicast --port=https --hostname=api-3scale-apicast-staging.$WILDCARD_DOMAIN
oc create route passthrough --service=apicast --port=https --hostname=api-3scale-apicast-staging.$WILDCARD_DOMAINCopy to Clipboard Copied! Toggle word wrap Toggle overflow 注意您要使用的每个 API 和每个 API 的域更改都需要这一步。
通过在占位符中指定 [Your_user_key]，验证之前部署的网关是否正常工作并且配置已保存。
curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN?user_key=[Your_user_key] -v --cacert ca/certs/ca.crt
curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN?user_key=[Your_user_key] -v --cacert ca/certs/ca.crtCopy to Clipboard Copied! Toggle word wrap Toggle overflow
4.1.17.3. 在策略链中配置 TLS 客户端证书验证
4.1.17.3.1. 先决条件
- 您需要 3scale 登录凭据。
- 您需要使用 TLS Client Certificate Validation 策略配置 APIcast。
4.1.17.3.2. 配置策略
- 要将 TLS 客户端证书验证策略添加到您的 API，请按照 启用标准策略中介绍的步骤操作， 然后选择 TLS 客户端证书验证。
- 单击 TLS 客户端证书验证 链接。
- 若要启用该策略，选中 Enabled 复选框。
-
若要添加证书到白名单，可单击加号
+图标。 -
指定包括
-----BEGIN CERTIFICATE-----和-----END CERTIFICATE-----的证书。 - 使用 TLS 客户端证书验证设置完 API 后，单击 Update Policy。
另外：
-
您可以通过单击加号
+图标来添加更多证书。 - 您还可以通过单击上下箭头来重新组织证书。
要保存更改，请点击 Update & test in Staging Environment。
4.1.17.4. 验证 TLS 客户端证书验证策略的功能
4.1.17.4.1. 先决条件：
- 您需要 3scale 登录凭据。
- 您需要使用 TLS Client Certificate Validation 策略配置 APIcast。
4.1.17.4.2. 验证策略功能
您可以通过在占位符中指定 [Your_user_key] 来验证应用的策略。
curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/client.crt --key ca/keys/client.key curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/server.crt --key ca/keys/server.key curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt
curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/client.crt --key ca/keys/client.key
curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt --cert ca/certs/server.crt --key ca/keys/server.key
curl https://api-3scale-apicast-staging.$WILDCARD_DOMAIN\?user_key\=[Your_user_key] -v --cacert ca/certs/ca.crt4.1.17.5. 从白名单中删除证书
4.1.17.5.1. 先决条件
- 您需要 3scale 登录凭据。
- 您需要使用 TLS 客户端证书验证策略设置 APIcast。
- 您需要通过在 策略链中配置 TLS 客户端证书验证将证书 添加到白名单。
4.1.17.5.2. 删除证书
- 单击 TLS 客户端证书验证 链接。
-
要从白名单中删除证书，请点击
x图标。 - 删除证书后，点击 Update Policy。
要保存更改，请点击 Update & test in Staging Environment。
4.1.17.6. 参考材料
有关使用证书的更多信息，请参阅 红帽认证系统。
4.1.18. 上游策略
通过 Upstream 策略，您可以使用正则表达式来解析主机请求标头，并将私有基本 URL 中定义的上游 URL 替换为不同的 URL。
例如：
具有 regex /foo 的策略和 URL 字段 newexample.com 将 URL https://www.example.com/foo/123/ 替换为 newexample.com
策略链参考：
| 属性 | 描述 | 值 | 必需？ |
|---|---|---|---|
| regex |
| 数据类型：字符串，必须是一个有效的正则表达式语法 | 是 |
| url |
使用 | 数据类型：字符串，确定这是有效的 URL | 是 |
策略对象示例
有关如何配置策略的详情，请参考文档的创建策略链部分。
4.1.19. URL 重写策略
URL 重写策略允许您修改请求的路径和查询字符串。
当与 3scale APIcast 政策结合使用时，如果将 URL 重新编写策略放在策略链中的 3scale APIcast 策略之前，APIcast 映射规则将应用到修改后的路径。如果在策略链中将 URL 重新写入策略放在 APIcast 下，则映射规则将应用到原始路径。
该策略支持以下两组操作：
-
命令：用于重写请求路径的命令列表。 -
query_args_commands：要应用的命令列表来重写请求的查询字符串。
4.1.19.1. 重写路径的命令
以下是 commands 列表中每个命令的配置参数，其中包括：
-
op:要应用的操作。可用的选项包括：sub和gsub。sub操作仅用您指定的正则表达式替换第一个匹配项。gsub操作会将所有匹配项替换为您指定的正则表达式。请参阅有关 sub 和 gsub 操作的文档。 -
正则表达式：要匹配的与 Perl 兼容的正则表达式。 -
替换：替换在匹配项中使用的 : 替换字符串。 -
Options（可选）：定义正则表达式的执行方式
的选项。有关可用选项的详情，请查看 OpenResty Lua 模块项目文档中的 ngx.re.match 部分。 -
break（可选）：如果将设置为 true（已启用）时，如果命令重新编写了 URL，它将是最后应用的一个（将丢弃列表中的所有 posterior 命令）。
4.1.19.2. 重写查询字符串的命令
以下是 query_args_commands 列表中每个命令由以下部分组成的配置参数：
op: 操作要应用到查询参数。可用的选项如下：-
添加: 为现有参数添加一个值。 -
设置：在未设置时创建 arg，并在设置时替换其值。 -
push：在未设置时创建 arg，并在设置时添加值。 -
删除：删除 arg。
-
-
ARG：用于操作的查询参数名称。 -
值：指定用于查询参数的值。对于值类型"liquid"，值应当采用{{ variable_from_context }}格式。对于delete操作，不考虑该值。 -
value_type（可选）：定义查询参数值的评估方式，可以是纯文本的纯文本，或者作为 Liquid 模板进行评估。更多信息请参阅 第 5.1 节 “在策略中使用变量和过滤器”。如果没有指定，则默认使用类型"plain"。
示例
URL 重写策略配置如下：
发送到 APIcast 的原始请求 URI：
https://api.example.com/api/v1/products/123/details?user_key=abc123secret&pusharg=first&setarg=original
https://api.example.com/api/v1/products/123/details?user_key=abc123secret&pusharg=first&setarg=original应用 URL 重写后 APIcast 发送到 API 后端的 URI：
https://api-backend.example.com/internal/products/123/details?pusharg=first&pusharg=pushvalue&setarg=setvalue
https://api-backend.example.com/internal/products/123/details?pusharg=first&pusharg=pushvalue&setarg=setvalue应用以下转换：
-
子字符串
/api/v1/匹配唯一的路径重写命令，它被/internal/替换。 -
已删除
user_key查询参数。 -
值
pushvalue作为pusharg查询参数的额外值添加。 -
查询参数
setarg的original值替换为配置的值setvalue。 -
命令
add没有被应用，因为原始 URL 中不存在查询参数addarg。
有关如何配置策略的详情，请参考文档中的创建策略链 部分。
4.1.20. 使用 Captures 策略的 URL 重写
使用 Captures 策略的 URL Rewriting 是 第 4.1.19 节 “URL 重写策略” 策略的替代，并允许在将 API 请求传递给 API 后端前重写 API 请求的 URL。
URL 使用 Captures 策略检索 URL 中的参数，并在重写 URL 中使用其值。
该策略支持 transformations 配置参数。这是一个对象列表，用于描述将哪些转换应用到请求 URL。每个调整对象由两个属性组成：
-
match_rule：此规则与传入请求 URL 匹配。它可以包含{nameOfArgument}格式的命名参数；这些参数可以在重写 URL 中使用。将 URL 与match_rule进行比较，作为正则表达式。匹配指定参数的值必须只包含以下字符（在 PCRE regex 表示法中）：[\w-.~%!$&'（）*+,;=@:]+。可以在match_rule表达式中使用其他 regex 令牌，如^表示字符串开头，$代表字符串末尾。 -
模板：原始 URL 重写的 URL 模板；它可以使用match_rule中的命名参数。
原始 URL 的查询参数与 template 中指定的查询参数合并。
示例
使用 Captures 的 URL 重写如下：
发送到 APIcast 的原始请求 URI：
https://api.example.com/api/v1/products/123/details?user_key=abc123secret
https://api.example.com/api/v1/products/123/details?user_key=abc123secret应用 URL 重写后 APIcast 发送到 API 后端的 URI：
https://api-backend.example.com/internal/products/details?user_key=abc123secret&extraparam=anyvalue&id=123
https://api-backend.example.com/internal/products/details?user_key=abc123secret&extraparam=anyvalue&id=1234.2. 启用标准策略
执行以下步骤在 Admin Portal 中启用策略：
- 登录 3scale。
- 导航到 API 服务。
-
从 [your_API_name] > Integration > Configuration，选择
edit APIcast configuration。 -
在 POLICIES 部分下，单击
add policy。 - 选择您要添加和填写所需字段的策略。
- 单击 Update and test in Staging Environment 按钮，以保存策略链。
4.3. 创建自定义 APIcast 策略
您可以完全创建自定义 APIcast 策略，或修改标准策略。
要创建自定义策略，您必须了解以下内容：
- 策略用 Lua 编写。
- 策略必须遵循，并且必须放在正确的文件目录中。
- 策略行为受到策略链中的放置方式的影响。
- 完全支持添加自定义策略的接口，但不支持自定义策略本身。
4.4. 在 APIcast 中添加自定义策略
如果创建了自定义策略，则必须将它们添加到 APIcast 中。您执行此操作的方式取决于 APIcast 部署的位置。
您可以将自定义策略添加到以下 APIcast 自我管理部署中：
- APIcast 内置网关作为 OpenShift 中 3scale 内部部署的一部分
- APIcast on OpenShift 和 Docker 容器化环境
您无法将自定义策略添加到 APIcast 托管。
切勿直接在生产网关上进行策略更改。始终测试您的更改。
4.4.1. 在内置 APIcast 中添加自定义策略
要将自定义 APIcast 策略添加到内部部署中，您必须构建包含自定义策略的 OpenShift 镜像，并将其添加到您的部署中。Red Hat 3scale 提供了一个示例存储库，您可以使用 作为框架来创建和添加自定义策略到内部部署。
此示例存储库包含自定义策略的正确目录结构，以及用于创建镜像流和 BuildConfig 的模板，用于构建包含您创建的任何自定义策略的新 APIcast OpenShift 镜像。
当您构建 apicast-custom-policies 时，构建过程 "pushes" a new image to the amp-apicast:latest 标签。当此镜像流标签上的镜像更改时(:latest)，apicast-staging 和 apicast-production 标签都默认配置为自动启动新部署。为了避免对生产服务（或暂存）造成任何中断（如果您愿意），请禁用自动部署（在镜像更改时"自动启动新部署 "），或者为生产环境配置不同的镜像流标签（例如 amp-apicast:production）。
按照以下步骤将自定义策略添加到内部部署中：
- 使用策略示例对 https://github.com/3scale/apicast-example-policy [public 软件仓库进行分叉，或使用其内容创建私有存储库。您需要在 Git 存储库中提供自定义策略的代码，供 OpenShift 构建该镜像。请注意，为了使用私有 Git 存储库，您必须在 OpenShift 中设置机密。
- 在本地克隆存储库，为您的策略添加实施，并将更改推送到您的 Git 存储库。
更新
openshift.yml模板。特别是，更改以下参数：-
策略 BuildConfig 中的
spec.source.git.uri: https://github.com/3scale/apicast-example-policy.git- 将它更改为 Git 存储库位置。 -
自定义策略 BuildConfig 中的
spec.source.images[0].paths.sourcePath: /opt/app-root/policies/example- 把example改为您在存储库中的policies目录下添加的自定义策略名称。 -
（可选）更新 OpenShift 对象名称和镜像标签。但是，您必须确保更改是共同的（例如：
apicast-example-policyBuildConfig 构建），并推送apicast-policy:example镜像，然后被apicast-custom-policiesBuildConfig 作为源使用。因此，标签应该相同。
-
策略 BuildConfig 中的
运行以下命令来创建 OpenShift 对象：
oc new-app -f openshift.yml --param AMP_RELEASE=2.5.0
oc new-app -f openshift.yml --param AMP_RELEASE=2.5.0Copy to Clipboard Copied! Toggle word wrap Toggle overflow 如果构建没有自动启动，请运行以下两个命令：如果您更改了它，请将
apicast-example-policy替换为您自己的 BuildConfig 名称（如apicast-<name>-policy）。等待第一个命令完成，然后执行第二个命令。oc start-build apicast-example-policy oc start-build apicast-custom-policies
oc start-build apicast-example-policy oc start-build apicast-custom-policiesCopy to Clipboard Copied! Toggle word wrap Toggle overflow
如果 build-in APIcast 镜像在它们上有一个触发器，跟踪 amp-apicast:latest 镜像流中的更改，APIcast 模式的新部署将启动。在 apicast-staging 重新启动后，进入 admin 门户上的 Integration 页面，然后点击 Add Policy 按钮，查看您的自定义策略。选择并配置它后，点 Update & test in Staging Environment，使自定义策略在 staging APIcast 中正常工作。
您可以通过从 Integrated OpenShift Container Registry 中获取包含自定义策略的 APIcast 镜像，将自定义策略添加到 OpenShift Container Platform(OCP)上的 APIcast 镜像。
在另一个 OpenShift Container Platform 上将自定义策略添加到 APIcast 中
- 在 APIcast 内置中添加策略
- 如果您没有在 OpenShift 主集群中部署 APIcast 网关，请 建立对主 OpenShift 集群上的内部注册表的访问。
- 下载 3scale 2.5 APIcast OpenShift 模板。
要修改模板，请将默认
镜像目录替换为内部注册表中的完整镜像名称。image: <registry>/<project>/amp-apicast:latest
image: <registry>/<project>/amp-apicast:latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow 使用 OpenShift 模板部署 APIcast，指定自定义镜像：
oc new-app -f customizedApicast.yml
oc new-app -f customizedApicast.ymlCopy to Clipboard Copied! Toggle word wrap Toggle overflow
4.5. 在 3scale 中创建策略链
作为 APIcast 网关配置的一部分，在 3scale 中创建策略链。按照以下步骤在 UI 中修改策略链：
- 登录到您的 AMP
进入 API 服务
从 [your_API_name] > Integration > Configuration，选择
edit APIcast configuration在 POLICIES 部分下，使用箭头图标来重新排序策略链中的策略。始终将 APIcast 策略最后一个放在策略链中。
- 点 Update and test in Staging Environment 按钮保存策略链
4.6. 创建策略链 JSON 配置文件
如果您使用原生部署 APIcast，您可以创建一个 JSON 配置文件来控制 AMP 之外的策略链。
JSON 配置文件策略链包含一个由以下信息组成的 JSON 数组：
-
带有
id值的services对象，用于指定策略链按照数字应用到哪个服务 -
proxy对象，其中包含 policy_chain 和后续对象 -
policy_chain对象，其中包含定义策略链的值 -
单个
策略对象，用于指定识别策略和配置策略行为所需的名称和配置数据
以下是自定义策略 sample_policy_1 和 API 内省标准策略 token_introspection 的策略链示例：
所有策略链都必须包含内置策略 APIcast。将 APIcast 置于策略链中的位置将影响策略行为。
第 5 章 将策略链与 APIcast 原生部署集成
对于原生 APIcast 部署，您可以通过使用 THREESCALE_CONFIG_FILE 环境变量指定配置文件来集成 自定义策略链。以下示例指定了配置文件 example.json ：
THREESCALE_CONFIG_FILE=example.json bin/apicast
THREESCALE_CONFIG_FILE=example.json bin/apicast5.1. 在策略中使用变量和过滤器
一些 第 4.1 节 “APIcast 标准策略” 支持 Liquid 模板，它允许使用纯文本值，还包括在请求上下文中存在的变量。
要使用上下文变量，将其名称打包在 {{ 和 }} 中，例如： {{ uri }}。如果变量是对象，您也可以访问其属性，例如： {{ somevar.attr }}。
以下是所有策略中的标准变量：
-
URI：没有查询参数的请求路径（内嵌的 NGINX 变量$uri的值）。 -
主机：请求的主机（内嵌的 NGINX 变量$host的值）。 -
REMOTE_ADDR：客户端的 IP 地址（嵌入式 NGINX 变量的值
$）。remote_addr -
标头：包含请求标头的对象。使用{{headers['Some-Header']}}获取特定的标头值。 -
http_method：请求方法：GET、POST 等。
这些变量可在请求 的上下文中 找到。策略可以向上下文添加额外变量。这些变量可由策略链中相同的其他策略使用，只要使用它们的阶段在添加变量的阶段之后执行它们。如果变量在添加变量的策略后显示的策略中使用了同一阶段，则也可以是同一阶段。
以下是标准 3scale APIcast 策略添加到上下文中的变量示例：
-
JWT：用于 OpenID Connect 身份验证的 JWT 令牌的解析 JSON 载荷。 -
Credentials：包含应用凭证的对象。示例："app_id": "972f7b4f","user_key": "13b668c4d1e10eaebaa5144b4749713f". -
Service ：包含当前请求的服务配置的对象。
示例：服务 ID 将为 {{ service.id }}。
有关上下文中可用对象和值的完整列表，请查看 第 4.1.9 节 “liquid Context Debug 策略”。
变量配合 Liquid 模板使用。示例： {{ remote_addr }}、{{ headers['Some-Header'] }}、{{ jwt.aud }}.支持值变量的策略具有一个特殊参数，通常带有 _type 后缀（例如： value_type、name_type 等等），它接受两个值："plain"表示纯文本，"liquid"用于 liquid 模板。
APIcast 还支持 Liquid 过滤器，可应用于变量的值。过滤器将 NGINX 功能应用到 Liquid 变量的值。
过滤器在变量输出标签 {{ }} 中放置，紧随变量的名称或通过竖线字符 | 和过滤器的名称来排列的字面值。示例：{ { 'username:password' | encode_base64 }}, {{ uri | escape_uri }}.
有些过滤器不需要参数，因此您可以使用空字符串而不是 变量。示例： {{ '' | utctime }} 将以 UTC 时区返回当前时间。
过滤器可以按如下所示链接：{{ variable | function1 | function2 }}。示例： {{ '' | utctime |scap_uri }}.
以下是可用功能列表：
第 6 章 APIcast 环境变量
APIcast 环境变量允许您修改 APIcast 的行为。以下值是受支持的环境变量：
- 不支持或已弃用的环境变量不会被列出
- 有些环境变量功能可能已移到 APIcast 策略
- APICAST_BACKEND_CACHE_HANDLER
- APICAST_CONFIGURATION_CACHE
- APICAST_CONFIGURATION_LOADER
- APICAST_CUSTOM_CONFIG
- APICAST_ENVIRONMENT
- APICAST_LOG_FILE
- APICAST_LOG_LEVEL
- APICAST_ACCESS_LOG_FILE
- APICAST_OIDC_LOG_LEVEL
- APICAST_MANAGEMENT_API
- APICAST_MODULE
- APICAST_PATH_ROUTING
- APICAST_POLICY_LOAD_PATH
- APICAST_PROXY_HTTPS_CERTIFICATE_KEY
- APICAST_PROXY_HTTPS_CERTIFICATE
- APICAST_PROXY_HTTPS_PASSWORD_FILE
- APICAST_PROXY_HTTPS_SESSION_REUSE
- APICAST_HTTPS_VERIFY_DEPTH
- APICAST_REPORTING_THREADS
- APICAST_RESPONSE_CODES
- APICAST_SERVICES_LIST_URL
- APICAST_SERVICES_LIST
- APICAST_SERVICE_${ID}_CONFIGURATION_VERSION
- APICAST_WORKERS
- BACKEND_ENDPOINT_OVERRIDE
- OPENSSL_VERIFY
- RESOLVER
- THREESCALE_CONFIG_FILE
- THREESCALE_DEPLOYMENT_ENV
- THREESCALE_PORTAL_ENDPOINT
- OPENTRACING_TRACER
- OPENTRACING_CONFIG
- OPENTRACING_HEADER_FORWARD
- APICAST_HTTPS_PORT
- APICAST_HTTPS_CERTIFICATE
- APICAST_HTTPS_CERTIFICATE_KEY
- all_proxy ALL_PROXY
- http_proxy HTTP_PROXY
- https_proxy HTTPS_PROXY
- no_proxy NO_PROXY
APICAST_BACKEND_CACHE_HANDLER
Values: strict | resilient
Default: strict
弃用 ： 使用 缓存 策略。
定义当后端不可用时授权缓存的行为方式。当后端不可用时，请严格删除缓存的应用。弹性仅在从后端获取授权时才会这样做。
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
Default:
Value: string[:]
示例 ：production:cloud-hosted
双冒号(:)分隔的环境列表（或路径）应当加载 APIcast。可以在 CLI 上使用它而不是 -e 或 ---environment 参数，例如作为默认环境存储在容器镜像中。CLI 上传递的任何值都会覆盖此变量。
APICAST_LOG_FILE
默认 ： stderr
定义用于存储 OpenResty 错误日志的文件。它供 error_log 指令中的 bin/apicast 使用。如需更多信息，请参阅 NGINX 文档。文件路径可以是绝对的，也可以是相对于前缀目录（默认为apicast）。
APICAST_LOG_LEVEL
值 ：debug | info | notice | warn | error | crit | alert | emerg
默认 ：warn
指定 OpenResty 日志的日志级别。
APICAST_ACCESS_LOG_FILE
Default: stdout
定义将存储访问日志的文件。
APICAST_OIDC_LOG_LEVEL
值 ：debug | info | notice | warn | error | crit | alert | emerg
默认 ：err
允许为与 OpenID Connect 集成相关的日志设置日志级别。
APICAST_MANAGEMENT_API
值 ：
-
disabled：完全禁用，只侦听端口 -
状态： 仅启用用于健康检查的/status/端点 -
debug：会打开完整的 API
管理 API 功能强大，可以控制 APIcast 配置。您应该只为调试启用 debug 级别。
APICAST_MODULE
默认 ：apicast
已弃用 ： 使用 策略 替代。
指定实施 API 网关逻辑的主 Lua 模块的名称。自定义模块可以覆盖默认 apicast.lua 模块的功能。请参阅有关如何使用模块的示例。
APICAST_PATH_ROUTING
值 ：
-
true或1用于 true -
false、0或空用于 false
当此参数设置为 true 时，除了基于主机的默认路由外，网关还将使用基于路径的路由。API 请求将从请求的 Host 标头值与公共基础 URL 匹配的服务列表中路由到具有匹配映射规则的第一个服务。
APICAST_POLICY_LOAD_PATH
默认 ：APICAST_DIR/policies
Value: string[:]
示例 ：~/apicast/policies:$PWD/policies
双冒号(:)分隔的路径列表，其中 APIcast 应该查找策略。它可用于首先从开发目录加载策略或加载示例。
APICAST_PROXY_HTTPS_CERTIFICATE_KEY
Default:
值 ：字符串
示例 ：/home/apicast/my_certificate.key
客户端 SSL 证书密钥的路径。
APICAST_PROXY_HTTPS_CERTIFICATE
Default:
值 ：字符串
示例 ：/home/apicast/my_certificate.crt
APIcast 与上游连接时将使用的客户端 SSL 证书的路径。请注意，此证书将用于配置中的所有服务。
APICAST_PROXY_HTTPS_PASSWORD_FILE
Default:
值 ：字符串
示例 ：/home/apicast/passwords.txt
使用 APICAST_PROXY_HTTPS_CERTIFICATE_KEY 指定 SSL 证书密钥的密语文件的路径。
APICAST_PROXY_HTTPS_SESSION_REUSE
默认 ： on
值 ：
-
on：重用 SSL 会话。 -
off：不重复使用 SSL 会话。
APICAST_HTTPS_VERIFY_DEPTH
默认 ： 1
值 ：正整数。
定义客户端证书链的最大长度。如果此参数的值为 1，这表示此长度可能包含一个额外证书，如 中间 CA。
APICAST_REPORTING_THREADS
默认 ： 0
值 ：整数 >= 0
实验性: 在极端负载可能具有无法预计的性能并丢失报告。
大于 0 的值将启用对后端的带外报告。这是一个全新的 实验 功能，用于提高性能。客户端不会看到后端延迟，一切都将异步处理。这个值决定了在客户端因增加延迟而节流前可以同时运行多少异步报告。
APICAST_RESPONSE_CODES
值 ：
-
true或1用于 true -
false、0或空用于 false
默认 ：<empty>(false)
当设置为 true 时，APIcast 将记录 3scale 中 API 后端返回的响应代码。在 3scale 客户门户网站上查找响应代码功能的更多信息。
APICAST_SERVICES_LIST_URL
值 ：PCRE（Perl 兼容正则表达式），如 *.example.com。
过滤 3scale API Manager 中配置的服务。
此过滤器与公共基本 URL 匹配。与过滤器不匹配的服务将被丢弃。如果无法编译正则表达式，则不会加载任何服务。
如果服务不匹配但 包含在 APICAST_SERVICES_LIST 中，则服务不会被丢弃。
例 6.1. example
Regexp 过滤器 http://.*.foo.dev 应用到以下后端端点：
在这种情况下，1 和 3 在嵌入的 APIcast 和 2 中被丢弃。
APICAST_SERVICES_LIST
value ：以逗号分隔的服务 ID 列表
APICAST_SERVICES_LIST 环境变量用于过滤您在 3scale API Manager 中配置的服务。这仅应用网关中特定服务的配置，从而丢弃未在列表中指定的服务标识符。您可以在 Products > [Your_product_name] > Overview 下的 Admin Portal 中找到您的产品的服务标识符，然后参阅 Configuration、Methods 和 Settings 以及 API 调用的 ID。
APICAST_SERVICE_${ID}_CONFIGURATION_VERSION
将 ${ID} 替换为实际的服务 ID。该值应当是您可以在管理门户的配置历史记录中看到的配置版本。将它设置为特定版本将阻止它自动更新，并且始终使用该版本。
APICAST_WORKERS
默认 ：auto
值: number | auto
这是 nginx worker_processes 指令 中使用的值。默认情况下，APIcast 使用 auto，但使用 1 的开发环境除外。
BACKEND_ENDPOINT_OVERRIDE
从配置覆盖后端端点的 URI。在 OpenShift 外部部署 AMP 时非常有用.示例：https://backend.example.com.
OPENSSL_VERIFY
值 ：
-
0,false: 禁用对等验证 -
1,true：启用对等验证
控制 OpenSSL 对等验证.它默认为 off，因为 OpenSSL 无法使用系统证书存储。它需要自定义证书捆绑包并将其添加到可信证书中。
建议您使用 https://github.com/openresty/lua-nginx-module#lua_ssl_trusted_certificate 并指向由 export-builtin-trusted-certs 生成的证书捆绑包。
RESOLVER
允许指定将由 OpenResty 使用的自定义 DNS 解析器。如果 RESOLVER 参数为空，则会自动发现 DNS 解析器。
THREESCALE_CONFIG_FILE
带有网关配置的 JSON 文件的路径。您必须提供 THREESCALE_PORTAL_ENDPOINT 或 THREESCALE_CONFIG_FILE 才能成功运行网关。在这两个环境变量中，THREESCALE_CONFIG_FILE 采用优先权。
Proxy Config Show 和 Proxy Config Show Latest 端点也按 service 和 Proxy Configs List 服务限定。您必须知道服务的 ID。使用以下选项：
使用 Proxy Configs List 供应商端点： <
schema>://<admin-portal-domain>/admin/api/account/proxy_configs/<env>.json-
端点返回该提供程序的所有已存储代理配置，而不仅仅是每个服务的最新代理配置。迭代 JSON 返回的
proxy_configs数组，并选择proxy_config.content，其proxy_config.version都是具有相同proxy_config.content.id的所有代理配置之间的最高，即服务 ID。
-
端点返回该提供程序的所有已存储代理配置，而不仅仅是每个服务的最新代理配置。迭代 JSON 返回的
使用 Service List 端点：
/admin/api/services.json- 端点列出了提供程序的所有服务。迭代服务的数组，每个服务都使用 Proxy Config Show Latest 端点，该端点由服务限定。
当使用容器镜像部署网关时：
- 将 文件配置为只读卷。
- 指定指示挂载卷的位置的路径。
您可以在 Example 文件夹中找到 示例 配置文件。
THREESCALE_DEPLOYMENT_ENV
值 ： stage | production
默认 ：production
此环境变量的值定义从中下载配置的环境；在使用新 APIcast 时是 3scale staging 或 production。
这个值也会在对 3scale Service Management API 的 authorize/report 请求的 header X-3scale-User-Agent 中使用。3scale 仅将它用于统计数据目的。
THREESCALE_PORTAL_ENDPOINT
以以下格式包含密码和门户端点的 URI：
<schema>://<password>@<admin-portal-domain>.
其中：
示例 ：https://access-token@account-admin.3scale.net。
当提供了 THREESCALE_PORTAL_ENDPOINT 环境变量时，网关会在初始化时从 3scale 下载配置。配置包括 API 集成页面中提供的所有设置。
需要为 网关提供成功运行的 THREESCALE_PORTAL_ENDPOINT 或 THREESCALE_CONFIG_FILE （优先）。
OPENTRACING_TRACER
示例 ：jaeger
此环境变量控制将加载的追踪库，现在只有一个打开追踪器可用，即 jaeger。
如果为空，将禁用 opentracing 支持。
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 标头将转发到上游服务器。
APICAST_HTTPS_PORT
Default: 没有值
控制哪些端口 APIcast 应开始侦听 HTTPS 连接。如果此冲突与 HTTP 端口冲突，它将仅用于 HTTPS。
APICAST_HTTPS_CERTIFICATE
Default: 没有值
HTTPS 的 PEM 格式带有 X.509 证书的文件路径。
APICAST_HTTPS_CERTIFICATE_KEY
Default: 没有值
使用 PEM 格式的 X.509 证书 secret 密钥的文件路径。
all_proxy,ALL_PROXY
Default: no value Value: string Example: http://forward-proxy:80
定义要在未指定特定于协议的代理时用于连接服务的 HTTP 代理。不支持身份验证。
HTTP_PROXY,HTTP_PROXY
默认值 ：无值 值： 字符串 示例： http://forward-proxy:80
定义用于连接 HTTP 服务的 HTTP 代理。不支持身份验证。
HTTPS_PROXY,HTTPS_PROXY
默认值 ：无值 值： 字符串 示例： https://forward-proxy:443
定义用于连接 HTTPS 服务的 HTTP 代理。不支持身份验证。
NO_PROXY,NO_PROXY
Default: no value Value: string\[,<string>\]; * Example: foo,bar.com,.extra.dot.com
定义不应代理请求的主机名和域名的逗号分隔列表。设置为单个 * 字符（匹配所有主机）有效禁用代理。
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}