cloudflare-manager

Cloudflare 管理器

全面的 Cloudflare 服务管理技能，可用于部署和配置 Workers、KV 存储、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，以在本节中填入当前权限。

示例

示例 1：部署新的 Worker API

用户请求：

"Set up a Cloudflare worker for handling API requests and give me the URL"

工作流：

1. 验证 .env 中是否存在 API 凭据
2. 部署 Worker 脚本：

   bun scripts/workers.ts deploy api-handler ./worker.js
   

3. 从响应中提取 Cloudflare 生成的 URL
4. 返回 URL：https://api-handler.username.workers.dev

预期输出：

✅ Worker deployed successfully!
📍 URL: https://api-handler.username.workers.dev
🆔 Worker ID: abc123def456

耗时： 2-5 秒

---

示例 2：完整应用程序栈（Worker + KV + R2）

用户请求：

"Set up a complete Cloudflare application with worker, key-value storage, and file storage"

工作流：

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

   bun scripts/kv-storage.ts create-namespace app-sessions
   # Returns: namespace-id-123
   

2. 创建用于用户上传的 R2 存储桶：

   bun scripts/r2-storage.ts create-bucket app-uploads
   # Returns: Bucket created: app-uploads
   

3. 部署带有绑定的 Worker：

   bun scripts/workers.ts deploy app-api ./worker.js \
     --kv-binding SESSION_STORE=namespace-id-123 \
     --r2-binding UPLOADS=app-uploads
   

4. 配置自定义域名路由：

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

预期输出：

✅ KV namespace created: app-sessions (namespace-id-123)
✅ R2 bucket created: app-uploads
✅ Worker deployed: https://app-api.username.workers.dev
✅ Route configured: api.example.com/* → app-api

总耗时： 8-12 秒

---

示例 3：将静态网站部署到 Pages

用户请求：

"Deploy my static site to Cloudflare Pages"

工作流：

1. 创建 Pages 项目（如果尚不存在）：

   bun scripts/pages.ts deploy my-site ./dist
   

2. 首次部署文件时，使用 Wrangler：

   npx wrangler pages deploy ./dist --project-name=my-site
   

3. 设置环境变量：

   bun scripts/pages.ts set-env my-site API_URL https://api.example.com
   bun scripts/pages.ts set-env my-site DEBUG false --env production
   

预期输出：

✅ Pages project created: my-site
📍 URL: https://my-site.pages.dev
🚀 Deploying files... (via Wrangler)
✅ Deployment complete!
✅ Environment variables set

耗时： 15-30 秒（取决于网站大小）

---

快速入门指南

部署 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 秒内完成

常见陷阱

⚠️ 最关键的问题——遇到问题时请先排查这些：

1. API 令牌权限范围（最常见的失败原因）

问题：权限不足或范围配置不正确的 API 令牌会静默失败并返回 403 错误，导致调试非常困难。

如何避免：

• 在 https://dash.cloudflare.com/profile/api-tokens 创建令牌时，使用 “Edit Cloudflare Workers” 模板——不要使用“Read All”或权限范围不正确的自定义配置
• 最低所需权限范围：
  • Account > Workers Scripts > Edit
  • Account > Workers KV Storage > Edit
  • Account > Workers R2 Storage > Edit
  • Zone > DNS > Edit（仅在使用自定义域名时需要）
• 创建后立即验证令牌：

  bun scripts/validate-api-key.ts
  

  这会准确显示你拥有的权限。每次创建或更新令牌时都要执行此操作。

快速诊断：

# If you see "Insufficient permissions", stop and fix the token:
bun scripts/validate-api-key.ts
# If any required permission shows ❌, update token at:
# https://dash.cloudflare.com/profile/api-tokens

---

2. Wrangler OAuth 端口冲突

问题：wrangler login 使用端口 8976 处理 OAuth 回调。如果另一个 wrangler dev 或 wrangler pages dev 进程已在运行，登录流程会静默失败——浏览器标签页会打开，但始终收不到 OAuth 重定向。

如何避免：

• 运行 wrangler login 前，终止所有其他 Wrangler 进程：

  pkill -f wrangler
  

• 然后运行登录命令：

  wrangler login
  

• 登录完成后，再启动 wrangler dev 或 Pages

原因：Wrangler 不会排队处理 OAuth 回调——第一个绑定端口 8976 的进程会收到回调。如果该进程是开发服务器，登录尝试就会静默失败。

---

3. 部署超时（大型项目）

问题：如果项目过大或网络连接不稳定，Workers 和 Pages 部署会超时。Cloudflare 负载高峰期也可能发生超时。

如何避免：

• Worker 脚本：保持在 1MB 以内（越小，冷启动越快）
• Pages 部署：
  • 包含超过 1000 个文件的项目可能需要 5-10 分钟
  • 使用 .cloudflare/ 忽略模式排除 node_modules、构建缓存等
  • 对于大型部署，直接使用 Wrangler CLI：

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

• 网络：通过稳定的网络连接部署。重试会采用指数退避，通常会自动成功
• 如果一直处于待处理状态：

  bun scripts/pages.ts list-deployments my-app  # Check status
  # If truly stuck, delete and recreate the project
  

---

参考：故障排除指南

有关特定错误消息的详细解决方案，请参阅下方的故障排除部分。

创建并使用 KV 存储

创建 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 存储采用最终一致性。写入的数据可能需要最多 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：

npx 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 存储和 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 存储执行批量操作：

# 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

性能：

• 部署 Worker 以尽可能降低延迟（它们运行在 Cloudflare 边缘节点）
• 使用 KV 存储频繁读取的数据（而非频繁写入的数据）
• 使用 R2 存储大文件（KV 的单个键值上限为 25MB）
• 启用缓存并设置适当的 TTL
• 将 Worker 脚本控制在 1MB 以内，以加快冷启动速度

开发工作流：

• 先在本地测试：使用 wrangler dev 进行本地测试
• 在生产环境部署前先使用暂存环境
• 更新令牌后验证凭据：bun scripts/validate-api-key.ts
• 监控 Worker 日志：wrangler tail worker-name
• 为 Worker 进行版本管理：使用 api-v1、api-v2 之类的名称

命名约定：

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

资源管理：

• 删除未使用的 Worker、命名空间和存储桶
• 在 Cloudflare 控制面板中监控用量
• 免费套餐限额：Worker 每天 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 配置模板

故障排除

快速链接：高优先级问题

如需了解生产环境中遇到的最关键问题，请参阅上文的 常见陷阱：

• API 令牌范围问题 → API 令牌范围
• Wrangler OAuth 失败 → Wrangler OAuth 端口冲突
• 部署超时 → 部署超时

诊断命令

发生故障时的第一步：

# 1. Validate API credentials and permissions
bun scripts/validate-api-key.ts

# 2. List existing resources to check state
bun scripts/workers.ts list
bun scripts/kv-storage.ts list-namespaces
bun scripts/r2-storage.ts list-buckets
bun scripts/pages.ts list-projects

# 3. Check specific resource details
bun scripts/workers.ts get worker-name
bun scripts/pages.ts list-deployments project-name

各步骤的适用场景：

• 步骤 1（验证）：任何命令失败时，都应首先运行此步骤
• 步骤 2（列出）：检查实际存在的资源
• 步骤 3（获取详情）：调查特定资源的状态

常见问题与解决方案

问题：“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. 在项目根目录（而非技能目录）中创建 .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/