Cloudflare 推出 cf：用一个可编程 CLI 覆盖完整 API

2026-09-28 24 预计阅读时间: 1 分钟
来源: blog.cloudflare.com AI 摘要 Original link

Disclaimer: This article is an AI-assisted summary. Read it together with the original source when precision matters. The summary may omit context, version differences, or edge cases and is not official documentation.

预计阅读时间：12 分钟

Cloudflare 发布了新的命令行工具 cf。它的目标不是再包装几个常用操作，而是映射整个 Cloudflare API，并允许开发者使用 TypeScript 编写程序化配置。与此同时，Cloudflare 还开源了内部使用的 SDK 生成器 Forge，这解释了 cf 如何跟上规模庞大且持续变化的 API。

这项变化对平台工程团队尤其重要：命令行、自动化脚本和智能代理终于可以围绕同一套 API 表面工作，而不必为每种资源手写一层不一致的封装。

“覆盖整个 API”改变了什么

传统云服务 CLI 往往只覆盖高频功能。遇到较新的产品或冷门参数时，开发者还是要退回 HTTP 请求，自行处理路径、请求体、分页和错误响应。

cf 选择镜像整个 Cloudflare API，意味着 CLI 的能力边界将更接近 API 本身。实际价值主要体现在三类场景：

  • 交互式运维：工程师可以在终端中发现并调用不同产品的操作。
  • 脚本与 CI/CD：自动化流程不必在 CLI 和手写 HTTP 请求之间频繁切换。
  • Agent 工具调用：智能代理可以面对更统一、可发现的命令结构，而不是依赖大量临时脚本。

这里的重点不是“命令变多了”，而是 API 与 CLI 之间的重复实现减少了。如果命令和类型能够由 API 描述生成，新接口进入工具链的速度通常会更快，参数漂移也更容易被发现。

不过，覆盖面广不等于默认安全。一个可以访问整个 API 的 CLI，同样可能删除 DNS 记录、改变安全策略或修改生产环境配置。应把它视为完整的控制平面入口，而不是普通的本地辅助命令。

TypeScript 配置适合表达复杂逻辑

声明式文件适合固定配置，但现实中的基础设施经常带有环境判断、批量生成和共享规则。例如，测试环境与生产环境可能使用不同的缓存策略，一组域名又需要复用相同的安全设置。

程序化 TypeScript 配置可以把这些逻辑留在类型系统和普通函数中：

  • 用函数生成重复资源；
  • 用联合类型限制环境名称；
  • 在提交前进行静态检查；
  • 将公共策略封装成模块；
  • 通过代码审查观察配置逻辑，而不只是最终 JSON。

来源摘要没有给出 cf 的具体 TypeScript 配置接口，因此下面是一个可运行的配置建模示例，不是对正式 API 名称的复刻。接入时，需要将本地接口替换为 cf 当前版本提供的类型和入口函数。

mkdir cf-config-demo
cd cf-config-demo

cat > package.json <<'EOF'
{
  "name": "cf-config-demo",
  "private": true,
  "type": "module",
  "scripts": {
    "check": "tsc --noEmit"
  },
  "devDependencies": {
    "typescript": "^5.5.0"
  }
}
EOF

cat > tsconfig.json <<'EOF'
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noEmit": true
  },
  "include": ["cloudflare.config.ts"]
}
EOF

cat > cloudflare.config.ts <<'EOF'
type Environment = "staging" | "production";

type ZonePolicy = {
  zone: string;
  environment: Environment;
  cacheTtlSeconds: number;
  securityLevel: "medium" | "high";
};

function policyFor(zone: string, environment: Environment): ZonePolicy {
  return {
    zone,
    environment,
    cacheTtlSeconds: environment === "production" ? 3600 : 60,
    securityLevel: environment === "production" ? "high" : "medium"
  };
}

export const configuration = [
  policyFor("example.com", "production"),
  policyFor("staging.example.com", "staging")
] satisfies ZonePolicy[];
EOF

npm install
npm run check

这个项目可以直接完成 TypeScript 类型检查。正式接入 cf 时，可以保留 policyFor 之类的业务函数，只替换示例类型、字段和导出方式。这样能把“环境策略”与具体 CLI 适配层分开。

程序化配置也有代价：代码可以执行任意逻辑，因此审查者未必能一眼看出最终变更。比较稳妥的流程是要求工具先输出计划或差异，再允许执行写操作。如果当前版本提供 dry-run、plan 或预览能力，应优先在 CI 中启用；具体参数应以安装版本的帮助信息为准。

