cloudflare-manager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloudflare Manager

Cloudflare 管理器

Comprehensive Cloudflare service management skill that enables deployment and configuration of Workers, KV Storage, R2 buckets, Pages, DNS records, and routing. Automatically validates API credentials, extracts deployment URLs, and provides actionable error messages.

这是一款全面的Cloudflare服务管理工具，支持部署和配置Workers、KV Storage、R2存储桶、Pages、DNS记录及路由。可自动验证API凭证、提取部署URL，并提供可操作的错误提示信息。

Initial Setup

初始设置

Before using this skill for the first time:

Install Dependencies

bash

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

Configure API Key
Create a
```
.env
```
file in your project root:
bash
```
CLOUDFLARE_API_KEY=your_api_token_here
CLOUDFLARE_ACCOUNT_ID=your_account_id  # Optional, auto-detected
```
Getting your API token:
- Visit https://dash.cloudflare.com/profile/api-tokens
- Click "Create Token"
- Use "Edit Cloudflare Workers" template (or create custom token)
- Required permissions:
  - Account > Workers Scripts > Edit
  - Account > Workers KV Storage > Edit
  - Account > Workers R2 Storage > Edit
  - Account > Cloudflare Pages > Edit
  - Zone > DNS > Edit (if using custom domains)

Validate Credentials

Run validation to verify your API key and check permissions:

bash

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

Expected output:

✅ 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

Troubleshooting validation:

If validation fails with 401/403: Check your API token is correct in
```
.env
```
If validation fails with network error: Check internet connection

Use

--no-cache

flag to force fresh validation:

bun scripts/validate-api-key.ts --no-cache

首次使用本工具前，请完成以下步骤：

安装依赖

bash

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

配置API密钥
在项目根目录创建
```
.env
```
文件：
bash
```
CLOUDFLARE_API_KEY=your_api_token_here
CLOUDFLARE_ACCOUNT_ID=your_account_id  # 可选，会自动检测
```
获取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（若使用自定义域名）

验证凭证

运行验证命令，确认API密钥有效性及权限：

bash

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

预期输出:

✅ API密钥有效！
ℹ️  令牌状态：active
ℹ️  账户：你的账户名称 (abc123...)

🔑 已授予权限:
  ✅ 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

Current API Permissions

当前API权限

Run

bun scripts/validate-api-key.ts

to populate this section with your current permissions.

运行

bun scripts/validate-api-key.ts

可填充当前权限信息至本区域。

Quick Start Guide

快速入门指南

Deploy a Worker Container

部署Worker容器

To deploy a new worker container sandbox:

bash

undefined

部署新的Worker容器沙箱：

bash

undefined

Using the skill

使用本工具

bun scripts/workers.ts deploy worker-name ./worker-script.js


**What happens**:
- Creates new worker container
- Deploys JavaScript/TypeScript code
- Automatically extracts and returns Cloudflare-generated URL (e.g., `https://worker-name.username.workers.dev`)
- Returns worker ID and configuration

**Example conversation**:

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


**Exit codes**:
- `0`: Success - worker deployed and URL returned
- `1`: Failure - check error message for details

**Performance**: Deployment typically completes in 2-5 seconds

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

Create and Use KV Storage

创建并使用KV存储

To create a KV namespace and store data:

bash

undefined

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

bash

undefined

Create namespace

创建命名空间

bun scripts/kv-storage.ts create-namespace user-sessions

Returns: Namespace ID (e.g., abc123def456)

返回：命名空间ID（例如：abc123def456）

Save this ID for binding to workers

保存此ID用于绑定Worker

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"}

