Cloudflare One 客户端

本指南帮助您诊断并解决 Cloudflare One Client（前身为 WARP）的常见问题。内容涵盖如何在桌面操作系统（包括 Windows、macOS 和 Linux）上对 Cloudflare One Client 进行故障排查。

1. 开始之前：前提条件、权限、版本控制和客户端基础知识。
2. 收集日志：通过 Cloudflare 仪表板（使用 DEX 远程捕获）或命令行界面（CLI）（warp-diag）。
3. 检查日志：状态、设置、配置文件 ID、split tunnel 配置及其他设置。
4. 修复常见配置错误：配置文件不匹配、split tunnel 问题、托管网络问题、用户组不匹配。
5. 提交支持工单：在穷尽所有故障排查选项后，如何提交工单。

• 您必须已完成 Zero Trust 入门流程并创建了 Zero Trust 组织。
• 您必须在终端用户设备上安装了 Cloudflare One Client。
• 您必须拥有能够在 Cloudflare 仪表板上访问日志的管理员权限角色。

许多故障排查问题都是由过时的客户端版本引起的。为获得最佳性能和兼容性，管理员应在尝试排查其他问题之前检查新版本并更新 Cloudflare One Client。

更新 Cloudflare One Client 后，请监测问题是否再次出现。如果问题持续存在，请继续阅读本故障排查指南。

1. 登录 Cloudflare 仪表板 ↗，转到 Zero Trust > Team & Resources（团队和资源） > Devices（设备） > Your devices（您的设备）。
2. 选择要调查的设备。
3. 在侧边菜单的 Client version 下查找设备的客户端版本。
4. 将设备版本与 Cloudflare One Client 最新版本进行比较。

了解 Cloudflare One Client 的架构、安装路径和模式，有助于更准确地诊断问题。

Cloudflare One Client 由以下部分组成：

• 图形用户界面 (GUI)：允许最终用户查看客户端 状态 并执行诸如开启或关闭 Cloudflare One Client 等操作的客户端界面。
• WARP 守护进程（或服务）：负责在您的设备上建立安全隧道（使用 WireGuard 或 MASQUE）并处理所有客户端功能的核心后台组件。

有关 Cloudflare One Client 如何与设备的操作系统交互以路由流量的更多信息，请参阅 客户端架构。

GUI 和守护进程（或服务）具有不同的名称，并存储在以下位置：

除了 Cloudflare One Client GUI 和守护进程之外，机器上还会 安装 warp-cli 和 warp-diag，并将其添加到系统路径中以供在任何终端会话中使用。

warp-diag 是一个命令行诊断工具，可从 Cloudflare One Client 收集日志、配置详细信息和连接数据，以帮助解决问题。

warp-cli 是用于管理和配置 Cloudflare One Client 的命令行界面 (CLI)，允许用户以编程方式进行连接、断开连接和调整设置。

Cloudflare One Client 以多种模式运行，每种模式具有不同的流量处理能力：

每种客户端模式提供一组不同的 Zero Trust 功能。

您可以通过两种方式收集诊断日志：Cloudflare 仪表板或 warp-diag 命令行界面（CLI）。

使用数字体验监控（DEX）的远程捕获功能，从 Cloudflare 仪表板远程收集客户端诊断日志。

设备必须主动连接到互联网才能运行远程捕获。

要从远程设备捕获数据：

1. 在 Cloudflare One ↗ 中，前往 DEX > Remote captures（远程捕获）。
2. 选择最多 10 台您要运行捕获的设备。设备必须已在您的 Zero Trust 组织中 注册。
3. 配置要运行的捕获类型。

   • Packet capture (PCAP)（分组捕获）：对 WARP 隧道之外的流量（默认网络接口）和 WARP 隧道之内的流量（虚拟接口）进行分组捕获。

   • Device diagnostics（设备诊断日志）：生成过去 96 小时的 Cloudflare One Client 诊断日志。要在您的 分流隧道配置 中包含针对所有 IP 和域的路由测试，请选择 Test all routes（测试所有路由）。

     You must select Device Diagnostic Logs. You can also choose to run a PCAP and reproduce the issue in the window the PCAP is running to gain further network insight. The scope of this troubleshooting covers only client diagnostic logs. If not choosing PCAPs, reproduce the issue right before running diagnostics.
