ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

ToolJet MinIO 数据源接入指南:连接配置与七种对象存储操作详解

ToolJet MinIO 数据源接入指南:连接配置与七种对象存储操作详解 ToolJet MinIO 数据源接入指南连接配置与七种对象存储操作详解【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJetToolJet 内置了对 MinIO 的官方支持允许你在可视化应用构建器中直接连接 MinIO或任何 S3 兼容对象存储服务通过查询面板完成对象的上传、读取、删除、桶列表查询以及预签名 URL 生成等常见操作。本文以 docs/docs/data-sources/minio.md 为基础结合 plugins/packages/minio 下的真实插件源码与 schema 配置系统讲解数据源建立、参数含义、七种支持操作的用法及底层实现原理帮助你在一站式掌握 MinIO 数据源的同时了解 ToolJet 数据源插件的工作机制。一、MinIO 数据源插件概述在 ToolJet 中MinIO 属于内置的云存储类cloud-storage数据源插件。从仓库的 manifest.json 可以看到插件声明的元信息如下数据源类型cloud-storage插件标识kindminio对外暴露变量isLoading查询加载状态、data解析后的数据、rawData原始数据。插件底层基于 Node.js 官方minio客户端 SDK 实现核心服务类位于 index.ts它通过一个统一的run()方法将查询面板中选择的操作分发给 operations.ts 中对应的处理函数返回结构统一的QueryResult。二、建立与 MinIO 的连接2.1 操作入口要建立 MinIO 数据源连接有两种入口点击查询面板上的 Add new data source添加新数据源按钮在弹出列表中搜索并选择 MinIO从 ToolJet 首页左侧导航进入 Data Sources数据源 管理页面再点击添加数据源。2.2 连接参数说明根据 manifest.json 的定义连接 MinIO 需要以下配置项配置项表单类型是否必填默认值说明Hosttext是play.min.ioMinIO 服务主机地址表单内默认预填官方演示服务地址Porttext是9000MinIO API 服务端口SSLtoggle是开启true是否启用 HTTPS/TLS 加密访问Access keytext是空访问密钥 ID对应 AWS Access Key 概念Secret keypassword是空密钥对应 AWS Secret Key 概念保存时按加密字段处理encrypted: true上图为数据源配置界面的实际形态顶部支持按Development / Staging / Production环境分别维护配置Host 默认填play.min.ioMinIO 官方公开演示服务Port 默认9000SSL 开关默认开启Secret key 以密码框形式录入并在保存后加密显示。如果 MinIO 服务部署在受限网络界面会提示将 ToolJet 服务器的出口 IP 加入白名单。从源码实现来看index.ts 中的getConnection()方法会把这些表单值直接映射为minio客户端 SDK 的ClientOptionsconst credentials: ClientOptions { endPoint: sourceOptions[host], port: sourceOptions[port], // 字符串端口会被强制转为数值 useSSL: !!sourceOptions[ssl_enabled], // 开关值被转换为布尔型 accessKey: sourceOptions[access_key], secretKey: sourceOptions[secret_key], }; return new MinioClient(credentials);由此可以确认两点底层细节端口即使以字符串输入也会被正确转换因此不会出现连接失败SSL 开关直接决定客户端使用 http 还是 https 协议发起请求请保证其与实际部署的 MinIO 服务协议一致。2.3 测试连接配置完成后可点击Test connection验证连通性。对应实现位于 index.tsasync testConnection(sourceOptions: SourceOptions): PromiseConnectionTestResult { const minioClient: MinioClient await this.getConnection(sourceOptions); await minioClient.listBuckets(); // 通过列出所有桶来验证凭据与服务可用性 return { status: ok }; }即 ToolJet 会调用listBuckets()一次若请求成功返回{ status: ok }否则抛出异常并提示连接失败。测试成功后点击Save保存数据源即可在查询面板中使用。三、在查询面板中执行 MinIO 操作新建 MinIO 查询的标准流程如下点击编辑器底部查询管理器Query Manager的 Add按钮新建查询将数据源选择为上一步保存的 MinIO 数据源在Operation操作下拉框中选择要执行的操作按当前操作填写对应的参数Bucket、Object Name 等点击Run按钮执行查询结果会在右侧展示并被赋值到该查询的data/rawData变量中供其他组件引用。:::tip 查询结果还可以通过 ToolJet 的 Transformations数据转换功能进一步加工例如过滤字段、改写结构或聚合计算。关于转换的详细用法请阅读 数据转换Transformations指南。 :::从执行链路看服务端入口 index.ts 的run()方法会先根据queryOptions.operation构建连接再通过switch将请求路由到对应操作函数一旦执行抛出异常会被统一包装为QueryError(Query could not be completed, error.message, {})并在查询面板中呈现该错误信息。四、七种支持的 MinIO 操作详解MinIO 数据源共支持七种操作。操作下拉选项及其内部取值定义在 operations.json 中与 index.ts 的分发逻辑一一对应界面显示名称operation 取值用途Read objectget_object读取下载某个对象的内容Put objectput_object上传或更新桶中的对象List bucketslist_buckets列出所有存储桶List objects in a bucketlist_objects列出指定桶内的对象Presigned url for downloadsigned_url_for_get生成对象下载的预签名 URLPresigned url for uploadsigned_url_for_put生成对象上传的预签名 URLRemove objectremove_object删除桶中的某个对象所有操作表单中的参数控件Bucket、Object Name 等类型均为codehinter意味着这些参数支持写入静态值也可以引用应用中的组件变量、全局变量或运行 JS 表达式便于实现动态桶名、动态对象路径等场景。4.1 Read Object读取对象从指定桶中读取并下载对象内容。必填参数Bucket存储桶名称Object Name对象的完整键名key可包含目录前缀例如images/photo.png。底层实现与返回结构对应 operations.ts。实现会通过minioClient.getObject(bucket, objectName)取得一个可读流再将流的二进制数据完整收集为 Buffer最后返回return { Body: bufferData.toString(utf-8), // 以 UTF-8 字符串形式呈现文本类对象 rawData: bufferData, // 原始二进制 Buffer便于二进制场景使用 };也就是说文本型对象可直接在Body中使用如果是图片等二进制内容可从rawData变量取得原始字节后交给其他处理逻辑。4.2 Put Object上传对象向桶中上传新对象或覆盖更新一个已存在的对象。必填参数Bucket目标存储桶名称Object Name对象键名含目录路径则自动创建虚拟目录层级Upload data要上传的数据内容。可选参数Content Type对象的内容类型Content-Type例如image/png、application/json。留空时由服务端自动推断。底层实现与上传细节对应 operations.ts。上传前会先对data做 Base64 自动识别let data queryOptions[data]; if (isBase64(data)) { data Buffer.from(data, base64); } return await minioClient.putObject( queryOptions[bucket], queryOptions[objectName], data, queryOptions[contentType] { contentType: queryOptions[contentType] } );其中isBase64的判定规则为字符串长度为 4 的倍数且字符完全匹配^[A-Za-z0-9/]*{0,2}$。满足条件时数据会被解码为二进制 Buffer 上传否则按字符串内容直接上传。Content Type 仅在填写时作为请求头传入。4.3 Remove Object删除对象从桶中删除指定对象。必填参数Bucket对象所在存储桶Object Name要删除的对象键名。删除操作在服务端会先调用minioClient.removeObject(bucket, objectName)随后返回空对象{}作为查询结果详见 operations.ts。该操作不可恢复请谨慎使用。4.4 List Buckets列出所有桶返回当前账号可访问的全部存储桶列表。参数无。该操作直接调用 MinIO SDK 的listBuckets()并原样返回结果见 operations.ts。返回数组中的每个元素包含桶的name与creationDate等字段常用于构建选择桶 → 再列出对象的级联交互。由于该操作无需任何请求参数是验证数据源配置是否可用的最快捷方式测试连接也复用了该接口。4.5 List Objects in a Bucket列出桶内对象返回指定桶中符合条件的所有对象信息。必填参数Bucket要查询的存储桶。可选参数Prefix对象名前缀用于过滤。例如填images/只返回images/目录下的对象。底层实现细节对应 operations.ts。实现使用listObjectsV2并显式开启递归遍历const stream minioClient.listObjectsV2( queryOptions[bucket], queryOptions[prefix], true // recursive );recursive true意味着会跨虚拟目录展开所有层级而不会只返回一层。返回的对象信息随后通过流式收集以{ Body: [...] }形式输出每个对象条目通常包含name、size、lastModified、etag等元数据。4.6 Presigned URL for Download下载预签名 URL为指定对象生成一个带签名、限时有效的下载链接。该 URL 可以在短时间内直接分发给浏览器或第三方系统无需暴露 Access key / Secret key。必填参数Bucket对象所在存储桶Object Name要下载的对象键名。可选参数Expires inURL 有效时长秒默认值8640024 小时schema 中已预填该初始值。底层实现对应 operations.tsconst defaultExpiry queryOptions[expiresIn] || 86400; const url await minioClient.presignedGetObject(queryOptions[bucket], queryOptions[objectName], defaultExpiry); return { url };需要注意queryOptions[expiresIn] || 86400的兜底逻辑当参数为空或无法转换为有效数值时一律回退到 86400 秒。查询成功后将返回{ url: https://... }可在前端直接用于a下载链接或跳转。4.7 Presigned URL for Upload上传预签名 URL生成一个可向指定桶/对象键执行上传的预签名 URL基于 HTTP PUT允许客户端绕过 ToolJet 服务端、直传对象到 MinIO。必填参数Bucket目标存储桶Object Name将要写入的对象键名。可选参数Expires inURL 有效时长秒默认同样为86400。底层实现对应 operations.ts调用 SDK 的presignedPutObject(bucket, objectName, expiry)并返回{ url }。获得该 URL 后可使用fetch(url, { method: PUT, body: file })等方式实现服务端不落盘的文件直传适合大文件上传与带宽卸载场景。五、查询结果与可编程性MinIO 查询执行后会以{ status: ok, data: result }的统一结构返回见 index.ts。所有 MinIO 数据源插件均对外暴露三个变量isLoading布尔值表示查询是否正在执行可用于按钮 Loading 状态绑定data本次查询的解析结果如对象文本、URL、桶列表等rawData未经处理的原始返回数据。由于所有操作参数都是可求值表达式你可以实现很多典型的自动化场景用表格组件选中行的某个字段动态作为Object Name实现点选即预览对象用List buckets的结果驱动下拉选项再用选中的桶名作为List objects的动态Bucket参数用 Put object 的Upload data传入表单组件的文件内容变量实现文件入库将 Presigned URL 输出到文本/按钮组件实现受控的文件分享。六、注意事项与最佳实践测试连接会调用listBuckets()因此请确保所用 Access key 至少具备s3:ListAllMyBuckets权限否则即使读写正常测试连接也可能报错。SSL 开关必须与 MinIO 实际协议匹配服务端按useSSL决定请求协议若填错将出现协议握手或 TLS 错误。Secret key 加密存储保存后以密文形式展示如需更换需通过 Edit 重新录入。Presigned URL 有效期默认为 86400 秒24 小时为空或非法值都会回退到该默认值如用于高安全场景请显式调小。Put object 支持文本与 Base64 两种数据形态插件会按长度与字符集规则自动判断长文本偶尔满足 Base64 特征时建议关注结果是否符合预期。List objects 是递归遍历前缀过滤只能收敛范围无法只列出单层目录处理海量对象时注意结果体积。由于 MinIO 与 S3 API 高度兼容该数据源同样可对接多数兼容 S3 协议的对象存储服务只需把 Host/Port/Access key/Secret key 换成对应服务的端点与凭据即可。七、相关仓库资源若希望深入阅读实现或参与二次开发可重点关注以下路径文档原文docs/docs/data-sources/minio.md数据源总览docs/docs/data-sources/overview.md数据转换教程docs/docs/tutorial/transformations.md插件主服务类连接构建、操作分发、测试连接plugins/packages/minio/lib/index.ts各操作的底层实现plugins/packages/minio/lib/operations.ts数据源连接表单 schema 与默认值plugins/packages/minio/lib/manifest.json查询操作下拉项与参数 schemaplugins/packages/minio/lib/operations.json类型定义plugins/packages/minio/lib/types.ts上述插件采用与仓库内其他数据源插件一致的QueryService接口约定run/testConnection/getConnection因此理解 MinIO 这一个插件后迁移到同目录下其他数据源如s3、mongodb等的代码结构会非常顺畅。【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表