快速入门

设置 Cloudflare Mesh，以便您的设备和服务器可以通过私有 IP 相互访问。

• 一个 Cloudflare 账户 ↗

• 一个具有有效订阅（包括 Free 套餐）的 Zero Trust 组织

• 一台作为客户端设备连接的笔记本电脑或手机

• （可选）一台用于部署 Mesh 节点的 Linux 服务器

  Linux 服务器要求

  OS 版本	RHEL 9 1、RHEL 10、Debian 12、Debian 13、Fedora 43、Fedora 44、Ubuntu 22.04 LTS、Ubuntu 24.04 LTS、Ubuntu 26.04 LTS
  处理器	AMD64 / x86-64 或 ARM64 / AArch64
  vCPU	最低 3 个，推荐 4 个
  无桌面环境的 RAM	最低 1 GB，推荐 2 GB（例如 Ubuntu Server）
  带桌面环境的 RAM	最低 4 GB，推荐 8 GB（例如 Ubuntu GNOME）
  磁盘空间	最低 250 MiB，推荐 500 MiB
  网络接口类型	Wi-Fi 或 LAN
  MTU	建议 1381 字节 2

  Footnotes

  1. 在 RHEL 9 及更高版本上，安装 cloudflare-warp 之前，请启用 Extra Packages for Enterprise Linux (EPEL) ↗ 仓库。EPEL 提供 client UI 所需的依赖项。有关 RHEL 命令，请参阅 EPEL 快速入门 ↗。 ↩

  2. 启用 路径 MTU 发现 时最低 1281 字节 ↩

Cloudflare Mesh 要求将 Mesh 节点的设备配置文件配置为使用 MASQUE。如果设备配置文件改用 WireGuard，主机名路由、IPv6 CIDR 路由和高可用性将无法工作。

根据希望连接的对象选择注册方式：

选择仪表板向导，或使用 API 和 Terraform 资源。

set -euo pipefail

PROFILE_RESPONSE=$(
    curl --fail-with-body --silent --show-error \
        "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/devices/policy" \
        --request POST \
        --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
        --header "Content-Type: application/json" \
        --data "$(jq -n \
            --arg match "identity.email == \"warp_connector@$TEAM_NAME.cloudflareaccess.com\"" \
            '{
                name: "Cloudflare Mesh nodes",
                description: "Route Mesh IP traffic through Cloudflare",
                enabled: true,
                precedence: 100,
                match: $match,
                service_mode_v2: {mode: "warp"},
                tunnel_protocol: "masque",
                include: [{address: "100.96.0.0/12", description: "Cloudflare Mesh IPs"}]
            }')"
)

jq -e '.success == true and (.result.id | type == "string")' \
    <<< "$PROFILE_RESPONSE" > /dev/null
PROFILE_ID=$(jq -r '.result.id' <<< "$PROFILE_RESPONSE")

set -euo pipefail

NODE_RESPONSE=$(
    curl --fail-with-body --silent --show-error \
        "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/warp_connector" \
        --request POST \
        --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
        --header "Content-Type: application/json" \
        --data '{"name":"web-server"}'
)

jq -e '.success == true and (.result.id | type == "string")' \
    <<< "$NODE_RESPONSE" > /dev/null
NODE_ID=$(jq -r '.result.id' <<< "$NODE_RESPONSE")

TOKEN_RESPONSE=$(
    curl --fail-with-body --silent --show-error \
        "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/warp_connector/$NODE_ID/token" \
        --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
)

MESH_NODE_TOKEN=$(jq -er \
    'select(.success == true) | .result | select(type == "string" and length > 0)' \
    <<< "$TOKEN_RESPONSE")

printf 'net.ipv4.ip_forward = 1\nnet.ipv6.conf.all.forwarding = 1\nnet.ipv6.conf.all.accept_ra = 2\n' | sudo tee /etc/sysctl.d/99-zzz-cloudflare-warp-connector.conf &&
sudo sysctl --system

curl -fsSL https://pkg.cloudflareclient.com/pubkey.gpg | sudo gpg --yes --dearmor -o /usr/share/keyrings/cloudflare-warp-archive-keyring.gpg &&
echo "deb [signed-by=/usr/share/keyrings/cloudflare-warp-archive-keyring.gpg] https://pkg.cloudflareclient.com/ $(. /etc/os-release && echo $VERSION_CODENAME) main" | sudo tee /etc/apt/sources.list.d/cloudflare-client.list &&
sudo apt-get update -qq && sudo apt-get install -y -qq cloudflare-warp

sudo warp-cli --accept-tos connector new <TOKEN> && sudo warp-cli --accept-tos connect

sudo subscription-manager repos --enable codeready-builder-for-rhel-$(rpm -E %rhel)-$(arch)-rpms &&
sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-$(rpm -E %rhel).noarch.rpm

curl -fsSL https://pkg.cloudflareclient.com/cloudflare-warp-ascii.repo | sudo tee /etc/yum.repos.d/cloudflare-warp.repo &&
sudo dnf install -y cloudflare-warp

sudo warp-cli --accept-tos connector new <TOKEN> && sudo warp-cli --accept-tos connect

使用添加设备流程，查找笔记本电脑或手机的 Cloudflare One Client 安装程序和组织名称：

该工作流不会注册设备或验证连接。Cloudflare One Client 显示 Connected 后，请按照连接两台设备中的说明测试连接。

