代理配置

使用 config.yaml 配置 Cloud Workload Security (CWS) 代理进程。首先参阅快速入门中的完整本地配置，然后根据此参考文档中的选项替换相关代码块。

两种 API 身份验证模式都可以与直接或链式出站连接以及任意缓存模式组合使用。

该文件必须包含三个顶层对象：

系统会拒绝未知设置，包括这些对象中的未知字段。仅包含一个对象的示例属于部分配置。请保留文件中的其他必需对象。

编辑配置后，请先验证再启动代理：

cws-proxy --config config.yaml --config-test

验证成功时会输出 CWS proxy configuration is valid。此检查会验证本地设置，但不会获取部署配置、验证凭据、连接 Redis，也不能证明监听器能够启动。

更改 config.yaml 或其进程环境后，请重启代理。仪表板策略更改则通过配置刷新加载。

cws 对象用于将代理连接到一个账户和一个部署。其设置如下：

请选择且仅选择一种身份验证模式。使用 API token 身份验证时，请省略 api_key_env 和 api_key_email。使用 Global API Key 身份验证时，请同时提供这两个密钥字段，并省略 api_token_env。请勿将未使用的身份验证字段设为 null。

请使用具有目标账户的 Cloud Workload Security Deployment 权限的 API token。要创建 token，请参阅创建代理 API token。

将 <ACCOUNT_ID> 和 <DEPLOYMENT_ID> 替换为你的资源 ID：

cws:
  api_base_url: "https://api.cloudflare.com/client/v4"
  api_poll_interval_secs: 30
  api_token_env: CWS_DEPLOYMENT_TOKEN
  account_id: "<ACCOUNT_ID>"
  deployment_id: "<DEPLOYMENT_ID>"

通过代理进程环境中的 CWS_DEPLOYMENT_TOKEN 提供 token。api_token_env 存储的是变量名称，而非其值。此凭据用于加载 CWS 配置。客户端仍需提供自己的云服务提供商凭据。

使用 Global API Key 身份验证时，请将整个 cws 对象替换为以下形式。替换邮箱和资源占位符：

cws:
  api_base_url: "https://api.cloudflare.com/client/v4"
  api_poll_interval_secs: 30
  api_key_env: CWS_GLOBAL_API_KEY
  api_key_email: "<ACCOUNT_EMAIL>"
  account_id: "<ACCOUNT_ID>"
  deployment_id: "<DEPLOYMENT_ID>"

通过代理进程环境中的 CWS_GLOBAL_API_KEY 提供密钥。

api_base_url、account_id 和 deployment_id 也接受完整的环境变量引用，例如 ${CWS_ACCOUNT_ID}。引用的变量必须存在且包含非空值。不支持嵌入式替换和 shell 表达式。

例如，将现有 cws 对象中的两个 ID 值替换为：

account_id: "${CWS_ACCOUNT_ID}"
deployment_id: "${CWS_DEPLOYMENT_ID}"

其他字符串仍按字面值处理。对于 api_token_env、api_key_env 和 Redis url_env，请直接使用变量名称，不要使用 ${...}。证书路径和 api_key_email 不会展开环境变量引用。

proxy 对象必须包含 logging、tls_interception 和 upstream。其监听器和日志记录选项如下：

如果客户端与代理位于同一主机或网络命名空间，请保留 127.0.0.1:8080。对于共享代理，请选择客户端可以访问的地址，并将网络访问限制为预期客户端。0.0.0.0 会监听所有 IPv4 接口，不能用作客户端的目标地址。

空的 logging: {} 会使用 JSON 格式和 INFO 级别。要使用便于人阅读的日志，请将 proxy.logging 替换为：

logging:
  format: text
  verbosity: INFO

有关日志事件、决策字段和脱敏指南，请参阅读取代理日志。

proxy.tls_interception 对象必须包含以下三项设置：

客户端信任的是 ca_cert，而不是私钥。有关 CA 创建和客户端设置，请参阅准备证书颁发机构。

路径相对于代理进程的工作目录解析，而非配置文件所在目录。如果这两个目录不同，请使用绝对路径。

如果网络会检查出站 TLS，请将其批准的 CA 证书添加到 extra_root_cas。每个文件仅读取其中的第一个证书，因此每个额外根证书都应使用单独的 PEM 文件。此设置不会配置客户端信任，也不会配置用于为拦截证书签名的 CA。

