Extensible Service Proxy V2 启动选项

Extensible Service Proxy V2 (ESPv2) 是一个基于 Envoy 的代理，通过该代理，Cloud Endpoints 可以提供 API 管理功能。如需配置 ESPv2，您可以在部署 ESPv2 服务时指定配置标志。

设置配置标志

设置 ESPv2 配置标志的方法因部署平台而异，如以下部分所述。

Compute Engine 虚拟机

Compute Engine 的 ESPv2 配置标志在 docker run 命令中指定。例如：

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:2 \
    --service=SERVICE_NAME \
    --rollout_strategy=managed \
    --backend=YOUR_API_CONTAINER_NAME:8080

在此示例中，--service、--rollout_strategy 和 --backend 是 ESPv2 配置标志。

GKE 和 Kubernetes

您可以在部署清单文件的 args 字段中为 GKE 和 Kubernetes 指定配置标志。例如：

containers:
- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:2
  args: [
    "--listener_port=8081",
    "--backend=127.0.0.1:8080",
    "--service=SERVICE_NAME",
    "--rollout_strategy=managed"
  ]

在此示例中，--listener_port、--backend、--service 和 --rollout_strategy 是 ESPv2 配置标志。

适用于无服务器平台的 Cloud Run

要为适用于无服务器平台的 Cloud Run 指定启动选项，请使用 ESPv2_ARGS 环境变量。可以在 gcloud run deploy 命令中使用 --set-env-vars 选项设置此变量。

例如：

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--enable_debug

在此示例中，--enable_debug 是 ESPv2 配置标志。

如需详细了解 gcloud run deploy 命令，请参阅适用于 OpenAPI 的 Cloud Functions、适用于 OpenAPI 的 Cloud Run 或适用于 gRPC 的 Cloud Run。

如需在 ESPv2_ARGS 环境变量中设置多个参数，请指定自定义分隔符，并使用该分隔符分隔多个参数。请勿使用英文逗号作为分隔符。将自定义分隔符放置在 ESPv2_ARGS 环境变量的开头，并使用插入符号括起来。

以下示例使用 ++ 作为分隔符：

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=^++^--cors_preset=basic++--cors_allow_origin=your_host.com

如果要设置的标记包含英文逗号，您必须在 gcloud_build_image 脚本中设置 ESPv2_ARGS 环境变量。

例如，如需添加 --cors_allow_methods=PUT,POST,GET 标志，请执行以下操作：

  • 下载 gcloud_build_image 脚本。
  • 修改 gcloud_build_image，如下所示：
    cat <<EOF > Dockerfile
  FROM BASE_IMAGE

  ENV ENDPOINTS_SERVICE_PATH /etc/endpoints/service.json
  COPY service.json \ENDPOINTS_SERVICE_PATH

  ENV ESPv2_ARGS ^++^--cors_preset=basic++--cors_allow_method="GET,PUT,POST"++--cors_allow_credentials

  ENTRYPOINT ["/env_start_proxy.py"]
  EOF
  • 运行 gcloud_build_image 脚本以构建映像。

ESPv2 配置标志

ESPv2 配置标志可分为以下几类：

如需查看 ESPv2 标志的更多一般示例和帮助文本，请访问 GitHub 代码库。

非无服务器配置

在非无服务器平台（如 GKE、Compute Engine 和 Kubernetes）中运行 ESPv2 时需要使用这些标志。当针对无服务器平台部署到 Cloud Run 中时，您无法设置这些标志。

``

标志 说明
--service 设置 Endpoints 服务的名称。
--version 设置 Endpoints 服务的服务配置 ID。
--rollout_strategy 指定服务配置部署策略，[fixed|managed]。默认为 fixed。
--listener_port 标识接受下游连接的端口。它支持 HTTP/1.x、HTTP/2 和 gRPC 连接。默认为 8080。
--backend 指定本地后端应用服务器地址。有效协议为 http、https、grpc 和 grpcs（如果包含）。默认协议为 >http。

日志记录

