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 name="storage" label={t('Files storage')} initialValue="local"> <Select options={storages} /> </Form.Item>

几个值得注意的细节：

表单项的initialValue为"local"，即未做任何配置时默认使用本地存储；
下拉选项storages由listStorageOptions异步加载；
保存后调用aiSettings资源的update动作（filterByTk: 1），将选中的存储名写入设置记录。

页面加载时会并行执行两个请求（见 AdminSettingsPage.tsx#L96-L130）：

loadAdminSettings：调用aiSettings:get，读取当前已保存的存储设置，回填到表单；
listStorageOptions：调用aiSettings:listStorages，获取全部可选存储列表。

Files storage 的可选项从哪里来

原文档明确指出：Files storage的可选存储项目，在文件管理插件中设置。也就是说，下拉框里的每一项都对应文件管理插件中已注册的一个存储（Storage）实例，而不是 AI 插件自己定义的枚举。

在服务端，listStorages动作的实现位于 aiSettings.ts：

listStorages: 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 目录：

存储类型	配置表单文件	服务端实现
本地存储（Local）	LocalStorageForm.tsx	storages/local.ts
S3 兼容对象存储	S3StorageForm.tsx	storages/s3.ts
阿里云 OSS	AliOssStorageForm.tsx	storages/ali-oss.ts
腾讯云 COS	TxCosStorageForm.tsx	storages/tx-cos.ts

每种存储都继承 StorageType 抽象基类，统一实现上传引擎（make）、删除（delete）、文件存在性检查（exists）、文件复制（copy）、URL 生成（getFileURL）与流式读取（getFileStream）等能力，因此无论选择哪种存储，AI 员工的文件上传链路保持一致。

本地存储的默认配置

以本地存储为例，其默认值定义在 local.ts#L99-L114：

static 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.ts：

export 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' }, ], });

存储选择保存在options（jsonb 类型）字段中，默认值为{ storage: 'local' }，与前端表单的initialValue="local"保持一致——这也是「零配置即用本地存储」的依据。

aiSettings资源暴露了多个动作（见 server/resource/aiSettings.ts）：

动作	作用
`get`	读取当前设置，返回`options`及`defaultLLMService`、`defaultModel`
`update`	合并更新`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 员工对话文件选择合适的落盘方案。

企业官网建设流程全解析