4. 选择 Run diagnostics（运行诊断）。

DEX 现在将向配置的设备发送捕获请求。如果 Cloudflare One Client 已断开连接，则捕获将在 10 分钟后超时。

要查看捕获列表，请前往 Insights（洞察） > Digital experience（数字体验） > Diagnostics（诊断）。Status（状态） 列显示以下选项之一：

• Success（成功）：捕获已完成并可供下载。任何部分成功的捕获仍会上传到 Cloudflare。例如，可能会出现 PCAP 在主网络接口上成功但在 WARP 隧道接口上失败的情况。您可以 查看 PCAP 结果 以确定哪些 PCAP 成功或失败。
• Running（运行中）：正在设备上进行捕获。
• Pending Upload（等待上传）：捕获已完成，但尚未准备好供下载。
• Failed：捕获已超时或遇到错误。要重试捕获，请检查 Cloudflare One Client 版本和 连接状态，然后开始一个 新捕获。

1. 在 Cloudflare One ↗ 中，前往 DEX > Remote captures（远程捕获）。
2. 找到一次成功的捕获。
3. 选择三点菜单并选择 Download（下载）。

这将在您的本地计算机上下载一个名为 <capture-id>.zip 的 ZIP 文件。DEX 将根据我们的 日志保留策略 存储捕获数据。

获得诊断文件后，转到检查关键文件继续排查。

使用桌面的 warp-diag CLI 收集客户端诊断日志。

要在桌面设备上查看客户端日志：

获得诊断文件后，转到检查关键文件继续排查。

客户端诊断日志记录了应用所有 MDM 策略和其他软件设置后，设备上 Cloudflare One Client 的最终配置和状态。审查这些日志有助于识别配置错误或意外行为。

打开 warp-status.txt 文件，查看收集 warp-diag 时 Cloudflare One Client 的连接状态。已连接的 Cloudflare One Client 将显示为：

Ok(Connected)

如果 Cloudflare One Client 出现问题，错误将显示在设备上 Cloudflare One Client 的 GUI 中。请使用客户端错误文档来识别错误、其原因和解决方案。

检查客户端状态后，请查看设备上 Cloudflare One Client 的设置，确认是否已应用预期配置。打开 warp-settings.txt 文件以查看 Cloudflare One Client 设置。您需要检查设备已应用的设备配置文件和 split tunnel 配置。

在桌面找到客户端诊断日志，并打开 warp-settings.txt 文件。请查阅以下 warp-settings.txt 示例文件及其内容描述。

Merged configuration:
(derived)   Always On: true
(network policy)    Switch Locked: false # If false, does not allow the user to turn off the WARP toggle and disconnect the WARP client
(network policy)    Mode: WarpWithDnsOverHttps # The device's WARP mode, this mode is WARP with Gateway mode
(network policy)    WARP tunnel protocol: WireGuard
(default)   Disabled for Wifi: false
(default)   Disabled for Ethernet: false
(reg defaults)  Resolve via: 1xx0x1011xx000000000f0x00000x11.cloudflare-gateway.com @ [1xx.1xx.1x.1, 1x01:1x00:1x00::1xx1] # The SNI Cloudflare will use and the IP address for DNS-over-HTTPS (DoH) requests
(user set)  qlog logging: Enabled
(default)   Onboarding: true # If true, the user sees an onboarding prompt when they first install the WARP client
(network policy)    Exclude mode, with hosts/ips: # Split tunnel configuration
  1xx.1xx.1xx.1xx/25 (zoom)
...
  cname.user.net

(network policy)    Fallback domains: # Local domain fallback configuration
  intranet
