ToolJet 接入 S3 兼容对象存储使用 Custom Endpoint 连接 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/ToolJet本文是一篇面向 ToolJet 用户的实战指南讲解如何通过 AWS S3 数据源中的Custom Endpoint自定义端点能力连接 MinIO 等 S3 兼容对象存储服务。读完本文后你将掌握在 ToolJet 中配置自定义端点、生成并填写 MinIO 访问凭证、测试并验证连接以及在查询编辑器中执行对象读写等核心操作从而在不使用 AWS 原生服务的情况下复用 ToolJet 完整的数据源能力。为什么需要 Custom EndpointToolJet 的 AWS S3 数据源默认面向 AWS 官方服务其底层基于aws-sdk/client-s3构建见 S3 插件入口。但生产环境中存在大量非 AWS 的 S3 兼容存储例如自建的 MinIO / Ceph / SeaweedFS 集群各类云厂商提供的 S3 协议兼容对象存储内网部署的、需要自定义域名或路径访问的存储服务。这些服务实现了与 AWS S3 一致的 API 协议但端点endpoint地址并不在 AWS 的官方域名之下。ToolJet 为此在 AWS S3 数据源的连接配置中提供了Custom Endpoint开关允许你覆盖默认的 AWS 服务地址将其指向任意 S3 兼容服务。本指南以MinIO为例演示完整接入流程。前置准备在开始配置之前请确认你有一个可访问的 ToolJet 实例自托管部署或云端版本均可并已登录 Dashboard目标 MinIO或同类 S3 兼容服务已启动且其API 端口对 ToolJet 实例可达已从 MinIO 控制台生成一对Access Key与Secret KeyMinIO 中称为 Access Key / Secret Key等价于 AWS 的 Access Key ID / Secret Access Key。提示如果 MinIO 服务未对公网开放ToolJet 连接弹窗中会给出提示——需要将 ToolJet 的出口 IP 加入白名单确保数据源可达见下方截图中的提示框。创建应用并添加 AWS S3 数据源打开 ToolJet Dashboard点击Create new application创建新应用进入应用编辑器在左侧边栏中切换到Sources数据源面板点击 Add添加新数据源在数据源列表中搜索并选择AWS S3此时会弹出数据源连接配置弹窗对应下图所有连接参数的填写都在这个弹窗中完成。上图展示的是版本 2.50.0-LTS 中 AWS S3 数据源的连接弹窗顶部为环境标签Development / Staging / Production中部为 Region、Authentication、Access key、Secret key 等配置字段底部为Test Connection测试连接与Save保存按钮。在连接弹窗中配置连接参数1. 选择认证方式与填写凭证在弹窗的Authentication下拉框中选择Use IAM Access Keys使用 IAM 访问密钥这是连接 MinIO 等自建服务最直接的认证方式随后填写RegionS3 兼容服务通常不强校验区域但该字段为必填可任选一个 AWS 区域如us-east-1。从源码可见区域值会直接传给S3Client见 S3 插件入口Access keyMinIO 控制台生成的 Access KeySecret keyMinIO 控制台生成的 Secret Key。凭证的获取路径为登录 MinIO 控制台 → 左侧Access Keys→Create Access Key系统会生成 Access Key 与 Secret Key 各一对Secret Key 仅在创建时完整展示一次请妥善保存。在 ToolJet 中保存数据源后Secret Key 会被标记为Encrypted加密存储见 S3 数据源清单 中的tj:encrypted: [secret_key]声明。2. 打开 Custom Endpoint 开关并填写端点地址这是本指南的核心步骤在弹窗中找到Custom Endpoint开关并将其打开在下方的Custom endpoint输入框中填写 MinIO 服务器的 API 地址例如http://minio.example.com:9000即你的 MinIO Server API 暴露的地址而不是控制台 Web 地址。从数据源配置清单manifest.json可以看到endpoint_enabled与endpoint是两个独立配置项且endpoint字段仅在开关打开时才会在界面中展示true: { endpoint: {...} }的 UI 规则。3. 可选配置默认 Bucket弹窗中还提供Bucket字段用于填写默认存储桶名。该字段配合Allow dynamic connection parameters允许动态连接参数开关使用当开关开启时每次查询可以单独指定 Bucket 名称关闭后则统一使用此处配置的默认 Bucket。对应逻辑在 S3 插件入口 中实现const allowDynamicConnectionParameters this._normalizeBool(sourceOptions.allow_dynamic_connection_parameters) ?? true; const resolvedQueryOptions: QueryOptions { ...queryOptions, bucket: allowDynamicConnectionParameters ? queryOptions.bucket || sourceOptions.bucket_name : sourceOptions.bucket_name, };4. 测试连接并保存填写完毕后点击Test Connection测试连接按钮验证连通性。底层实现中该按钮会调用 S3 插件的testConnection方法通过ListBucketsCommand向目标端点发起一次真实的列出存储桶请求成功则返回status: ok见 S3 插件入口async testConnection(sourceOptions: SourceOptions): PromiseConnectionTestResult { const client: S3Client await this.getConnection(sourceOptions); await listBuckets(client, {}); return { status: ok }; }连接测试通过后点击Save保存数据源即可在查询编辑器中使用该数据源。底层原理Custom Endpoint 如何生效理解了 UI 操作后再看底层实现会更容易把握原理。在 S3 插件入口 中当认证方式为 IAM Access Keys 时连接构建逻辑如下const credentials { accessKeyId: sourceOptions[access_key], secretAccessKey: sourceOptions[secret_key], }; const endpointOptions sourceOptions.endpoint_enabled { endpoint: sourceOptions?.endpoint, forcePathStyle: true, }; return new S3Client({ region, credentials, ...endpointOptions });这里有三个关键点值得注意endpoint将 AWS SDK 的 S3 客户端请求目标指向自定义地址这是连接 MinIO 等服务的核心forcePathStyle: true强制使用**路径风格path-style**寻址即请求形如http://minio.example.com:9000/bucket-name/key而不是虚拟主机风格virtual-hosted-style的http://bucket-name.minio.example.com/key。绝大多数自建 S3 兼容服务包括 MinIO依赖路径风格寻址SDK 默认的虚拟主机风格会导致请求失败region沿用你在弹窗中选择的区域值虽然 MinIO 通常不校验它但 SDK 构造请求时需要该参数。需要说明的是Custom Endpoint 选项仅在Use IAM Access Keys认证方式下提供。数据源清单manifest.json显示ToolJet 的 S3 数据源还支持Use AWS Instance Credentials、Use AWS ARN Role、Default Credential Provider Chain三种认证方式分别对应实例元数据凭证、STS AssumeRole 临时凭证与默认凭证链源码见 S3 插件入口但它们面向 AWS 云环境内的场景一般不与自定义端点搭配使用。连接后的数据操作数据源保存成功后即可在查询编辑器中执行各类 S3 操作。操作下拉框中的选项与插件支持的 Operation 枚举一一对应见 types.ts主要包括操作说明必需参数Create a new bucket新建存储桶BucketRead object读取对象内容Bucket、KeyUpload object上传/更新对象Bucket、Key、Content Type、Upload dataRemove object删除对象Bucket、KeyList buckets列出所有存储桶无List objects in a bucket列出桶内对象Bucket可选 Prefix、Max keys、Offset、Next Continuation TokenSigned URL for download生成限时下载签名 URLBucket、Key、Expires inSigned URL for upload生成限时上传签名 URLBucket、Key、Expires in、Content Type这些操作的具体实现集中在 operations.ts例如读取对象时会将返回的流转换为 UTF-8 字符串getObject 实现上传对象时支持通过encoding指定字符编码、contentType指定 MIME 类型uploadObject 实现签名 URL 的默认有效期expiresIn为 3600 秒signedUrlForGet 实现。执行查询的完整流程是在查询编辑器点击 Add添加查询 → 选择刚保存的 S3 数据源 → 选择操作并填写参数 → 点击Run或Preview执行。查询结果还可以配合 ToolJet 的 Transformations 功能做进一步的数据加工。常见问题排查Test Connection 失败优先检查 Custom Endpoint 地址是否完整含协议与端口以及 ToolJet 所在网络能否访问该地址同时确认 MinIO 控制台与 API 地址不是同一个端口MinIO 默认 API 端口为9000控制台端口通常为9001连接成功但操作报 404/403多为凭证权限不足或存储桶不存在请在 MinIO 控制台确认该 Access Key 对目标 Bucket 具备对应读写权限请求报寻址错误确认 Custom Endpoint 开关处于开启状态因为关闭时 SDK 不会注入forcePathStyle: true默认的虚拟主机风格寻址在自建服务上通常会失败。相关资源S3 数据源完整说明Amazon S3 数据源文档MinIO 数据源参考MinIO 数据源文档S3 插件源码插件入口 · 操作实现 · 数据源配置清单 · 类型定义数据源接入基础Adding a Datasource查询构建与转换Building Queries · Transformations【免费下载链接】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），仅供参考