使用这些标志配置 ESPv2 以将其他信息写入 Stackdriver 日志。

标志 说明
--log_request_headers

记录所指定请求标头的值（以英文逗号分隔，不带空格）。例如，将此标志设置为：

--log_request_headers=foo,bar

如果请求中有“foo”和“bar”标头的值，则 Endpoints 日志包含：

request_headers: foo=foo_value;bar=bar_value

--log_response_headers

记录所指定响应标头的值（以英文逗号分隔，不带空格）。例如，将此标志设置为：

--log_response_headers=baz,bing

如果响应中有“baz”和“bing”标头的值，则 Endpoints 日志包含：

response_headers: baz=baz_value;bing=bing_value

--log_jwt_payloads

记录所指定 JWT 载荷原初字段的值（以英文逗号分隔，不带空格）。例如，将此标志设置为：

--log_jwt_payload=sub,project_id,foo.foo_name

如果 JWT 载荷中有这些值，则 Endpoints 日志包含：

jwt_payloads: sub=sub_value;project_id=project_id_value; foo.foo_name=foo.foo_name_value

JWT 载荷中的值必须是原初字段（字符串、整数）。系统不会记录 JSON 对象和数组。
--access_log

如果指定，则为访问日志条目将要写入的本地文件的路径。
--access_log_format

用于指定访问日志格式的字符串格式。如果未设置，则会使用 >默认格式字符串。如需详细了解格式语法，请参阅格式字符串参考。

跟踪

使用这些标志配置发送到 Stackdriver 的 ESPv2 跟踪数据。只有在启用跟踪功能后，这些标志才适用。

标志 说明
--disable_tracing

停用跟踪功能。默认情况下，系统会启用跟踪功能。

启用后，ESPv2 每秒会对发送至 API 的请求进行少量采样，以获取其发送至 Stackdriver Trace 的跟踪记录。默认情况下，对 1000 个请求中的 1 个进行采样。使用 --tracing_sample_rate 标志更改采样率。
--tracing_project_id

Stackdriver 跟踪的 Google 项目 ID。

跟踪是一项付费服务。系统将向所指定的项目收取跟踪费用。

默认情况下，系统会对已部署的 ESPv2 服务的项目 ID 计费。

通过在启动时调用 Google Cloud 实例元数据服务器来确定项目 ID。如果 ESPv2 部署在 Google Cloud 外部（使用 --non_gcp 标志），则除非您明确设置此标志，否则系统会自动停用跟踪记录。
--tracing_sample_rate

将跟踪记录采样率设置为 0.0 到 1.0 之间的值。此值用于指定所采样请求的比例。

默认值为 0.001，相当于 1000 个请求中的 1 个。
--tracing_incoming_context

此标志指定要在哪些 HTTP 标头中检查跟踪上下文，标志值以英文逗号分隔，不带空格。 请注意，顺序很重要：跟踪记录上下文将从匹配的第一个标头派生。

可能的值包括 traceparent、x-cloud-trace-context 和 grpc-trace-bin。

如果省略，则系统会按顺序检查 traceparent 和 x-cloud-trace-context 标头。

如需了解详情，请参阅跟踪 API。
--tracing_outgoing_context

在发送到后端服务的请求中设置 trace context 标头。

此标志指定要设置的 HTTP 标头，标志值由英文逗号分隔，不带空格。

可能的值包括 traceparent、x-cloud-trace-context 和 grpc-trace-bin。

如果省略，则系统将发送 traceparent 和 x-cloud-trace-context 标头。

如需了解详情，请参阅跟踪 API。

健康检查

使用以下标志为 ESPv2 配置健康检查。第一个标志可用于设置健康处理程序，以响应健康检查调用。其他标志可用于为 gRPC 后端启用健康检查。

