Cloudflare Network InterconnectsCNIAPI 完全指南REST 端点、SDK 命名空间与多语言自动化实战【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skillsCloudflare Network InterconnectCNI是面向企业用户的私有高性能网络连接方案而本文所讲的 CNI API 则是把互联线路Interconnect申请、BGP 配置对象CNI Object管理、机柜槽位Slot查询、LOA 文件下载等运维动作全面脚本化的官方接口。本文以仓库中的 CNI API 参考文档 为主体骨架结合同目录的 README、configuration.md、patterns.md 与 gotchas.md 做纵深扩充。读完本文你将掌握CNI 全套 REST 端点的地址与请求体字段、TypeScript / Python 官方 SDK 与 cURL 的三种实操写法、健康检查与默认 ASN 的配置方式以及哪些能力 API 不提供、只能走 Dashboard 或联系账户团队。CNI 是什么API 自动化的前提背景在进入端点细节前先明确 CNI 的定位它是连接到 Cloudflare 全球网络的私有、高性能链路属于**企业版Enterprise-only**能力。根据 network-interconnect/README.mdCNI 提供三种连接类型连接类型说明Direct在共享机房中的物理光纤支持 10/100 Gbps需自行向机房下单交叉连接cross-connectPartner通过 Console Connect、Equinix、Megaport 等伙伴平台提供的虚拟连接由伙伴 SDN 管理CloudAWS Direct Connect 或 GCP Cloud Interconnect仅适用于 Magic WAN数据平面分两个版本v1Classic支持 GRE 隧道、VLAN/BFD/LACPMTU 不对称下行 1500 / 上行 1476支持公网对等互联peeringv2Beta无 GRE双向 1500 MTU暂不支持 VLAN/BFD/LACP改用 ECMP。API 能自动化的边界来自 README 的 Automation Boundary 一节总结如下可 API 自动化列出/创建/删除互联线路Direct、Partner、列出可用槽位、查询线路状态、下载 LOA PDF、创建/更新 CNI 对象BGP 配置、查询设置。需要账户团队初始请求审批、AWS Direct Connect 配置、GCP Cloud Interconnect 最终激活、Partner 互联接受Equinix、Megaport、v1 的 VLAN 分配、v1 配置文档生成、升级与排障支持。完全无法自动化物理交叉连接安装、伙伴门户操作虚拟电路下单、AWS/GCP 门户操作、维护窗口协调。理解了这条边界就能明白为什么下面的 API 设计能做这些、不做那些。API 基础Base URL 与认证方式所有 CNI 端点都挂在 Cloudflare API v4 的基础地址之下使用 Bearer Token 认证https://api.cloudflare.com/client/v4 Auth: Authorization: Bearer token配合环境变量使用时典型做法是export CF_TOKENyour-api-token # API 令牌 export ACCOUNT_IDyour-account-id # 账户 IDURL 路径参数 account_id 的取值在 CI/CD 场景下可参考 SKILL.md 中 wrangler 的认证约定将CF_TOKEN作为机密环境变量注入。需要提醒的是如果账户不是企业版调用 CNI 端点会得到403 Forbidden: Enterprise plan required详见 gotchas.md此时只能联系账户团队升级套餐。SDK 命名空间主用与弃用官方 SDK 将 CNI 能力收敛在networkInterconnects命名空间下包含三个子命名空间主用推荐client.networkInterconnects.interconnects.* client.networkInterconnects.cnis.* client.networkInterconnects.slots.*弃用替代client.magicTransit.cfInterconnects.*规则明确所有新代码一律使用networkInterconnects命名空间。interconnects对应物理/虚拟互联线路资源cnis对应 BGP 配置对象CNI Objectslots对应可用的机柜槽位资源。Python SDK 中对应为client.network_interconnects.interconnects.*、client.network_interconnects.cnis.*、client.network_interconnects.slots.*。Interconnects 端点详解线路全生命周期端点一览GET /accounts/{account_id}/cni/interconnects # Query: page, per_page POST /accounts/{account_id}/cni/interconnects # Query: validate_onlytrue (optional) GET /accounts/{account_id}/cni/interconnects/{icon} GET /accounts/{account_id}/cni/interconnects/{icon}/status GET /accounts/{account_id}/cni/interconnects/{icon}/loa # Returns PDF DELETE /accounts/{account_id}/cni/interconnects/{icon}GET列表支持分页参数page与per_pagePOST创建时可带可选查询参数validate_onlytrue做只校验不落库的干跑dry-run{icon}是互联线路的 ID响应体中的id字段形如icon_abcGET .../loa返回 PDF 格式的 Letter of Authorization授权函。Create Body 字段说明创建线路的请求体包含以下字段字段说明account账户 ID与 URL 中的{account_id}一致slot_id目标槽位 ID从 Slots 接口查询必须未被占用type连接类型direct、partner、cloud对应 README 中的三种连接方式facility机房设施代码例如EWR1纽瓦克。必须使用合法代码否则返回400 invalid facility codespeed带宽规格如10G、100Gname线路名称业务标识如prod-interconnectdescription描述信息Status 取值与含义线路状态字段取值为active | healthy | unhealthy | pending | down。结合 configuration.md 的监控状态表 可以进一步理解每个值的物理含义状态含义healthy链路运行、流量正常、健康检查通过active链路已 up、光功率充足、以太网协商成功unhealthy链路 down、光功率低低于 -20 dBm、无法协商pending交叉连接未完成、设备无响应、RX/TX 光纤接反down物理链路断开、完全无连通性响应示例{result: [{id: icon_abc, name: prod, type: direct, facility: EWR1, speed: 10G, status: active}]}注意type: direct与status: active的搭配——创建成功后线路并非立即可用通常会经历pending阶段等待交叉连接施工与光纤接续需通过status端点轮询推进。轮询策略建议patterns.md 中的 HA 模式代码使用pollUntilActive函数等待线路激活而 gotchas.md 的反模式表 明确指出不要每秒轮询 status浪费配额、易触发限速轮询间隔建议 3060 秒。CNI Objects 端点详解BGP 配置对象CNI Object 是绑定在互联线路上的 BGP 配置实体。端点如下GET /accounts/{account_id}/cni/cnis POST /accounts/{account_id}/cni/cnis GET /accounts/{account_id}/cni/cnis/{cni} PUT /accounts/{account_id}/cni/cnis/{cni} DELETE /accounts/{account_id}/cni/cnis/{cni}请求体字段字段说明account账户 IDcust_ip客户侧 IP/31 点对点子网中的一个地址如192.0.2.1/31cf_ipCloudflare 侧 IP同 /31 子网的另一个地址如192.0.2.0/31bgp_asn客户 BGP ASN如65000私用 ASN 区间bgp_passwordBGP MD5 密码可选但推荐vlanVLAN 编号关于 VLAN 有一个关键陷阱在 v1 数据平面下VLAN 由 Cloudflare 分配而不是自行指定。因此 gotchas.md 的反模式表 特别警告不要在自动化里硬编码 VLAN正确做法是从 CNI Object 的创建/查询响应中动态读取分配到的 VLAN ID。BGP 配置参考v1结合 configuration.md 的 BGP 配置一节v1 线路的 BGP 对等参数示例如下Router ID: 192.0.2.1 Peer IP: 192.0.2.0 Remote ASN: 13335 # Cloudflare 的 ASN Local ASN: 65000 Password: [optional] VLAN: 100 # 由 CF 分配勿硬编码v2 的 BGP 配置更为简化另外值得注意的是configuration.md 中注明为 2024 年 12 月的演进Magic WAN/Transit 现在可以直接在 CNI v2 上对等 BGP无需 GRE 隧道。Slots 端点详解查询可用槽位在创建 Direct/Partner 线路前通常需要先确认目标机房有没有可用的物理槽位GET /accounts/{account_id}/cni/slots GET /accounts/{account_id}/cni/slots/{slot}支持的查询参数参数说明facility按机房过滤如EWR1occupied按占用状态过滤false表示只看空闲槽位speed按带宽过滤如10G如果跳过这一步直接创建很可能撞上400 Bad Request: slot_id already occupied——即该槽位已被其他互联线路占用。官方推荐的标准姿势是先用occupiedfalse过滤拿到空闲槽位gotchas.md 中的 API 错误处理await client.networkInterconnects.slots.list({ account_id: id, occupied: false, facility: EWR1, });健康检查在隧道端点层配置CNI 自身的健康检查并不通过独立的/cni/*端点配置而是通过Magic Transit / WAN 隧道端点CNI v2来配置。在 TypeScript SDK 中示例如下await client.magicTransit.tunnels.update(accountId, tunnelId, { health_check: { enabled: true, target: 192.0.2.1, rate: high, type: request }, });target健康检查目标 IPrate检查频率high|medium|lowtype探测类型request|reply。配置完成后建议立即开启维护通知Dashboard → NotificationsCNI Connection Maintenance 告警可提前最多 2 周预告维护窗口新订阅的维护告警最长有 6 小时延迟详见 configuration.md 的监控与告警一节。Settings 端点查询与更新默认 ASN账户级的 CNI 默认设置通过以下端点管理GET /accounts/{account_id}/cni/settings PUT /accounts/{account_id}/cni/settings请求体仅一个字段default_asn。它用于为账户设置默认 BGP ASN便于后续 CNI 对象创建时复用避免每次重复传参。三语言实战TypeScript / Python / cURL 完整示例TypeScript SDK以下示例完整覆盖列表、创建带/不带校验、查状态、下载 LOA、创建 CNI 对象、筛选槽位六个高频操作import Cloudflare from cloudflare; const client new Cloudflare({ apiToken: process.env.CF_TOKEN }); // List列出所有互联线路可带分页参数 await client.networkInterconnects.interconnects.list({ account_id: id }); // Create with validation干跑只校验配置不真正创建 await client.networkInterconnects.interconnects.create({ account_id: id, account: id, slot_id: slot_abc, type: direct, facility: EWR1, speed: 10G, name: prod-interconnect, }, { query: { validate_only: true }, // Dry-run validation }); // Create without validation正式创建 await client.networkInterconnects.interconnects.create({ account_id: id, account: id, slot_id: slot_abc, type: direct, facility: EWR1, speed: 10G, name: prod-interconnect, }); // Status查询线路状态注意参数是 accountId 与 iconId await client.networkInterconnects.interconnects.get(accountId, iconId); // LOASDK 未封装 PDF 下载直接用 fetch 拉取并落盘 const res await fetch(https://api.cloudflare.com/client/v4/accounts/${id}/cni/interconnects/${iconId}/loa, { headers: { Authorization: Bearer ${token} }, }); await fs.writeFile(loa.pdf, Buffer.from(await res.arrayBuffer())); // CNI object创建 BGP 配置对象/31 点对点子网 await client.networkInterconnects.cnis.create({ account_id: id, account: id, cust_ip: 192.0.2.1/31, cf_ip: 192.0.2.0/31, bgp_asn: 65000, vlan: 100, }); // Slots按机房与带宽过滤空闲槽位 await client.networkInterconnects.slots.list({ account_id: id, occupied: false, facility: EWR1, speed: 10G, });两点实用提示validate_onlytrue是创建前最值得用的一步——如果配置有问题接口会返回422 Unprocessable: validate_only request failed并附带具体错误详情此时应先修正配置再正式创建gotchas.md。LOA 下载需要fs与Buffer配合fetch完成注意令牌通过Authorization请求头传递。Python SDKPython 端的模式与 TypeScript 一一对应只需注意命名空间使用下划线风格network_interconnectsimport os from cloudflare import Cloudflare client Cloudflare(api_tokenos.environ[CF_TOKEN]) # List, create, status与 TypeScript 同构 client.network_interconnects.interconnects.list(account_idid) client.network_interconnects.interconnects.create(account_idid, accountid, slot_idslot_abc, typedirect, facilityEWR1, speed10G) client.network_interconnects.interconnects.get(account_idid, iconicon_id) # CNI objects and slots client.network_interconnects.cnis.create(account_idid, cust_ip192.0.2.1/31, cf_ip192.0.2.0/31, bgp_asn65000) client.network_interconnects.slots.list(account_idid, occupiedFalse)注意Python SDK 中创建 CNI 对象时可省略account参数由account_id推导而查询互联线路状态用的是icon关键字参数。cURL不依赖任何 SDK 时直接用 REST 端点# List interconnects列出互联线路 curl https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/cni/interconnects \ -H Authorization: Bearer ${CF_TOKEN} # Create interconnect创建线路validate_onlytrue 干跑校验 curl -X POST https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/cni/interconnects?validate_onlytrue \ -H Authorization: Bearer ${CF_TOKEN} -H Content-Type: application/json \ -d {account: id, slot_id: slot_abc, type: direct, facility: EWR1, speed: 10G} # LOA PDF下载授权函到本地文件 curl https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/cni/interconnects/${ICON_ID}/loa \ -H Authorization: Bearer ${CF_TOKEN} --output loa.pdfAPI 不提供的能力明确边界与替代方案原文档明确列出了以下API 无法覆盖的能力自动化设计时必须为它们预留人工/外部通道BGP 会话状态查询——只能通过 Dashboard 或 BGP 日志查看带宽利用率指标——需要外部监控系统每条互联线路的流量统计历史可用性/宕机数据光功率读数light level——需联系账户团队维护窗口排期——仅支持通知不开放 API 编排。与之呼应的 gotchas.md 的 Whats Not Queryable via API 一节 还补充了光纤路径细节、交叉连接施工状态、维护窗口时间表同样不可查询。推荐的变通做法是BGP 状态 → 外部监控如对端路由器的 BGP 会话监控历史数据 → 日志聚合平台维护窗口 → 订阅 Cloudflare Status 维护通知。常见 API 错误与限速实战排错清单把 gotchas.md 的 API Errors 一节 与本文端点对照整理成可直接对号入座的排错表错误原因解法400 slot_id already occupied槽位已被其他线路占用用occupiedfalse过滤空闲槽位后再选400 invalid facility code机房代码拼写错误或不受支持核对官方设施代码表403 Enterprise plan required账户非企业版联系账户团队升级422 validate_only request failed干跑校验发现问题槽位错误、配置非法阅读错误详情修正后再正式创建速率限制官方限制为每个令牌1200 请求 / 5 分钟。应对策略包括实现指数退避exponential backoff重试、缓存槽位列表以减少重复查询gotchas.md。自动化落地建议与反模式结合 patterns.md 的 Failover Security 一节 与 gotchas.md 的反模式表面向 API 自动化给出以下可执行建议最小权限令牌为自动化脚本签发只包含 CNI 相关权限的 API Token并定期轮换凭证BGP 密码认证CNI 对象创建时尽量携带bgp_password配合 BGP 路由过滤注意不要被防火墙拦截 TCP/179避免每秒轮询status 轮询间隔控制在 3060 秒不要硬编码 VLANv1 的 VLAN 由 Cloudflare 分配须从 CNI 对象响应中读取不要假设 BGP up 即流量通BGP 会话建立 ≠ 路由已安装上线后必须验证路由表与实际流量patterns.md生产环境至少两条线路CNI 无 SLA单一线路是单点故障应使用 ≥2 条且设备多样性的线路并通过 BGP local preference 分级如主线路 200、备线路 150、第三线路 100、公网兜底。继续深入本仓库配套参考本文对应的完整参考集位于 network-interconnect 目录按任务场景推荐阅读顺序首次搭建先读 README 了解连接类型与前提条件 → 再读 configuration.md 完成 BGP 与监控配置 → 最后回到本文的 api.md 做 API 化设计高可用架构参考 patterns.mdHA、多云混合、多机房模式排障直接翻阅 gotchas.md物理层、BGP 层、API 层错误全覆盖若需了解 CNI 在部署流程中的整体定位可查看 cloudflare-deploy 技能的 SKILL.md其中我需要网络/连接决策树将私有网络连接导向 network-interconnect 参考集。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考