NocoBase 文件管理器完全指南文件表、附件字段与本地/OSS/S3/COS 多存储引擎实战【免费下载链接】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 中负责「文件上传、元信息管理与多存储对接」的核心插件它通过文件表保存文件元信息、通过附件字段把文件关联到业务记录并支持本地存储、阿里云 OSS、Amazon S3、腾讯云 COS等多种存储引擎。读完本文你将掌握文件表与附件字段的创建和配置方法、各存储引擎的通用参数与专用参数、以及通过 HTTP API 完成服务端上传与客户端直传的完整调用流程。插件概览四个核心组成从 文件管理器文档 的定义看NocoBase 中的「文件」本质上是特定结构的数据表记录整个插件围绕四个部分展开文件表File Collection用于存储文件元信息的数据表内置attachments表作为默认文件表附件字段Attachment Field与文件表相关联的特定关系字段负责把文件记录挂到业务记录上文件存储引擎Storage把文件本体保存到特定服务服务器硬盘、云存储等的适配层HTTP API支持通过 REST 接口完成文件上传分为服务端上传与客户端直传两种模式。从源码看插件在服务端预置了两张共享系统表attachments 表shared: truetemplate: file含createdBy/updatedBy与 storages 表dataCategory: system同样shared: true二者分别对应「文件元信息」与「存储引擎配置」两类基础数据。文件表存储文件元信息的专用数据表文件表保存什么文件表适合保存文件元信息比如文件名、扩展名、大小、MIME 类型、路径、URL、预览地址、存储位置和自定义 meta。文件本体由文件存储引擎保存文件表保存的是文件元数据二者职责分离。需要注意的限制文件表只能通过主数据库页面创建外部数据库、REST API 数据源和外部 NocoBase 数据源不支持创建文件表。适用场景合同附件、发票文件、报销凭证产品图片、员工证件、项目文档业务记录的上传文件、预览文件和下载文件需要单独管理文件元信息的附件库使用流程文件表通常不直接作为主业务表使用常见流程为创建文件表保存文件标题、文件名、大小、类型、URL、存储位置等元信息在业务表中创建关系字段关联到文件表例如「合同」表关联「合同附件」文件表在业务表的表单区块中添加关系字段让用户在新增或编辑业务记录时上传文件上传完成后NocoBase 会把文件元信息写入文件表并通过关系字段把文件记录关联到当前业务记录在业务表的详情区块、表格区块或列表区块中展示附件字段让用户查看、预览或下载文件。创建配置在主数据库中点击「Create collection」选择「File collection」即可创建文件表。创建配置与普通表基本一致各配置项含义如下配置说明Collection display name数据表在界面中显示的名称比如「合同附件」「发票文件」「产品图片」。Collection name数据表的标识名称用于 API、关系字段、权限、工作流等内部引用。Categories数据表分类。只影响数据表管理界面的组织方式不改变数据表结构。Description数据表说明可写这个文件表保存什么文件、由谁上传、和哪些业务表有关。Preset fields预设字段。创建文件表时建议保留系统字段和文件表内置字段。内置字段文件表创建后通常包含以下内置字段其字段定义可在源码 attachments 集合定义 中看到字段字段名说明IDid默认主键字段用于唯一标识一条文件记录。Titletitle文件标题通常用于界面展示源码注释为「用户文件名不含扩展名」。File namefilename文件名源码注释为「系统文件名含扩展名」。Extension nameextname文件扩展名含「.」。Sizesize文件大小字节。MIME typemimetype文件 MIME 类型。Pathpath文件在存储中的路径源码注释为「相对路径含/前缀」。URLurl文件访问地址。Previewpreview文件预览地址。Storagestorage/storageId文件所属存储。storage是belongsTo关系字段storageId是对应外键源码中deletable: false不可删除。Metameta文件扩展元信息jsonb类型如图片宽高默认{}。创建时间createdAt自动记录文件记录的创建时间。创建人createdBy自动记录上传或创建文件记录的用户。更新时间updatedAt自动记录文件记录最后一次更新的时间。更新人updatedBy自动记录最后一次更新文件记录的用户。空间space启用多空间插件后可用用于按空间隔离数据没有启用多空间时不会出现。主键字段文件表和普通表一样需要主键字段附件字段和关系字段会通过主键记录关联文件元信息。如果文件表没有主键需要在编辑数据表时设置「Record unique key」否则附件记录可能无法正确关联、预览或编辑。建立关联关系在业务表中创建关系字段关联到文件表即可让业务记录挂接文件记录随后可在各区块中使用配置位置用途表单区块在业务表记录中上传附件。详情区块展示、预览或下载附件。表格区块在列表中展示附件字段。关系区块直接管理关联到当前业务记录的文件记录。编辑与删除在数据表列表中点击文件表右侧的「Edit」可修改显示名称、分类、说明、简单分页模式和「Record unique key」等配置。文件元信息字段通常由上传过程自动写入不建议把url、path、storageId等字段改成其他业务含义如需扩展文件业务信息应新增字段如「文件类型」「所属阶段」「是否归档」。点击「Delete」可删除文件表会同时删除文件元信息记录和相关 Collection 元数据。删除前务必确认业务表中的附件字段、关系字段、页面区块、权限、工作流和 API 是否仍然依赖它——文件表保存的是元信息删除记录可能导致业务记录里的附件引用失效是否同步删除文件本体取决于文件存储和业务配置。附件字段把文件挂到业务记录上的关系字段附件字段是与文件表相关联的特定关系字段可以通过「附件类型字段」创建也可以通过「关系字段」配置。注意在 附件字段文档 中附件字段已被标注为废弃deprecated官方建议改用文件表或附件 URL 字段。如果只是保存外部文件链接应选择附件 URL 或 URL 字段。不过存量场景中它仍是理解文件关联机制的重要入口。创建配置在数据表的「Configure fields」页面中点击「Add field」选择「附件」创建附件字段配置说明Field interface字段的界面类型附件对应attachment决定页面中如何录入和展示。Field display name字段在界面中显示的名称建议使用业务人员能直接理解的名称。Field name字段标识名称用于 API、关系字段、权限、工作流等内部引用只支持字母、数字和下划线且必须以字母开头。Field type字段在数据层的类型附件字段通常是关系字段关联文件表中的文件记录。Default value默认值新增记录时自动带出。Validation rules校验规则可限制是否必填文件数量、大小和类型通常在上传组件或文件存储配置中控制。Description字段说明适合写字段含义、填写要求、数据来源或维护人。字段特性特性说明默认 Field interfaceattachment默认 Field typebelongsToMany可选 Field typebelongsToMany等关系类型具体以文件字段配置为准页面组件编辑模式使用附件上传组件筛选通常按是否为空、是否有关联文件筛选排序通常不用于排序校验支持必填等基础校验上传限制以组件配置为准编辑、删除与注意事项创建后点击「Edit」可编辑附件字段显示名称、默认值、校验规则、说明均可调整Field name创建后通常不能修改主数据库字段或同步字段在字段映射时可以调整Field interface与Field type。切换 Field type 或 Field interface 不等于改显示名称——它会直接影响字段的存储方式、输入组件、校验规则、筛选条件和工作流变量使用方式已有数据较多时需先确认数据格式是否匹配。删除附件字段同理主数据库中新建的附件字段通常会同删数据库真实列及已有数据删除前需确认字段是否仍被页面区块、表单、筛选、权限、工作流、API、导入导出引用。页面使用场景附件字段适合在表单区块上传一个或多个文件、详情区块查看/预览/下载附件、表格区块展示附件数量或入口以及工作流把附件作为审批、通知或导出的相关文件中使用。文件存储引擎通用参数与各引擎配置存储引擎用于将文件保存到特定服务包括本地存储保存到服务器硬盘与云存储。系统安装时会自动添加一个本地存储引擎可直接使用也可以添加新的或编辑已有引擎参数。引擎通用参数除不同引擎类别的特有参数外所有引擎共享以下通用参数详见存储引擎概述参数说明标题存储引擎的名称用于人工识别。系统名存储引擎的系统名称用于系统识别必须是系统唯一的不填会由系统自动随机生成。访问 URL 基础文件对外可访问的 URL 地址前缀可以是 CDN 的访问 URL 基础如https://cdn.nocobase.com/app无需结尾的/。路径存储文件时使用的相对路径访问时也会被自动拼接到最终 URL 中如user/avatar无需开头和结尾的/。文件大小限制上传文件的大小限制超过则无法上传。系统默认限制为 20MB可调整的最大限制为 1GB。文件类型限制上传文件类型使用 MIME 语法描述如image/*代表图片类多个类型用英文逗号分隔如image/*, application/pdf。默认存储引擎勾选后设为系统默认存储引擎附件字段或文件表未指定存储引擎时上传文件均保存至默认存储引擎默认存储引擎不可删除。删除记录时保留文件勾选后附件表或文件表记录被删除时仍保留存储中已上传的文件默认不勾选即删除记录时同步删除存储中的文件。文件上传后最终访问路径由几部分拼接而成访问 URL 基础/路径/文件名后缀名例如https://cdn.nocobase.com/app/user/avatar/20240529115151.png。从源码看storages 表的字段定义见 storages 集合定义与上述参数一一对应title标题、name系统名uid类型且unique: true、type引擎类型标识如local/ali-oss、optionsjsonb配置项、rulesjsonb文件规则、path存储相对路径、baseUrl访问地址前缀、renameMode重命名模式默认appendRandomID即追加随机 ID、default是否默认引擎、paranoid删除记录时是否保留文件默认false。本地存储上传文件将保存在服务器本地硬盘目录中适用于系统管理的上传文件总量较少或试验性场景。本地存储的专用参数只有一个路径同时表达文件存储在服务器上的相对路径和 URL 访问路径。如user/avatar代表了上传时存储在服务器上的相对路径/path/to/nocobase-app/storage/uploads/user/avatar访问时的 URL 地址前缀http://localhost:13000/storage/uploads/user/avatar。源码层面本地存储实现在 local.ts默认documentRoot为storage/uploads可用环境变量LOCAL_STORAGE_DEST覆盖通过multer.diskStorage落盘文件名由diskFilenameGetter按重命名模式生成同时实现了exists/copy/delete/getFileStream/getFileURL等方法并在路径解析中内置了路径穿越防护resolveSafePath校验目标必须位于文档根目录之内越界访问抛出PATH_TRAVERSAL错误。阿里云 OSS基于阿里云 OSS 的存储引擎使用前需要准备相关账号和权限专用参数如下参数说明区域OSS 存储的区域例如oss-cn-hangzhou。只需截取区域前缀部分无需完整域名。AccessKey ID阿里云授权访问密钥的 ID。AccessKey Secret阿里云授权访问密钥的 Secret。存储桶OSS 存储的存储桶名称。腾讯云 COS基于腾讯云 COS 的存储引擎专用参数如下参数说明区域COS 存储的区域例如ap-chengdu。只需截取区域前缀部分无需完整域名。SecretId腾讯云授权访问密钥的 ID。SecretKey腾讯云授权访问密钥的 Secret。存储桶COS 存储的存储桶名称例如qing-cdn-1234189398。Amazon S3 与 S3 Pro内置引擎中的 Amazon S3 文档标注为「待补充」源码层面对应 s3.ts。对于需要完整 S3 兼容能力的场景官方提供商业插件file-storage-s3-pro详见 S3 (Pro) 文档它有两个关键能力客户端上传文件上传过程无需经过 NocoBase 服务器直接对接文件存储服务更高效、快速私有访问访问文件时所有 URL 均为经过签名的临时授权地址保证文件访问的安全性和时效性。S3 Pro 兼容任何支持 S3 协议的对象存储服务例如亚马逊 S3、阿里云 OSS、腾讯云 COS、MinIO、Cloudflare R2 等。启用流程为开启plugin-file-storage-s3-pro插件 → 进入「Setting → FileManager」→ 点击「Add new」选择「S3 Pro」→ 按各服务商文档填写表单。不同服务商的配置要点Amazon S3创建 Bucket 后需配置 CORS允许POST/PUT方法与ETag暴露头获取 AccessKey/SecretAccessKey可选配置公开访问与 CloudFront 动态图片缩略图Thumbnail rule形如?width100Access endpoint填部署后 Outputs 的 ApiEndpoint 值Full access URL style勾选 Ignore阿里云 OSS创建 Bucket 后在「Content Security → CORS」创建规则获取 AccessKey 与 Regionendpoint填入 NocoBase 时需要加https://前缀可选配置图片处理缩略图MinIO私有部署无 Region 概念Region 可填autoEndpoint 填部署的服务域名或 IPFull access URL style需设置为 Path-Style腾讯 COS、Cloudflare R2参考上述服务配置逻辑相似。HTTP API服务端上传与客户端直传附件字段和文件表的文件上传均支持通过 HTTP API 处理根据存储引擎不同调用方式分为两类详见 HTTP API 文档。服务端上传针对 S3、OSS、COS 等内置开源存储引擎HTTP API 与界面上传调用相同文件均通过服务端上传。调用接口需要在Authorization请求头中传递基于用户登录的 JWT 令牌否则将被拒绝访问。附件字段对附件表attachments资源发起create操作通过file字段上传二进制内容文件会上传至默认存储引擎curl -X POST \ -H Authorization: Bearer JWT \ -F filepath/to/file \ http://localhost:3000/api/attachments:create如需上传至不同的存储引擎通过attachmentField参数指定数据表字段已配置的存储引擎未配置则上传至默认存储引擎curl -X POST \ -H Authorization: Bearer JWT \ -F filepath/to/file \ http://localhost:3000/api/attachments:create?attachmentFieldcollection_name.field_name文件表对文件表上传会自动生成文件记录请求同样通过file字段上传二进制内容文件会上传至该表配置的存储引擎无需指定引擎curl -X POST \ -H Authorization: Bearer JWT \ -F filepath/to/file \ http://localhost:3000/api/file_collection_name:create客户端上传S3 Pro针对商业插件 S3-Pro 提供的 S3 兼容存储引擎HTTP API 上传分为以下几步1. 获取存储引擎信息对存储表storages发起getBasicInfo操作携带存储空间标识curl http://localhost:13000/api/storages:getBasicInfo/storage_name \ -H Authorization: Bearer JWT返回示例{ id: 2, title: xxx, name: xxx, type: s3-compatible, rules: { ... } }2. 获取服务商的预签名信息对fileStorageS3资源发起createPresignedUrl操作在 body 中携带文件相关信息curl http://localhost:13000/api/fileStorageS3:createPresignedUrl \ -X POST \ -H Accept: application/json, text/plain, */* \ -H Authorization: Bearer JWT \ -H Content-Type: application/json \ --data-raw {name:name,size:size,type:type,storageId:storageId,storageType:storageType}其中name为文件名size为文件大小bytestype为 MIME 类型storageId与storageType取第一步返回的id与type字段。示例请求数据--data-raw {name:a.png,size:4405,type:image/png,storageId:2,storageType:s3-compatible}返回的预签名信息{ putUrl: https://xxxxxxx, fileInfo: { key: xxx, title: xxx, filename: xxx, extname: .png, size: 4405, mimetype: image/png, meta: {}, url: } }3. 文件上传使用返回的putUrl发起PUT请求将文件作为 body 上传curl putUrl \ -X PUT \ -T file_path4. 创建文件行记录上传成功后对附件表attachments发起create操作创建文件记录curl http://localhost:13000/api/attachments:create?attachmentFieldcollection_name.field_name \ -X POST \ -H Accept: application/json, text/plain, */* \ -H Authorization: Bearer JWT \ -H Content-Type: application/json \ --data-raw {title:title,filename:filename,extname:extname,path:,size:size,url:,mimetype:mimetype,meta:meta,storageId:storageId}data-raw 中字段与第二步返回的fileInfo对应title、filename取fileInfo.key、extname、size、mimetype、meta均取自fileInfopath与url默认为空storageId取第一步返回的id。示例--data-raw {title:ATT00001,filename:ATT00001-8nuuxkuz4jn.png,extname:.png,path:,size:4405,url:,mimetype:image/png,meta:{},storageId:2}文件表场景前三步与附件字段相同仅第四步改为对文件表资源发起create操作curl http://localhost:13000/api/file_collection_name:create \ -H Authorization: Bearer JWT \ -H Content-Type: application/json \ --data-raw {title:title,filename:filename,extname:extname,path:,size:size,url:,mimetype:mimetype,meta:meta,storageId:storageId}源码视角文件管理器的实现脉络插件源码位于 plugin-file-manager 目录几个值得深入的关键点attachments 集合common/collections/attachments.ts声明了title、filename、extname、size、mimetype、storagebelongsTostorages外键storageId不可删除、path、metajsonb、url等字段印证了「文件表 元信息表」的设计storages 集合common/collections/storages.ts以title/name/type/options/rules/path/baseUrl/renameMode/default/paranoid等字段承载引擎配置renameMode默认appendRandomID解释了为什么上传后的文件名会带有随机后缀存储引擎适配server/storages 目录local.ts、ali-oss.ts、s3.ts、tx-cos.ts分别实现本地、阿里云 OSS、S3、腾讯 COS 的读写与 URL 生成其中本地存储在路径安全上做了白名单与防目录穿越校验HTTP 动作server/actions 目录attachments.ts、storages.ts分别承载attachments:create、storages:getBasicInfo等 API 动作与上文 HTTP API 一一对应。如果需要基于文件管理器做二次开发自定义存储引擎、扩展文件元信息、接入更多对象存储可参考扩展开发文档继续深入。【免费下载链接】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），仅供参考