/tbody>
标志 说明
-z, --healthz 定义健康检查端点。例如，-z healthz 会使 ESPv2 为路径 /healthz 返回代码 200。
--health_check_grpc_backend 启用 ESPv2 以定期检查由 --backend 标志指定的后端的 gRPC 健康服务。后端必须使用 gRPC 协议并实现 gRPC 健康检查协议。由标志 --healthz 启用的健康检查端点将反映后端健康检查结果。
--health_check_grpc_backend_service 在调用后端 gRPC 健康检查协议时指定服务名称。只有在使用 --health_check_grpc_backend 标志时才会应用此标志的值。此标志是可选标志，如果未设置，则默认值为空。服务名称为空是查询 gRPC 服务器的整体健康状况。
--health_check_grpc_backend_interval 在调用后端 gRPC 健康服务时，指定检查间隔和请求超时。只有在使用 --health_check_grpc_backend 标志时才会应用此标志的值。默认值为 1 秒。接受的格式是一系列十进制数字，每个数字都包含一个可选的小数和单位后缀，例如“5s”、“100ms”或“2m”。有效的时间单位包括“m”（表示分钟）、“s”（表示秒）、“ms”（表示毫秒）。

调试

使用这些标志为 ESPv2 配置调试。这些标志可用于设置 Envoy 管理端口以提取配置和统计信息，或在调试模式下运行 Envoy 以将调试级别信息写入日志。

标志 说明
--status_port、--admin_port 在此端口上启用 ESPv2 Envoy 管理。如需了解详情，请参阅 Envoy 管理接口参考。管理端口默认处于停用状态。
--enable_debug 启用调试级别日志并添加调试标头。

非 Google Cloud 部署

如果在非 Google Cloud 环境中部署 ESPv2，则可能需要以下标志。

标志 说明
--service_account_key

指定用于访问 Google 服务的服务账号密钥 JSON 文件。如果省略此选项，代理会与 Google Cloud 元数据服务器联系以获取访问令牌。
--dns_resolver_addresses DNS 解析器的地址。每个地址应采用 IP_ADDR 或 IP_ADDR:PORT 格式，并使用英文分号 (;) 分隔。IP_ADDR 将使用默认 DNS 端口 52。例如：--dns_resolver_addresses=127.0.0.1;127.0.0.2;127.0.0.3:8000)。如果未设置，ESPv2 将使用 /etc/resolv.conf 中配置的默认解析器
--backend_dns_lookup_family 定义所有后端的 DNS 查找系列。选项包括 auto、v4only、v6only、v4preferred 和 all。默认值为 v4preferred。请注意，auto 是旧版值。将该标志设置为 auto 会导致行为与 v6preferred 等效。
--non_gcp 默认情况下，代理会尝试连接到 Google Cloud 元数据服务器，以在前几个请求中获取虚拟机位置。如需跳过此步骤，请将此标志设置为 true。

本地测试

可以在工作站上本地部署 ESPv2 以进行测试。如需了解详情，请参阅在本地或其他平台上运行 ESP。

将这些标志与非 Google Cloud 部署标志搭配使用，以便在持续集成中更轻松地进行本地部署和测试。

标志 说明
--service_json_path

指定 ESPv2 的路径以加载端点服务配置。借助此标志，ESPv2 将使用“固定”发布策略，并且以下标志将被忽略：

  • --service
  • --version
  • --rollout_strategy

此标志会阻止 ESPv2 使用 Service Management API 配额。
--enable_backend_address_override

可以使用 --backend 标志或服务配置中的 backend.rule.address 字段指定后端地址。对于 OpenAPI 用户，请注意 backend.rule.address 字段通过 x-google-backend 扩展中的 address 字段设置。

您通常会为无服务器路由指定服务配置每项操作 backend.rule.address。默认情况下，backend.rule.address 优先于每项操作的 --backend 标记。

如果您希望改为 --backend 标志优先，请启用此标志。如果您在本地工作站上进行开发，这会非常有用。然后，您可以使用同一生产服务配置，但通过 --backend 标志替换后端地址以用于本地测试。

注意：只有地址会被覆盖。backend.rule 的所有其他组成部分仍将适用（截止时间、后端身份验证、路径转换等）。

客户端 IP 提取

使用这些标志为 ESPv2 配置客户端 IP 提取。

