Spaces:

HFHash789
/

cfmanager

Sleeping

File size: 12,249 Bytes

32e4bbf

# 文件上传指南 (File Upload Guide)

这份文档详细说明如何上传文件到 Cloudflare Pages 和 Workers。

This guide explains how to upload files to Cloudflare Pages and Workers in detail.

---

## 目录 (Table of Contents)

1. [上传文件到 Pages](#上传文件到-pages)
2. [上传文件到 Worker](#上传文件到-worker)
3. [API 详细说明](#api-详细说明)
4. [完整示例代码](#完整示例代码)

---

## 上传文件到 Pages

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

这是最简单的方法，会自动扫描目录并上传所有文件。

```python
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` 方法会：

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

### 上传的数据格式

```python
# 内部实现的数据格式
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 脚本非常简单：

```python
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 或其他资源：

```python
# 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`：

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

### 上传的数据格式

```python
# 内部实现
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`: 失败时

**示例**:
```python
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`: 失败时

**示例**:
```python
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 列表

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

### get_worker()

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

**参数**:
- `script_name` (str): Worker 脚本名称

**返回值**: 
- `Dict`: Worker 详情（成功时）
- `None`: 失败时

**示例**:
```python
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

**示例**:
```python
if cf.delete_worker("old-worker"):
    print("Worker 已删除")
```

---

## 完整示例代码

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

```python
#!/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

```python
#!/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 存储

```python
#!/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

```python
#!/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: 对于大型项目，建议：
1. 使用构建工具（Webpack、Rollup）打包和压缩
2. 排除 `node_modules` 等不必要的目录
3. 使用 `.gitignore` 风格的过滤

### Q4: 上传失败怎么办？

A: 检查：
1. API Token 权限是否正确
2. 文件路径是否存在
3. 文件格式是否正确
4. 网络连接是否正常

### Q5: 如何查看上传进度？

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

---

## 技术细节 (Technical Details)

### Pages 部署 API

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

**请求格式**: `multipart/form-data`

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

**示例请求**:
```python
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 脚本内容

**示例请求**:
```python
files = {
    'metadata': (None, json.dumps({
        "main_module": "_worker.js",
        "compatibility_date": "2023-01-01"
    }), 'application/json'),
    '_worker.js': ('_worker.js', worker_content, 'text/javascript'),
}
```

---

## 相关文档

- [API 参考手册](./API_REFERENCE.md)
- [使用指南](./USAGE_GUIDE.md)
- [快速开始](./GET_STARTED.md)
- [项目概述](./README.md)

---

## 总结

这份指南覆盖了：

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

如有其他问题，请查看 [API_REFERENCE.md](./API_REFERENCE.md) 或提交 Issue。