NocoBase AI 员工文件存储配置指南通过 Settings 的 Files storage 与文件管理插件管理对话上传文件【免费下载链接】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 AI 员工AI Employees对话过程中上传文件的存储方式展开完整讲解配置入口、可选项来源、存储类型与底层实现原理。读完本文你将掌握如何在 AI 员工插件配置页的Settings中为对话上传文件选择存储位置如何在文件管理插件中新建各类存储本地、S3、阿里云 OSS、腾讯云 COS以及这些选项从前端表单到后端资源再到上传链路的完整数据流。文件管理在 AI 员工中的定位AI 员工是 NocoBase 中以对话方式完成业务任务的 AI 能力载体。在与 AI 员工对话时用户常常需要上传附件图片、文档、表格等AI 也可能在对话过程中产出文件。这些文件存到哪里、以什么方式存储由 AI 员工插件中的「文件管理」设置统一决定。nocobase/plugin-ai插件通过一个名为Files storage的配置项来指定对话上传文件的默认存储而所有可供选择的存储实例本身由独立的文件管理插件nocobase/plugin-file-manager负责维护。二者通过资源接口协作形成「AI 员工选存储、文件管理管存储」的清晰分工。配置入口AI 员工插件 Settings 页面根据 docs/docs/cn/ai-employees/file-manager.md 的说明配置步骤如下进入AI 员工插件配置页面点击Settings标签页进入存储方式设置页在Files storage下拉框中选择期望的存储方式点击保存。该页面在源码中的实现位于 AdminSettingsPage.tsx其核心就是一个Files storage下拉表单项Form.Item namestorage label{t(Files storage)} initialValuelocal Select options{storages} / /Form.Item几个值得注意的细节表单项的initialValue为local即未做任何配置时默认使用本地存储下拉选项storages由listStorageOptions异步加载保存后调用aiSettings资源的update动作filterByTk: 1将选中的存储名写入设置记录。页面加载时会并行执行两个请求见 AdminSettingsPage.tsx#L96-L130loadAdminSettings调用aiSettings:get读取当前已保存的存储设置回填到表单listStorageOptions调用aiSettings:listStorages获取全部可选存储列表。Files storage 的可选项从哪里来原文档明确指出Files storage的可选存储项目在文件管理插件中设置。也就是说下拉框里的每一项都对应文件管理插件中已注册的一个存储Storage实例而不是 AI 插件自己定义的枚举。在服务端listStorages动作的实现位于 aiSettings.tslistStorages: async (ctx, next) { const plugin ctx.app.pm.get(file-manager) as PluginFileManagerServer; const storages plugin.storagesCache.values(); ctx.body Array.from(storages).map((storage) ({ label: storage.title, value: storage.name, })); await next(); },从源码结构看它直接从文件管理插件的storagesCache中读取所有存储实例并将其title作为下拉标签、name作为提交值。因此在文件管理插件中新建的存储会立即出现在AI 员工 Settings 的下拉列表中下拉选项的展示名是存储的标题如 Local storage提交值是存储的 name如local若文件管理插件中没有可用的存储则下拉为空此时应先去文件管理插件创建存储。在文件管理插件中新建存储文件管理插件nocobase/plugin-file-manager维护独立的storages集合定义见 server/collections/storages.ts其管理页面由 FileStoragePage.tsx 实现。插件内置了四类存储的配置表单见 storage-forms 目录存储类型配置表单文件服务端实现本地存储LocalLocalStorageForm.tsxstorages/local.tsS3 兼容对象存储S3StorageForm.tsxstorages/s3.ts阿里云 OSSAliOssStorageForm.tsxstorages/ali-oss.ts腾讯云 COSTxCosStorageForm.tsxstorages/tx-cos.ts每种存储都继承 StorageType 抽象基类统一实现上传引擎make、删除delete、文件存在性检查exists、文件复制copy、URL 生成getFileURL与流式读取getFileStream等能力因此无论选择哪种存储AI 员工的文件上传链路保持一致。本地存储的默认配置以本地存储为例其默认值定义在 local.ts#L99-L114static defaults() { return { title: Local storage, type: STORAGE_TYPE_LOCAL, name: local, baseUrl: /storage/uploads, options: { documentRoot: storage/uploads, }, path: , rules: { size: FILE_SIZE_LIMIT_DEFAULT, }, }; }baseUrl默认/storage/uploads是文件对外访问的 URL 前缀options.documentRoot默认storage/uploads是文件在服务器上的落盘目录可通过环境变量LOCAL_STORAGE_DEST覆盖根目录LOCAL_STORAGE_ALLOWED_ROOTS声明额外允许的根目录见 local.ts#L48-L57所有本地路径都经过resolveSafePath的目录越界校验越界访问会抛出PATH_TRAVERSAL错误防止路径穿越攻击见 local.ts#L75-L82。设置如何被保存与读取aiSettings 资源与数据模型AI 员工的存储设置落在一个名为aiSettings的系统集合中其字段定义见 ai-settings.tsexport default defineCollection({ name: aiSettings, dataCategory: system, migrationRules: [overwrite, schema-only], fields: [ { type: jsonb, name: options, defaultValue: { storage: local }, }, { type: string, name: defaultLLMService }, { type: string, name: defaultModel }, ], });存储选择保存在optionsjsonb 类型字段中默认值为{ storage: local }与前端表单的initialValuelocal保持一致——这也是「零配置即用本地存储」的依据。aiSettings资源暴露了多个动作见 server/resource/aiSettings.ts动作作用get读取当前设置返回options及defaultLLMService、defaultModelupdate合并更新options如将storage改为所选存储名publicGet公开读取仅返回{ storage }供前端会话初始化使用listStorages从文件管理插件拉取可选存储列表供 Settings 下拉框渲染isKnowledgeBaseEnabled查询知识库功能是否启用update的实现值得注意它把defaultLLMService、defaultModel之外的其余值合并进已有options见 aiSettings.ts#L27-L44因此修改存储不会影响其他 AI 设置。对话上传文件的完整链路与限制校验配置好存储后AI 员工对话中的上传请求会按以下链路工作前端聊天框根据当前 AI 员工的存储配置通过storages:getBasicInfo/{storageName}获取该存储的基本信息含rules见 useUploadFiles.ts存储的rules.size等限制被解析为上传校验规则超限附件会被拦截相关校验逻辑集中在 chatbox/utils 中并有配套测试 attachmentLimits.test.ts 与 uploadAttachment.test.ts 验证文件经上传动作写入所选存储服务端将附件记录写入attachments集合见 file-manager 的 collections/attachments.ts后续 AI 员工会话中的附件读取、预览与下载均基于存储类型生成 URL 或流式读取。另外AI 员工不仅能在对话中接收文件还能在工作流节点中产出或处理文件相关实现见 workflow/nodes/employee/files.ts其文件处理同样依赖文件管理插件的存储能力。常见场景与配置建议开发/内网试用保持默认local即可文件落在服务端storage/uploads目录无需额外依赖多节点部署或需要共享访问建议在文件管理插件中新建 S3 兼容存储如 MinIO或云厂商对象存储避免本地磁盘在多实例间不一致上传大小限制在各存储实例的rules.size中配置AI 员工上传时即按该限制在前端校验设置不生效排查确认aiSettings集合中options.storage的值与文件管理插件中存储的name一致注意name并非展示标题title存储被删除后的表现由于下拉选项来自storagesCache若选中的存储被删除前端将回退为空选项需要重新选择并保存。小结AI 员工的文件管理本质是一个「选择存储」的配置问题AI 员工插件负责在 Settings 中提供 Files storage 选择入口并持久化选择结果文件管理插件负责存储实例的创建、参数配置与实际读写。二者通过aiSettings资源的listStorages动作和文件管理插件的storagesCache完成衔接。掌握了这条链路你便可以根据部署环境灵活地为 AI 员工对话文件选择合适的落盘方案。相关参考文档原文docs/docs/cn/ai-employees/file-manager.md设置页面实现packages/plugins/nocobase/plugin-ai/src/client-v2/pages/AdminSettingsPage.tsx服务端资源packages/plugins/nocobase/plugin-ai/src/server/resource/aiSettings.ts设置数据模型packages/plugins/nocobase/plugin-ai/src/server/collections/ai-settings.ts文件管理插件存储实现packages/plugins/nocobase/plugin-file-manager/src/server/storages存储配置表单packages/plugins/nocobase/plugin-file-manager/src/client-v2/storage-forms【免费下载链接】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），仅供参考
NocoBase AI 员工文件存储配置指南：通过 Settings 的 Files storage 与文件管理插件管理对话上传文件
NocoBase AI 员工文件存储配置指南通过 Settings 的 Files storage 与文件管理插件管理对话上传文件【免费下载链接】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 AI 员工AI Employees对话过程中上传文件的存储方式展开完整讲解配置入口、可选项来源、存储类型与底层实现原理。读完本文你将掌握如何在 AI 员工插件配置页的Settings中为对话上传文件选择存储位置如何在文件管理插件中新建各类存储本地、S3、阿里云 OSS、腾讯云 COS以及这些选项从前端表单到后端资源再到上传链路的完整数据流。文件管理在 AI 员工中的定位AI 员工是 NocoBase 中以对话方式完成业务任务的 AI 能力载体。在与 AI 员工对话时用户常常需要上传附件图片、文档、表格等AI 也可能在对话过程中产出文件。这些文件存到哪里、以什么方式存储由 AI 员工插件中的「文件管理」设置统一决定。nocobase/plugin-ai插件通过一个名为Files storage的配置项来指定对话上传文件的默认存储而所有可供选择的存储实例本身由独立的文件管理插件nocobase/plugin-file-manager负责维护。二者通过资源接口协作形成「AI 员工选存储、文件管理管存储」的清晰分工。配置入口AI 员工插件 Settings 页面根据 docs/docs/cn/ai-employees/file-manager.md 的说明配置步骤如下进入AI 员工插件配置页面点击Settings标签页进入存储方式设置页在Files storage下拉框中选择期望的存储方式点击保存。该页面在源码中的实现位于 AdminSettingsPage.tsx其核心就是一个Files storage下拉表单项Form.Item namestorage label{t(Files storage)} initialValuelocal Select options{storages} / /Form.Item几个值得注意的细节表单项的initialValue为local即未做任何配置时默认使用本地存储下拉选项storages由listStorageOptions异步加载保存后调用aiSettings资源的update动作filterByTk: 1将选中的存储名写入设置记录。页面加载时会并行执行两个请求见 AdminSettingsPage.tsx#L96-L130loadAdminSettings调用aiSettings:get读取当前已保存的存储设置回填到表单listStorageOptions调用aiSettings:listStorages获取全部可选存储列表。Files storage 的可选项从哪里来原文档明确指出Files storage的可选存储项目在文件管理插件中设置。也就是说下拉框里的每一项都对应文件管理插件中已注册的一个存储Storage实例而不是 AI 插件自己定义的枚举。在服务端listStorages动作的实现位于 aiSettings.tslistStorages: async (ctx, next) { const plugin ctx.app.pm.get(file-manager) as PluginFileManagerServer; const storages plugin.storagesCache.values(); ctx.body Array.from(storages).map((storage) ({ label: storage.title, value: storage.name, })); await next(); },从源码结构看它直接从文件管理插件的storagesCache中读取所有存储实例并将其title作为下拉标签、name作为提交值。因此在文件管理插件中新建的存储会立即出现在AI 员工 Settings 的下拉列表中下拉选项的展示名是存储的标题如 Local storage提交值是存储的 name如local若文件管理插件中没有可用的存储则下拉为空此时应先去文件管理插件创建存储。在文件管理插件中新建存储文件管理插件nocobase/plugin-file-manager维护独立的storages集合定义见 server/collections/storages.ts其管理页面由 FileStoragePage.tsx 实现。插件内置了四类存储的配置表单见 storage-forms 目录存储类型配置表单文件服务端实现本地存储LocalLocalStorageForm.tsxstorages/local.tsS3 兼容对象存储S3StorageForm.tsxstorages/s3.ts阿里云 OSSAliOssStorageForm.tsxstorages/ali-oss.ts腾讯云 COSTxCosStorageForm.tsxstorages/tx-cos.ts每种存储都继承 StorageType 抽象基类统一实现上传引擎make、删除delete、文件存在性检查exists、文件复制copy、URL 生成getFileURL与流式读取getFileStream等能力因此无论选择哪种存储AI 员工的文件上传链路保持一致。本地存储的默认配置以本地存储为例其默认值定义在 local.ts#L99-L114static defaults() { return { title: Local storage, type: STORAGE_TYPE_LOCAL, name: local, baseUrl: /storage/uploads, options: { documentRoot: storage/uploads, }, path: , rules: { size: FILE_SIZE_LIMIT_DEFAULT, }, }; }baseUrl默认/storage/uploads是文件对外访问的 URL 前缀options.documentRoot默认storage/uploads是文件在服务器上的落盘目录可通过环境变量LOCAL_STORAGE_DEST覆盖根目录LOCAL_STORAGE_ALLOWED_ROOTS声明额外允许的根目录见 local.ts#L48-L57所有本地路径都经过resolveSafePath的目录越界校验越界访问会抛出PATH_TRAVERSAL错误防止路径穿越攻击见 local.ts#L75-L82。设置如何被保存与读取aiSettings 资源与数据模型AI 员工的存储设置落在一个名为aiSettings的系统集合中其字段定义见 ai-settings.tsexport default defineCollection({ name: aiSettings, dataCategory: system, migrationRules: [overwrite, schema-only], fields: [ { type: jsonb, name: options, defaultValue: { storage: local }, }, { type: string, name: defaultLLMService }, { type: string, name: defaultModel }, ], });存储选择保存在optionsjsonb 类型字段中默认值为{ storage: local }与前端表单的initialValuelocal保持一致——这也是「零配置即用本地存储」的依据。aiSettings资源暴露了多个动作见 server/resource/aiSettings.ts动作作用get读取当前设置返回options及defaultLLMService、defaultModelupdate合并更新options如将storage改为所选存储名publicGet公开读取仅返回{ storage }供前端会话初始化使用listStorages从文件管理插件拉取可选存储列表供 Settings 下拉框渲染isKnowledgeBaseEnabled查询知识库功能是否启用update的实现值得注意它把defaultLLMService、defaultModel之外的其余值合并进已有options见 aiSettings.ts#L27-L44因此修改存储不会影响其他 AI 设置。对话上传文件的完整链路与限制校验配置好存储后AI 员工对话中的上传请求会按以下链路工作前端聊天框根据当前 AI 员工的存储配置通过storages:getBasicInfo/{storageName}获取该存储的基本信息含rules见 useUploadFiles.ts存储的rules.size等限制被解析为上传校验规则超限附件会被拦截相关校验逻辑集中在 chatbox/utils 中并有配套测试 attachmentLimits.test.ts 与 uploadAttachment.test.ts 验证文件经上传动作写入所选存储服务端将附件记录写入attachments集合见 file-manager 的 collections/attachments.ts后续 AI 员工会话中的附件读取、预览与下载均基于存储类型生成 URL 或流式读取。另外AI 员工不仅能在对话中接收文件还能在工作流节点中产出或处理文件相关实现见 workflow/nodes/employee/files.ts其文件处理同样依赖文件管理插件的存储能力。常见场景与配置建议开发/内网试用保持默认local即可文件落在服务端storage/uploads目录无需额外依赖多节点部署或需要共享访问建议在文件管理插件中新建 S3 兼容存储如 MinIO或云厂商对象存储避免本地磁盘在多实例间不一致上传大小限制在各存储实例的rules.size中配置AI 员工上传时即按该限制在前端校验设置不生效排查确认aiSettings集合中options.storage的值与文件管理插件中存储的name一致注意name并非展示标题title存储被删除后的表现由于下拉选项来自storagesCache若选中的存储被删除前端将回退为空选项需要重新选择并保存。小结AI 员工的文件管理本质是一个「选择存储」的配置问题AI 员工插件负责在 Settings 中提供 Files storage 选择入口并持久化选择结果文件管理插件负责存储实例的创建、参数配置与实际读写。二者通过aiSettings资源的listStorages动作和文件管理插件的storagesCache完成衔接。掌握了这条链路你便可以根据部署环境灵活地为 AI 员工对话文件选择合适的落盘方案。相关参考文档原文docs/docs/cn/ai-employees/file-manager.md设置页面实现packages/plugins/nocobase/plugin-ai/src/client-v2/pages/AdminSettingsPage.tsx服务端资源packages/plugins/nocobase/plugin-ai/src/server/resource/aiSettings.ts设置数据模型packages/plugins/nocobase/plugin-ai/src/server/collections/ai-settings.ts文件管理插件存储实现packages/plugins/nocobase/plugin-file-manager/src/server/storages存储配置表单packages/plugins/nocobase/plugin-file-manager/src/client-v2/storage-forms【免费下载链接】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），仅供参考