从 Windows、macOS 或 Linux 客户端设备验证到 Mesh 节点或其他已注册设备的 TCP 连接。例如，测试 SSH：

nc -vz <MESH-IP> 22

Test-NetConnection <MESH-IP> -Port 22

将 <MESH-IP> 替换为 Mesh 概览页面中显示的 Mesh IP。将端口 22 替换为服务使用的端口。可以从移动浏览器测试 HTTP 服务。客户端已连接或连接器状态健康，并不代表已验证对等连接。请验证计划使用的应用协议。如果开启 ICMP Gateway 代理，还可以运行 ping <MESH-IP> 进行诊断检查。

Mesh 流量显示在 Gateway 网络日志中：由 Mesh 节点发送时，Mesh 显示为 Traffic Source（流量来源）；路由到 Mesh 节点时，显示为 Traffic Destination（流量目标）。客户端设备流量显示在已注册用户的身份下。

要查看会话级详情，请使用 Zero Trust 网络会话日志。Mesh 会话将 OnrampType 或 Offramp 报告为 MESH，DestinationReplicaID 标识高可用节点的哪个副本为会话提供服务。

对于新部署，仪表板向导会自动配置以下 Cloudflare One 设置。未使用向导的部署也必须配置相同设置：

对于自动化部署，设备配置文件文档包含 API 和 Terraform 示例。设置 service_mode_v2 = { mode = "warp" }，将通用示例中的 wireguard 协议替换为 tunnel_protocol = "masque"，并配置拆分隧道，将 100.96.0.0/12 通过 Cloudflare 路由。使用 identity.email == "warp_connector@<TEAM_NAME>.cloudflareaccess.com" 匹配 Mesh 节点，将此配置文件排在范围更广的配置文件之前。设备注册文档包含 Terraform 注册策略流程。

cloudflare_zero_trust_device_settings ↗ 资源支持唯一设备 IP，以及 TCP 和 UDP Gateway 代理：

resource "cloudflare_zero_trust_device_settings" "mesh" {
    account_id                        = var.cloudflare_account_id
    use_zt_virtual_ip                 = true
    gateway_proxy_enabled             = true
    gateway_udp_proxy_enabled         = true
}

Terraform 资源不会配置 Allow all Cloudflare One traffic to reach enrolled devices（允许所有 Cloudflare One 流量到达已注册设备） 或 ICMP Gateway 代理。连接参与者前，在仪表板中开启已注册设备可达性。只有需要 ping、traceroute 或其他基于 ICMP 的流程时，才开启 ICMP。

如果您的账户已经部署了 Cloudflare One，设置向导将不会覆盖您现有的配置。验证是否已启用以下设置以使 Mesh 正常工作：

• 设备注册 — 必须存在至少一个注册规则，以便设备和节点可以注册到您的账户。
• Mesh 节点的设备配置文件 — Mesh 节点需要一个设备配置文件，将 Mesh IP 范围（100.96.0.0/12）通过 Cloudflare 路由。在包含模式下，添加 Mesh 范围。在排除模式下，确认没有自定义或旧版条目包含 Mesh 范围。
• Mesh 连接性 — 在您的设备配置文件设置中，启用允许所有 Cloudflare One 流量到达已注册的设备。
• 唯一设备 IP — 启用为每个设备分配唯一 IP 地址，以便每个参与者都能获得一个可路由的 Mesh IP。
• 客户端模式 — Mesh 节点必须在流量和 DNS 模式下运行。不支持仅 DNS 或仅代理模式。
• 流量代理 — 为使用的协议开启 Gateway 代理。TCP 和 UDP 承载 Mesh 服务。ICMP 支持 ping 和 traceroute 等诊断工具。

• 节点显示为 Offline — 在服务器上，运行 warp-cli status。如果输出未显示 Status update: Connected：
  • 运行 warp-cli connect。
  • 如果您的私有网络使用防火墙限制互联网流量，请确保它允许 WARP 端口和 IP。
  • 查看您的 WARP 守护进程日志，了解有关连接失败原因的信息。
• client device 无法访问 Mesh IP — 验证 Split Tunnel 配置是否通过 Cloudflare 路由 Mesh IP 地址范围 (100.96.0.0/12)。有关详细信息，请参阅连接两台设备。
• Windows 防火墙阻止 Mesh 流量 — Windows 防火墙默认阻止来自 100.96.0.0/12 的入站流量。添加一条防火墙规则，允许针对您所需的协议和端口来自此范围的传入请求。

对于一般的客户端问题，请参阅对 Cloudflare One Client 进行故障排除。

对于无法访问的 Mesh IP、路由 subnet 和单向站点流量，请参阅排查 Cloudflare Mesh 连接问题。

• 连接两台设备 — 注册两台设备并验证它们之间的专用连接。
• 在 Linux 上运行 Mesh — 在 Debian、Ubuntu 或 RHEL 上安装 Mesh 节点，并逐条说明每个命令。
• 在 Docker / Kubernetes 中运行 — 将 Mesh 节点部署为 Docker 容器，用于 Docker Compose、Kubernetes 和 CI/CD 流水线。
• 添加路由 — 让节点后方的整个子网可访问（数据库、打印机和其他服务器）。
• 启用高可用性 — 运行多个副本，提升生产环境的韧性。
• 技巧与最佳实践 — 云 VPC 配置、客户端更新以及与 cloudflared 并行运行。