serverpod-file-uploads

Serverpod 文件上传

流程：服务端签发上传描述 → 客户端上传 → 服务端验证。默认存储为数据库；生产环境请使用 S3、GCP、R2 或兼容的对象存储。

服务端：创建上传描述

Future<String> getUploadDescription(Session session, String path) async {
  return await session.storage.createUploadDescription(
    storageId: 'public',
    path: path,
  );
}

始终对请求进行授权，并根据可信的服务端状态（用户 ID、租户 ID、对象 ID）生成路径。不要接受任意客户端路径。

服务端：验证上传

Future<bool> verifyUpload(Session session, String path) async {
  return await session.storage.verifyUpload(
    storageId: 'public', path: path);
}

使用对象存储时，客户端上传后始终要进行验证。

客户端：上传

var desc = await client.myEndpoint.getUploadDescription('profile/$userId/avatar.png');
var uploader = FileUploader(desc);
await uploader.upload(byteDataOrStream);
await client.myEndpoint.verifyUpload('profile/$userId/avatar.png');

大文件请使用 Stream。路径要求：不以斜杠开头、兼容对象存储、经过规范化，并限定在已验证用户或租户的范围内。

安全检查清单

• 对描述和验证端点都要求身份验证和授权。
• 签发描述前，验证或生成内容类型、大小和扩展名。
• 绝不允许客户端选择跨租户路径或存储 ID。
• verifyUpload 成功后，将元数据存储在数据库中。

访问已存储的文件

• session.storage.fileExists(storageId: 'public', path: path)
• session.storage.publicDownloadUrl(storageId: 'public', path: path)（仅限公共存储）
• session.storage.temporaryDownloadUrl(storageId: 'private', path: path)（对私有文件的访问有时限）
• session.storage.retrieveFile(storageId: 'public', path: path)

存储后端

• 数据库（默认）：public 和 private 存储。适合开发环境。
• **Google Cloud Storage：**添加 serverpod_cloud_storage_gcp，在 passwords.yaml 或环境变量中设置 HMAC 密钥。注册：pod.addCloudStorage(GoogleCloudStorage(...))。
• **AWS S3：**添加 serverpod_cloud_storage_s3，设置 AWS 密钥。注册：pod.addCloudStorage(S3CloudStorage(...))。
• **兼容 S3 的存储/R2：**针对兼容服务商时，使用匹配的集成包。

替换默认存储时，请使用 storageId: 'public' 或 'private'。