...
  test
(not set)   Daemon Teams Auth: false
(network policy)    Disable Auto Fallback: false
(network policy)    Captive Portal: 180
(network policy)    Support URL: my-organizations-support-portal.com # Your organization's support portal or IT help desk
(user set)  Organization: Organization-Name
(network policy)    Allow Mode Switch: true  # The user is allowed to switch between WARP modes
(network policy)    Allow Updates: false # WARP client will not perform update checks
(network policy)    Allowed to Leave Org: true
(api defaults)  Known apple connectivity check IPs: xx.xxx.0.0/16;
(network policy)    LAN Access Settings: Allowed until reconnect on a /24 subnet # The maximum size of network that will be allowed when Access Lan is clicked.
(network policy)    Profile ID: 000000x1-00x1-1xx0-1xx1-11101x1axx11

查看 warp-settings.txt 中与故障排查相关字段的含义。

指 GUI 中连接切换开关的当前状态。在示例文件中，切换开关处于开启状态。

Always On: true

指锁定设备客户端开关，该开关允许用户使用客户端的连接切换并断开客户端。在示例文件中，值为 false，表示用户可以自行选择连接或断开连接。

Switch Locked: false

当锁定设备客户端开关启用（true）时，用户需要管理员覆盖代码才能临时断开其设备上的 Cloudflare One Client。

指设备正在使用的客户端模式。在示例文件中，客户端模式为 WarpWithDnsOverHttps，即流量和 DNS 模式。请参阅客户端模式对比矩阵，将 warp-settings.txt 文件中的值与模式名称进行匹配。

Mode: WarpWithDnsOverHttps

指您的 split tunnel 设置。在示例文件中，Cloudflare One Client 以排除模式运行，即除发往这些主机和 IP 的流量外，所有流量都将通过 WARP 隧道发送。主机 cname.user.net 和 IP 1xx.1xx.1xx.1xx/25 均被排除在 WARP 隧道之外。

Exclude mode, with hosts/ips:
  1xx.1xx.1xx.1xx/25 (zoom)
...
  cname.user.net

指您的本地域名回退设置。在示例文件中，Cloudflare One Client 将 intranet 列为不会发送到 Gateway 处理的域名，该域名将直接发送到已配置的回退服务器。

(network policy)    Fallback domains:
  intranet
...

指模式切换设置。在示例文件中，模式切换已启用（true），表示用户可以在流量和 DNS 模式和 Gateway with DNS-over-HTTPS（DoH）模式之间切换。

Allow Mode Switch: true

指允许更新设置。在示例文件中，允许更新设置为 false，表示用户在有新版 Cloudflare One Client 时不会收到更新通知，且无法在未经管理员批准的情况下更新客户端。

Allow Updates: false

Allowed to Leave Org

指允许设备离开组织设置。在示例文件中，值设置为 true，表示用户可以从您的 Zero Trust 组织注销。

Allowed to Leave Org: true

LAN Access Settings

指允许用户启用本地网络排除设置。启用后，允许用户通过从 WARP 隧道中排除检测到的本地子网，临时访问本地设备（如打印机）。此示例表明访问被允许至客户端下次重新连接，且仅适用于不超过 /24 的子网。

LAN Access Settings: Allowed until reconnect on a /24 subnet

Profile ID

指设备正在使用的设备配置文件。在此示例中，ID 为 000000x1-00x1-1xx0-1xx1-11101x1axx11。

Profile ID: 000000x1-00x1-1xx0-1xx1-11101x1axx11

要验证 Cloudflare One Client 是否已正确配置并正常工作，请检查以下内容：

1. 设备上是否应用了错误的配置文件 ID？
2. 设备上是否激活了错误的 split tunnel 配置？

配置文件 ID 是分配给 Cloudflare 仪表板中每个设备配置文件的唯一标识符，用于确定哪些配置设置适用于某台设备。

要检查已应用的设备配置文件是否为预期的设备配置文件：

