如何一次配好 NocoBase 外部存储权限：从上传规则到私有文件访问-开发者社区

如何一次配好 NocoBase 外部存储权限：从上传规则到私有文件访问

【免费下载链接】nocobaseNocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase

当你把 NocoBase 部署到生产环境后，文件管理器的默认状态并不安全：本地存储引擎会生成任何人都能直接打开的公开 URL，上传接口默认对登录用户开放。如果存储权限不做任何配置，一个离职员工上传的简历 PDF，可能变成公网爬虫也能下载的公共资源；一个被劫持的会话，可能往服务器里塞满超大文件或恶意脚本。本文解决的就是这件事：如何在 NocoBase 的文件管理器插件里，把外部存储权限和文件访问控制一次性配到位。

不配存储权限会出什么问题

NocoBase 的文件能力由文件管理器插件提供，它管理两个层面：存储引擎（文件放哪里、怎么读）和附件记录（谁上传、存在哪张表）。风险集中在存储引擎这一侧：

默认 URL 即公开。本地存储的文件落在storage/uploads目录，访问地址是普通的静态 URL，没有鉴权。拿到链接的人，无论是否登录，都能直接下载。
上传只要求登录，不限类型和大小。服务端的 ACL 只把attachments:upload和attachments:create限制为loggedIn，即任何登录用户都能上传；若不额外配置规则，文件类型和大小上限基本不设防。
自定义反向代理可能放大风险。如果上传目录没有正确配置响应头，用户上传的 HTML、SVG 文件在浏览器里会被直接渲染，形成存储型 XSS 的入口。官方在文件存储安全指南中专门列出了这项要求。

换句话说，"能不能传"和"传完谁能看"是两道独立的闸门，只开一道等于没开。

这个能力适合什么场景

文件管理器插件内置四种存储引擎：本地存储（local）、阿里云 OSS（ali-oss）、AWS S3 兼容存储（s3）、腾讯云 COS（tx-cos），实现分别位于 src/server/storages/ 目录。按访问安全强度划分：

公开可访问场景：产品图片、营销素材、头像等本来就要展示给外部的文件。本地存储 + 对象存储的公开 Bucket 足够用。
半私有场景：只有登录用户该看到的内容，靠应用内权限控制访问入口，文件 URL 本身仍可能被猜到。
严格私有场景：合同、证件、财务单据。这类文件必须配合支持私有读写和签名 URL的引擎，NocoBase 提供商业版 S3 Pro 引擎（内网可用 MinIO 这类兼容 S3 协议的自建存储），本地存储引擎明确不支持私有访问（见本地存储文档）。

选型原则只有一条：文件的敏感程度决定引擎，不要反过来用"URL 没人知道"来赌安全。

按四步把存储权限配到位

第一步：启用文件管理器插件

目标：让存储引擎和附件 API 进入系统。

做法：在管理界面的"设置 → 插件"中启用@nocobase/plugin-file-manager。首次安装时，插件会自动创建名为local的默认本地存储引擎（server.ts中的install()逻辑），无需手工建表。

验证：进入"设置 → 插件 → 文件管理器"，应能看到存储引擎列表，且至少有一条local默认引擎记录；用浏览器登录后调用上传接口返回 200，未登录返回 403，说明 ACL 已生效。

第二步：限制上传文件类型与大小

目标：把"任何登录用户传任何文件"收紧为"只传业务需要的文件"。

做法：每个存储引擎都有一段rules配置，包含 MIME 类型白名单（mimetype）和单文件大小上限（size，单位字节）。服务端在接收请求时按这条规则过滤，实现见 rules/mimetype.ts。在存储引擎编辑页填入类似下面的规则即可：

{ "mimetype": "image/jpeg,image/png,application/pdf", "size": 5242880 }

验证：用curl或 Postman 传一个.exe文件，应被拒绝；传一个 6 MB 的 PDF，也应被拒绝；传一张 PNG 成功。三条都符合预期才算通过。

第三步：按敏感程度选择存储引擎

目标：让敏感文件不再拥有"公开直达 URL"。

做法：

在插件设置中新建一个存储引擎，类型选s3（兼容 S3 协议，包括 MinIO、S3 Pro），配置 Bucket、Access Key 与端点。
在数据模型里，把敏感表（如"合同"集合）的附件字段或文件表绑定到这个新引擎，而不是默认的local。
保持默认引擎只承载公开素材，敏感引擎不设为默认。

验证：向绑定 S3 引擎的字段上传一份文件后，把返回的 URL 复制到无痕窗口打开——私有引擎返回的是签名地址，过期或无权限时应 403/404；同时确认该文件不会出现在storage/uploads目录下。

第四步：给文件域名加上响应头保护

目标：即使 URL 泄露，浏览器也不会把上传文件当可执行内容运行。

做法：官方 Docker 镜像和生成的 nginx 配置已内置以下保护；如果你用自定义反向代理，需要在上传目录的 location 上补齐（完整示例见安全指南：文件存储）：

所有上传文件返回X-Content-Type-Options: nosniff；
html、xhtml、svg、pdf等主动内容文件返回Content-Disposition: attachment强制下载。

验证：curl -I一个已上传的.svg文件，响应头中应同时看到上述两个头；在浏览器地址栏粘贴该 URL，行为应是下载而不是渲染。

日常运维与风险清单

定期清理公开 URL：文件删除时本地引擎会同步删盘（paranoid开启的引擎除外），但要核对"删记录 ≠ 删文件"的异常，可查日志中FileDeleteError关键字。
本地存储路径白名单：本地引擎已内置路径穿越防护，documentRoot必须落在storage目录或LOCAL_STORAGE_ALLOWED_ROOTS环境变量声明的目录内，自定义部署时不要绕过这个校验。
存储引擎被引用时不可删除：系统会拦截被文件表引用的引擎删除操作，重建引擎前先迁移绑定关系，避免上传中断。
敏感操作留痕：storages:*全部动作已注册为独立 ACL 片段，可单独授权给运维角色，避免普通管理员随意改存储配置。
多节点部署：存储配置变更后集群节点会自动重载（reloadStorages同步消息），但对象存储的 Bucket 策略、AK 权限变更不会自动生效，改完需在存储设置里重新保存触发检查。
升级前确认引擎版本：从本地存储迁移到 S3 Pro 属于数据迁移行为，先在预发环境验证迁移脚本再动生产。