# Cloudflare 管理器全面的 Cloudflare 服务管理技能，支持部署和配置 Workers、KV 存储、R2 存储桶、页面、DNS 记录和路由。自动验证 API 凭据、提取部署 URL 并提供可操作的错误消息。 ## 初始设置第一次使用该技能之前： 1. **安装依赖项** cd ~/.claude/skills/cloudflare-manager 包子安装 2. **配置API密钥** 在项目根目录中创建一个“.env”文件： CLOUDFLARE_API_KEY=your_api_token_here CLOUDFLARE_ACCOUNT_ID=your_account_id # 可选，自动检测 **获取您的 API 令牌**： *访问 * 点击“创建令牌” * 使用“编辑 Cloudflare Workers”模板（或创建自定义令牌） * 所需权限： * 账户 > Workers 脚本 > 编辑 * 账户 > Workers KV 存储 > 编辑 * 账户 > Workers R2 存储 > 编辑 * 帐户 > Cloudflare 页面 > 编辑 * 区域 > DNS > 编辑（如果使用自定义域） 3. **验证凭证** 运行验证以验证您的 API 密钥并检查权限： cd ~/.claude/skills/cloudflare-manager 面包脚本/validate-api-key.ts **预期输出**： ✅ API 密钥有效！ ℹ️ 代币状态：活跃 ℹ️帐户：您的帐户名称（abc123...） 🔑 授予权限： ✅ Workers 脚本：编辑 ✅ Workers KV 存储：编辑 ✅ Workers R2 存储：编辑 **故障排除验证**： * 如果验证失败并显示 401/403：检查 `.env` 中的 API 令牌是否正确 * 如果验证因网络错误而失败：检查互联网连接 * 使用 `--no-cache` 标志强制进行新验证：`bun script/validate-api-key.ts --no-cache` ## 当前 API 权限运行“bun scripts/validate-api-key.ts”以使用您当前的权限填充此部分。 ## 快速入门指南 ### 部署工作容器要部署新的工作容器沙箱： # 使用技能 Bun scripts/workers.ts 部署worker-name ./worker-script.js **发生了什么**： * 创建新的工作容器 * 部署 JavaScript/TypeScript 代码 * 自动提取并返回 Cloudflare 生成的 URL（例如，`https://worker-name.username.workers.dev`） * 返回worker ID和配置 **对话示例**：用户：“设置并部署一个名为‘api-handler’的新 cloudflare 工作容器沙箱并返回 URL” Claude：[使用bunscripts/workers.ts部署api-handler./worker.js部署worker] 返回 URL：https://api-handler.username.workers.dev **退出代码**： * `0`: 成功 - 部署工作线程并返回 URL * `1`：失败 - 检查错误消息以获取详细信息 **性能**：部署通常在 2-5 秒内完成 ### 创建并使用KV存储创建KV命名空间并存储数据： # 创建命名空间 Bun 脚本/kv-storage.ts 创建命名空间用户会话 # 返回：命名空间 ID（例如 abc123def456） # 保存此ID以绑定到worker # 写入键值对 Bun script/kv-storage.ts write "session:user123" '{"userId":"123","token":"abc"}' # 读取值 Bun scripts/kv-storage.ts 读取 “session:user123” # 返回：{"userId":"123","token":"abc"} # 列出所有键（对于调试有用） Bun 脚本/kv-storage.ts list-keys # 删除一个键 Bun scripts/kv-storage.ts 删除 "session:user123" **重要**：KV 存储使用最终一致性。写入操作最多可能需要 60 秒才能在全球范围内传播。对于立即读取，请使用写入数据的同一边缘位置。 ### 创建R2桶并上传文件创建 R2 存储桶并管理对象： # 创建桶 Bun 脚本/r2-storage.ts create-bucket 媒体资产 # 上传文件 Bun scripts/r2-storage.ts 上传媒体资产 ./images/logo.png logo.png # 列出对象 Bun 脚本/r2-storage.ts 列表对象媒体资产 # 下载对象 Bun 脚本/r2-storage.ts 下载媒体资产 logo.png ./downloaded-logo.png ### 部署到 Cloudflare 页面要将静态站点或应用程序部署到页面： # 创建 Pages 项目（或获取现有项目信息） Bun 脚本/pages.ts 部署 my-app ./dist # 返回：https://my-app.pages.dev # 设置环境变量 Bun scripts/pages.ts set-env my-app API_URL https://api.example.com # 设置特定环境的环境变量包脚本/pages.ts set-env my-app DEBUG true --env Preview # 获取部署地址 Bun 脚本/pages.ts get-url my-app **自动提取的 URL** ：Pages 脚本自动从部署响应中提取并返回 Cloudflare 生成的 URL（例如，`https://my-app.pages.dev`）。 **注意**：API 创建项目结构，但对于实际文件上传，您需要 Wrangler CLI： Bunx Wrangler 页面部署 ./dist --project-name=my-app **为什么有效**：该技能创建/验证页面项目并返回 URL。对于文件的初始部署，Wrangler 处理复杂的分段上传过程。 ### 配置 DNS 和路由创建 DNS 记录并配置工作路由： # 创建DNS A记录包脚本/dns-routes.ts create-dns example.com A api 192.168.1.1 # 将模式路由到worker Bun 脚本/dns-routes.ts create-route example.com "*.example.com/api/*" api-handler ## 常见工作流程 ### 多服务设置要设置包含工作程序、KV 存储和 R2 存储桶的完整应用程序： 1. **创建KV命名空间用于缓存** Bun 脚本/kv-storage.ts 创建命名空间应用程序缓存 2. **为媒体创建R2存储桶** Bun 脚本/r2-storage.ts create-bucket 应用程序媒体 3. **使用绑定部署工作人员** Bun 脚本/workers.ts 部署应用程序工作人员 ./worker.js --kv-绑定应用程序缓存 --r2-绑定应用程序媒体 4. **配置路线** 包脚本/dns-routes.ts create-route example.com“example.com/*”app-worker ### 更新工作配置要更新现有工作人员的代码或绑定： # 更新工人代码面包脚本/workers.ts更新工人名称./new-worker-script.js # 获取工人详细信息 Bun scripts/workers.ts 获取工人名称 # 列出所有工人 Bun 脚本/workers.ts 列表 ### 批量 KV 操作对KV存储执行批量操作： # 从 JSON 文件批量写入 Bun 脚本/kv-storage.ts 批量写入命名空间名称 ./data.json # 删除多个key Bun 脚本/kv-storage.ts 批量删除命名空间名称 key1 key2 key3 ## 错误处理 ### 缺少 API 密钥如果缺少`.env`文件或未设置`CLOUDFLARE_API_KEY`：错误：在环境中找不到 CLOUDFLARE_API_KEY 解决方案：在项目根目录中创建 .env 文件： echo "CLOUDFLARE_API_KEY=your_token_here" > .env ### 无效权限如果 API 令牌缺少所需的权限：错误：没有足够的权限来部署 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` **性能**： * 部署工作人员以最大限度地减少延迟（他们在 Cloudflare 边缘运行） * 对于经常读取的数据（不经常写入的数据）使用KV存储 * 对于大文件使用 R2（KV 每个密钥有 25MB 限制） * 使用适当的 TTL 启用缓存 * 将工作脚本保持在 1MB 以下，以实现更快的冷启动 **开发工作流程**： * 先本地测试：`wrangler dev`进行本地测试 * 在生产前使用暂存环境 * 令牌更新后验证凭证：`bunscripts/validate-api-key.ts` * 监控worker日志：`wrangler tailworker-name` * 对您的工作人员进行版本控制：使用“api-v1”、“api-v2”等名称 **命名约定**： * Workers：使用描述性名称（例如“user-auth-worker”而不是“worker1”） * KV 命名空间：包括用途（例如，`app-sessions`、`api-cache`） * R2 存储桶：使用带连字符的小写字母（例如“media-assets-prod”） * 整个基础设施保持一致 **资源管理**： * 删除未使用的worker、命名空间和存储桶 * 在 Cloudflare 仪表板中监控使用情况 * 免费等级限制：工人每天 100,000 个请求 * 设置账单提醒以避免意外 ## 高级用法对于高级场景包括： * 复杂的路由配置 * 多区域部署 * 自定义域名设置 * 工人与工人之间的沟通 * 耐用对象集成 * 批量操作和迁移有关全面的示例和模式，请参阅 [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 记录和工作路由 * **utils.ts** ：用于 API 调用和错误处理的共享实用程序 ## 模板入门模板位于 `~/.claude/skills/cloudflare-manager/templates/` 中： * **worker-template.js** ：带有获取处理程序的基本工作模板 * **wrangler.toml.template** ：Wrangler 配置模板 ## 故障排除 ### 常见问题和解决方案 **问题**：“工作部署失败，出现未知错误” **症状**：部署命令退出，错误代码为 1，无具体错误消息 **解决方案**： 1.检查脚本语法：`node --check ./worker.js` 2.验证文件是否存在：`ls -lh ./worker.js` 3. 重新验证 API 密钥：`bun templates/validate-api-key.ts --no-cache` 4. 检查工人姓名是否有效（仅限字母数字、连字符、下划线） ** ** **问题**：“未找到 KV 命名空间” **症状**：尝试读取/写入命名空间时出错 **解决方案**： 1. 列出所有命名空间：`bun script/kv-storage.ts list-namespaces` 2. 验证您在命令中使用命名空间 ID（而不是名称） 3.检查命名空间没有被删除 4. 确保API token具有KV存储权限 ** ** **问题**：“R2 存储桶已存在”或“存储桶名称已被占用” **症状**：无法创建具有所选名称的存储桶 **解决方案**： 1. 存储桶名称在所有 Cloudflare 账户中必须是全局唯一的 2. 尝试使用更具体的名称：“my-app-media-2024”而不是“media” 3. 使用现有存储桶：`bun templates/r2-storage.ts list-buckets` 4. 名称必须为 3-63 个字符，仅限小写字母/数字/连字符 ** ** **问题**：“页面部署超时”或“部署待处理” **症状**：部署未完成，处于挂起状态 **解决方案**： 1. 检查部署状态：`bun script/pages.ts list-deployments project-name` 2. 在仪表板中查看： 3. 大型部署（>1000 个文件）可能需要 5-10 分钟 4. 如果卡住则取消并重试：删除项目并重新创建 ** ** **问题**：“DNS 记录创建失败” **症状**：无法创建 DNS 记录或路由 **解决方案**： 1. 验证区域是否存在：`bun script/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 /路径/到/您的/项目 echo "CLOUDFLARE_API_KEY=your_token_here" > .env 面包脚本/validate-api-key.ts ## 安全说明 * API 密钥永远不会记录或显示在输出中 * 所有API请求均使用HTTPS * 在 API 调用之前验证用户输入 * 破坏性操作（删除）需要确认 * 权限缓存 24 小时，以最大程度地减少令牌暴露 ## 其他资源 * Cloudflare API 文档： * 工人文档： * KV存储指南： * R2 存储指南： * 页面文档：

Cloudflare 管理器

包含技能