1. 在 Cloudflare 仪表板 ↗中，转到 Zero Trust > Team & Resources（团队和资源） > Devices（设备） > Device profiles（设备配置文件） > General profiles（常规配置文件）。
2. 找到并选择该设备的预期设备配置文件。
3. 在 Profile details 下，将显示的 Profile ID 与 warp-settings.txt 文件中的 Profile ID 进行比较。

如果您的组织在 Cloudflare 仪表板中定义了多个设备配置文件，设备可能会因以下原因被匹配到非预期的配置文件：

• 配置文件优先级的配置方式。
• 托管网络问题（如果您使用的是托管网络）。
• 用户组不匹配。
• 缺少精确匹配规则。

Cloudflare One 客户端根据层次结构动态评估设备配置文件。当设备连接时，客户端自上而下检查在仪表板中显示的配置文件。客户端遵循首次匹配原则——一旦设备匹配了某个配置文件，客户端将停止评估，后续任何配置文件都无法覆盖该决定。

Default（默认） 配置文件始终位于列表底部。只有当设备不满足其上方列出的任何配置文件的条件时，它才会被应用。如果您将另一个自定义配置文件设为默认值，所有设置都将复制到 Default（默认） 配置文件中。

管理员可以创建多个配置文件，根据特定条件（例如用户身份、位置或操作系统）应用不同的设置。理解这种自上而下的评估顺序对于确保向设备应用正确的策略至关重要。

托管网络是您使用 TLS 端点定义的网络位置，例如实体办公室。Cloudflare One Client 会检查此 TLS 端点以确定其位置，并应用相应的设备配置文件。

如果托管网络配置错误或 TLS 端点无法访问，设备可能会回退到非预期的配置文件。

排查 Cloudflare One Client 的托管网络问题时：

1. 验证端点是否可达。

   Cloudflare One Client 连接到 TLS 端点以识别网络。如果端点宕机或无法访问，Cloudflare One Client 将无法检测到网络并应用错误的配置文件。

   要测试连接性并获取远程服务器的 SHA-256 指纹：

   openssl s_client -connect <private-server-IP>:443 < /dev/null 2> /dev/null | openssl x509 -noout -fingerprint -sha256 | tr -d :

   输出将类似于：

   SHA256 Fingerprint=DD4F4806C57A5BBAF1AA5B080F0541DA75DB468D0A1FE731310149500CCD8662

   如果端点宕机，您将收到 Could not find certificate from <stdin> 响应。

   如果您收到了返回的 SHA-256 指纹：

   1. 登录 Cloudflare 仪表板 ↗，转到 Zero Trust > Team & Resources（团队和资源） > Devices（设备） > Device profiles（设备配置文件）。
   2. 转到 Managed networks（托管网络） > Edit（编辑）。
   3. 比较仪表板中的 TLS Cert SHA-256 与终端中返回的指纹，确保两者匹配。

2. 对单个位置使用单个配置文件。

   为简化管理并防止错误，请避免为同一位置创建多个托管网络配置文件。例如，如果您在一个办公室有多个 TLS 端点，请将它们全部链接到单个设备配置文件。这可降低因配置错误导致设备匹配到非预期配置文件的风险。

如果用户遇到设备配置文件问题，可能是因为他们不属于正确的用户组。当组织未使用 SCIM 进行身份提供商（IdP）自动更新时，可能会发生这种情况。

要检查用户是否属于预期的组：

1. 登录 Cloudflare 仪表板 ↗，转到 Zero Trust > Team & Resources（团队和资源） > Devices（设备） > Your devices（您的设备）。
2. 选择该用户。
3. 在 User Registry Identity（用户注册表身份） 下，选择用户的姓名。
4. Get-identity endpoint 列出了用户所属的所有组。

如果用户最近被添加到某个组，他们需要更新其在 Cloudflare Zero Trust 中的组成员资格。可以通过登录重新认证端点来完成此操作。