Forge 为什么值得关注

Forge 是 Cloudflare 开源的内部 SDK 生成器。它与 cf 同时出现并非偶然：当 API 数量增长到一定规模后，依靠人工维护命令、请求类型和响应模型会产生明显成本。

生成式工具链通常可以承担以下工作：

  1. 读取机器可解析的 API 描述；
  2. 生成请求和响应类型；
  3. 生成调用客户端或命令定义；
  4. 在 API 变化后重新生成并检查差异。

摘要没有披露 Forge 的具体输入格式、模板接口或生成命令，因此不应假设它可以直接读取任意 OpenAPI 文件，也不应默认生成结果适合所有项目。它的开源价值在于，团队能够检查生成过程、理解 cf 的构建方式，并评估是否能将相同思路用于内部 API。

对维护大型内部平台的团队来说，这可能比单个 CLI 命令更有启发：不要手工维护数百个薄封装，而是把 API 描述、代码生成和兼容性检查连成一条流水线。

给自动化和 Agent 加一道执行闸门

Agentic CLI 的便利之处在于，智能代理可以发现命令、组合参数并执行任务；风险也来自同一个地方。自然语言中的“清理旧配置”可能被解释为范围过大的删除操作。

下面的包装脚本不依赖 cf 的具体子命令。它默认只打印准备执行的命令，只有显式设置 CF_EXECUTE=1 并人工确认后才真正运行，因此可以直接改造成 CI 或 Agent 的审批闸门：

cat > safe-cf.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

if [[ $# -eq 0 ]]; then
  echo "Usage: ./safe-cf.sh -- cf <actual arguments>" >&2
  exit 64
fi

if [[ "$1" == "--" ]]; then
  shift
fi

printf 'Requested command:'
printf ' %q' "$@"
printf '\n'

if [[ "${CF_EXECUTE:-0}" != "1" ]]; then
  echo "Preview only. Set CF_EXECUTE=1 to request execution."
  exit 0
fi

read -r -p "Type APPLY to continue: " confirmation
if [[ "$confirmation" != "APPLY" ]]; then
  echo "Cancelled."
  exit 1
fi

exec "$@"
EOF

chmod +x safe-cf.sh

# 安全预览：把后面的参数替换为当前 cf 版本支持的真实命令
./safe-cf.sh -- cf --help

# 需要执行时再显式解锁；此处仍以无破坏性的帮助命令演示
CF_EXECUTE=1 ./safe-cf.sh -- cf --help

生产环境还应增加更严格的控制：

  • 为不同账户和环境使用独立凭据；
  • 令牌只授予任务所需的最小权限；
  • 不把令牌直接写入命令参数、代码或 Agent 提示词；
  • 对删除、批量更新和权限修改设置人工审批；
  • 保存命令、操作者、目标账户与结果的审计记录；
  • 固定 CLI 版本，并在升级时检查生成命令或类型是否变化。

安装完成后，可以先用帮助系统探索实际命令，而不是让脚本猜测接口：

command -v cf
cf --help

# 不同版本可能采用不同的版本参数，按实际支持情况使用
cf version || cf --version

采用时不要从“全自动写入”开始

引入 cf 的稳妥路径是从只读任务开始，例如资源盘点、配置检查和状态查询；随后再进入带预览与审批的写操作。等权限边界、审计记录和回滚流程稳定后，才适合把更多操作交给 CI 或 Agent。

可以使用这份检查清单：

  • [ ] 已确认安装版本的命令与 TypeScript 配置接口；
  • [ ] 开发、测试和生产账户使用独立凭据；
  • [ ] 自动化令牌遵循最小权限原则；
  • [ ] 写操作具有预览、差异或人工确认阶段；
  • [ ] 破坏性操作有额外审批与回滚方案；
  • [ ] CLI 与生成代码版本已固定；
  • [ ] 日志中不会泄露令牌或敏感配置。

cf 最值得关注的地方，是把完整 API、程序化配置和 Agent 工作流放进了同一个命令行入口；Forge 则展示了支撑这种广度的生成式工具链。它们可以减少胶水代码，但不会自动消除权限和变更风险。真正可靠的落地方式，是用类型约束配置，用生成工具减少重复劳动，再用最小权限、预览和审批守住执行边界。

# AI # Cloudflare # LLM # TypeScript # 云平台 # 前端 # 后端 # 平台工程

相关推荐