NocoBase 文件存储引擎阿里云 OSS 配置、私有访问限制与跨域预览下载实战【免费下载链接】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/nocobaseNocoBase 内置「阿里云 OSS」存储引擎可将附件直接上传到阿里云对象存储OSS实现文件与业务系统的解耦。本文基于 docs/docs/cn/file-manager/storage/aliyun-oss.md 展开结合nocobase/plugin-file-manager的源码实现与测试用例完整讲解该引擎的专用配置参数、前置权限要求、私有访问限制以及 PDF 预览变下载、图片下载 CORS 报错两大高频故障的排查与修复方案。读完本文你将能够独立完成 OSS 存储引擎的配置、自定义域名绑定与响应头验证。引擎概述与使用前置条件基于阿里云 OSS 的存储引擎位于nocobase/plugin-file-manager插件中服务端实现见 server/storages/ali-oss.ts底层通过阿里云官方 SDKali-oss的putStream流式上传实现文件写入。使用前需要准备一个阿里云账号并在阿里云 OSS 控制台创建存储空间bucket一对有权访问该 bucket 的 AccessKeyID 与 Secret记录 bucket 所在区域的 Region 前缀如oss-cn-hangzhou。在 NocoBase 管理界面进入「文件管理器 → 存储引擎」页面即可新增或编辑「阿里云 OSS」类型的引擎。系统安装时会自动创建一个本地存储引擎OSS 引擎需要手动添加。私有访问限制重要:::warning 注意该引擎不支持私有访问。文件上传后NocoBase 会生成可直接访问的 URL任何获得该 URL 的用户都可以访问文件。即使 OSS bucket 本身在控制台配置为私有NocoBase 内置的阿里云 OSS 引擎也不会为文件访问生成临时签名 URL。如果需要私有访问请使用支持签名 URL 的 S3 Pro 存储引擎。已有历史文件时可参考 迁移到 S3 Pro。:::这一限制可以从源码层面得到印证server/storages/ali-oss.ts 中getFileURL仅在options.download为真即用户显式点击下载时才调用client.signatureUrl生成带下载响应头的签名 URL普通预览/访问路径走基类StorageType.getFileURL直接拼接baseUrl path filename返回公网 URL见 server/storages/index.ts。这意味着只要文件记录返回的是原始存储 URL任何拿到链接的人都能读取文件与 bucket 的私有策略无关文件记录的权限控制只能通过「NocoBase URL 文件记录权限」间接实现无法依靠 OSS 自身的签名机制存储引擎的通用「文件 URL 与访问控制」配置中存储引擎概述 也明确提示阿里云 OSS 等内置云存储引擎不会生成临时签名 URL。因此若业务涉及合同、证件、内部资料等不应公开的文件建议直接选用 S3 Pro。配置参数详解:::info{title提示} 以下仅介绍阿里云 OSS 存储引擎的专用参数通用参数标题、系统名、路径、文件大小限制、文件类型、默认存储引擎、删除记录时保留文件等请参考 引擎通用参数。 :::专用参数在客户端表单中的定义见 client/schemas/storageTypes/ali-oss.tsx服务端默认值见 server/storages/ali-oss.ts。各参数说明如下基础 URL填写文件访问地址的前缀比如绑定到当前 bucket 的自定义域名https://oss.example.com。如果使用阿里云 OSS 默认域名访问 PDF可能遇到浏览器强制下载的问题建议先绑定自定义域名详细说明见下文常见问题。从源码看该值对应存储记录中的baseUrl字段最终访问 URL 由baseUrl 路径 文件名拼接而成默认值取环境变量ALI_OSS_STORAGE_BASE_URL。区域填写 OSS 存储的区域前缀例如oss-cn-hangzhou。:::info{title提示} 可以在阿里云 OSS 控制台中查看存储空间的区域信息且只需截取区域前缀部分即可无需完整域名。 :::源码中该值对应options.region默认取环境变量ALI_OSS_REGION会被原样传给ali-ossSDK 的OSS(config)构造函数用于定位服务端点。AccessKey ID填写阿里云授权访问密钥的 ID对应options.accessKeyId默认取环境变量ALI_OSS_ACCESS_KEY_ID。表单中为必填项。AccessKey Secret填写阿里云授权访问密钥的 Secret对应options.accessKeySecret默认取环境变量ALI_OSS_ACCESS_KEY_SECRET。表单中为必填项且以密码框形式展示password: true避免明文泄露。存储桶填写 OSS 存储的存储桶名称对应options.bucket默认取环境变量ALI_OSS_BUCKET。表单中为必填项。超时时间填写上传到阿里云 OSS 的超时时间单位为毫秒。文档界面中默认值为60000毫秒即 60 秒需要说明的是服务端代码 ali-oss.ts 的make()中设置的是timeout: 600_000600 秒作为兜底默认值客户端表单的默认值定义见 ali-oss.tsx。配置时以你在界面上填写的值为准。下载与删除的源码行为除配置参数外理解引擎的底层行为有助于排查问题下载响应getFileURL在download模式下会生成签名 URL并通过response[content-disposition]注入下载响应头其值由getDownloadContentDisposition生成包含filename与filename*UTF-8...两段确保中文文件名也能正确下载见 server/storages/index.ts。文件删除删除记录时引擎调用client.deleteMulti批量删除对象若勾选了「删除记录时保留文件」paranoid则只删记录不删对象。这一行为有对应测试覆盖server/tests/storages/ali-oss.test.ts 中「destroy record should also delete file」与「destroy record should not delete file when paranoid」两个用例分别验证了两种路径。对象存在性检查exists通过client.head发起 HEAD 请求识别NoSuchKey、NotFoundError判断对象是否缺失。对象复制copy通过client.copy在 bucket 内复制对象例如记录复制场景。测试用例还验证了文件记录url以 NocoBase 路径/files/main/main/attachments/{id}返回、文件内容可正常读取等行为可作为接入后的验收参考。常见问题PDF 预览时变成下载NocoBase 对跨域 PDF 使用 iframe 预览。此时浏览器会直接访问 OSS 文件 URL最终是预览还是下载由 OSS 返回的响应头决定。如果 PDF 在 iframe 中变成下载可以在浏览器开发者工具的「网络」面板检查文件请求。常见的异常响应头如下Content-Type: application/pdf Content-Disposition: attachment x-oss-force-download: trueContent-Type: application/pdf表示文件类型正确不过Content-Disposition: attachment会要求浏览器下载文件。阿里云 OSS 默认域名在部分场景下会强制下载详见阿里云官方文档「如何配置访问 PDF 文件时是预览行为」。推荐按以下方式配置按照「通过自定义域名访问 OSS 资源」为 bucket 绑定自定义域名将域名解析和 HTTPS 证书配置完成确认自定义域名能直接访问文件根据使用的 NocoBase 存储引擎填写访问地址。其中第 3 步有两种情况使用内置「阿里云 OSS」存储引擎时将「基础 URL」设置为绑定后的自定义域名比如https://oss.example.com使用 S3 Pro 连接阿里云 OSS 时上传 endpoint 可以继续使用 OSS 区域 endpoint将访问 endpoint 设置为自定义域名并将Full access URL style设置为Ignore。配置后重新上传一个 PDF 进行验证。已有文件记录中如果保存了完整 URL还需要确认实际返回给前端的 URL 已经切换到自定义域名。:::tip 判断响应头iframe 预览跨域 PDF 本身不要求 CORS。PDF 能否内嵌显示主要取决于Content-Type和Content-Disposition这与下方下载按钮需要的 CORS 是两个不同的问题。:::图片能预览但点击下载提示 CORS 错误图片预览通常通过img加载PDF 跨域预览通过 iframe 加载这两种方式都可以在没有 CORS 响应头时显示资源。不过预览组件的下载按钮需要通过fetch读取文件再生成 Blob 交给浏览器下载。这个请求受浏览器同源策略限制。如果控制台出现以下错误说明 OSS 没有针对当前 NocoBase 站点返回Access-Control-Allow-OriginAccess to fetch at https://oss.example.com/path/to/file.jpg from origin https://example.com has been blocked by CORS policy: No Access-Control-Allow-Origin header is present on the requested resource.按照阿里云官方文档「配置跨域资源共享」为 bucket 新建 CORS 规则。用于预览组件下载时可以按以下内容配置配置项建议值来源Allowed OriginsNocoBase 的完整 origin比如https://example.com允许的方法Allowed MethodsGET、HEAD允许的请求头Allowed Headers*暴露的响应头Expose HeadersETag、Content-Disposition缓存时间MaxAgeSeconds600如果 S3 Pro 还需要浏览器直传文件请根据浏览器「网络」面板中的实际上传请求把PUT、POST等方法加入同一规则或单独创建上传规则。配置保存后使用 NocoBase 站点的 origin 重新请求文件。预期响应至少包含Access-Control-Allow-Origin: https://example.com Access-Control-Allow-Methods: GET, HEAD浏览器可能已经缓存了图片预览时取得的响应。该响应没有携带Origin请求头也可能没有Access-Control-Allow-Origin响应头。如果配置 CORS 后下载仍然失败可以先清除该文件的浏览器缓存或在开发者工具中勾选「停用缓存」后重试。如何验证响应头可以用curl模拟从 NocoBase 站点发起的跨域请求。把示例 origin、文件地址和签名参数替换为实际值curl -sS -D - -o /dev/null \ -H Origin: https://example.com \ https://oss.example.com/path/to/file.pdf?signed-query检查结果时分别确认PDF 预览返回Content-Type: application/pdf且没有Content-Disposition: attachment跨域下载返回与 NocoBase 站点匹配的Access-Control-Allow-Origin实际文件 URL 使用自定义域名而不是*.oss-cn-*.aliyuncs.com默认域名。如果不带Origin的请求没有返回 CORS 响应头这是正常现象。验证 CORS 时必须保留示例中的Origin请求头。环境变量速查服务端在创建存储时会以环境变量作为默认值见 server/storages/ali-oss.ts便于在自动化部署场景下预置配置环境变量对应参数ALI_OSS_STORAGE_BASE_URL基础 URLALI_OSS_REGION区域ALI_OSS_ACCESS_KEY_IDAccessKey IDALI_OSS_ACCESS_KEY_SECRETAccessKey SecretALI_OSS_BUCKET存储桶注意环境变量仅在创建新的存储引擎时作为默认值预填运行期修改仍以界面保存的配置为准。相关链接文件预览S3 Pro迁移到 S3 Pro存储引擎概述【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考