若要手动刷新您的 Cloudflare Access 会话并从您的身份提供商 (IdP) 更新您的组信息，请在浏览器中访问以下 URL 并填写您的 团队名称：

https://<your-team-name>.cloudflareaccess.com/cdn-cgi/access/refresh-identity

重新进行身份验证会重置您的 会话持续时间 并从组织的 IdP 获取最新的组信息。

要修改设备配置文件的匹配规则，您需要编辑该设备配置文件。要编辑设备配置文件：

1. 在 Cloudflare 仪表板 ↗中，转到 Zero Trust > Team & Resources（团队和资源） > Devices（设备） > Device profiles（设备配置文件） > General profiles（常规配置文件）。

2. 找到您要更新的设备配置文件并选择 Configure（配置）。

3. 根据需要使用选择器来添加或调整匹配规则，并修改此配置文件的设备客户端设置。

4. 选择 Save profile（保存配置文件）。

新更新的设置可能需要多达 10 分钟才能传播到设备。

分流隧道可以配置为排除或包含 IP 地址或域，使其不通过 Cloudflare One Client（前身为 WARP）。此功能通常用于与 VPN 协同运行 Cloudflare One Client（在排除模式下），或提供对特定私有网络的访问（在包含模式下）。

由于分流隧道在网络级别控制 Gateway 的可见性，我们建议在向最终用户推出更新之前测试所有更改。

配置错误的 split tunnel 可能导致连接问题。

例如，如果您将模式设置为"排除 IP 和域名"并意外排除了某个应用程序所需的 IP 地址，该应用程序可能无法正常工作。同样，在"包含 IP 和域名"模式下，如果忘记包含必要的 IP 或域名，流量将绕过 Cloudflare One Client，您将失去对 Zero Trust 安全功能的访问权限。

下载客户端诊断日志后，检查您的配置是否按预期工作：

1. 打开 warp-settings.txt 文件，找到 Exclude mode, with hosts/ips: 或 Include mode, with hosts/ips:。

2. 登录 Cloudflare 仪表板 ↗，转到 Zero Trust > Team & Resources（团队和资源） > Devices（设备） > Device profiles（设备配置文件） > General profiles（常规配置文件）。

3. 找到并选择该设备的预期设备配置文件。

4. 选择 Edit（编辑）。

5. 找到 Split Tunnels 并记录您选择的模式 > 选择 Manage（管理）。

6. 将您在 Cloudflare 仪表板中配置的 IP/主机与 warp-settings.txt 中列出的 IP/主机进行交叉比对。

如果您的仪表板 split tunnel 配置与 warp-settings.txt 文件配置不匹配，您可能需要强制 Cloudflare One Client 更新其设置。

如果 warp-settings.txt 中的 split tunnel 配置与仪表板不匹配，您可以强制 Cloudflare One Client 获取最新设置。

可以通过指示终端用户断开并重新连接客户端，或重置其加密密钥来完成此操作。

两种方法都会使用最新配置更新客户端。

选项 A：断开并重新连接客户端

客户端在重新连接时将获取新设置。

选项 B：重置加密密钥

要在终端用户的桌面上重置加密密钥：

重置加密密钥会强制客户端重新建立其隧道并检索最新配置。

为了尽可能快地进行故障排除，请确保您的支持工单包含详尽的详细信息。您提供的上下文越多，识别和解决您问题的速度就越快。

为了确保在 联系支持人员 时能够高效解决问题，请在工单中包含尽可能多的相关细节：

• 上下文：简要描述场景或用例（例如，用户在哪里，他们试图做什么）。

• 重现步骤：描述您在故障排除过程中为重现该问题所采取的步骤。

• 时间戳：具体说明并包括问题发生的确切时间和时区。

• 故障排除尝试：概述已尝试解决问题的任何故障排除步骤或更改。

• 客户端诊断日志：包括您从仪表板或通过 CLI 下载的客户端诊断。

有关更多信息，请参阅完整的 Cloudflare One 客户端文档。