Spaces:

HFHash789
/

cfmanager

Sleeping

from cloudflare_manager import CloudflareManager, CloudflareAccount

# 初始化账户
account = CloudflareAccount(
    email="your-email@example.com",
    token="your-api-token"
)
cf = CloudflareManager(account)

# 先创建项目（如果还没有创建）
cf.create_pages_project("my-website", "main")

# 从目录部署（上传所有文件）
cf.deploy_pages_project(
    project_name="my-website",
    directory="./my-site",          # 本地目录路径
    branch="main",                  # 分支名称
    commit_message="Initial deploy"  # 提交信息
)

工作原理 (How It Works)

deploy_pages_project 方法会：

扫描指定目录下的所有文件
计算每个文件的 SHA-256 哈希值
构建 manifest（文件清单）
使用 multipart/form-data 格式上传所有文件
返回部署详情

上传的数据格式

# 内部实现的数据格式
files = [
    ("branch", (None, "main")),
    ("commit_message", (None, "Deploy via API")),
    ("manifest", (None, '{"index.html": "abc123...", "style.css": "def456..."}')),
    ("index.html", ("index.html", file_content, "text/html")),
    ("style.css", ("style.css", file_content, "text/css")),
    # ... 更多文件
]

支持的文件类型

所有常见的 Web 文件类型都支持：

HTML: .html, .htm
CSS: .css
JavaScript: .js, .mjs
图片: .png, .jpg, .jpeg, .gif, .svg, .ico
字体: .woff, .woff2, .ttf, .otf
JSON: .json
文本: .txt, .md

上传文件到 Worker

基本用法

上传 Worker 脚本非常简单：

from cloudflare_manager import CloudflareManager, CloudflareAccount

# 初始化账户
account = CloudflareAccount(
    email="your-email@example.com",
    token="your-api-token"
)
cf = CloudflareManager(account)

# 上传 Worker 脚本
cf.upload_worker(
    script_name="my-worker",
    worker_file="./worker.js"
)

带绑定的高级用法 (Advanced Usage with Bindings)

如果你的 Worker 需要绑定 KV、R2 或其他资源：

# KV 命名空间绑定
bindings = [
    {
        "type": "kv_namespace",
        "name": "MY_KV",
        "namespace_id": "your-kv-namespace-id"
    }
]

cf.upload_worker(
    script_name="my-worker",
    worker_file="./worker.js",
    bindings=bindings
)

Worker 文件示例

创建一个简单的 Worker 文件 worker.js：

// worker.js
export default {
  async fetch(request, env, ctx) {
    return new Response('Hello from Cloudflare Worker!', {
      headers: { 'Content-Type': 'text/plain' }
    });
  }
}

上传的数据格式

# 内部实现
metadata = {
    "main_module": "_worker.js",
    "compatibility_date": "2023-01-01",
    "bindings": []  # 可选的绑定
}

files = {
    'metadata': (None, json.dumps(metadata), 'application/json'),
    '_worker.js': ('_worker.js', worker_content, 'text/javascript'),
}

API 详细说明

deploy_pages_project()

功能: 从本地目录部署 Pages 项目

参数:

project_name (str): 项目名称
directory (str): 本地目录路径
branch (str, 默认="main"): 分支名称
commit_message (str, 默认="Deploy via API"): 提交信息

返回值:

Dict: 部署详情（成功时）
None: 失败时

示例:

result = cf.deploy_pages_project(
    project_name="my-website",
    directory="./dist",
    branch="main",
    commit_message="Update homepage"
)

if result:
    print(f"部署 ID: {result['id']}")
    print(f"URL: {result['url']}")
    print(f"状态: {result['latest_stage']['status']}")

upload_worker()

功能: 上传 Worker 脚本

参数:

script_name (str): Worker 脚本名称
worker_file (str): Worker .js 文件路径
bindings (List[Dict], 可选): 资源绑定列表

返回值:

Dict: Worker 详情（成功时）
None: 失败时

示例:

result = cf.upload_worker(
    script_name="api-worker",
    worker_file="./api.js",
    bindings=[
        {
            "type": "kv_namespace",
            "name": "CACHE",
            "namespace_id": "abc123..."
        }
    ]
)