标志 说明
--envoy_use_remote_address

Envoy HttpConnectionManager 配置，请参阅 Envoy 参考了解详情。默认为 off。

--envoy_xff_num_trusted_hops Envoy HttpConnectionManager 配置，请参阅 Envoy 参考了解详情。默认值为 2。

CORS 支持

如需了解可用的 CORS 支持选项的说明，请参阅支持 CORS。本部分介绍如何使用 ESPv2 启动标志来支持 CORS。

如需在 ESPv2 中启用 CORS 支持，请添加 --cors_preset 选项，并设置以下标志之一：

  • --cors_preset=basic
  • --cors_preset=cors_with_regex

如果您添加 --cors_preset=basic 或 --cors_preset=cors_with_regex，ESPv2 将：

  • 假定所有位置路径都具有相同的 CORS 政策。
  • 同时响应简单请求和预检 HTTP OPTIONS 请求。
  • 最多可将预检 OPTIONS 请求的结果缓存 20 天（1728000 秒）。

  • 将响应标头设置为以下值：

    Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization
Access-Control-Expose-Headers: Content-Length,Content-Range
Access-Control-Max-Age: 1728000

如需替换 Access-Control-Allow-Origin 的默认值，请指定以下其中一个选项：

选项 说明
--cors_allow_origin 与 --cors_preset=basic 配合使用可将 Access-Control-Allow-Origin 设置为特定的来源。
示例：
--cors_preset=basic
--cors_allow_origin=http://example.com
--cors_allow_origin_regex 与 --cors_preset=cors_with_regex 配合使用。可让您通过正则表达式来设置 Access-Control-Allow-Origin。
示例：
--cors_preset=cors_with_regex
--cors_allow_origin_regex=^https?://.+\.example\.com$

上述示例中的正则表达式允许 http 或 https 的来源以及 example.com 的任何子网域。

在 Kubernetes 配置文件中设置此选项时，您需要添加额外的反斜杠字符以对字符串中出现的两个 \ 进行转义，例如：

"--cors_preset","cors_with_regex",
"--cors_allow_origin_regex","^https?://.+\\.example\\.com$"

在 Cloud Run 的 gcloud_build_image 脚本中设置此选项时，请避免使用转义字符和反斜杠，因为在启动时，它们可能无法从 bash 脚本正确传递到代理。请使用字符类而非元序列。例如： Original: \d Recommended: [0-9]

设置 --cors_preset=basic 或 --cors_preset=cors_with_regex 以启用 CORS 后，您可以通过指定以下一个或多个选项来替换其他响应标头的默认值：

选项 说明
--cors_allow_methods 将 Access-Control-Allow-Methods 设置为指定的 HTTP 方法。将 HTTP 方法指定为字符串，并用英文逗号分隔各个 HTTP 方法。
示例：
--cors_preset=basic
--cors_allow_methods=GET,POST,PUT,OPTIONS
--cors_allow_headers 将 Access-Control-Allow-Headers 设置为指定的 HTTP 标头。将 HTTP 标头指定为字符串，并用英文逗号分隔各个 HTTP 标头。
示例：
--cors_preset=basic
--cors_allow_headers=Origin,Content-Type,Accept
--cors_allow_credentials 在响应中加入 Access-Control-Allow-Credentials 标头并将其值设置为 true。默认情况下，响应中不会包含 Access-Control-Allow-Credentials 标头。
示例：
--cors_preset=basic
--cors_allow_credentials
--cors_expose_headers 将 Access-Control-Expose-Headers 设置为指定的标头。指定哪些标头可以字符串形式公开显示在响应中，并用英文逗号分隔各个标头。
示例：
--cors_preset=basic
--cors_expose_headers=Content-Length
--cors_max_age 将 Access-Control-Max-Age 设置为指定的时长。可接受的格式是一系列十进制数字，每个数字都有一个可选的小数值和单位后缀，例如“300m”、“1.5h”或“2h45m”。有效时间单位为“m”（分钟）、“h”（小时）。如果未设置，则默认值为“480h”。
示例：
--cors_preset=basic
--cors_max_age=24h

