故障排除

诊断 Cloud Workload Security (CWS) 代理、客户端和策略问题。本指南涵盖快速入门中的代理设置。

使用以下各节定位症状并验证修复结果。从运行代理的终端或服务中读取日志。有关相关字段，请参阅读取代理日志。

代理在接受连接前退出。终端会报告配置、文件或监听器错误。

在不启动代理的情况下验证配置文件：

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

验证成功时会输出：

CWS proxy configuration is valid

更正报告的 YAML 或架构错误，然后重新验证。请使用代理配置中的 cws、proxy 和 redis 设置。系统会拒绝未知设置。

此检查会验证本地配置，但不会验证 API token、获取部署配置，也不能证明监听器能够启动。

代理需要证书颁发机构 (CA) 证书及其匹配的私钥。确认 proxy.tls_interception.ca_cert 和 ca_private_key 指向代理进程可读取的文件。如果从其他目录启动代理，请使用绝对路径。

检查 proxy.listen_addr 是否包含 IP 地址和端口，例如 127.0.0.1:8080。该地址必须在代理主机上可用，且端口未被其他进程占用。

如果找不到 cws-proxy，请确认在启动代理的环境中已成功安装软件包。检查已安装的命令是否位于该进程的 PATH 中。

如果操作系统无法执行该命令，请检查软件包是否兼容你的 Linux 发行版和 CPU 架构。有关软件包设置和可用命令检查，请参阅安装代理。

使用 cws-proxy --config config.yaml 启动代理。等待 remote_config_loaded 和 action_mapper_loaded 出现，然后重试客户端请求。如果配置加载失败，请参阅代理无法加载部署配置。

代理未达到 remote_config_loaded 状态。日志会报告凭据缺失、API 响应失败或配置获取重试。

cws.api_token_env 存储的是环境变量名称，而不是 token 值。对于快速入门中的设置，变量名称为 CWS_DEPLOYMENT_TOKEN。

在启动代理的终端中检查变量是否已设置，但不要输出 token：

if [ -n "${CWS_DEPLOYMENT_TOKEN:-}" ]; then
  printf '%s\n' "CWS_DEPLOYMENT_TOKEN is set"
else
  printf '%s\n' "CWS_DEPLOYMENT_TOKEN is not set or is empty"
fi

cws_api_token_missing 错误表示配置的变量缺失或为空。服务或容器必须在自己的进程环境中收到该变量。在客户端终端中设置变量不会将其设置到代理进程中。

此存在性检查不会验证 token 是否有效。更正代理进程环境后，请重启代理。

确认 cws.account_id 和 cws.deployment_id 指向预期部署。API token 必须具有该账户的 Cloud Workload Security Deployment 权限。

对于 401 或 403 API 响应，请检查 token 是否有效以及账户权限。对于 404，请检查账户和部署 ID，以及该部署是否仍然存在。请参阅创建代理 API token。

API 的 cws.api_base_url 请使用 https://api.cloudflare.com/client/v4。检查代理主机能否解析并连接该源站。根据日志中的连接、超时或证书错误定位失败的连接。

如果网络会检查传输层安全性 (TLS)，请通过 proxy.tls_interception.extra_root_cas 配置获准的信任根证书。客户端的 NODE_EXTRA_CA_CERTS 不会更改代理的出站信任设置。

本地配置验证不会验证已下载的部署包。如果 API 请求成功，但代理无法解析或编译配置，请向联系 Open Beta 团队提供代理版本和脱敏后的错误信息。

更改本地配置或进程环境后，请重启代理。重试客户端请求前，请确认 remote_config_loaded 和 action_mapper_loaded 已出现。启动时暂时性的配置获取失败可能会重试，但凭据缺失或配置无效则需要修正。

客户端报告连接被拒绝或证书验证错误，无法通过代理完成请求。

将客户端代理地址与 proxy.listen_addr 进行比较。在本地设置中，两者都使用 127.0.0.1:8080，且 HTTPS_PROXY 使用 http:// 方案：

export HTTP_PROXY="http://127.0.0.1:8080"
export HTTPS_PROXY="http://127.0.0.1:8080"

回环地址只能在同一主机或网络命名空间内访问代理。位于其他容器或主机中的客户端需要可访问的代理地址。重试前，请确认代理已完成启动。