if result:
    print(f"Worker ID: {result['id']}")
    print(f"创建时间: {result['created_on']}")

list_workers()

功能: 列出所有 Worker 脚本

参数: 无

返回值: List[Dict] - Worker 列表

示例:

workers = cf.list_workers()
for worker in workers:
    print(f"- {worker['id']}")

get_worker()

功能: 获取指定 Worker 的详细信息

参数:

script_name (str): Worker 脚本名称

返回值:

Dict: Worker 详情（成功时）
None: 失败时

示例:

worker = cf.get_worker("my-worker")
if worker:
    print(f"脚本名称: {worker['id']}")
    print(f"修改时间: {worker['modified_on']}")

delete_worker()

功能: 删除 Worker 脚本

参数:

script_name (str): Worker 脚本名称

返回值: bool - 成功返回 True，失败返回 False

示例:

if cf.delete_worker("old-worker"):
    print("Worker 已删除")

完整示例代码

示例 1: 部署静态网站到 Pages

#!/usr/bin/env python3
from cloudflare_manager import CloudflareManager, CloudflareAccount
import os

# 配置账户
account = CloudflareAccount(
    email="your-email@example.com",
    token="your-api-token"
)
cf = CloudflareManager(account)

# 项目名称
project_name = "my-blog"

# 创建 Pages 项目
print("📝 创建 Pages 项目...")
cf.create_pages_project(project_name, "main")

# 部署网站
print("📦 部署网站...")
result = cf.deploy_pages_project(
    project_name=project_name,
    directory="./public",  # Hugo/Jekyll 等的输出目录
    branch="main",
    commit_message="Deploy blog v1.0"
)

if result:
    print(f"✅ 部署成功！")
    print(f"访问地址: {result['url']}")
else:
    print("❌ 部署失败")

示例 2: 上传 Worker API

#!/usr/bin/env python3
from cloudflare_manager import CloudflareManager, CloudflareAccount

# 配置账户
account = CloudflareAccount(
    email="your-email@example.com",
    token="your-api-token"
)
cf = CloudflareManager(account)

# 创建 Worker 文件
worker_code = '''
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    
    if (url.pathname === '/api/hello') {
      return new Response(JSON.stringify({
        message: 'Hello from Worker!',
        timestamp: new Date().toISOString()
      }), {
        headers: { 'Content-Type': 'application/json' }
      });
    }
    
    return new Response('404 Not Found', { status: 404 });
  }
}
'''

# 保存到文件
with open('api-worker.js', 'w', encoding='utf-8') as f:
    f.write(worker_code)

# 上传 Worker
print("📤 上传 Worker...")
result = cf.upload_worker(
    script_name="api-worker",
    worker_file="api-worker.js"
)

if result:
    print("✅ Worker 上传成功！")
    print(f"可以通过 https://api-worker.{account.name}.workers.dev 访问")
else:
    print("❌ Worker 上传失败")

示例 3: Worker + KV 存储

#!/usr/bin/env python3
from cloudflare_manager import CloudflareManager, CloudflareAccount

account = CloudflareAccount(
    email="your-email@example.com",
    token="your-api-token"
)
cf = CloudflareManager(account)

# Worker 代码（使用 KV）
worker_code = '''
export default {
  async fetch(request, env, ctx) {
    const key = new URL(request.url).pathname.slice(1) || 'counter';
    
    // 从 KV 读取
    let count = await env.MY_KV.get(key);
    count = count ? parseInt(count) : 0;
    
    // 增加计数
    count++;
    
    // 写入 KV
    await env.MY_KV.put(key, count.toString());
    
    return new Response(`访问次数: ${count}`, {
      headers: { 'Content-Type': 'text/plain; charset=utf-8' }
    });
  }
}
'''

with open('counter-worker.js', 'w', encoding='utf-8') as f:
    f.write(worker_code)

# 上传带 KV 绑定的 Worker
print("📤 上传 Worker (with KV)...")
result = cf.upload_worker(
    script_name="counter-worker",
    worker_file="counter-worker.js",
    bindings=[
        {
            "type": "kv_namespace",
            "name": "MY_KV",
            "namespace_id": "your-kv-namespace-id"  # 替换为你的 KV ID
        }
    ]
)

