src/lib/plugins/storage/do-spaces.ts

src/lib/plugins/storage/do-spaces.ts

DigitalOcean Spaces 存储插件，支持文件上传到 DigitalOcean 的对象存储服务。

概述

该插件基于 AWS SDK for JavaScript v3，因为 DigitalOcean Spaces 完全兼容 S3 API。提供针对 Spaces 的专门优化，包括特定的端点构造和 CDN 支持。

主要导出

doSpacesStoragePlugin

存储插件实例，实现了 StoragePlugin 接口。

import { doSpacesStoragePlugin } from "@/lib/plugins/storage/do-spaces";

功能特性

DigitalOcean 专用端点

自动构造 Spaces 专用端点：

function getEndpoint(): string {
  return `https://${region}.digitaloceanspaces.com`;
}

URL 格式：https://{bucket}.{region}.digitaloceanspaces.com/{key}

CDN 支持

支持 CDN 加速的 Spaces：

function getFileUrl(key: string): string {
  // 如果配置了 CDN endpoint，使用 CDN URL
  if (process.env.DO_SPACES_CDN_ENDPOINT) {
    return `${process.env.DO_SPACES_CDN_ENDPOINT}/${key}`;
  }
  // 否则使用标准 Spaces URL
  return `https://${bucket}.${region}.digitaloceanspaces.com/${key}`;
}

公开访问

默认设置 ACL 为 public-read，确保文件可通过 URL 直接访问：

await client.send(
  new PutObjectCommand({
    Bucket: process.env.DO_SPACES_BUCKET!,
    Key: key,
    Body: buffer,
    ContentType: contentType,
    ACL: "public-read",  // 公开可读
  })
);

虚拟托管式 URL

使用虚拟托管式 URL（virtual-hosted style）：

forcePathStyle: false  // DO Spaces 使用虚拟托管式

环境变量

# 必需
DO_SPACES_BUCKET=your-bucket-name
DO_SPACES_REGION=nyc3  # 或其他区域：sfo3, ams3, sgp1, fra1
DO_SPACES_ACCESS_KEY_ID=your-spaces-key
DO_SPACES_SECRET_ACCESS_KEY=your-spaces-secret

# 可选
DO_SPACES_CDN_ENDPOINT=https://your-cdn-endpoint.com

可用区域

区域代码位置
nyc3纽约
sfo3旧金山
ams3阿姆斯特丹
sgp1新加坡
fra1法兰克福

API 参考

isConfigured

检查 DigitalOcean Spaces 是否已正确配置：

isConfigured: () => boolean

upload

上传文件到 Spaces：

async upload(
  file: File | Buffer, 
  options?: UploadOptions
): Promise<UploadResult>

参数：

参数类型说明
file`File \Buffer`要上传的文件
options?.filenamestring自定义文件名（可选）
options?.mimeTypestringMIME 类型（Buffer 时必需）
options?.folderstring目标文件夹（默认："uploads"）

返回值：

interface UploadResult {
  url: string;      // 文件访问 URL（如果使用 CDN，则是 CDN URL）
  key: string;      // Spaces 对象 key
  size: number;     // 文件大小（字节）
  mimeType?: string; // MIME 类型
}

delete

从 Spaces 删除文件：

async delete(keyOrUrl: string): Promise<void>

配置方式

在环境变量中启用：

ENABLED_STORAGE=do-spaces

并配置上述所有必需的环境变量。

获取访问密钥

  1. 登录 DigitalOcean 控制台
  2. 进入 API → Spaces Keys
  3. 点击 "Generate New Key"
  4. 保存 Key 和 Secret（Secret 只显示一次）

CDN 配置

如果使用 CDN 加速：

  1. 在 DigitalOcean 控制台中为你的 Spaces 启用 CDN
  2. 获取 CDN endpoint（如 https://bucket.region.cdn.digitaloceanspaces.com）
  3. 设置 DOSPACESCDN_ENDPOINT

与 S3 插件的区别

特性S3 插件DO Spaces 插件
Endpoint 构造灵活配置自动构造 DO 格式
CDN 支持手动配置原生支持
ACL 默认无public-read
URL 风格路径或虚拟托管虚拟托管
forcePathStyle可选false

安装依赖

使用此插件需要安装 AWS SDK：

npm install @aws-sdk/client-s3

注意事项

  1. 区域选择：选择离用户最近的区域以获得最佳性能
  2. 流量费用：注意 DigitalOcean 的出站流量费用
  3. CDN 推荐：生产环境建议使用 CDN 加速
  4. 密钥安全：妥善保管 Spaces 访问密钥
  5. CORS 配置：前端直传时需要在 Spaces 设置中配置 CORS
← 返回目录