cloudflare-manager

Cloudflare Manager

全面的 Cloudflare 服务管理技能，可用于部署和配置 Workers、KV Storage、R2 存储桶、Pages、DNS 记录和路由。自动验证 API 凭据、提取部署 URL，并提供可执行的错误消息。

初始设置

首次使用此技能前：

1. 安装依赖项

   cd ~/.claude/skills/cloudflare-manager
   bun install
   

2. 配置 API 密钥

   在项目根目录中创建 .env 文件：

   CLOUDFLARE_API_KEY=your_api_token_here
   CLOUDFLARE_ACCOUNT_ID=your_account_id  # Optional, auto-detected
   

   获取 API 令牌：

   • 访问 https://dash.cloudflare.com/profile/api-tokens
   • 点击“Create Token”
   • 使用“Edit Cloudflare Workers”模板（或创建自定义令牌）
   • 所需权限：
     • Account > Workers Scripts > Edit
     • Account > Workers KV Storage > Edit
     • Account > Workers R2 Storage > Edit
     • Account > Cloudflare Pages > Edit
     • Zone > DNS > Edit（如果使用自定义域名）

3. 验证凭据

   运行验证，检查 API 密钥和权限：

   cd ~/.claude/skills/cloudflare-manager
   bun scripts/validate-api-key.ts
   

   预期输出：

   ✅ API key is valid!
   ℹ️  Token Status: active
   ℹ️  Account: Your Account Name (abc123...)
   
   🔑 Granted Permissions:
     ✅ Workers Scripts: Edit
     ✅ Workers KV Storage: Edit
     ✅ Workers R2 Storage: Edit
   

   验证故障排除：

   • 如果验证失败并返回 401/403：检查 .env 中的 API 令牌是否正确
   • 如果验证因网络错误失败：检查互联网连接
   • 使用 --no-cache 标志强制进行全新验证：bun scripts/validate-api-key.ts --no-cache

当前 API 权限

运行 bun scripts/validate-api-key.ts，以在此处填入当前权限。

快速入门指南

部署 Worker 容器

部署新的 Worker 容器沙箱：

# Using the skill
bun scripts/workers.ts deploy worker-name ./worker-script.js

执行内容：

• 创建新的 Worker 容器
• 部署 JavaScript/TypeScript 代码
• 自动提取并返回 Cloudflare 生成的 URL（例如，https://worker-name.username.workers.dev）
• 返回 Worker ID 和配置

对话示例：

User: "Set up and deploy a new cloudflare worker container sandbox named 'api-handler' and return the URL"
Claude: [Deploys worker using bun scripts/workers.ts deploy api-handler ./worker.js]
       Returns URL: https://api-handler.username.workers.dev

退出代码：

• 0：成功——Worker 已部署并返回 URL
• 1：失败——查看错误消息了解详情

性能：部署通常会在 2–5 秒内完成

创建和使用 KV Storage

创建 KV 命名空间并存储数据：

# Create namespace
bun scripts/kv-storage.ts create-namespace user-sessions
# Returns: Namespace ID (e.g., abc123def456)
# Save this ID for binding to workers

# Write key-value pair
bun scripts/kv-storage.ts write <namespace-id> "session:user123" '{"userId":"123","token":"abc"}'

# Read value
bun scripts/kv-storage.ts read <namespace-id> "session:user123"
# Returns: {"userId":"123","token":"abc"}

# List all keys (useful for debugging)
bun scripts/kv-storage.ts list-keys <namespace-id>

# Delete a key
bun scripts/kv-storage.ts delete <namespace-id> "session:user123"

重要提示：KV Storage 使用最终一致性。写入的数据可能需要最多 60 秒才能传播到全球。若要立即读取，请使用写入数据时所在的同一边缘位置。

创建 R2 存储桶并上传文件

创建 R2 存储桶并管理对象：

# Create bucket
bun scripts/r2-storage.ts create-bucket media-assets

# Upload file
bun scripts/r2-storage.ts upload media-assets ./images/logo.png logo.png

# List objects
bun scripts/r2-storage.ts list-objects media-assets

# Download object
bun scripts/r2-storage.ts download media-assets logo.png ./downloaded-logo.png

部署到 Cloudflare Pages

将静态站点或应用部署到 Pages：

