Cloudflare Manager 是一个综合性的 Cloudflare 服务管理技能，用于部署和配置 Workers、KV Storage、R2 存储桶、Pages、DNS 记录以及路由。它会自动验证 API 凭证、提取部署 URL，并提供可操作的错误信息。
初始设置
首次使用前需要完成以下步骤：
安装依赖：
cd ~/.claude/skills/cloudflare-manager bun install
配置 API Key：在项目根目录创建 .env 文件：
CLOUDFLARE_API_KEY=your_api_token_here CLOUDFLARE_ACCOUNT_ID=your_account_id # 可选，自动检测
获取 API token 的方式：访问 https://dash.cloudflare.com/profile/api-tokens，点击 "Create Token"，使用 "Edit Cloudflare Workers" 模板（或创建自定义 token）。所需权限包括：Account > Workers Scripts > Edit、Account > Workers KV Storage > Edit、Account > Workers R2 Storage > Edit、Account > Cloudflare Pages > Edit、Zone > DNS > Edit（如使用自定义域名）。
验证凭证：运行验证以检查 API key 和权限：
cd ~/.claude/skills/cloudflare-manager bun scripts/validate-api-key.ts
预期输出会显示 API key 有效、Token 状态、账户信息以及已授予的权限。若验证失败并返回 401/403，请检查 .env 中的 API token 是否正确；若为网络错误，请检查网络连接。可使用 --no-cache 标志强制重新验证：bun scripts/validate-api-key.ts --no-cache。
快速开始
部署 Worker 容器
部署新的 worker 容器沙箱：
bun scripts/workers.ts deploy worker-name ./worker-script.js
该命令会创建新的 worker 容器、部署 JavaScript/TypeScript 代码、自动提取并返回 Cloudflare 生成的 URL（例如 https://worker-name.username.workers.dev），并返回 worker ID 和配置。退出码 0 表示成功，1 表示失败。部署通常可在 2-5 秒内完成。
创建和使用 KV 存储
创建 KV 命名空间并存储数据：
bun scripts/kv-storage.ts create-namespace user-sessions bun scripts/kv-storage.ts write <namespace-id> "session:user123" '{"userId":"123","token":"abc"}' bun scripts/kv-storage.ts read <namespace-id> "session:user123" bun scripts/kv-storage.ts list-keys <namespace-id> bun scripts/kv-storage.ts delete <namespace-id> "session:user123"
注意：KV 存储使用最终一致性，写入可能需要最多 60 秒才能全局传播。如需立即读取，请使用写入数据所在的同一边缘位置。
创建 R2 存储桶并上传文件
bun scripts/r2-storage.ts create-bucket media-assets bun scripts/r2-storage.ts upload media-assets ./images/logo.png logo.png bun scripts/r2-storage.ts list-objects media-assets bun scripts/r2-storage.ts download media-assets logo.png ./downloaded-logo.png
部署到 Cloudflare Pages
bun scripts/pages.ts deploy my-app ./dist bun scripts/pages.ts set-env my-app API_URL https://api.example.com bun scripts/pages.ts set-env my-app DEBUG true --env preview bun scripts/pages.ts get-url my-app
Pages 脚本会自动从部署响应中提取并返回 Cloudflare 生成的 URL（例如 https://my-app.pages.dev）。注意：API 会创建项目结构，但实际文件上传需要使用 Wrangler CLI：bunx wrangler pages deploy ./dist --project-name=my-app。
配置 DNS 和路由
bun scripts/dns-routes.ts create-dns example.com A api 192.168.1.1 bun scripts/dns-routes.ts create-route example.com ".example.com/api/" api-handler
常见工作流
多服务设置：创建 KV 命名空间用于缓存、创建 R2 存储桶用于媒体、部署带绑定的 worker、配置路由。
更新 Worker 配置：使用 workers.ts update 更新代码，使用 get 获取详情，使用 list 列出所有 worker。
批量 KV 操作：支持从 JSON 文件批量写入（bulk-write）以及批量删除多个键（bulk-delete）。
错误处理
缺少 API Key 时，需在项目根目录创建 .env 文件。权限不足时，需在 https://dash.cloudflare.com/profile/api-tokens 更新 token 权限。API 速率限制（429）时，脚本会自动以指数退避重试（3 次）。网络问题时，检查网络连接并重试。
最佳实践
安全方面：切勿提交 .env 文件，始终添加到 .gitignore；使用基于 token 的认证（而非 API key）；定期轮换 token（建议每 90 天）；遵循最小权限原则；通过 Wrangler CLI 存储密钥：wrangler secret put SECRET_NAME。
性能方面：将 worker 部署到 Cloudflare 边缘以减少延迟；KV 存储用于频繁读取的数据（而非频繁写入）；R2 用于大文件（KV 每个键有 25MB 限制）；启用适当 TTL 的缓存；worker 脚本保持在 1MB 以下以加快冷启动。
开发工作流：先用 wrangler dev 本地测试；生产前使用 staging 环境；token 更新后验证凭证；使用 wrangler tail worker-name 监控 worker 日志；对 worker 进行版本管理（如 api-v1、api-v2）。
命名约定：Workers 使用描述性名称；KV 命名空间包含用途；R2 存储桶使用小写加连字符；保持基础设施命名一致。
资源管理：删除未使用的 worker、命名空间和存储桶；在 Cloudflare 仪表板监控使用情况；Workers 免费层限制为每天 100,000 次请求；设置计费警报。
脚本参考
所有脚本位于 ~/.claude/skills/cloudflare-manager/scripts/：validate-api-key.ts（验证 API 凭证并显示权限）、workers.ts（部署、更新和管理 Workers）、kv-storage.ts（创建和管理 KV 命名空间及键值对）、r2-storage.ts（创建和管理 R2 存储桶及对象）、pages.ts（部署和配置 Cloudflare Pages 项目）、dns-routes.ts（配置 DNS 记录和 worker 路由）、utils.ts（API 调用和错误处理的共享工具）。
模板位于 ~/.claude/skills/cloudflare-manager/templates/：worker-template.js（带 fetch 处理器的基本 worker 模板）、wrangler.toml.template（Wrangler 配置模板）。
故障排除
常见问题包括：Worker 部署失败（检查脚本语法、文件存在性、重新验证 API key、检查 worker 名称有效性）；KV 命名空间未找到（列出所有命名空间、确认使用命名空间 ID 而非名称、检查命名空间是否被删除、确保 API token 有 KV 权限）；R2 存储桶已存在（存储桶名称需全局唯一、尝试更具体的名称、名称需为 3-63 字符的小写字母/数字/连字符）；Pages 部署超时（检查部署状态、在仪表板查看、大型部署可能需 5-10 分钟）；DNS 记录创建失败（验证 zone 存在、确保域名已添加到 Cloudflare 并激活、检查 nameserver、验证 API token 有 Zone > DNS > Edit 权限）；API 速率限制（脚本自动重试、等待 1-2 分钟后手动重试、减少并发操作、速率限制为每 5 分钟 1200 次请求）；CLOUDFLARE_API_KEY 未找到（在项目根目录创建 .env 文件、验证文件内容、确保等号周围无空格、从存在 .env 的项目根目录运行命令）。
安全说明
API key 从不记录或显示在输出中；所有 API 请求使用 HTTPS；用户输入在 API 调用前经过验证；破坏性操作（删除）需要确认；权限缓存 24 小时以减少 token 暴露。
附加资源
Cloudflare API 文档：https://developers.cloudflare.com/api/；Workers 文档：https://developers.cloudflare.com/workers/；KV 存储指南：https://developers.cloudflare.com/kv/；R2 存储指南：https://developers.cloudflare.com/r2/；Pages 文档：https://developers.cloudflare.com/pages/。