Cloudflare Spectrum 完全 API 指南REST 端点、Schema 与多语言 SDK 实战【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skillsCloudflare Spectrum 是运行在全球边缘节点上的 L4Layer 4反向代理为 SSH、游戏、数据库、MQTT、SMTP、RDP 等任意 TCP/UDP 协议的应用提供 DDoS 防护、源站 IP 隐藏与 Argo 智能路由加速。本文以skills/.curated/cloudflare-deploy技能中的 api.md 为骨架系统讲解 Spectrum 的 REST API 端点、请求/响应 Schema、TypeScript/Python/Go 三套 SDK 用法与分析 API并结合同目录下的 configuration.md、patterns.md 与 gotchas.md 对每个字段做源码级解读。读完本文你将能通过 API 或 SDK 完成 Spectrum 应用的创建、查询、更新、删除与指标采集并避开常见的配置陷阱。Spectrum 是什么什么时候该用它按照 README.md 的定义Cloudflare Spectrum 为任何基于 TCP 或 UDP 的应用提供安全与加速能力。它是一个运行在 Cloudflare 边缘节点上的全局 L4 反向代理可把 MQTT、邮件、文件传输、版本控制、游戏等非 HTTP 流量接入 Cloudflare从而隐藏源站并抵御 DDoS 攻击。何时使用 Spectrum当你的协议不是 HTTP/HTTPS 时HTTP 流量应使用 Cloudflare 的标准代理Spectrum 负责其余一切——SSH、游戏、数据库、MQTT、SMTP、RDP 及自定义协议。在技能总入口 SKILL.md 的Networking/Connectivity决策树中Spectrum 被明确标注为TCP/UDP 代理非 HTTP的对应产品。值得注意的是Spectrum 的能力受套餐限制README.md 给出的 Plan Capabilities 如下能力Pro/BusinessEnterpriseTCP 协议仅选定端口全部端口1-65535UDP 协议仅选定端口全部端口1-65535端口范围❌✅Argo Smart Routing✅✅IP Firewall✅✅Load balancer 源站✅✅这意味着是否支持端口范围、是否支持全端口协议直接取决于你的套餐等级在调用 API 前应先确认账号对应的套餐能力。REST API 端点全景api.md 给出了 Spectrum 的全部 REST 端点均挂在 Zone站点维度之下路径前缀为/zones/{zone_id}/spectrumGET /zones/{zone_id}/spectrum/apps # 列出应用 POST /zones/{zone_id}/spectrum/apps # 创建应用 GET /zones/{zone_id}/spectrum/apps/{app_id} # 获取单个应用 PUT /zones/{zone_id}/spectrum/apps/{app_id} # 更新应用 DELETE /zones/{zone_id}/spectrum/apps/{app_id} # 删除应用 GET /zones/{zone_id}/spectrum/analytics/aggregate/current GET /zones/{zone_id}/spectrum/analytics/events/bytime GET /zones/{zone_id}/spectrum/analytics/events/summary其中前五个端点是 Spectrum 应用的完整 CRUD 生命周期后三个是分析查询端点aggregate/current获取当前聚合指标如流量字节数、连接数events/bytime按时间维度展开的连接事件序列events/summary按维度汇总的事件统计。所有请求都需要在Authorization: Bearer $CLOUDFLARE_API_TOKEN头中携带 API Token见下文的 curl 示例。路径中的zone_id是 DNS 所在的站点 IDapp_id是 Spectrum 应用创建成功后返回的唯一标识。这套端点也是 terraform 与 pulumi 等 IaC 工具底层所调用的接口理解 REST 语义有助于读懂 Terraform 资源cloudflare_spectrum_application的每个属性。请求与响应 Schema 详解CreateSpectrumAppRequest创建请求创建应用的核心请求体如下api.md 用 TypeScript 接口给出了完整字段interface CreateSpectrumAppRequest { protocol: string; // tcp/22, udp/53 dns: { type: CNAME | ADDRESS; name: string; // ssh.example.com }; origin_direct?: string[]; // [tcp://192.0.2.1:22] origin_dns?: { name: string }; // {name: origin.example.com} origin_port?: number | { start: number; end: number }; proxy_protocol?: off | v1 | v2 | simple; ip_firewall?: boolean; tls?: off | flexible | full | strict; edge_ips?: { type: dynamic | static; connectivity: all | ipv4 | ipv6; }; traffic_type?: direct | http | https; argo_smart_routing?: boolean; }各字段在 configuration.md 中有对应的落地用法逐个说明如下protocol必填入口协议与端口格式为tcp/22、udp/53这类协议/端口组合Enterprise 套餐还支持端口范围写法如tcp/25565-25575。dns必填对外暴露的 DNS 记录。type: CNAME表示使用 CNAME 记录patterns.md 与 gotchas.md 都强调Spectrum 场景下 DNS 必须是 CNAME 而非 A/AAAAtype: ADDRESS表示直接指定地址name为公开域名如ssh.example.com。origin_direct与origin_dns二选一均可选源站指向方式。origin_direct是静态 IP 列表形如[tcp://192.0.2.1:22]origin_dns是源站主机名如db-primary.internal.example.comSpectrum 会动态解析 DNS。对应 configuration.md 中的Direct IP Origin与CNAME Origin两种源站类型。origin_port可选源站端口。可传单个数字如3306也可传{ start, end }范围对象以配合 Enterprise 的端口范围能力。proxy_protocol可选默认off代理协议版本用于把真实客户端 IP 透传给源站取值off | v1 | v2 | simple。其中v1适用于大多数 TCP 应用SSH、数据库v2适用于高性能 TCPsimple是 Cloudflare 专有的 UDP 格式。开启后源站必须能解析 PROXY 头否则应用行为会异常。ip_firewall可选是否对流量应用 Zone 级别的防火墙规则。置为true后Spectrum 流量会受站点 WAF/防火墙规则约束是保护 SSH、RDP、数据库等高危端口的关键开关。tls可选TLS 模式取值off | flexible | full | strict语义详见下文TLS 四档模式。edge_ips可选边缘 IP 类型与连接性。type为dynamic动态分配或static静态保留connectivity为all双栈默认、ipv4或ipv6。若源站不支持 IPv6应显式设为ipv4。traffic_type可选流量类型direct | http | https用于告知 Spectrum 源站流量形态。argo_smart_routing可选是否启用 Argo Smart Routing 智能路由开启后可降低源站链路延迟patterns.md 中多个协议示例都同时开启了它。SpectrumApp Response响应体创建或查询成功后的应用对象结构如下interface SpectrumApp { id: string; protocol: string; dns: { type: string; name: string }; origin_direct?: string[]; origin_dns?: { name: string }; origin_port?: number | { start: number; end: number }; proxy_protocol: string; ip_firewall: boolean; tls: string; edge_ips: { type: string; connectivity: string; ips?: string[] }; argo_smart_routing: boolean; created_on: string; modified_on: string; }相比请求体响应额外包含id应用唯一 ID后续 GET/PUT/DELETE 及分析查询都要依赖它edge_ips.ips仅在静态 IPtype: static场景下出现列出分配给该应用的边缘 IPcreated_on/modified_on创建与最后修改时间戳ISO 8601 字符串。从 patterns.md 的七个协议示例可以看出同一份 Schema 足以覆盖 SSH、Minecraft、MQTT、SMTP、PostgreSQL/MySQL、RDP 与多源站故障切换等全部场景——差异仅在于protocol、dns、origin_*、tls与ip_firewall的组合方式。三套官方 SDK 实战TypeScript SDKapi.md 给出了基于官方cloudflarenpm 包的完整用法import Cloudflare from cloudflare; const client new Cloudflare({ apiToken: process.env.CLOUDFLARE_API_TOKEN }); // Create const app await client.spectrum.apps.create({ zone_id: your-zone-id, protocol: tcp/22, dns: { type: CNAME, name: ssh.example.com }, origin_direct: [tcp://192.0.2.1:22], ip_firewall: true, tls: off, }); // List const apps await client.spectrum.apps.list({ zone_id: your-zone-id }); // Get const appDetails await client.spectrum.apps.get({ zone_id: your-zone-id, app_id: app.id }); // Update await client.spectrum.apps.update({ zone_id: your-zone-id, app_id: app.id, tls: full }); // Delete await client.spectrum.apps.delete({ zone_id: your-zone-id, app_id: app.id }); // Analytics const analytics await client.spectrum.analytics.aggregate({ zone_id: your-zone-id, metrics: [bytesIngress, bytesEgress], since: new Date(Date.now() - 3600000).toISOString(), });要点Token 通过环境变量CLOUDFLARE_API_TOKEN注入避免硬编码apps命名空间下的create/list/get/update/delete与 REST 端点一一对应analytics.aggregate的metrics数组、since时间参数对应分析 API 的查询语义。Python SDKPython 侧使用同名cloudflare包接口风格与 TypeScript 版完全平行from cloudflare import Cloudflare from datetime import datetime, timedelta client Cloudflare(api_tokenyour-api-token) # Create app client.spectrum.apps.create( zone_idyour-zone-id, protocoltcp/22, dns{type: CNAME, name: ssh.example.com}, origin_direct[tcp://192.0.2.1:22], ip_firewallTrue, tlsoff, ) # List apps client.spectrum.apps.list(zone_idyour-zone-id) # Get app_details client.spectrum.apps.get(zone_idyour-zone-id, app_idapp.id) # Update client.spectrum.apps.update(zone_idyour-zone-id, app_idapp.id, tlsfull) # Delete client.spectrum.apps.delete(zone_idyour-zone-id, app_idapp.id) # Analytics analytics client.spectrum.analytics.aggregate( zone_idyour-zone-id, metrics[bytesIngress, bytesEgress], sincedatetime.now() - timedelta(hours1), )注意 Python 版本把布尔值写成True如ip_firewallTrue时间参数直接传datetime对象SDK 会自动序列化其余参数名与请求 Schema 完全一致。Go SDKGo 使用github.com/cloudflare/cloudflare-go包函数风格以方法调用呈现import github.com/cloudflare/cloudflare-go api, _ : cloudflare.NewWithAPIToken(your-api-token) // Create app, _ : api.CreateSpectrumApplication(ctx, zone-id, cloudflare.SpectrumApplication{ Protocol: tcp/22, DNS: cloudflare.SpectrumApplicationDNS{Type: CNAME, Name: ssh.example.com}, OriginDirect: []string{tcp://192.0.2.1:22}, IPFirewall: true, ArgoSmartRouting: true, }) // List apps, _ : api.SpectrumApplications(ctx, zone-id) // Delete _ api.DeleteSpectrumApplication(ctx, zone-id, app.ID)Go 版本的方法命名CreateSpectrumApplication、SpectrumApplications、DeleteSpectrumApplication与结构化类型SpectrumApplication、SpectrumApplicationDNS直接映射 REST 语义注意示例为演示省略了错误处理生产代码中应逐一检查返回的error。从 configuration.md 看同样的SpectrumApplication字段在 Terraform 资源cloudflare_spectrum_application中也有逐一对应origin_direct、ip_firewall、tls、argo_smart_routing等三套 SDK 与 IaC 共享同一套字段模型迁移成本很低。Analytics API指标、维度与查询示例指标Metricsapi.md 定义了四个核心指标bytesIngress—— 从客户端接收的字节数bytesEgress—— 发送给客户端的字节数count—— 连接数duration—— 连接时长秒。维度Dimensionsevent—— 连接事件类型appID—— Spectrum 应用 IDcoloName—— 数据中心名称ipVersion—— IPv4 或 IPv6。curl 查询示例curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/spectrum/analytics/aggregate/current?metricsbytesIngress,bytesEgress,countdimensionsappID \ --header Authorization: Bearer $CLOUDFLARE_API_TOKEN查询返回按appID维度的入向/出向字节与连接数聚合结果。实际使用中要注意 gotchas.md 提到的**数据保留期Analytics Data Retention**问题套餐实时历史Pro最近 1 小时❌Business最近 1 小时有限Enterprise最近 1 小时90 天因此since参数的取值范围要落在套餐的保留窗口内否则查不到历史数据如需长期留存应在窗口内主动导出到外部系统如通过 analytics-engine 或自建存储。关键字段的配置语境TLS、Proxy Protocol 与源站类型理解 API 字段的最佳方式是回到 configuration.md 的配置语境这里把与请求体直接相关的三组概念展开TLS 四档模式模式描述适用场景源站证书off不启用 TLS非加密流量SSH、游戏不需要flexible客户端→CF 加密CF→源站明文测试环境不需要full端到端 TLS自签名证书也可生产环境任意含自签名strictfull 强制校验源站证书合法性最高安全要求需 CA 签发例如 configuration.md 中数据库场景强制tls: strict而 SSH/RDP 因协议自带加密则用tls: off。当出现 TLS 握手失败或 525 错误时参考 gotchas.md 的 TLS 模式对照表定位连接被拒源站未启用 TLS应改用off525 证书无效自签名证书遇到 strict应降级full或换有效证书握手超时源站期望 TLS 而配置是 flexible应改用full。Proxy Protocol 兼容矩阵版本协议适用场景off-源站不需要客户端 IPv1TCP大多数 TCP 应用SSH、数据库v2TCP高性能 TCPsimpleUDPUDP 应用兼容性方面v1被 HAProxy、nginx、SSH 及多数数据库广泛支持v2需要 HAProxy 1.5 / nginx 1.11simple是 Cloudflare 专有 UDP 格式。源站配置示例nginx stream 模块stream { server { listen 22 proxy_protocol; proxy_pass backend:22; } }若连接正常但应用行为异常多半是源站不支持 Proxy Protocol——gotchas.md 建议先用proxy_protocol: off验证再逐步开启并让源站解析 PROXY 头HAProxy 对应bind :22 accept-proxy。三种源站类型速查Direct IP Origin单台静态 IP 服务器用origin_direct对应[tcp://192.0.2.1:22]CNAME Origin源站是主机名IP 会变动用origin_dns: { name: ... }Spectrum 动态解析Load Balancer Origin高可用/故障切换origin_dns指向负载均衡器主机名配合cloudflare_load_balancer与健康检查 monitor 使用参考 terraform/configuration.md 的 Load Balancers 一节。常见协议场景与 API 参数组合patterns.md 用同一份 API 覆盖了七个高频场景可作为调用参数的模板场景protocoldns.type源站tls必开项SSH 防护tcp/22CNAMEorigin_directoffip_firewall: true游戏Minecrafttcp/25565CNAMEorigin_directoffproxy_protocol: v1保留玩家 IPMQTT Brokertcp/8883明文用 1883CNAMEorigin_directfull明文用 off-SMTP Relaytcp/587CNAMEorigin_directfullSTARTTLS⚠️ 见下方限制PostgreSQLtcp/5432CNAMEorigin_dnsstrictip_firewall: trueMySQLtcp/3306CNAMEorigin_dnsstrictip_firewall: trueRDPtcp/3389CNAMEorigin_directoffRDP 自带加密ip_firewall: true其中值得特别注意的限制详见 gotchas.mdSMTP 反向 DNSSpectrum 边缘 IP 没有 PTR反向 DNS记录大量邮件服务器会因缺少合法 rDNS 而拒收因此出站 SMTP 不建议走 Spectrum入站建议改用 Cloudflare Email Routing内部中继则要在对端白名单 Spectrum IP数据库/远程桌面安全红线数据库场景必须tls: strictip_firewall: true并通过 Zone 防火墙把访问限制在已知 IP或考虑改用 VPN / Cloudflare AccessRDP 是 DDoS 与暴力破解的高发目标同样强制ip_firewall: true并白名单管理员 IP。常见故障排查清单结合 gotchas.mdAPI 交付后最常见的四类问题及解法1. 连接超时/失败原因通常是源站防火墙拦截了 Cloudflare IP、源站服务未在预期端口监听或 DNS 配置错误。排查顺序确认源站防火墙放行 Cloudflare IP 段 → 确认源站服务与端口 → 确保 DNS 是 CNAME 而非 A/AAAA → 复核源站 IP/主机名。验证命令nc -zv app.example.com 22 dig app.example.com2. 客户端 IP 显示为 Cloudflare IP原因是未开启 Proxy Protocol 或源站未解析 PROXY 头。在应用上启用proxy_protocol: v1TCP 用 v1/v2UDP 用 simple并配置源站nginx 用listen 22 proxy_protocol;HAProxy 用bind :22 accept-proxy。3. TLS 错误525 / 握手失败按上文 TLS 模式对照表调整tls取值并用openssl s_client -connect app.example.com:443 -showcerts检查证书链路。4. Enterprise 专属功能不可用端口范围tcp/25565-25575、全端口 TCP/UDP、扩展分析保留期、高级负载均衡均需 Enterprise 套餐Pro/Business 仅支持选定端口创建时不要提交端口范围请求。总结从 api.md 出发Spectrum 的编程接入链路非常清晰REST 端点CRUD Analytics→ 统一的请求/响应 Schema → TypeScript / Python / Go 三套平行 SDK。字段语义上protocol、dns、origin_direct/origin_dns、tls、ip_firewall、proxy_protocol、argo_smart_routing构成了几乎全部实战场景的配置空间配合 configuration.md 的源站类型与 TLS 模式、patterns.md 的协议模板、gotchas.md 的坑位清单即可把任意 TCP/UDP 服务安全地接入 Cloudflare 边缘网络。延伸阅读继续在仓库内查看 Spectrum 技能总览套餐能力与决策树、Spectrum 配置详解Terraform/Pulumi 形态、Spectrum 协议模式分协议示例、Spectrum 避坑指南生产环境排查或返回 技能入口 SKILL.md 了解 Spectrum 在整个 Cloudflare 部署技能栈中的定位。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考