# Create Pages project (or get existing project info)
bun scripts/pages.ts deploy my-app ./dist
# Returns: https://my-app.pages.dev

# Set environment variable
bun scripts/pages.ts set-env my-app API_URL https://api.example.com

# Set environment variable for specific environment
bun scripts/pages.ts set-env my-app DEBUG true --env preview

# Get deployment URL
bun scripts/pages.ts get-url my-app

自动提取 URL：Pages 脚本会自动从部署响应中提取并返回 Cloudflare 生成的 URL（例如，https://my-app.pages.dev）。

注意：API 会创建项目结构，但若要实际上传文件，需要使用 Wrangler CLI：

bunx wrangler pages deploy ./dist --project-name=my-app

原理：此技能会创建/验证 Pages 项目并返回 URL。首次部署文件时，Wrangler 会处理复杂的多部分上传流程。

配置 DNS 和路由

创建 DNS 记录并配置 Worker 路由：

# Create DNS A record
bun scripts/dns-routes.ts create-dns example.com A api 192.168.1.1

# Route pattern to worker
bun scripts/dns-routes.ts create-route example.com "*.example.com/api/*" api-handler

常见工作流

多服务设置

设置包含 Worker、KV Storage 和 R2 存储桶的完整应用：

1. 创建用于缓存的 KV 命名空间

   bun scripts/kv-storage.ts create-namespace app-cache
   

2. 创建用于媒体文件的 R2 存储桶

   bun scripts/r2-storage.ts create-bucket app-media
   

3. 部署带有绑定的 Worker

   bun scripts/workers.ts deploy app-worker ./worker.js --kv-binding app-cache --r2-binding app-media
   

4. 配置路由

   bun scripts/dns-routes.ts create-route example.com "example.com/*" app-worker
   

更新 Worker 配置

更新现有 Worker 的代码或绑定：

# Update worker code
bun scripts/workers.ts update worker-name ./new-worker-script.js

# Get worker details
bun scripts/workers.ts get worker-name

# List all workers
bun scripts/workers.ts list

KV 批量操作

对 KV Storage 执行批量操作：

# Bulk write from JSON file
bun scripts/kv-storage.ts bulk-write namespace-name ./data.json

# Delete multiple keys
bun scripts/kv-storage.ts bulk-delete namespace-name key1 key2 key3

错误处理

缺少 API 密钥

如果缺少 .env 文件或未设置 CLOUDFLARE_API_KEY：

Error: CLOUDFLARE_API_KEY not found in environment

Solution: Create .env file in project root:
  echo "CLOUDFLARE_API_KEY=your_token_here" > .env

权限无效

如果 API 令牌缺少所需权限：

Error: Insufficient permissions for Workers deployment

Required: Workers Scripts: Edit
Current: Workers Scripts: Read

Solution: Update token permissions at:
  https://dash.cloudflare.com/profile/api-tokens

API 速率限制

如果请求过多：

Error: Rate limit exceeded (429)

Solution: Retry automatically with exponential backoff (3 attempts)

网络问题

如果无法访问 API：

Error: Failed to connect to Cloudflare API

Solution: Check internet connection and retry

最佳实践

安全性：

• 切勿提交 .env 文件，务必将其添加到 .gitignore
• 使用基于令牌的身份验证（而非 API 密钥）
• 定期轮换令牌（建议每 90 天一次）
• 遵循最小权限原则：仅授予所需权限
• 通过 Wrangler CLI 存储机密：wrangler secret put SECRET_NAME

性能：

• 将 Workers 部署到尽可能靠近用户的位置以降低延迟（它们运行在 Cloudflare 边缘节点）
• 对频繁读取的数据使用 KV 存储（不适用于频繁写入的数据）
• 大型文件使用 R2（KV 的单个键有 25 MB 限制）
• 启用缓存，并设置适当的 TTL
• 将 Worker 脚本控制在 1 MB 以下，以缩短冷启动时间

开发工作流：

• 先在本地测试：使用 wrangler dev 进行本地测试
• 在生产环境之前使用预发布环境
• 更新令牌后验证凭据：bun scripts/validate-api-key.ts
• 监控 Worker 日志：wrangler tail worker-name
• 为 Workers 添加版本号：使用 api-v1、api-v2 这样的名称

命名约定：