请使用代理配置的 CA 文件。如果文件路径与 ca-cert.pem 和 ca-key.pem 不同，请替换为实际路径。

有关 CA 设置，请参阅准备证书颁发机构。

通过代理重试只读请求，例如验证防护策略中的托管域列表请求。确认连接和证书验证成功。HTTP 错误应另行通过请求收到意外的 403 响应进行诊断。

客户端成功完成了按防护规则应被阻止的请求。代理可能没有相应的请求记录，也可能记录了允许决策。

创建部署不会自动转发流量。确认客户端进程收到了预期代理设置。检查 NO_PROXY 和 no_proxy 是否绕过了目标源站。

对于文档所述的 cf 设置，请使用 Node.js 24.5 或更高版本。检查客户端终端中的版本：

node --version

启动客户端前设置 NODE_USE_ENV_PROXY=1。请参阅通过代理转发 CLI 流量。

仅有连接记录并不能证明 CWS 评估了 HTTP 请求。请检查是否存在请求决策记录。未分类的目标可能会作为原始隧道流量直接通过，而不进行请求策略评估。

将 cws.deployment_id 与你编辑的部署进行比较。验证从部署到策略的配置路径：

有关编辑流程，请参阅配置策略。配置刷新后，请检查 request.policy_sets，了解已评估的策略、其决策和 enforce 值。

启用了强制执行且返回 false 的策略会阻止匹配的请求。未启用强制执行的策略可以记录拒绝决策，但不会阻止请求。没有策略匹配时，将应用部署的 Default mode。对于策略评估错误，还请检查 On error action 和错误结果。

确认客户端发送的操作和请求正文符合 Rego 检查的预期。如果代理报告 request_body_inspection_skipped_too_large，则会跳过请求正文检查，且 input.http.request.body 为 null。依赖请求正文的检查可能因此得到不同结果。

如果筛选器依赖 Basic Auth 身份，请检查配置的凭据以及密钥是否过期或已轮换。请参阅管理流量范围。部署 API token 不会识别客户端身份，也不能替代客户端的云服务提供商凭据。

使用受控测试请求，一个应通过，另一个应失败。确认代理日志中记录了预期决策和已评估策略。对于空 R2 存储桶演练，请按照验证防护规则操作；如果阻止测试成功，还需恢复私有访问权限。

客户端收到 HTTP 403、CWS.Error 响应，或 CONNECT 请求被拒绝。

域访问控制列表 (ACL) 可以在请求策略评估前拒绝 CONNECT。请查找 domain_acl_denied_connect。检查附加到部署的 ACL 及其默认操作。

检查目标模式：example.com 表示精确匹配，而 .example.com 包含父域及其子域。请使用管理流量范围更正预期目标对应的条目。

ACL 的允许决策会放行连接，但不会绕过请求策略。

CWS.Error 表示 CWS 拒绝了请求。检查相关请求日志，了解拒绝原因和已评估的策略。如果匹配的策略拒绝请求，请将其 Rego 检查与请求进行比较。即使一项策略通过，另一项启用了强制执行的策略仍可能阻止请求。

如果没有策略匹配，请检查部署的 Default mode 和预期请求范围。如果发生评估错误，请检查错误以及部署的 On error action。使用配置策略更正相关配置或策略。

如果应用分类在策略评估前失败，日志可能会报告该失败，而非正常的策略决策。联系Open Beta 团队时，请附上该错误。

如果 request.outcome 为 allowed，且响应记录中的 upstream_status: 403，则表示云服务提供商拒绝了转发的请求。请检查客户端的提供商凭据、资源权限和提供商错误消息。

CWS 部署 token 用于加载代理配置，不会授予对云服务提供商资源的访问权限。

重试经过授权且位于范围内的请求。分别确认代理决策和提供商响应。仅凭 403 状态码无法确定请求被哪一层拒绝。

你保存了策略、策略集或部署更改，但后续请求的行为仍与之前相同。

确认正在运行的代理使用的是你编辑的账户和部署。等待 cws.api_poll_interval_secs 中配置的间隔后再测试，最短间隔为 30 秒。

查找 polling_remote_config 以及任何获取或准备失败记录。并非每次应用策略更改都会发出 remote_config_updated。请通过后续请求决策和已评估策略验证更改。

remote_config_fetch_failed_keeping_current 和 remote_config_prepare_failed_keeping_current 表示刷新失败。正在运行的代理会保留先前有效的部署配置。

