存储引擎：S3 (Pro)

介绍

在文件管理插件的基础上，新增支持兼容 S3 协议的文件存储类型。任何支持 S3 协议的对象存储服务均可轻松接入，例如亚马逊 S3、阿里云 OSS、腾讯云 COS、MinIO、Cloudflare R2等，进一步提升存储服务的兼容性与灵活性。

功能特点

客户端上传：文件上传过程无需经过 NocoBase 服务器，直接对接文件存储服务，实现更加高效、快速的上传体验。
私有访问：默认使用带有效期的签名 URL 访问文件，也可以为公开存储桶生成无签名 URL。

使用场景

文件表管理：集中管理和存储所有上传的文件，支持多种文件类型和存储方式，方便文件的分类与检索。
附件字段存储：用于表单或记录中上传附件的数据存储，支持与具体数据记录的关联。

插件配置

开启 plugin-file-storage-s3-pro 插件
点击 "Setting-> FileManager" 进入文件管理设置
点击 "Add new" 按钮，选择 "S3 Pro"

在弹出浮层后，您将看到需要填写的表单内容较多。可以参考后续文档，获取对应文件服务的相关参数信息，并将其正确填写到表单中。

URL 配置

S3 Pro 除了支持文件管理器通用的「NocoBase URL」「原始 URL」和「允许公开访问」，还可以分别配置上传 URL、访问 URL 的格式，以及是否使用签名 URL。通用选项的含义见存储引擎概述。

这几个选项控制不同环节：

「NocoBase URL / 原始 URL」控制文件记录返回哪种地址
「允许公开访问」控制访问 NocoBase URL 时是否检查文件记录的查看权限
「不使用签名 URL」控制对象存储是否校验 URL 签名

这些配置可以独立组合。默认推荐使用 NocoBase URL、不勾选「允许公开访问」，并保持签名 URL 启用。

20260723221441

如何选择

使用场景	文件 URL	允许公开访问	不使用签名 URL
文件需要遵循角色和数据权限，存储桶保持私有	NocoBase URL	不勾选	不勾选
需要提供一个公开的 NocoBase 文件地址，存储桶仍保持私有	NocoBase URL	勾选	不勾选
外部服务需要临时读取存储地址	原始 URL	不适用	不勾选，并设置访问地址有效期
使用公开存储桶或 CDN，需要无签名的原始地址	原始 URL	不适用	勾选

上传 URL 格式

「上传 URL 格式」控制客户端上传文件时使用的 S3 URL。根据存储服务支持的格式选择即可，配置界面会按照当前 Endpoint、Bucket 和路径显示实际示例。其中：

「存储桶作为子域名」：https://bucket-name.s3.example.com/path/to/object
「存储桶作为子路径」：https://s3.example.com/bucket-name/path/to/object
「忽略存储桶」：https://upload.example.com/path/to/object

访问 URL 格式

「访问 URL 格式」控制 S3 Pro 生成文件访问地址时，Bucket 出现在域名、路径中，还是不出现在 URL 中。三个选项的格式和上传 URL 相同，不过可以单独配置——比如上传使用 S3 Endpoint，访问使用不包含 Bucket 的 CDN 域名。

该选项会影响原始 URL，以及访问 NocoBase URL 后最终跳转到的存储地址，但不会改变 NocoBase URL 本身的格式。

不使用签名 URL

S3 Pro 默认使用签名 URL。生成的原始 URL 会包含签名参数，比如：

https://bucket-name.s3.example.com/path/to/object?X-Amz-Signature=xxxx

签名 URL 在「访问地址有效期」设置的时间内有效，存储桶可以保持私有。使用 NocoBase URL 时，NocoBase 会在权限检查通过后生成或跳转到签名地址。

勾选「不使用签名 URL」后，S3 Pro 会生成不带签名参数的地址。此时必须确保存储桶和上传的对象允许公开读取，「访问地址有效期」也不再生效。

「不使用签名 URL」只控制存储服务是否校验签名，不会改变 NocoBase 的文件记录权限。如果同时选择 NocoBase URL 且未勾选「允许公开访问」，请求仍然需要先通过 NocoBase 的权限检查。

服务商配置

亚马逊S3

Bucket 创建

打开 https://ap-southeast-1.console.aws.amazon.com/s3/home 进入S3控制台
点击右侧 "Create bucket" 按钮

填写 Bucket Name（存储桶名称），其他字段可保持默认设置，向下滚动至页面底部，点击 "Create" 按钮完成创建。

CORS配置

进入buckets 列表，找到并点击刚刚创建的 Bucket 以进入其详细页面

点击 "Permission" 标签页，然后向下滚动找到 CORS 配置部分

填入以下配置（可以自定细化配置），并保存

[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "POST",
            "PUT"
        ],
        "AllowedOrigins": [
            "*"
        ],
        "ExposeHeaders": [
            "ETag"
        ],
        "MaxAgeSeconds": 3000
    }
]

AccessKey、SecretAccessKey 获取

点击页面右上角的 "Security credentials" 按钮

向下滚动，找到 "Access Keys" 部分，点击 "Create Access Key" 按钮。

点击同意（此处为主账号演示，建议在正式环境中使用 IAM 进行操作）。

保存页面中显示的 Access key 和 Secret access key

参数获取与配置

AccessKey ID 和 AccessKey Secret 为您在上一操作中获取到的对应值，请准确填写
进入 bucket 详情页的 properties 面板，您可以在其中获取到 Bucket 名称和 Region（区域）信息。

无签名公开访问（可选）

只有当你需要使用无签名 URL 时，才需要把 Bucket 和上传的对象设置为公开读取。如果只是希望公开分享 NocoBase URL，可以勾选「允许公开访问」并继续使用签名 URL，不需要开放 Bucket。

进入Permissions 面板，向下滚动到Object Ownership，点击编辑，开启 ACLs

滚动到Block public access，点击编辑，设置成允许ACLs控制

在 NocoBase 中勾选「不使用签名 URL」

缩略图配置（可选）

此配置为可选项，适用于优化图像预览尺寸或效果时使用。请注意，该部署方案可能产生额外费用，具体费用请参考 AWS 的相关条款。

访问 Dynamic Image Transformation for Amazon CloudFront。
点击页面底部的 Launch in the AWS Console 按钮，开始部署方案。
按照提示完成配置，以下几个选项需要特别注意：
1. 在创建堆栈时，您需要指定一个包含源图像的 Amazon S3 存储桶名称。请填写您之前创建的存储桶名称。
2. 如果您选择了部署演示 UI，部署完成后可通过该界面测试图像处理功能。在 AWS CloudFormation 控制台中，选择您的堆栈，转到“输出”选项卡，找到 DemoUrl 键对应的值，点击该链接打开演示界面。
3. 本方案使用了 sharp Node.js 库来高效处理图像。您可以从 GitHub 仓库下载源代码，按需进行自定义。
配置完成后，等待部署状态变为 CREATE_COMPLETE 即可。
在 NocoBase 配置中，有以下几个注意事项：
1. Thumbnail rule：填写图像处理相关参数，例如 ?width=100。具体可参考 AWS 文档。
2. Access endpoint：填写部署后 Outputs -> ApiEndpoint 的值。
3. 「访问 URL 格式」：选择「忽略存储桶」（因为配置中已经填写了存储桶名称，访问时不再需要）。

配置示例