TLS 支持

使用这些标志配置 ESPv2 以使用 TLS 连接。

标志 说明
--ssl_server_cert_path 代理的服务器证书路径。配置后，ESPv2 仅接受 listener_port 上的 HTTP/1.x 和 HTTP/2 安全连接。此路径中需要证书和密钥文件“server.crt”和“server.key”。
--ssl_server_cipher_suites 要用于下游连接的加密套件，以用英文逗号分隔的列表的形式指定。请参阅加密套件配置。
--ssl_backend_client_cert_path 代理的客户端证书路径。配置后，ESPv2 会为 HTTPS 后端启用 TLS 双向身份验证。此路径中需要证书和密钥文件“client.crt”和“client.key”。
--ssl_backend_client_root_certs_file ESPv2 用来验证后端服务器证书的根证书的文件路径。如果未指定，ESPv2 默认使用“/etc/ssl/certs/ca-certificates.crt”。
--ssl_backend_client_cipher_suites 要用于 HTTPS 后端的加密套件，以用逗号分隔的列表的形式指定。请参阅加密套件配置。
--ssl_minimum_protocol 客户端连接的最低 TLS 协议版本。请参阅此处
--ssl_maximum_protocol 客户端连接的最高 TLS 协议版本。请参阅此处
--enable_strict_transport_security 启用 HSTS（HTTP 严格传输安全协议）。值为“max-age=31536000; includeSubdomains;”的“Strict-Transport-Security”响应标头会添加到所有响应中。
--generate_self_signed_cert 在启动时生成自签名证书和密钥，然后将其存储在“/tmp/ssl/endpoints/server.crt”和“/tmp/ssl/endpoints/server.key”中。如果只需要一个随机的自签名证书来处理 HTTPS 请求，这将非常有用。生成的证书的通用名称为“localhost”，有效期为 10 年。

超时和重试

使用这些标志为 ESPv2 配置远程 HTTP 调用超时和重试。

标志 说明
--http_request_timeout_s

设置向外部服务（后端和 Google Service Control 除外）发出的请求的超时，以秒为单位。它包括 Google ServiceManagement、元数据服务器和 Google IAM 服务器。必须大于 0，如果未设置，则默认为 30 秒。

--service_control_network_fail_open

在连接 Google Service Control 时发生网络故障的情况下，如果此标志处于启用状态，则允许请求。默认为 on。

--service_control_check_timeout_ms 设置 Service Control Check 请求的超时（以毫秒为单位）。必须大于 0，如果未设置，则默认为 1000。
--service_control_report_timeout_ms 设置 Service Control Report 请求的超时（以毫秒为单位）。必须大于 0，如果未设置，则默认为 1000。
--service_control_quota_timeout_ms 设置 Service Control Quota 请求的超时（以毫秒为单位）。必须大于 0，如果未设置，则默认为 1000。
--service_control_check_retries 设置 Service Control Check 请求的重试次数。必须大于等于 0，如果未设置，则默认为 3。
--service_control_report_retries 设置 Service Control Report 请求的重试次数。必须大于等于 0，如果未设置，则默认为 5。
--service_control_quota_retries 设置 Service Control Quota 请求的重试次数。必须大于等于 0，如果未设置，则默认为 1。
--backend_retry_ons

ESPv2 在后端重试的条件。可采用以英文逗号分隔的列表指定一个或多个 retryOn 条件。默认值为 reset,connect-failure,refused-stream。 将此标志留空，以停用重试功能。

有关接受的条件，请参阅以下链接：
--backend_retry_num 允许的重试次数。必须大于等于 0，默认为 1。

gRPC 转码

使用这些标志配置 ESPv2，以将 HTTP/JSON 转码为 gRPC。

标志 说明
--transcoding_always_print_primitive_fields

指定是否输出 grpc-json 转码的原初字段。默认情况下，JSON 输出中将省略具有默认值的原初字段。例如，设置为 0 的 int32 字段将被省略。如果将此标志设置为 true，系统将覆盖默认行为并输出原初字段（无论其值为何）。默认值为 false。
--transcoding_always_print_enums_as_ints

