@antelopejs/file-storage-s3
用于S3兼容对象存储的AntelopeJS文件存储模块,如AWS S3和Cloudflare R2. 用这个 @aws-sdk/client-s3,客户端通过预先签名的URL直接从桶上上传并读取文件.
接口
| 接口 | 文档 |
|---|---|
@antelopejs/interface-file-storage | 文件存储 |
界面页面文档上传、阅读、能见度、元数据、中继和宣传.
安装
ajs project modules add @antelopejs/file-storage-s3
模块没有默认配置, 所以添加一个 config 块为 default 在项目启动前存储.
配置
import { defineConfig } from "@antelopejs/interface-core/config";
export default defineConfig({
name: "my-project",
modules: {
"file-storage-s3": {
source: {
type: "package",
package: "@antelopejs/file-storage-s3",
version: "^0.1.5",
},
config: {
default: {
endpoint: "https://<account>.r2.cloudflarestorage.com",
region: "auto",
accessKeyId: "<access-key-id>",
secretAccessKey: "<secret-access-key>",
bucket: "app-files",
attachmentPrivateBucket: "app-private-files",
publicUrl: "https://cdn.example.com",
defaultVisibility: "private",
defaultUploadExpiration: 3600,
defaultReadExpiration: 300,
stagingExpirationDays: 1,
assumePrivateBuckets: false,
},
storages: {
media: {
endpoint: "https://<account>.r2.cloudflarestorage.com",
region: "auto",
accessKeyId: "<access-key-id>",
secretAccessKey: "<secret-access-key>",
bucket: "app-media",
publicUrl: "https://media.example.com",
defaultVisibility: "public",
defaultUploadExpiration: 3600,
defaultReadExpiration: 300,
},
},
},
},
},
envOverrides: {
S3_SECRET_ACCESS_KEY:
"modules.file-storage-s3.config.default.secretAccessKey",
},
});
| 密钥 | 说明 |
|---|---|
endpoint, (中文(简体) ), region | S3端点与区域. R2 使用区域 auto。 。 。 . |
accessKeyId, (中文(简体) ), secretAccessKey | S3客户端的全权证书. |
bucket | 拿着档案的巴基特. |
attachmentPrivateBucket | 上传请求的可选桶 visibility: "private",远离公众 bucket没有它,这样的上传投出. |
publicUrl | 可选公共来源 bucket。从 <publicUrl>/<resourceKey>没有 publicUrl,通过一个预先签名的URL读取. |
defaultVisibility | 上传文件的可见度,没有, "public" 或者说 "private"。 。 。 . |
defaultUploadExpiration | 上传URL的寿命, 以秒计 . |
defaultReadExpiration | 私人的寿命读取 URL, 以秒计, 当呼叫者设置无 . |
stagingExpirationDays | 可选的 启动时,模块设置了一个生命周期规则 bucket 财务报告和审定财务报表 attachmentPrivateBucket 过了这么多天,文件就过期了 当你的基础设施 管理生命周期规则时, 放弃它. |
assumePrivateBuckets | 可选的, false 默认。 放松无法通过私人桶的验证. |
除了可选的钥匙以外,所有钥匙都需要. default 持有主存储. storages 添加带有相同密钥的命名存储器,以及 storage 参数。 名称 default 保留在 storages,模块拒绝从它开始.
快开始
在处理上传的模块中,添加接口:
pnpm add @antelopejs/interface-file-storage
import {
CreateReadUrl,
CreateUploadUrl,
} from "@antelopejs/interface-file-storage";
const upload = await CreateUploadUrl(
{ filename: "avatar.png", size: 52_000, mimetype: "image/png" },
{ maxSize: 1_000_000, allowedMimetypes: ["image/png", "image/jpeg"] },
);
const read = await CreateReadUrl(upload.resourceKey);
客户端发送文件 PUT upload.uploadUrl 和每个标题 upload.headers,不变,然后从 read.url。 。 。 .
部署前
- 上传 URL 签名
If-None-Match: *条件,所以上传不会取代已有对象。 提供者必须执行有条件的PUT,而桶 CORS规则必须允许if-none-match头曰. - 模块核查
attachmentPrivateBucket在使用前屏蔽所有公共访问。 MinIO 和 Hetzner 对象存储需要assumePrivateBuckets: true。 。 。 . - S3 在小写中存储元数据密钥, 所以
GetFileMetadata返回时tenantid用于发送的上传tenantId。只有大小写不同的两个键才使上传投出.
乌巴解组织 详细说明这些保证。 它涵盖只创建的上传,促销,隐私和过期,私人桶验证,元数据密钥和CORS.
文档
- 文件存储 文档
@antelopejs/interface-file-storage与本模块执行的合同. - 配置 包括模块来源,
config区块和配置变量antelope.config.ts。 。 。 .
兼容性
| 软件包 | 支助 | 测试过 |
|---|---|---|
@antelopejs/interface-core | >=0.2.4 <1.0.0 | 0.2.4 |
@antelopejs/interface-file-storage | >=0.1.6 <0.2.0 | 0.1.6 |
.nvmrc 名称为 Node.js 发行用于开发。 测试与 Moto 图像相对 .github/release-services.yml 针.
捐款
测试需要一个 摩托 打开 S3 服务器 127.0.0.1:5005。启动 CI 使用的 :
docker compose -f .github/release-services.yml up -d --wait
然后检查:
pnpm install
pnpm lint
pnpm format:check
pnpm knip
pnpm test # build, then ajs module test
测试还管理着共用的兼容套件,包括: @antelopejs/interface-file-storage。阅读 捐款准则 在打开拉出请求之前.