存储

ShipSaaS 使用 Cloudflare R2 进行文件存储，通过 Wrangler 绑定直接访问 R2 存储桶。

设置

配置 Cloudflare API Token

请先完成 Cloudflare 配置，确保 Token 包含 Account > Workers R2 Storage > Edit 权限。

创建 R2 存储桶

可以通过 Cloudflare 仪表盘或 Wrangler CLI 创建 R2 存储桶：

Wrangler CLI

1. 创建新的 R2 存储桶：

bunx wrangler r2 bucket create your-bucket-name

Cloudflare 仪表盘

1. 登录 Cloudflare 仪表盘
2. 导航到 Storage & Databases > R2 Object Storage
3. 点击 Create Bucket
4. 输入全局唯一的存储桶名称
5. 选择靠近目标受众的区域
6. 点击 Create Bucket

配置 Wrangler 绑定

在 wrangler.jsonc 中配置 R2 存储桶绑定：

wrangler.jsonc

{
  "r2_buckets": [
    {
      "binding": "BUCKET",
      "bucket_name": "your-bucket-name" // 注意修改这里，更改为您的存储桶名称
    }
  ]
}

更新网站配置

一般情况下，保持默认配置即可，如果需要更改，可以修改 src/config/website.ts 中的 storage 配置：

src/config/website.ts

export const websiteConfig = {
  // ...其他配置
  storage: {
    enable: true,
    provider: 'r2',
    maxFileSize: 10 * 1024 * 1024,
    allowedTypes: [],
    userFilesFolder: 'userfiles',
  },
  // ...其他配置
}

如果您正在设置环境，现在可以回到环境配置文档并继续。本文档的其余部分可以稍后阅读。

环境配置设置环境变量

---

核心功能

• 文件上传和下载
• 使用文件夹组织文件
• 自动生成文件路径和文件命名
• 文件信息查询和用户文件列表
• 可配置的文件大小限制和类型限制

使用方法

基本文件操作

ShipSaaS 为常见文件操作提供简单的 API：

import { uploadFile, deleteFile, downloadFile, getFileInfo } from '@/storage';

// 上传文件
const { url, key } = await uploadFile(
  fileBuffer,
  'original-filename.jpg',
  'image/jpeg',
  { folder: 'uploads/images' }
);

// 删除文件
await deleteFile(key);

// 下载文件
const stream = await downloadFile(key);

// 获取文件信息
const info = await getFileInfo(key);

用户文件管理

import { listUserFiles, uploadFile } from '@/storage';

// 上传用户文件
const { url, key, metadata } = await uploadFile(
  file,
  filename,
  contentType,
  { folder: 'userfiles', userId: 'user_123' }
);

// 列出用户的所有文件
const { objects, hasMore, nextCursor } = await listUserFiles('user_123');

最佳实践

1. 文件组织：使用文件夹按类型或用途组织文件
2. 文件大小限制：设置合理的文件大小限制以防止滥用
3. 文件类型验证：在客户端和服务器端验证文件类型以确保安全

下一步

现在您了解了如何在 ShipSaaS 中使用文件存储，探索这些相关主题：

• 支付 - 配置网站支付功能

• 身份验证 - 配置用户身份验证

• 数据库 - 配置数据库

• 环境配置 - 配置环境变量

• 数据库

• 身份验证