指定是否将 grpc-json 转码的枚举输出为整数。默认情况下，它们呈现为字符串。默认值为 false。
--transcoding_stream_newline_delimited

如果为 true，则使用换行分隔符来分隔响应流式传输消息。如果为 false，所有响应流式传输消息都会转码为 JSON 数组。

--transcoding_case_insensitive_enum_parsing

通常，在 JSON 中使用原生枚举值时，应使用大写形式。 如果您的 JSON 请求使用非大写枚举值，请将此标志设置为 true。

--transcoding_preserve_proto_field_names

指定是否保留 grpc-json 转码的原型字段名称。默认情况下，protobuf 将按顺序使用 json_name 选项或小驼峰式命名法生成 JSON 字段名称。设置此标志将保留原始字段名称。默认值为 false。
--transcoding_ignore_query_parameters

grpc-json 转码中转码方法映射要忽略的查询参数列表（以英文逗号分隔）。默认情况下，转码器过滤器不会对具有未知/无效查询参数的请求进行转码。
--transcoding_ignore_unknown_query_parameters

指定是否忽略在 grpc-json 转码中无法映射到相应 protobuf 字段的查询参数。如果您无法控制查询参数，并且事先不知道这些参数，请使用此方法。否则，请使用 --transcoding_ignore_query_parameters。默认值为 false。
--transcoding_query_parameters_disable_unescape_plus

默认情况下，在 grpc-json 转码中，查询参数中的加号 "+" 不会转义为空格 " "。这是为了支持 HTML 2.0。如果不需要，请将此标志设置为 true 以停用此功能。

请求和响应修改

使用这些标志将 ESPv2 配置为部分修改请求和响应。

标志 说明
--add_request_header

在将请求发送到上游后端之前，为该请求添加 HTTP 标头。如果标头已在请求中，系统会将它的值替换为新的标头。

它支持 Envoy 自定义变量。

此参数可以重复多次以指定多个标头。例如：
--add_request_header=key1=value1
--add_request_header=key2=value2
--append_request_header

在将请求发送到上游后端之前，为该请求附加 HTTP 标头。如果请求中已经包含标头，将附加新值。

它支持 Envoy 自定义变量。

此参数可以重复多次以指定多个标头。例如：
--append_request_header=key1=value1
--append_request_header=key2=value2
--add_response_header

在将响应发送到下游客户端之前，为响应添加 HTTP 标头。如果标头已存在于响应中，系统会将它替换为新的标头。

它支持 Envoy 自定义变量。

此参数可以重复多次以指定多个标头。例如：
--add_response_header=key1=value1
--add_response_header=key2=value2
--append_response_header

在将响应发送到下游客户端之前，为响应附加 HTTP 标头。如果标头已存在于响应中，系统将附加新的标头。

它支持 Envoy 自定义变量。

此参数可以重复多次以指定多个标头。例如：
--append_response_header=key1=value1
--append_response_header=key2=value2

安全选项

使用这些标志可进一步优化 ESPv2 允许的请求。

标志 说明
--underscores_in_headers

允许标头名称包含要传递的下划线。默认值为 false。

header-7230 允许在标头名称中使用下划线字符。不过，此行为是作为安全措施实施的，因为某些系统将 _ 和 - 视为可互换。
--envoy_connection_buffer_limit_bytes

配置为每个请求/响应正文缓冲的最大数据量（以字节为单位）。如果未设置，则由 Envoy 确定默认值。请参阅 Envoy 的监听器配置。
--disable_normalize_path

根据 RFC 3986 停用 path HTTP 标头的标准化。如果您的后端默认执行路径规范化，我们建议保留此选项。

下表提供了基于此标志的配置，后端将从 ESPv2 接收的请求 path 的示例。

        -----------------------------------------------------------------
        | Request Path     | Without Normalization | With Normalization |
        -----------------------------------------------------------------
        | /hello/../world  | Rejected              | /world             |
        | /%4A             | /%4A                  | /J                 |
        | /%4a             | /%4a                  | /J                 |
        -----------------------------------------------------------------

