NocoBase 文件管理器腾讯云 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/nocobaseNocoBase 的文件管理器内置了多种存储引擎其中腾讯云 COSCloud Object Storage云对象存储引擎可以让附件字段和文件表直接将文件上传至腾讯云对象存储。本文以 腾讯云 COS 配置文档 为主体完整讲解其四个专用配置参数、与所有引擎共用的通用参数并结合插件源码tx-cos.ts剖析上传、删除、复制、签名 URL 生成的底层实现最后给出可复现的测试与接入步骤。读完本文你将能独立在 NocoBase 中接入腾讯云 COS并理解其工作原理。腾讯云 COS 存储引擎是什么NocoBase 文件管理器在系统安装时会自动添加一个本地存储引擎可直接使用同时它也支持接入阿里云 OSS、Amazon S3、腾讯云 COS 等云端对象存储。腾讯云 COS 引擎的存储类型标识为tx-cos定义见 constants.ts它在服务端通过腾讯云官方 Node.js SDKcos-nodejs-sdk-v5完成与 COS 的通信。使用该引擎前你需要准备腾讯云账号、具备对象存储权限的访问密钥SecretId / SecretKey以及一个已创建好的存储桶Bucket和对应区域Region。引擎通用参数腾讯云 COS 引擎除了自身的专用参数外还与其他引擎共用一套通用参数详见引擎通用参数。以本地存储为例通用参数如下参数说明标题存储引擎的名称用于人工识别。系统名存储引擎的系统名称用于系统识别。必须是系统唯一的不填会由系统自动随机生成。访问 URL 基础该文件对外可访问的 URL 地址前缀部分可以是 CDN 的访问 URL 基础如https://cdn.nocobase.com/app无需结尾的/。路径存储文件时使用的相对路径在访问时此部分也会被自动拼接到最终的 URL 中如user/avatar无需开头和结尾的/。文件大小限制对此存储引擎上传文件时的大小限制超过该设置大小的文件将无法上传。系统默认限制为 20MB可调整到的最大限制为 1GB。文件类型可对上传文件的类型进行限制使用 MIME 语法描述格式例如image/*代表图片类文件多个类型用英文逗号分隔如image/*, application/pdf表示允许图片和 PDF 文件。默认存储引擎勾选后设置为系统的默认存储引擎在附件字段或文件表未指定存储引擎时上传的文件均会保存至默认存储引擎中。默认存储引擎不可删除。删除记录时保留文件勾选后当附件表或文件表的数据记录被删除时仍然保留存储引擎中已上传的文件。默认不勾选即删除记录时会同时删除存储引擎中的文件。:::info 提示 文件上传后最终的访问路径由以下部分拼接而成访问 URL 基础/路径/文件名后缀名例如https://cdn.nocobase.com/app/user/avatar/20240529115151.png。 :::COS 引擎专用配置参数在“文件存储引擎”页面新建或编辑腾讯云 COS 引擎时需要填写以下四个专用参数区域Region填写 COS 存储的区域例如ap-chengdu。可在腾讯云 COS 控制台中查看存储空间的区域信息只需截取区域前缀部分即可无需完整域名即填ap-chengdu而不是cos.ap-chengdu.myqcloud.com这样的完整访问域名。从源码看Region会作为 SDK 客户端初始化参数与putObject/deleteObject/headObject等所有请求参数中的Region字段传入见 tx-cos.ts它决定了请求被路由到哪个地域的 COS 服务。SecretId填写腾讯云授权访问密钥的 ID。在 tx-cos.ts 中SecretId与SecretKey一起被传入cos-nodejs-sdk-v5的构造函数用于请求签名。SecretKey填写腾讯云授权访问密钥的 Secret。注意在配置表单中SecretKey 输入框被标记为密码类型password: true见 tx-cos.tsx输入时会被掩码处理。建议在腾讯云访问管理CAM中为 COS 创建专用的子账号密钥并仅授予所需存储桶的读写权限避免使用主账号密钥。存储桶Bucket填写 COS 存储的存储桶名称例如qing-cdn-1234189398。存储桶名称由自定义后缀与 AppId 组合而成需完整填写。同样地Bucket会作为 SDK 客户端参数以及每次对象操作请求的Bucket字段使用。配置表单中的附加选项从客户端表单 schematx-cos.tsx可以看到除上述四个必填参数required: true外还提供了以下可选项SecurityToken / XCosSecurityToken临时密钥场景下的安全令牌使用 STS 临时凭证时填写对应 SDK 构造参数。FileParallelLimit / ChunkParallelLimit / ChunkSize / Timeout / KeepAlive 等SDK 传输并发与超时调优参数。Domain / Protocol / ForcePathStyle / CompatibilityMode / UseAccelerate自定义域名、协议、路径风格与加速访问等高级选项。Thumbnail rule图片缩略图处理规则占位示例为?imageMogr2/thumbnail/!50p适用于开启了数据万象图片处理的存储桶。这些参数均透传至cos-nodejs-sdk-v5客户端实例可根据实际场景按需填写。配置步骤接入腾讯云 COS登录 NocoBase 后台进入“文件管理器”插件的存储引擎管理页面新安装系统后默认已存在一个本地存储引擎。点击“添加”新建存储引擎选择类型为“腾讯云 COSTencent COS”。依次填写通用参数标题、系统名、访问 URL 基础、路径、文件大小限制、文件类型等与专用参数区域、SecretId、SecretKey、存储桶。若希望通过 CDN 或自定义域名访问文件在“访问 URL 基础”中填写对应前缀如https://cdn.example.com不填时源码中的getUploadedFileURL会回退使用 SDK 返回的Location字段见 tx-cos.ts。如希望所有附件默认走 COS勾选“默认存储引擎”。保存后在附件字段见附件字段或文件表见文件表中即可指定该存储引擎上传文件。环境变量方式初始化服务端还支持通过环境变量为 COS 引擎提供默认配置见 tx-cos.ts环境变量对应参数TX_COS_REGION区域TX_COS_SECRET_IDSecretIdTX_COS_SECRET_KEYSecretKeyTX_COS_BUCKET存储桶TX_COS_STORAGE_BASE_URL访问 URL 基础这些环境变量在defaults()中被读取作为新建 COS 引擎时的默认值适合在部署时通过环境注入密钥避免在配置界面明文保存。源码级实现原理服务端存储引擎的实现位于 tx-cos.ts其核心是一个继承自StorageType的类通过make()方法实例化底层 COS 客户端。各文件操作与 SDK 方法的对应关系如下业务操作底层方法说明上传_handleFilecos.putObject将文件流通过管道流式上传并通过CountingStream统计实际传输字节数作为文件sizetext/plain类型会被强制带上charsetutf-8见 tx-cos.ts。删除_removeFilecos.deleteObject按Key删除单个对象tx-cos.ts。批量删除deletecos.deleteMultipleObject批量删除多个对象并返回实际删除数量与未删除记录tx-cos.ts。文件存在性existscos.headObject通过 HEAD 请求探测对象是否存在NoSuchKey/NotFound视为不存在tx-cos.ts。复制copycos.putObjectCopy按{Bucket}.cos.{Region}.myqcloud.com/{Key}构造复制源地址tx-cos.ts。下载/预览 URLgetFileURLcos.getObjectUrl仅在download场景下生成带签名的临时 URL默认有效期signedUrlExpires为 900 秒并通过response-content-disposition指定下载文件名tx-cos.ts。几个值得注意的实现细节流式上传上传时并不会把文件整体读入内存而是把请求的file.stream直接 pipe 给 SDK 的Body配合计数流统计字节数对超大文件更友好。文件名生成文件Key由cloudFilenameGetter基于存储引擎的path配置与重命名规则renameMode生成对应测试中path: test/path与Key: test/path/text.txt的断言。私有桶下载当 COS 存储桶为私有读写时普通预览 URL 走StorageType基类逻辑而下载请求使用签名 URL既保证了安全又避免了密钥泄露到浏览器端。测试验证插件仓库中提供了针对 COS 引擎的两类测试tx-cos.test.ts端到端上传测试storage:tx-cos在设置了TX_COS_SECRET_ID与TX_COS_SECRET_KEY环境变量时才会实际执行否则自动跳过验证通过attachments资源上传文件后数据库记录、URL 拼接${baseUrl}/${path}/${filename}以及通过 URL 读取文件内容均正常。引擎单元测试storage:tx-cos engine用 mock 的putObject验证流式上传的参数构造——包括Bucket、Region、Key、ContentType: text/plain; charsetutf-8以及返回的key、size、url是否符合预期。若要在本地复现端到端测试可先配置上述两个环境变量再运行对应用例单元测试不依赖真实 COS 服务可随时运行。常见问题与注意事项区域填错导致请求失败Region必须与存储桶创建时所在区域一致且只填区域前缀如ap-chengdu不要带上完整域名。密钥泄露风险SecretKey 属于敏感信息建议使用最小权限的子账号密钥或使用临时密钥配合 SecurityToken并通过环境变量注入。私有桶与 CDN若存储桶私有建议在“访问 URL 基础”中配置已绑定的 CDN 域名或自定义域名否则直接访问对象地址会返回签名错误此时下载功能依赖源码中的签名 URL 逻辑。默认存储引擎不可删除如需切换默认引擎先将新引擎勾选为默认再删除旧的。延伸阅读文件存储引擎概述与通用参数本地存储引擎阿里云 OSS 存储引擎Amazon S3 存储引擎文件管理器插件总览【免费下载链接】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 文件管理器：腾讯云 COS 存储引擎配置与实现原理详解
NocoBase 文件管理器腾讯云 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/nocobaseNocoBase 的文件管理器内置了多种存储引擎其中腾讯云 COSCloud Object Storage云对象存储引擎可以让附件字段和文件表直接将文件上传至腾讯云对象存储。本文以 腾讯云 COS 配置文档 为主体完整讲解其四个专用配置参数、与所有引擎共用的通用参数并结合插件源码tx-cos.ts剖析上传、删除、复制、签名 URL 生成的底层实现最后给出可复现的测试与接入步骤。读完本文你将能独立在 NocoBase 中接入腾讯云 COS并理解其工作原理。腾讯云 COS 存储引擎是什么NocoBase 文件管理器在系统安装时会自动添加一个本地存储引擎可直接使用同时它也支持接入阿里云 OSS、Amazon S3、腾讯云 COS 等云端对象存储。腾讯云 COS 引擎的存储类型标识为tx-cos定义见 constants.ts它在服务端通过腾讯云官方 Node.js SDKcos-nodejs-sdk-v5完成与 COS 的通信。使用该引擎前你需要准备腾讯云账号、具备对象存储权限的访问密钥SecretId / SecretKey以及一个已创建好的存储桶Bucket和对应区域Region。引擎通用参数腾讯云 COS 引擎除了自身的专用参数外还与其他引擎共用一套通用参数详见引擎通用参数。以本地存储为例通用参数如下参数说明标题存储引擎的名称用于人工识别。系统名存储引擎的系统名称用于系统识别。必须是系统唯一的不填会由系统自动随机生成。访问 URL 基础该文件对外可访问的 URL 地址前缀部分可以是 CDN 的访问 URL 基础如https://cdn.nocobase.com/app无需结尾的/。路径存储文件时使用的相对路径在访问时此部分也会被自动拼接到最终的 URL 中如user/avatar无需开头和结尾的/。文件大小限制对此存储引擎上传文件时的大小限制超过该设置大小的文件将无法上传。系统默认限制为 20MB可调整到的最大限制为 1GB。文件类型可对上传文件的类型进行限制使用 MIME 语法描述格式例如image/*代表图片类文件多个类型用英文逗号分隔如image/*, application/pdf表示允许图片和 PDF 文件。默认存储引擎勾选后设置为系统的默认存储引擎在附件字段或文件表未指定存储引擎时上传的文件均会保存至默认存储引擎中。默认存储引擎不可删除。删除记录时保留文件勾选后当附件表或文件表的数据记录被删除时仍然保留存储引擎中已上传的文件。默认不勾选即删除记录时会同时删除存储引擎中的文件。:::info 提示 文件上传后最终的访问路径由以下部分拼接而成访问 URL 基础/路径/文件名后缀名例如https://cdn.nocobase.com/app/user/avatar/20240529115151.png。 :::COS 引擎专用配置参数在“文件存储引擎”页面新建或编辑腾讯云 COS 引擎时需要填写以下四个专用参数区域Region填写 COS 存储的区域例如ap-chengdu。可在腾讯云 COS 控制台中查看存储空间的区域信息只需截取区域前缀部分即可无需完整域名即填ap-chengdu而不是cos.ap-chengdu.myqcloud.com这样的完整访问域名。从源码看Region会作为 SDK 客户端初始化参数与putObject/deleteObject/headObject等所有请求参数中的Region字段传入见 tx-cos.ts它决定了请求被路由到哪个地域的 COS 服务。SecretId填写腾讯云授权访问密钥的 ID。在 tx-cos.ts 中SecretId与SecretKey一起被传入cos-nodejs-sdk-v5的构造函数用于请求签名。SecretKey填写腾讯云授权访问密钥的 Secret。注意在配置表单中SecretKey 输入框被标记为密码类型password: true见 tx-cos.tsx输入时会被掩码处理。建议在腾讯云访问管理CAM中为 COS 创建专用的子账号密钥并仅授予所需存储桶的读写权限避免使用主账号密钥。存储桶Bucket填写 COS 存储的存储桶名称例如qing-cdn-1234189398。存储桶名称由自定义后缀与 AppId 组合而成需完整填写。同样地Bucket会作为 SDK 客户端参数以及每次对象操作请求的Bucket字段使用。配置表单中的附加选项从客户端表单 schematx-cos.tsx可以看到除上述四个必填参数required: true外还提供了以下可选项SecurityToken / XCosSecurityToken临时密钥场景下的安全令牌使用 STS 临时凭证时填写对应 SDK 构造参数。FileParallelLimit / ChunkParallelLimit / ChunkSize / Timeout / KeepAlive 等SDK 传输并发与超时调优参数。Domain / Protocol / ForcePathStyle / CompatibilityMode / UseAccelerate自定义域名、协议、路径风格与加速访问等高级选项。Thumbnail rule图片缩略图处理规则占位示例为?imageMogr2/thumbnail/!50p适用于开启了数据万象图片处理的存储桶。这些参数均透传至cos-nodejs-sdk-v5客户端实例可根据实际场景按需填写。配置步骤接入腾讯云 COS登录 NocoBase 后台进入“文件管理器”插件的存储引擎管理页面新安装系统后默认已存在一个本地存储引擎。点击“添加”新建存储引擎选择类型为“腾讯云 COSTencent COS”。依次填写通用参数标题、系统名、访问 URL 基础、路径、文件大小限制、文件类型等与专用参数区域、SecretId、SecretKey、存储桶。若希望通过 CDN 或自定义域名访问文件在“访问 URL 基础”中填写对应前缀如https://cdn.example.com不填时源码中的getUploadedFileURL会回退使用 SDK 返回的Location字段见 tx-cos.ts。如希望所有附件默认走 COS勾选“默认存储引擎”。保存后在附件字段见附件字段或文件表见文件表中即可指定该存储引擎上传文件。环境变量方式初始化服务端还支持通过环境变量为 COS 引擎提供默认配置见 tx-cos.ts环境变量对应参数TX_COS_REGION区域TX_COS_SECRET_IDSecretIdTX_COS_SECRET_KEYSecretKeyTX_COS_BUCKET存储桶TX_COS_STORAGE_BASE_URL访问 URL 基础这些环境变量在defaults()中被读取作为新建 COS 引擎时的默认值适合在部署时通过环境注入密钥避免在配置界面明文保存。源码级实现原理服务端存储引擎的实现位于 tx-cos.ts其核心是一个继承自StorageType的类通过make()方法实例化底层 COS 客户端。各文件操作与 SDK 方法的对应关系如下业务操作底层方法说明上传_handleFilecos.putObject将文件流通过管道流式上传并通过CountingStream统计实际传输字节数作为文件sizetext/plain类型会被强制带上charsetutf-8见 tx-cos.ts。删除_removeFilecos.deleteObject按Key删除单个对象tx-cos.ts。批量删除deletecos.deleteMultipleObject批量删除多个对象并返回实际删除数量与未删除记录tx-cos.ts。文件存在性existscos.headObject通过 HEAD 请求探测对象是否存在NoSuchKey/NotFound视为不存在tx-cos.ts。复制copycos.putObjectCopy按{Bucket}.cos.{Region}.myqcloud.com/{Key}构造复制源地址tx-cos.ts。下载/预览 URLgetFileURLcos.getObjectUrl仅在download场景下生成带签名的临时 URL默认有效期signedUrlExpires为 900 秒并通过response-content-disposition指定下载文件名tx-cos.ts。几个值得注意的实现细节流式上传上传时并不会把文件整体读入内存而是把请求的file.stream直接 pipe 给 SDK 的Body配合计数流统计字节数对超大文件更友好。文件名生成文件Key由cloudFilenameGetter基于存储引擎的path配置与重命名规则renameMode生成对应测试中path: test/path与Key: test/path/text.txt的断言。私有桶下载当 COS 存储桶为私有读写时普通预览 URL 走StorageType基类逻辑而下载请求使用签名 URL既保证了安全又避免了密钥泄露到浏览器端。测试验证插件仓库中提供了针对 COS 引擎的两类测试tx-cos.test.ts端到端上传测试storage:tx-cos在设置了TX_COS_SECRET_ID与TX_COS_SECRET_KEY环境变量时才会实际执行否则自动跳过验证通过attachments资源上传文件后数据库记录、URL 拼接${baseUrl}/${path}/${filename}以及通过 URL 读取文件内容均正常。引擎单元测试storage:tx-cos engine用 mock 的putObject验证流式上传的参数构造——包括Bucket、Region、Key、ContentType: text/plain; charsetutf-8以及返回的key、size、url是否符合预期。若要在本地复现端到端测试可先配置上述两个环境变量再运行对应用例单元测试不依赖真实 COS 服务可随时运行。常见问题与注意事项区域填错导致请求失败Region必须与存储桶创建时所在区域一致且只填区域前缀如ap-chengdu不要带上完整域名。密钥泄露风险SecretKey 属于敏感信息建议使用最小权限的子账号密钥或使用临时密钥配合 SecurityToken并通过环境变量注入。私有桶与 CDN若存储桶私有建议在“访问 URL 基础”中配置已绑定的 CDN 域名或自定义域名否则直接访问对象地址会返回签名错误此时下载功能依赖源码中的签名 URL 逻辑。默认存储引擎不可删除如需切换默认引擎先将新引擎勾选为默认再删除旧的。延伸阅读文件存储引擎概述与通用参数本地存储引擎阿里云 OSS 存储引擎Amazon S3 存储引擎文件管理器插件总览【免费下载链接】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），仅供参考