• Workers：使用描述性名称（例如，使用 user-auth-worker，而非 worker1）
• KV 命名空间：注明用途（例如，app-sessions、api-cache）
• R2 存储桶：使用小写字母和连字符（例如，media-assets-prod）
• 在整个基础设施中保持命名一致

资源管理：

• 删除未使用的 Workers、命名空间和存储桶
• 在 Cloudflare 仪表板中监控用量
• 免费套餐限制：Workers 每天 100,000 次请求
• 设置账单提醒，避免意外支出

高级用法

有关以下高级场景的信息：

• 复杂路由配置
• 多区域部署
• 自定义域名设置
• Worker 间通信
• Durable Objects 集成
• 批量操作和迁移

请参阅 examples.md，了解完整示例和模式。

脚本参考

所有脚本均位于 ~/.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 部署失败，发生未知错误”

症状：部署命令以错误代码 1 退出，但没有显示具体错误消息

解决方案：

1. 检查脚本语法：node --check ./worker.js
2. 确认文件存在：ls -lh ./worker.js
3. 重新验证 API 密钥：bun scripts/validate-api-key.ts --no-cache
4. 检查 Worker 名称是否有效（只能包含字母数字字符、连字符和下划线）

---

问题：“未找到 KV 命名空间”

症状：尝试读取或写入命名空间时出错

解决方案：

1. 列出所有命名空间：bun scripts/kv-storage.ts list-namespaces
2. 确认命令中使用的是命名空间 ID（而非名称）
3. 检查命名空间是否已被删除
4. 确保 API 令牌具有 KV Storage 权限

---

问题：“R2 存储桶已存在”或“存储桶名称已被占用”

症状：无法使用所选名称创建存储桶

解决方案：

1. 存储桶名称在所有 Cloudflare 账户中必须全球唯一
2. 尝试使用更具体的名称：例如用 my-app-media-2024 替代 media
3. 使用现有存储桶：bun scripts/r2-storage.ts list-buckets
4. 名称必须为 3-63 个字符，且只能包含小写字母、数字和连字符

---

问题：“Pages 部署超时”或“部署待处理”

症状：部署未完成，始终处于待处理状态

解决方案：

1. 检查部署状态：bun scripts/pages.ts list-deployments project-name
2. 在控制面板中查看：https://dash.cloudflare.com/pages
3. 大型部署（>1000 个文件）可能需要 5-10 分钟
4. 如果卡住，请取消并重试：删除项目并重新创建

---

问题：“DNS 记录创建失败”

症状：无法创建 DNS 记录或路由

解决方案：

1. 确认区域存在：bun scripts/dns-routes.ts list-zones
2. 确保域名已添加到 Cloudflare 且处于活动状态
3. 检查名称服务器是否指向 Cloudflare：dig NS yourdomain.com
4. 确认 API 令牌具有 Zone > DNS > Edit 权限

---

问题：“超出 API 速率限制（429）”

症状：命令因“请求过多”而失败

解决方案：

1. 脚本会自动以指数退避方式重试
2. 手动重试前等待 1-2 分钟
3. 减少并发操作
4. 速率限制：每 5 分钟 1200 个请求

---

问题：“环境中未找到 CLOUDFLARE_API_KEY”

症状：命令立即因环境错误而失败

解决方案：

1. 在项目根目录（而非 skill 目录）中创建 .env 文件
2. 检查文件内容：cat .env | grep CLOUDFLARE_API_KEY
3. 确保没有多余空格：CLOUDFLARE_API_KEY=token（= 两侧不能有空格）
4. 从 .env 所在的项目根目录运行命令

快速修复：

cd /path/to/your/project
echo "CLOUDFLARE_API_KEY=your_token_here" > .env
bun scripts/validate-api-key.ts

安全说明

• API 密钥绝不会被记录或显示在输出中
• 所有 API 请求均使用 HTTPS
• API 调用前会验证用户输入
• 破坏性操作（删除）需要确认
• 权限会缓存 24 小时，以尽量减少令牌暴露

其他资源

• Cloudflare API 文档：https://developers.cloudflare.com/api/
• Workers 文档：https://developers.cloudflare.com/workers/
• KV Storage 指南：https://developers.cloudflare.com/kv/
• R2 Storage 指南：https://developers.cloudflare.com/r2/
• Pages 文档：https://developers.cloudflare.com/pages/