返回：{"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"


**Important**: KV storage uses eventual consistency. Writes may take up to 60 seconds to propagate globally. For immediate reads, use the same edge location where you wrote the data.

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


**重要提示**: KV存储采用最终一致性模型。写入操作可能需要最多60秒才能在全球节点同步。如需立即读取，请在写入的边缘节点进行操作。

Create R2 Bucket and Upload Files

创建R2存储桶并上传文件

To create an R2 bucket and manage objects:

bash

undefined

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

bash

undefined

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

undefined

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

undefined

Deploy to Cloudflare Pages

部署至Cloudflare Pages

To deploy a static site or application to Pages:

bash

undefined

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

bash

undefined

Create Pages project (or get existing project info)

创建Pages项目（或获取现有项目信息）

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

Returns: https://my-app.pages.dev

返回：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

获取部署URL

bun scripts/pages.ts get-url my-app


**Auto-extracted URLs**: The Pages script automatically extracts and returns the Cloudflare-generated URL (e.g., `https://my-app.pages.dev`) from the deployment response.

**Note**: The API creates the project structure, but for actual file uploads, you'll need Wrangler CLI:
```bash
bunx wrangler pages deploy ./dist --project-name=my-app

Why this works: The skill creates/verifies the Pages project and returns the URL. For the initial deployment with files, Wrangler handles the complex multipart upload process.

bun scripts/pages.ts get-url my-app


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

**注意**: 本工具会创建/验证Pages项目并返回URL。若需上传实际文件，需使用Wrangler CLI：
```bash
bunx wrangler pages deploy ./dist --project-name=my-app

工作原理: 本工具负责创建/验证Pages项目并返回URL。初始文件上传的复杂分块流程由Wrangler处理。

Configure DNS and Routes

配置DNS及路由

To create DNS records and configure worker routes:

bash

undefined

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

bash

undefined

Create DNS A record

创建DNS A记录

bun scripts/dns-routes.ts create-dns example.com A api 192.168.1.1

Route pattern to worker

将路由规则绑定至Worker

bun scripts/dns-routes.ts create-route example.com ".example.com/api/" api-handler

undefined

bun scripts/dns-routes.ts create-route example.com ".example.com/api/" api-handler

undefined

Common Workflows

常见工作流

Multi-Service Setup

多服务部署

To set up a complete application with worker, KV storage, and R2 bucket:

Create KV namespace for caching

bash

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

Create R2 bucket for media

bash

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

Deploy worker with bindings

bash

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

Configure route

bash

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

搭建包含Worker、KV存储及R2存储桶的完整应用：

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

bash

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

创建用于媒体存储的R2存储桶

bash

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

部署带有绑定的Worker

bash

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

配置路由

bash

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

Update Worker Configuration

更新Worker配置

To update an existing worker's code or bindings:

bash

undefined

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

bash

undefined

Update worker code

更新Worker代码

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

Get worker details

获取Worker详情

bun scripts/workers.ts get worker-name

List all workers

列出所有Worker

bun scripts/workers.ts list

undefined

bun scripts/workers.ts list

undefined

Bulk KV Operations

KV批量操作

To perform bulk operations on KV storage:

bash

undefined

对KV存储执行批量操作：

bash

undefined

Bulk write from JSON file

从JSON文件批量写入

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

undefined

bun scripts/kv-storage.ts bulk-delete namespace-name key1 key2 key3

undefined

Error Handling

错误处理

Missing API Key

缺失API密钥

.env

file is missing or

CLOUDFLARE_API_KEY

is not set:

Error: CLOUDFLARE_API_KEY not found in environment

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

若.env文件缺失或未设置

CLOUDFLARE_API_KEY

：

Error: CLOUDFLARE_API_KEY not found in environment

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

Invalid Permissions

权限不足

If API token lacks required permissions:

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: Insufficient permissions for Workers deployment

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

解决方案：访问以下链接更新令牌权限：
  https://dash.cloudflare.com/profile/api-tokens

API Rate Limiting

API速率限制

If too many requests are made:

Error: Rate limit exceeded (429)

Solution: Retry automatically with exponential backoff (3 attempts)

若请求次数过多：

Error: Rate limit exceeded (429)

解决方案：自动通过指数退避重试（最多3次）

Network Issues

网络问题

If API is unreachable:

Error: Failed to connect to Cloudflare API

Solution: Check internet connection and retry

若无法连接到Cloudflare API：

Error: Failed to connect to Cloudflare API

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

Best Practices

最佳实践

Security:

Never commit
```
.env
```
files - always add to
```
.gitignore
```
Use token-based authentication (not API keys)
Rotate tokens periodically (every 90 days recommended)
Use least-privilege principle: only grant required permissions
Store secrets via Wrangler CLI:
```
wrangler secret put SECRET_NAME
```

Performance:

Deploy workers to minimize latency (they run at Cloudflare edge)
Use KV storage for frequently-read data (not frequently-written)
Use R2 for large files (KV has 25MB limit per key)
Enable caching with appropriate TTLs
Keep worker scripts under 1MB for faster cold starts

Development Workflow:

Test locally first:
```
wrangler dev
```
for local testing
Use staging environment before production
Validate credentials after token updates:
```
bun scripts/validate-api-key.ts
```
Monitor worker logs:
```
wrangler tail worker-name
```
Version your workers: use names like
```
api-v1
```
,
```
api-v2
```

Naming Conventions:

Workers: Use descriptive names (e.g.,
```
user-auth-worker
```
not
```
worker1
```
)
KV namespaces: Include purpose (e.g.,
```
app-sessions
```
,
```
api-cache
```
)
R2 buckets: Use lowercase with hyphens (e.g.,
```
media-assets-prod
```
)
Be consistent across your infrastructure

Resource Management:

Delete unused workers, namespaces, and buckets
Monitor usage in Cloudflare dashboard
Free tier limits: 100,000 requests/day for Workers
Set up billing alerts to avoid surprises

安全:

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

性能:

部署Worker时选择最优边缘节点以降低延迟
KV存储适用于频繁读取的数据（不适用于频繁写入）
R2适用于大文件存储（KV每个键的大小限制为25MB）
启用缓存并设置合适的TTL
保持Worker脚本大小在1MB以下以加快冷启动速度

开发流程:

先在本地测试：使用
```
wrangler dev
```
进行本地调试
上线前先在 staging 环境测试
更新令牌后重新验证凭证：
```
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控制台监控资源使用情况
免费版限制：Workers每日100,000次请求
设置账单预警避免意外支出

Advanced Usage

高级用法

For advanced scenarios including:

Complex routing configurations
Multi-region deployments
Custom domain setup
Worker-to-worker communication
Durable Objects integration
Bulk operations and migrations

See examples.md for comprehensive examples and patterns.

针对以下高级场景：

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

请查看examples.md获取完整示例及实现模式。

Script Reference

脚本参考

All scripts are located in

~/.claude/skills/cloudflare-manager/scripts/

validate-api-key.ts: Validate API credentials and display permissions
workers.ts: Deploy, update, and manage Workers
kv-storage.ts: Create and manage KV namespaces and key-value pairs
r2-storage.ts: Create and manage R2 buckets and objects
pages.ts: Deploy and configure Cloudflare Pages projects
dns-routes.ts: Configure DNS records and worker routes
utils.ts: Shared utilities for API calls and error handling

所有脚本位于

~/.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调用与错误处理的共享工具类

Templates

模板

Starter templates are available in

~/.claude/skills/cloudflare-manager/templates/

worker-template.js: Basic worker template with fetch handler
wrangler.toml.template: Wrangler configuration template

启动模板位于

~/.claude/skills/cloudflare-manager/templates/

worker-template.js: 包含fetch处理器的基础Worker模板
wrangler.toml.template: Wrangler配置模板

Troubleshooting

故障排查

Common Issues and Solutions

常见问题及解决方案

Issue: "Worker deployment failed with unknown error"

Symptoms: Deployment command exits with error code 1, no specific error message

Solutions:

Check script syntax:
```
node --check ./worker.js
```
Verify file exists:
```
ls -lh ./worker.js
```

Re-validate API key:

bun scripts/validate-api-key.ts --no-cache

Check worker name is valid (alphanumeric, hyphens, underscores only)

Issue: "KV namespace not found"

Symptoms: Error when trying to read/write to namespace

Solutions:

List all namespaces:

bun scripts/kv-storage.ts list-namespaces

Verify you're using namespace ID (not name) in commands
Check namespace wasn't deleted
Ensure API token has KV Storage permissions

Issue: "R2 bucket already exists" or "Bucket name taken"

Symptoms: Cannot create bucket with chosen name

Solutions:

Bucket names must be globally unique across all Cloudflare accounts
Try a more specific name:
```
my-app-media-2024
```
instead of
```
media
```
Use existing bucket:
```
bun scripts/r2-storage.ts list-buckets
```
Names must be 3-63 characters, lowercase letters/numbers/hyphens only

Issue: "Pages deployment timeout" or "Deployment pending"

Symptoms: Deployment doesn't complete, stays in pending state

Solutions:

Check deployment status:

bun scripts/pages.ts list-deployments project-name

View in dashboard: https://dash.cloudflare.com/pages
Large deployments (>1000 files) may take 5-10 minutes
Cancel and retry if stuck: Delete project and recreate

Issue: "DNS record creation failed"

Symptoms: Cannot create DNS records or routes

Solutions:

Verify zone exists:
```
bun scripts/dns-routes.ts list-zones
```
Ensure domain is added to Cloudflare and active
Check nameservers point to Cloudflare:
```
dig NS yourdomain.com
```
Verify API token has Zone > DNS > Edit permission

Issue: "API rate limit exceeded (429)"

Symptoms: Commands fail with "Too many requests"

Solutions:

Scripts automatically retry with exponential backoff
Wait 1-2 minutes before retrying manually
Reduce concurrent operations
Rate limits: 1200 requests per 5 minutes

Issue: "CLOUDFLARE_API_KEY not found in environment"

Symptoms: Commands fail immediately with environment error

Solutions:

Create
```
.env
```
file in project root (not skill directory)
Verify file content:
```
cat .env | grep CLOUDFLARE_API_KEY
```
Ensure no extra spaces:
```
CLOUDFLARE_API_KEY=token
```
(no spaces around
```
=
```
)
Run commands from project root where
```
.env
```
exists

Quick Fix:

bash

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

问题: "Worker部署失败，未知错误"

症状: 部署命令退出并返回错误码1，无具体错误信息

解决方案:

检查脚本语法：
```
node --check ./worker.js
```
验证文件存在：
```
ls -lh ./worker.js
```

重新验证API密钥：

bun scripts/validate-api-key.ts --no-cache

检查Worker名称是否合法（仅允许字母、数字、连字符及下划线）

问题: "KV命名空间未找到"

症状: 读取/写入KV时返回错误

解决方案:

列出所有命名空间：

bun scripts/kv-storage.ts list-namespaces

确认命令中使用的是命名空间ID（而非名称）
检查命名空间是否已被删除
确认API令牌拥有KV Storage权限

问题: "R2存储桶已存在"或 "存储桶名称已被占用"

症状: 无法使用指定名称创建存储桶

解决方案:

存储桶名称在所有Cloudflare账户中需全局唯一
使用更具体的名称：例如
```
my-app-media-2024
```
而非
```
media
```
使用现有存储桶：
```
bun scripts/r2-storage.ts list-buckets
```
名称需为3-63个字符，仅允许小写字母、数字及连字符

问题: "Pages部署超时"或 "部署处于待处理状态"

症状: 部署无法完成，持续处于待处理状态

解决方案:

检查部署状态：

bun scripts/pages.ts list-deployments project-name

在控制台查看：https://dash.cloudflare.com/pages
大型部署（超过1000个文件）可能需要5-10分钟
若部署卡住可取消并重新创建项目

问题: "DNS记录创建失败"

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

解决方案:

验证域名区域是否存在：
```
bun scripts/dns-routes.ts list-zones
```
确认域名已添加至Cloudflare且处于激活状态
检查域名服务器是否指向Cloudflare：
```
dig NS yourdomain.com
```
确认API令牌拥有Zone > DNS > Edit权限

问题: "API速率限制已超出 (429)"

症状: 命令返回"Too many requests"错误

解决方案:

脚本会自动通过指数退避重试
手动重试前等待1-2分钟
减少并发操作数量
速率限制：每5分钟最多1200次请求

问题: "CLOUDFLARE_API_KEY not found in environment"

症状: 命令立即返回环境变量错误

解决方案:

在项目根目录创建.env文件（而非工具目录）
验证文件内容：
```
cat .env | grep CLOUDFLARE_API_KEY
```
确保变量名后无多余空格：
```
CLOUDFLARE_API_KEY=token
```
（
```
=
```
两侧无空格）
在.env文件所在的项目根目录运行命令

快速修复:

bash

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

Security Notes

安全说明

API keys are never logged or displayed in output
All API requests use HTTPS
User inputs are validated before API calls
Destructive operations (delete) require confirmation
Permissions are cached for 24 hours to minimize token exposure

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

Additional Resources

额外资源

Cloudflare API Documentation: https://developers.cloudflare.com/api/
Workers Documentation: https://developers.cloudflare.com/workers/
KV Storage Guide: https://developers.cloudflare.com/kv/
R2 Storage Guide: https://developers.cloudflare.com/r2/
Pages Documentation: https://developers.cloudflare.com/pages/

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/