如果 CWS 必须通过另一个 HTTP 代理访问目标，请使用 proxy.upstream.proxy。这些设置适用于 CWS 代理进程，与客户端的 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 环境变量相互独立。

出站代理设置如下：

两个代理 URL 字段都接受 http:// 或 https://。字段决定目标流量的类型，URL 方案决定 CWS 是否使用 TLS 连接上游代理。例如，https_proxy: "http://proxy.example.com:8080" 会将端口 443 的流量通过 HTTP 代理转发。

请分别配置每种流量类型。仅设置 http_proxy 不会将端口 443 的流量通过该代理转发。对于相应类型的直接连接，请省略字段或将其设为 null。proxy.upstream.proxy: {} 会让两种类型都使用直接连接。

代理 URL 可以包含 Basic Auth 凭据。请通过你的密钥管理流程提供此类配置。不要将这些凭据与部署 API 凭据或客户端身份混淆。

将 proxy.upstream 替换为以下代码块，并替换为你的上游代理 URL 和 CA 路径：

upstream:
  proxy:
    http_proxy: "https://proxy.example.com:8443"
    https_proxy: "https://proxy.example.com:8443"
    ca_cert: /path/to/upstream-proxy-ca.pem
    no_proxy:
      - api.example.com
      - .internal.example.com
      - 192.0.2.10
      - 2001:db8::/32

ca_cert 用于建立对上游代理的信任。tls_interception.extra_root_cas 用于为出站目标证书建立额外信任。这两项设置适用于不同的连接。

no_proxy 支持以下规则类型：

主机名比较时不区分大小写。条目应为目标名称或地址，而非 URL 或 host:port 对。对于命名目标，请使用主机名规则，不要假设 CIDR 规则会解析其 DNS 名称。

例外规则会绕过额外的上游代理，但不会绕过 CWS 策略评估。域 ACL 和适用的请求策略仍会生效。

CWS 始终具有容量上限的进程本地内存缓存。Redis 可提供共享存储。不使用 Redis 时，缓存值仅对该进程可用，并会在进程退出时丢失。

请选择与你的 Redis 服务相匹配的连接模式：

这是快速入门中使用的配置：

redis:
  enabled: false

此模式下不会使用 Redis 连接和身份验证设置。内存缓存限制仍然适用。

将 redis 对象替换为：

redis:
  enabled: true
  url_env: CWS_REDIS_URL
  cluster_mode: false
  auth_type: basic

将 Redis 连接 URL 注入名为 CWS_REDIS_URL 的代理环境变量。URL 使用 redis:// 或 rediss://，并在需要时包含 Redis 用户名和密码。rediss:// 使用 TLS。

对于 Redis Cluster，请设置 cluster_mode: true。环境变量可以包含一个种子 URL，也可以包含以逗号分隔的多个种子 URL。每个种子都必须是完整 URL，且所有种子必须使用相同的方案。

将 redis 对象替换为以下形式。请填入你的复制组名称和 AWS 区域：

redis:
  enabled: true
  url_env: CWS_REDIS_URL
  cluster_mode: false
  auth_type: iam
  iam_cluster_name: "<REPLICATION_GROUP_NAME>"
  iam_region: "<AWS_REGION>"

对于 ElastiCache 集群，请设置 cluster_mode: true。连接 URL 必须使用 rediss://、包含 ElastiCache 用户名，并省略密码。所有种子 URL 必须使用相同的用户名。代理通过默认 AWS 凭据提供程序链获取 AWS 凭据，并生成 IAM 身份验证令牌。代理的 AWS 身份必须具有连接到该 ElastiCache 用户和复制组的权限。

启用 Redis 后，只有成功连接 Redis 才能启动。缺少连接变量、身份验证无效或连接重试耗尽都会导致启动失败。本地 --config-test 验证不会测试该连接。

redis 设置和默认值如下：

无论是否启用 Redis，这两项内存限制都适用。将 cache_item_size 设为零不会取消这些限制。

代理会在内部命名空间后追加 :。策略缓存键使用单独的、按账户和部署划分范围的命名空间 cws_data:<ACCOUNT_ID>:<DEPLOYMENT_ID>:。更改 redis.namespace 不会取代这种策略键隔离机制。