if result:
    print("✅ Worker (with KV) 上传成功！")

示例 4: 批量部署多个 Workers

#!/usr/bin/env python3
from cloudflare_manager import CloudflareManager, CloudflareAccount
import os

account = CloudflareAccount(
    email="your-email@example.com",
    token="your-api-token"
)
cf = CloudflareManager(account)

# Worker 文件列表
workers = [
    ("api-worker", "./workers/api.js"),
    ("auth-worker", "./workers/auth.js"),
    ("cache-worker", "./workers/cache.js"),
]

print("📤 批量上传 Workers...")
for name, filepath in workers:
    if os.path.exists(filepath):
        print(f"\n上传: {name} <- {filepath}")
        result = cf.upload_worker(name, filepath)
        if result:
            print(f"  ✅ {name} 上传成功")
        else:
            print(f"  ❌ {name} 上传失败")
    else:
        print(f"  ⚠️  文件不存在: {filepath}")

print("\n✅ 批量上传完成！")

常见问题 (FAQ)

Q1: Pages 部署支持哪些文件大小？

A: 单个文件最大 25MB，总部署大小最大 20,000 个文件。

Q2: Worker 脚本有大小限制吗？

A: 免费计划限制 1MB，付费计划（Workers Bundled）限制 5MB。

Q3: 如何处理大型项目？

A: 对于大型项目，建议：

使用构建工具（Webpack、Rollup）打包和压缩
排除 node_modules 等不必要的目录
使用 .gitignore 风格的过滤

Q4: 上传失败怎么办？

A: 检查：

API Token 权限是否正确
文件路径是否存在
文件格式是否正确
网络连接是否正常

Q5: 如何查看上传进度？

A: 目前库会在上传时打印文件数量。对于大型部署，建议使用 tqdm 等进度条库。

技术细节 (Technical Details)

Pages 部署 API

端点: POST /accounts/{account_id}/pages/projects/{project_name}/deployments

请求格式: multipart/form-data

必需字段:

manifest: JSON 字符串，包含文件名到哈希的映射
branch: 分支名称
各个文件字段

示例请求:

files = [
    ("manifest", (None, '{"index.html": "sha256-hash..."}')),
    ("branch", (None, "main")),
    ("index.html", ("index.html", file_content, "text/html")),
]

Worker 上传 API

端点: PUT /accounts/{account_id}/workers/scripts/{script_name}

请求格式: multipart/form-data

必需字段:

metadata: JSON 字符串，包含元数据和绑定
_worker.js: Worker 脚本内容

示例请求:

files = {
    'metadata': (None, json.dumps({
        "main_module": "_worker.js",
        "compatibility_date": "2023-01-01"
    }), 'application/json'),
    '_worker.js': ('_worker.js', worker_content, 'text/javascript'),
}

总结

这份指南覆盖了：

✅ Pages 文件部署（从目录上传）
✅ Worker 脚本上传
✅ Worker 资源绑定（KV、R2 等）
✅ 完整的示例代码
✅ API 详细说明
✅ 常见问题解答

如有其他问题，请查看 API_REFERENCE.md 或提交 Issue。

文件上传指南 (File Upload Guide)

目录 (Table of Contents)

上传文件到 Pages

方法 1: 从本地目录部署 (Deploy from Local Directory)

工作原理 (How It Works)

上传的数据格式

支持的文件类型

上传文件到 Worker

基本用法

带绑定的高级用法 (Advanced Usage with Bindings)

Worker 文件示例

上传的数据格式

API 详细说明

deploy_pages_project()

upload_worker()

list_workers()

get_worker()

delete_worker()

完整示例代码

示例 1: 部署静态网站到 Pages

示例 2: 上传 Worker API

示例 3: Worker + KV 存储

示例 4: 批量部署多个 Workers

常见问题 (FAQ)

Q1: Pages 部署支持哪些文件大小？

Q2: Worker 脚本有大小限制吗？

Q3: 如何处理大型项目？

Q4: 上传失败怎么办？

Q5: 如何查看上传进度？

技术细节 (Technical Details)

Pages 部署 API

Worker 上传 API

相关文档

总结