Cloudflare管理器 cloudflare-manager

---

name: cloudflare-manager description: 全面的Cloudflare账户管理，用于部署Workers、KV存储、R2、Pages、DNS和路由。适用于部署cloudflare服务、管理worker容器、配置KV/R2存储或设置DNS/路由。需要在.env中设置CLOUDFLARE_API_KEY，并安装Bun运行时及其依赖。 license: MIT

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  # 可选，自动检测
   

   获取API令牌：

   • 访问 https://dash.cloudflare.com/profile/api-tokens
   • 点击“创建令牌”
   • 使用“编辑Cloudflare Workers”模板（或创建自定义令牌）
   • 所需权限：
     • 账户 > Workers脚本 > 编辑
     • 账户 > Workers KV存储 > 编辑
     • 账户 > Workers R2存储 > 编辑
     • 账户 > Cloudflare Pages > 编辑
     • 区域 > DNS > 编辑（如果使用自定义域名）

3. 验证凭证

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

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

   预期输出：

   ✅ API密钥有效！
   ℹ️  令牌状态：活跃
   ℹ️  账户：您的账户名称（abc123...）
   
   🔑 授予的权限：
     ✅ Workers脚本：编辑
     ✅ Workers KV存储：编辑
     ✅ Workers R2存储：编辑
   

   验证故障排除：

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

当前API权限

<!-- PERMISSIONS_START --> 运行bun scripts/validate-api-key.ts以用当前权限填充此部分。 <!-- PERMISSIONS_END -->

快速入门指南

部署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和配置

示例对话：

用户：“设置并部署一个名为'api-handler'的新cloudflare worker容器沙箱，并返回URL”
Claude: [使用bun scripts/workers.ts deploy api-handler ./worker.js部署worker]
       返回URL: https://api-handler.username.workers.dev

退出代码：

• 0：成功 - worker部署并返回URL
• 1：失败 - 检查错误消息以获取详情

性能：部署通常需2-5秒完成

创建和使用KV存储

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

# 创建命名空间
bun scripts/kv-storage.ts create-namespace user-sessions
# 返回：命名空间ID（例如abc123def456）
# 保存此ID以绑定到workers

# 写入键值对
bun scripts/kv-storage.ts write <namespace-id> "session:user123" '{"userId":"123","token":"abc"}'

# 读取值
bun scripts/kv-storage.ts read <namespace-id> "session:user123"
# 返回: {"userId":"123","token":"abc"}

# 列出所有键（用于调试）
bun scripts/kv-storage.ts list-keys <namespace-id>

# 删除键
bun scripts/kv-storage.ts delete <namespace-id> "session:user123"

重要：KV存储使用最终一致性。写入可能需最多60秒才能全局传播。立即读取时，使用写入数据的同一边缘位置。

创建R2桶并上传文件

创建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

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

# 创建Pages项目（或获取现有项目信息）
bun scripts/pages.ts deploy my-app ./dist
# 返回：https://my-app.pages.dev

# 设置环境变量
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

# 获取部署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路由：

# 创建DNS A记录
bun scripts/dns-routes.ts create-dns example.com A api 192.168.1.1

# 路由模式到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的代码或绑定：

# 更新worker代码
bun scripts/workers.ts update worker-name ./new-worker-script.js

# 获取worker详情
bun scripts/workers.ts get worker-name

# 列出所有workers
bun scripts/workers.ts list

批量KV操作

对KV存储执行批量操作：

# 从JSON文件批量写入
bun scripts/kv-storage.ts bulk-write namespace-name ./data.json

# 删除多个键
bun scripts/kv-storage.ts bulk-delete namespace-name key1 key2 key3

错误处理

缺少API密钥

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

错误: 环境中未找到CLOUDFLARE_API_KEY

解决方案: 在项目根目录创建.env文件：
  echo "CLOUDFLARE_API_KEY=your_token_here" > .env

无效权限

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

错误: Workers部署权限不足

所需: Workers脚本: 编辑
当前: Workers脚本: 读取

解决方案: 在以下网址更新令牌权限：
  https://dash.cloudflare.com/profile/api-tokens

API速率限制

如果请求过多：

错误: 速率限制超出（429）

解决方案: 使用指数退避自动重试（3次尝试）

网络问题

如果API无法连接：

错误: 连接Cloudflare API失败

解决方案: 检查网络连接并重试

最佳实践

安全：

• 切勿提交.env文件 - 始终添加到.gitignore
• 使用基于令牌的认证（而非API密钥）
• 定期轮换令牌（建议每90天）
• 使用最小权限原则：仅授予所需权限
• 通过Wrangler CLI存储机密：wrangler secret put SECRET_NAME

性能：

• 部署workers以最小化延迟（它们在Cloudflare边缘运行）
• 使用KV存储用于频繁读取的数据（非频繁写入）
• 使用R2用于大文件（KV每键限制25MB）
• 启用具有适当TTL的缓存
• 保持worker脚本低于1MB以实现更快冷启动

开发工作流：

• 首先本地测试：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间通信
• 耐用对象集成
• 批量操作和迁移

参见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存储权限

---

问题：“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令牌具有区域 > DNS > 编辑权限

---

问题：“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存储指南：https://developers.cloudflare.com/kv/
• R2存储指南：https://developers.cloudflare.com/r2/
• Pages文档：https://developers.cloudflare.com/pages/