---
title: 用程序维护 Cloudflare 资源
subtitle: 选择调用入口，取得完整结果，再判断变更是否完成
source_cutoff: 2026-10-08
---

# 用程序维护 Cloudflare 资源

“控制台里有这个资源”“API 返回成功”“读者能用到服务”是三个需要分别检查的结果。程序可以减少重复盘点和配置操作；它也必须说明读了哪些范围、哪里失败，以及哪些结果还不知道。先确定手边的操作，再选择 CLI、REST 或现有语言的 SDK。

本文于 2026-10-08 定向查阅官方 SDK、Go `v7.12.0`、OpenAPI 仓库与 R2 API 文档；Tunnel 变更另复看已有来源。没有安装 SDK、访问账号或执行云端请求。下面的可靠操作方法是编辑建议；Go 的默认值只适用于所标版本。

## 控制台、CLI、REST、SDK、binding 各接哪一段

| 手边的操作 | 先找哪个入口 | 还需要检查什么 |
|---|---|---|
| 人查看资源、理解一次配置 | Dashboard 与相应产品文档 | 页面显示的 account、zone 和资源身份，是否属于目标环境 |
| 项目创建、开发、部署或重复 shell 操作 | 项目现有 CLI，例如 Wrangler；通用入口见 [cf CLI 介绍](../reports/2026-10-02.md#cf-cli先从看清账户开始) | 已有 config、命令的支持范围与部署目标；别同时建立第二套配置 owner |
| 只需核对一个接口，或已有少量可维护的请求 | 官方 REST API / curl 示例 | 方法、路径、权限、分页、超时与输出处理 |
| 已有应用要串联多个请求与结果 | 应用现有语言的官方 SDK | 锁定版本、客户端默认值、返回类型、迁移说明 |
| Worker 在请求中使用已绑定的资源 | 产品的 Workers binding | binding 名称、资源与环境；它不能证明管理接口也已配置好 |

官方 SDK 入口列出 Go、TypeScript、Python，并将集成现有应用、串联请求列为 SDK 的使用情形。它不要求为了使用 Go SDK 重写一个已有的 Python 或 TypeScript 项目。[S118]

R2 尤其需要分清入口：Workers API、S3-compatible API 和 Cloudflare REST API 均有用途。REST 支持 bucket 管理及对象操作；高吞吐工作负载应按官方建议使用 Workers 或 S3 路线。不能把“SDK 可以调用 REST”推成“所有文件交付都改走 REST”。[S122]

## 先知道自己读的是哪一组资源

盘点从项目现有 dependency、config 和实际调用路径开始，保留 account / zone / Worker / bucket / Tunnel 的归属线索。绑定名是应用中的名字；资源 ID、环境与部署版本是另外的身份。公共说明使用占位符，真实配置留在项目批准的位置。

建议把读取结果附上这几项：目标环境、接口或命令、查询条件、客户端版本、核对时间，以及是否取得全部页。查询成功只证明指定权限与筛选条件下的结果；它不证明账号里所有资源都已列出，更不证明服务可达。网页、Access、回源与应用响应的分层检查见[私有状态页实践](../practice/protected-status.md)。

写配置前先取得当前状态，形成具体差异，说明目标资源和失败范围。只有任务已授权该动作，才执行写入；随后读回配置，再检查受影响的使用路径。批量操作应逐项保留成功、失败和未知，不能把一个成功响应当成整批完成。

## 完整分页：第二页失败不能宣布盘点完成

一次列表响应、完整遍历与服务是否可用分别报告。迭代遇到错误时保留已取得的对象和失败页／cursor，标明 `complete: false`。空页仍可能有下一页；没有对象不自动表示结束。即便分页完成，筛选条件、权限和遍历期间的资源变化仍限定这次观察。

Go `v7.12.0` 的普通 `.List()` 取一页；`.ListAutoPaging()` 继续遍历，结束后须检查 `iter.Err()`。成功读到若干对象而没有检查结束错误，不能作为完整盘点证据。[S119]

语言无关的[离线操作例子](../examples/api-operations/README.md)用合成分页验证成功、重试、后页失败、空页与总期限。它由 Python 实现教学模型，没有调用 Cloudflare Python SDK，也没有验证真实 API 的分页语义。

## 超时与重试：整件事有自己的期限

给整个操作设置期限，覆盖分页、重试与等待；单次请求可以另设较短期限。若每次重试都重置整件事的时钟，agent 可能一直等，也无法及时交付部分结果。期限耗尽时，说明停在哪里，保留已有结果，不把停止解释成完整成功。

在 Go `v7.12.0` 中，请求默认没有 timeout；context 可以限定含重试的请求生命周期，`option.WithRequestTimeout()` 限定单次尝试。默认自动重试两次，范围包括连接错误、408、409、429 和 5xx；`option.WithMaxRetries()` 可调整。其他语言或版本须各自核对。[S119]

客户端重试不能决定整个业务动作是否安全。读操作也要看服务的具体语义；写操作响应丢失时，服务可能已经改完了。先记为 [uncertain / 结果未知](../docs/glossary.md#uncertain--结果未知)，通过该接口支持的状态查询、操作记录或稳定幂等约定核对，才能选择是否再执行。不要为一次未知结果生成新身份后重放；[任务恢复用例](../use-cases/recoverable-jobs.md)解释了本地任务状态与外部副作用之间的缺口。

> **想一想：列表已返回 20 个对象，下一页超时，能写“没有发现其他资源”吗？**
>
> **答案：不能。** 可以报告已读取的 20 个对象、筛选范围和失败位置；全量结论仍未知。写操作超时也只说明响应没有可靠取得，不能直接写成“未执行”。

错误报告保存安全摘要、状态码、操作身份和范围。真实请求头、token、完整响应 body、私有对象名和日志不复制进公共工单或本书；调试输出是否需要保留由项目的数据边界决定。

## SDK 与 OpenAPI 更新：先找到被使用的方法

Go `v7.12.0` release 增加 Containers application、instance、version、rollout、image 和 registry 的管理入口，也记录 Breaking Changes，例如部分 Zero Trust 列表由 `SinglePage` 变为分页类型。这说明接口可用与返回行为可能改变；它没有证明账号开放条件、权限或运行质量。[S120]

官方 `cloudflare/api-schemas` 保存 Cloudflare API 的 OpenAPI schemas。它适合检查接口层的方法、参数和返回结构；具体客户端的默认值和迁移细节仍看对应语言、版本的文档。[S121] 可使用下面的复查顺序：

1. 固定变化依据：旧／新版本或明确公告、生效日期、受影响的方法或字段。
2. 从本书来源定位候选内容：例如 `python3 tools/fieldbook.py impact-source S120`。
3. 到目标项目找对应的依赖版本、实际调用与解析代码；“用了同一个产品”只构成候选。
4. 命中后检查完整分页、调用参数和失败行为；需要改动时遵循该项目授权与验证入口。
5. 没命中就附核查范围收口；证据不够则保留未知，不宣布不受影响。

例如 Tunnel 的 list/get 内嵌 `connections` 于 2026-10-05 移除，应查询专用 connections endpoint。只有仍解析旧字段的调用需要据此修正；部署了 Tunnel 本身不能证明项目命中该变化。官方说明还区分了 `cloudflared` 与读取该字段的集成。[S117]

来源查询只检查登记条目的正文引用和 JSON `sources` 字段，接着沿 `depends_on` 传播；来源书目、代码示例、注释与来源附录不作为正文使用点。它返回当前复查、历史勘误和非活动候选，`related` 不传播。它不分析私人项目，不改变日期，也不判定所有引用已经过时。

## 把这次操作交回项目工作

一份可继续使用的结果应连在一起说明：当前任务、目标范围、现有采用理由、命中的变化、已得到的证据、仍未知的部分和下一项验证。检查失败时保留部分观察；技术选择的条件没变时复用它。

接下来读[把变化接到当前项目](../use-cases/project-context.md)，或直接使用[项目判断任务单](../templates/project-context-task.md)。采用理由和当前配置由项目自己的已有文档持有；本书提供解释与可检查的方法。

<!-- SOURCES -->