默认情况下，ESPv2 将对路径进行规范化。仅当您的流量受该行为影响时，您才能停用此功能。

注意：遵循 RFC 3986，此选项不会取消百分号编码的斜杠字符转义。如需启用此不合规行为，请参阅 --disallow_escaped_slashes_in_path 标志。

注意：即使启用了此选项，也不支持 RFC 3986 标准中的案例规范化。

如需了解详情，请参阅了解路径模板化。
--disable_merge_slashes_in_path

禁止在 path HTTP 标头中合并相邻的斜杠。如果您的后端默认执行合并，我们建议您启用此选项。

下表提供了基于此标志的配置，后端将从 ESPv2 接收的请求 path 的示例。

        -----------------------------------------------------------------
        | Request Path     | Without Normalization | With Normalization |
        -----------------------------------------------------------------
        | /hello//world    | Rejected              | /hello/world       |
        | /hello///        | Rejected              | /hello             |
        -----------------------------------------------------------------

默认情况下，ESPv2 将会合并斜杠。仅当您的流量受该行为影响时，您才能停用此功能。

如需了解详情，请参阅了解路径模板化。
--disallow_escaped_slashes_in_path

不允许含有百分号编码的转义斜杠字符的请求：

  • %2F 或 %2f 会被视为 /
  • %5C 或 %5c 会被视为 \

启用后，行为取决于所使用的协议：

  • 对于 OpenAPI 后端，含有百分号编码的转义斜杠的请求路径将通过重定向自动取消转义。
  • 对于 gRPC 后端，系统会拒绝含有百分号编码的转义斜杠的请求路径（gRPC 不支持重定向）。

此选项不符合 RFC 3986 标准，因此默认情况下处于关闭状态。如果您的后端不符合 RFC 3986 标准并且对斜杠进行了转义，则必须在 ESPv2 中启用此选项。这样可以防止因强制实施安全要求而导致的路径混乱攻击。

如需了解详情，请参阅了解路径模板化。

JWT 身份验证

使用以下标志将 ESPv2 配置为通过重试提取远程 Jwks。

标志 说明
--jwks_fetch_num_retries

在远程 JWKS 提取重试政策中指定重试次数。默认值为 0，不重试。
--jwks_fetch_retry_back_off_base_interval_ms

指定 JWKS 提取重试指数退避算法的基准间隔（以毫秒为单位）。如未设置，默认值为 200 毫秒。
--jwks_fetch_retry_back_off_max_interval_ms

指定 JWKS 提取重试指数退避算法的最长间隔（以毫秒为单位）。如未设置，则默认值为 32 秒。
--jwks_cache_duration_in_s

指定 JWT 公钥缓存时长（以秒为单位）。如果未设置，则默认值为 5 分钟。

--jwks_async_fetch_fast_listener

仅在未设置 --disable_jwks_async_fetch 标志时适用。 此标志用于确定 ESPv2 是否会等待初始 jwks 提取完成，然后再绑定监听器端口。如果为 false，则会等待。 默认值为 false。

--jwt_cache_size

将唯一 JWT 令牌的数量指定为 JWT 缓存大小上限。 缓存仅存储经过验证的令牌。如果为 0，则 JWT 缓存处于停用状态。 此标志会限制 JWT 缓存的内存用量。缓存使用的内存大致为每个令牌的（令牌大小 + 64 字节）。 如果未指定，默认值为 100000。

--disable_jwt_audience_service_name_check

通常，系统会根据 OpenAPI x-google-audiences 字段中指定的受众群体检查 JWT aud 字段。此标志会更改未指定 x-google-audiences 字段时的行为。 如果未指定 x-google-audiences 字段且未使用此标志，系统会使用服务名称检查 JWT aud 字段。 如果使用此标志，系统将不会检查 JWT aud 字段。

后续步骤

了解：