如果获取失败，请检查 API 访问和连接。如果准备失败，请查看报告的配置错误；若问题仍然存在，请联系 Open Beta 团队。仅在仪表板中保存更改并不能证明代理已应用该更改。

更改本地配置文件或凭据环境后，请重启代理。配置轮询不会重新加载这些本地设置。

成功刷新或重启后，请重复受控策略测试。确认日志中的预期策略集、强制执行状态和请求决策。

响应包含 HTTP 503 和消息 Action Mapper application data is unavailable。响应也可能包含 x-cws-proxy-err: Action Mapper unavailable。

Action Mapper 会对 API 请求分类以进行策略评估。当代理无法使用完整且有效的应用数据集时，会拒绝经过检查的 HTTP 流量。成功加载部署配置并不能证明这些数据已就绪。

启动期间，查找 initial_action_mapper_fetch_failed、initial_action_mapper_load_failed 或 initial_action_mapper_incomplete。运行期间，检查 action_mapper_application_pending、action_mapper_poll_failed_keeping_current 以及任何 action_mapper_degraded_denied_connect 或 action_mapper_degraded_denied_request 事件。

根据报告的错误检查 API 连接和身份验证。代理会重试加载应用数据。如果验证失败持续发生，请向联系 Open Beta 团队提供脱敏后的日志摘录。

启动时，请确认 action_mapper_loaded 已出现。运行时失败后，请在 mapper 日志中确认恢复，并重试只读请求。该请求不应再返回 Action Mapper 不可用响应。其他无关的 503 应根据其自身错误和日志进行调查。

客户端收到 HTTP 421。代理日志中会出现 request_host_tunnel_mismatch。

检查请求 URL、Host 标头和 CONNECT 目标的主机及有效端口是否一致。检查客户端配置或中间代理是否覆盖目标或改写 Host。

配置客户端，使其始终发送预期目标。保留代理的目标检查。参考日志中的 request_authority、context_authority 和 tunnel_authority 字段定位不一致之处。

启动新的客户端连接并重试请求。确认不再产生 421 或 request_host_tunnel_mismatch，然后检查其策略决策和提供商响应。

仪表板报告加载或保存错误。策略或工作负载表单可能会报告筛选器或 Rego 输入无效。

确认仪表板使用的是包含你资源的账户。检查账户角色是否允许执行相应资源操作。代理的部署 token 与你的仪表板权限用途不同。

如果发生加载错误，请检查连接并重新加载页面。如果资源缺失，请确认所选账户中仍存在该资源。

更正显示的字段错误。筛选器必须使用受支持的 Wirefilter 字段和运算符。请求正文检查应使用 input.http.request.body 写入 Rego。

对于仪表板策略，请声明 policy. 下的包和布尔型 valid 规则。检查语法以及导入的库或元数据路径。请参阅配置策略和管理策略参考资源。

如果操作仍然失败，请在可能的情况下向联系 Open Beta 团队提供脱敏后的 API 错误代码和消息。保存失败不能视作配置已应用。

确认资源已成功保存并重新加载。对于策略更改，请等待配置刷新，并通过代理验证其效果。

快速入门中的配置使用 INFO 级别的 JSON 日志。请读取处理该请求的代理进程记录。若存在 cws.request_id，请结合时间戳关联各条记录。

对于已评估的 HTTP 请求，请检查以下事件和字段：

以 JSON 编码的日志值可能会被截断。截断的审计信息不包含完整策略列表。CONNECT 拒绝和策略评估前的失败可能会产生各自的事件。缺少常规请求记录本身并不能证明客户端绕过了代理。

如果问题仍然存在，请联系 Open Beta 团队，并提供：

• 故障发生时间和时区。
• 代理版本、操作系统和 CPU 架构。
• 客户端名称、版本和错误消息。
• 账户、部署以及相关策略或策略集 ID。
• 目标 API 操作以及预期结果和实际结果。
• 简短的脱敏日志摘录、cws.request_id 和可用的响应引用。

要获取代理版本，请运行：

cws-proxy --version

仅包含相关配置键。删除 API token、密码、私钥和包含凭据的标头。分享前请对 Cookie、敏感 URL、请求正文和元数据进行脱敏。即使代理已对部分字段脱敏，也请再次检查日志。