#概述

#介绍

存储引擎用于将文件保存到特定的服务中，包括本地存储（保存到服务器硬盘）、云存储等。

使用任何上传文件之前，都需要先配置存储引擎。系统安装时会自动添加一个本地存储引擎，可直接使用。也可以添加新的或编辑已有的引擎参数。

#存储引擎类型

目前 NocoBase 内置支持的引擎类型如下：

• 本地存储
• Amazon S3
• 阿里云 OSS
• 腾讯云 COS
• S3 Pro

系统安装时会自动添加一个本地存储引擎，可直接使用。也可以添加新的或编辑已有的引擎参数。

#通用参数

除了不同引擎类别的特有参数外，以下部分为通用参数（以本地存储为例）：

#标题

存储引擎的名称，用于人工识别。

#系统名

存储引擎的系统名称，用于系统识别。必须是系统唯一的，不填会由系统自动随机生成。

#访问 URL 前缀

该文件对外可访问的 URL 地址前缀部分，可以是 CDN 的访问 URL 基础，如：“https://cdn.nocobase.com/app”（无需结尾的“/”）。

#路径

存储文件时使用的相对路径，在访问时此部分也会被自动拼接到最终的 URL 中。如：“user/avatar”（无需开头和结尾的“/”）。

#文件大小限制

对此存储引擎上传文件时的大小限制，超过该设置大小的文件将无法上传。系统默认限制为 20MB，可调整到最大的限制为 1GB。

#文件类型

可对上传文件的类型进行限制，使用 MIME 语法描述格式。例如：image/* 代表图片类文件。多个类型可以用英文逗号分隔，如：image/*, application/pdf 代表允许图片类型和 PDF 类型的文件。

#默认存储引擎

勾选后设置为系统的默认存储引擎，在附件字段或文件表未指定存储引擎时，上传的文件均会保存至默认存储引擎中。默认存储引擎不可删除。

#删除记录时保留文件

勾选后当附件表或文件表的数据记录被删除时，仍然保留存储引擎中已上传的文件。默认不勾选，即删除记录时会同时删除存储引擎中的文件。

<访问 URL 基础>/<路径>/<文件名><后缀名>

#文件 URL 与访问控制

存储引擎可以返回 NocoBase URL 或存储服务的原始 URL。默认使用 NocoBase URL，只有当外部服务必须直接使用存储地址时，才需要选择原始 URL。

这项配置按存储引擎生效。保存后，该引擎下已有文件和新上传文件都会按所选方式返回 URL，不会移动或重新上传文件。

#NocoBase URL

文件记录返回 NocoBase 提供的访问路径，比如：

/files/main/main/attachments/1.png

访问该 URL 时，请求会先经过 NocoBase，并遵循对应文件记录配置的查看权限。权限检查通过后，NocoBase 才会读取文件或跳转到存储服务生成的地址。

这是默认推荐的方式。文件记录中返回的是 NocoBase 路径，调用方不需要了解当前使用的是本地存储还是云存储。

#原始 URL

文件记录直接返回存储服务生成的地址，比如：

https://storage.example.com/path/to/file.png

该 URL 不检查文件记录的查看权限。对于本地存储，它通常是 /storage/uploads/ 历史地址，默认要求用户登录，但不会继续检查具体文件记录的权限；对于云存储，它通常是对象存储或 CDN 地址，其访问策略由对应存储服务决定。

只有当调用方无法使用 NocoBase URL——比如不能跟随 302 重定向，或明确需要对象存储 / CDN 地址时，才建议选择原始 URL。

#允许公开访问

「允许公开访问」只会在选择「NocoBase URL」时有效。勾选后仍然返回 NocoBase URL，不过访问时不再检查 NocoBase 中的文件记录权限——任何获得该 URL 的用户都可以访问文件。

这个选项不会修改存储服务自身的公开读取配置。它只控制请求经过 NocoBase 时是否检查文件记录权限。

Markdown、外部页面或第三方服务也可以使用公开的 NocoBase URL。外部使用时，需要将接口返回的路径补全为包含 NocoBase 域名的绝对 URL，并确保调用方支持跟随 302 重定向。

#如何选择

如果你已经在使用公开存储引擎，并希望把历史文件迁移到 S3 Pro，可参考 迁移到 S3 Pro。