ToolJet 使用自定义端点Custom Endpoint连接 S3 兼容对象存储以 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 官方文档s3-custom-endpoint.md与仓库源码讲解如何通过Custom Endpoint自定义端点让 ToolJet 连接任意S3 兼容的对象存储服务如 MinIO、Ceph RGW、SeaweedFS、自建 MinIO 集群等并以 MinIO 作为完整实操示例。读完本文你将掌握在 ToolJet 中创建 AWS S3 数据源并启用自定义端点、从 MinIO 控制台获取访问密钥、配置端点 URL、测试连接以及理解底层aws-sdk/client-s3客户端是如何通过endpoint_enabled与forcePathStyle参数实现非 AWS 端点接入的完整原理。为什么需要自定义端点ToolJet 内置的AWS S3数据源默认面向亚马逊官方 S3 服务连接时客户端会将请求发送到https://s3.region.amazonaws.com这类 AWS 官方域名。然而在实际项目中大量团队使用自托管或第三方提供的 S3 兼容对象存储MinIO最流行的开源 S3 兼容对象存储常用于私有云、边缘节点Ceph RADOS GatewayRGW基于 Ceph 集群的对象存储网关SeaweedFS、Garage、InfluxDB 等多种提供 S3 API 兼容层的存储系统云厂商的非 AWS 对象存储如阿里云 OSS兼容 S3 API 的接入方式、腾讯云 COS 等。这些服务都实现了 S3 的 REST API因此只要 ToolJet 能把请求指向你自己的端点地址就能像使用 AWS S3 一样读取、写入、列举对象。ToolJet 提供的Custom Endpoint开关正是为此设计——它让 S3 数据源不再被 AWS 官方域名绑定可自由对接任意 S3 兼容实现。前置准备MinIO 访问密钥在本指南中我们使用MinIO作为 S3 兼容对象存储的示例。在开始配置 ToolJet 之前你需要完成安装并启动 MinIO 服务单机版可直接使用minio server命令或通过 Docker 部署登录MinIO ConsoleWeb 管理界面在 Console 的Access Keys页面点击Create Access Key生成一对密钥Access Key访问密钥 IDSecret Key私有访问密钥生成的密钥将作为 ToolJet 数据源配置中的Credentials凭据使用。请妥善保管 Secret KeyToolJet 在保存数据源时会对其加密存储见下文源码解析中的tj:encrypted配置。提示从仓库源码看S3 数据源的secret_key字段在 manifest.json 中被声明为tj:encrypted: [secret_key]这意味着密钥在入库前会经过 ToolJet 的加密处理而不是明文保存。第一步创建应用并添加 AWS S3 数据源进入ToolJet 仪表盘Dashboard点击Create new application创建一个新的应用打开应用编辑器后在左侧边栏中找到Sources面板点击Add new data source在数据源列表中选择AWS S3此时会弹出连接配置弹窗Connection Modal即上方截图中展示的界面。该弹窗的字段结构由 S3 插件的数据源清单 manifest.json 定义它使用 ToolJet 插件系统声明数据源的属性、UI 控件与校验规则。第二步填写凭据与区域在连接弹窗中S3 数据源默认使用IAM Access Keys认证方式instance_metadata_credentials的默认值为iam_access_keys你需要填写字段说明示例Authentication认证方式下拉框可选 IAM Access Keys / AWS Instance Credentials / AWS ARN Role / Default Credential Provider ChainUse IAM Access KeysRegion区域下拉框对接 MinIO 时一般填写us-east-1见下文说明Access key从 MinIO Console 生成的 Access Keyminioadmin示例Secret key从 MinIO Console 生成的 Secret Key加密保存关于Region字段需要注意对接自建 MinIO 等非 AWS 存储时Region 主要用于 S3 签名与请求构造多数 S3 兼容服务并不真正校验区域。按照惯例填写us-east-1美国东部弗吉尼亚北部即可。从 manifest.json 可以看到Region 下拉框列出了完整的 AWS 区域清单us-east-1、us-east-2、ap-southeast-1等而底层客户端只把它作为S3Client的region参数传入。第三步启用 Custom Endpoint 并填写端点地址这是本文的核心步骤找到Custom Endpoint开关将其打开Toggle ON开关下方会出现Custom endpoint输入框在其中填入你的 MinIO 服务器 API 地址即 MinIO 服务对外暴露的 S3 API 端点。典型的端点地址格式MinIO 单机默认 API 端口为9000注意 Console 端口通常是9001两者不同因此常见写法为http://localhost:9000本机测试http://192.168.1.100:9000内网部署https://minio.example.com配置了域名与 TLS 的生产环境填写完毕后完整的配置如下所示Region : us-east-1 Access key : MinIO 生成的 Access Key Secret key : MinIO 生成的 Secret Key Custom Endpoint : http://minio.example.com:9000 ← 打开开关后出现的输入框底层原理endpoint_enabled 与 forcePathStyle在 ToolJet 的 S3 插件源码 lib/index.ts 中getConnection()方法的最后分支IAM Access Keys 场景这样构造 AWS SDK 客户端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_enabled开关只有当该值为真时endpoint才会被传入S3Client从而将请求指向自定义地址而非 AWS 官方域名forcePathStyle: true这是对接 MinIO 等自建 S3 兼容服务必不可少的参数。AWS 默认采用虚拟主机风格bucket.s3.region.amazonaws.com寻址而大多数自建 S3 实现尤其是 MinIO要求使用路径风格host/bucket/key寻址。强制启用路径风格后请求 URL 会形如http://minio.example.com:9000/my-bucket/my-object确保兼容性。这一设计同时解释了 types.ts 中SourceOptions的类型定义export type SourceOptions { access_key: string; secret_key: string; region: string; endpoint_enabled: boolean; endpoint: string; // ... 其余字段 };以及在 manifest.json 中endpoint_enabled被声明为default: false的布尔开关且只有当开关为true时 UI 才会渲染endpoint输入框对应true: { endpoint: { ... } }的 UI 定义。扩展其他认证方式不受影响值得说明的是Custom Endpoint 只作用于IAM Access Keys分支。从 lib/index.ts 的源码结构看getConnection()还支持另外三种认证路径AWS Instance Credentials通过fromInstanceMetadata从 EC2 实例元数据服务获取临时凭据使用 IAM 角色AWS ARN Role通过STSClient的AssumeRoleCommand完成角色扮演getAssumeRoleCredentials方法换取临时凭据Default Credential Provider Chain直接使用new S3Client({ region })交给 SDK 默认的凭据提供链解析。当使用这些 AWS 原生认证方式连接自建 S3 兼容存储时需要你的存储网关支持对应的凭据获取机制如 MinIO 对 STS AssumeRole 有独立实现普通场景下建议统一使用IAM Access Keys Custom Endpoint的组合。第四步测试连接填写完所有字段后点击弹窗底部的Test Connection按钮验证连通性。从源码看testConnection方法lib/index.ts的实现非常直观它用当前配置构造S3Client然后发送一个ListBucketsCommand请求——如果密钥、端点、网络均正常MinIO 会返回存储桶列表测试即通过async testConnection(sourceOptions: SourceOptions): PromiseConnectionTestResult { const client: S3Client await this.getConnection(sourceOptions); await listBuckets(client, {}); return { status: ok, }; }对应的底层命令封装在 lib/operations.tsexport async function listBuckets(client: S3Client, options: QueryOptions | object): Promiseobject { const command new ListBucketsCommand({}); return client.send(command); }常见连接失败排查现象可能原因处理方式连接超时 / 无法访问端点地址错误或 MinIO 服务未启动 / 端口不通用curl http://endpoint/minio/health/live检查 MinIO 健康接口返回 403 AccessDeniedAccess Key / Secret Key 错误或密钥权限不足在 MinIO Console 重新生成密钥并核对SignatureDoesNotMatchRegion 或时间不同步签名依赖时间戳检查服务器时钟同步NTP并将 Region 统一为us-east-1400/404 请求失败存储桶路径解析问题确认forcePathStyle生效使用 Custom Endpoint 时插件会自动开启见上文源码TLS 证书报错使用了自签名证书的 HTTPS 端点为 MinIO 配置受信任证书或临时改用 HTTP 验证连通性连接成功后的操作S3 查询能力连接建立后你可以在查询编辑器底部点击 Add新建查询选择刚添加的 AWS S3 数据源并从操作下拉框中选择要执行的操作。ToolJet 的 S3 插件共支持 8 种操作枚举定义见 types.ts实现见 lib/operations.ts操作枚举值用途关键参数Create Bucketcreate_bucket创建新存储桶BucketList Bucketslist_buckets列举所有存储桶无List Objectslist_objects列举存储桶内对象Bucket、Prefix、MaxKeys、StartAfter、ContinuationTokenRead Objectget_object读取对象内容源码中将流转换为 UTF-8 字符串返回Bucket、KeyUpload Objectupload_object上传对象Bucket、Key、Content Type、Upload dataSigned URL for Downloadsigned_url_for_get生成带签名的下载 URL默认 3600 秒过期Bucket、KeySigned URL for Uploadsigned_url_for_put生成带签名的上传 URLBucket、Key、Content TypeRemove Objectremove_object删除对象Bucket、Key例如使用List Objects查询 MinIO 中的某个存储桶只需要提供Bucket名称而Signed URL for Download则会调用aws-sdk/s3-request-presigner的getSignedUrl生成临时访问链接operations.ts可用于在浏览器中直接下载私有存储桶中的文件。关于动态桶参数进阶S3 数据源还提供了一个Allow dynamic connection parameters开关默认开启。当开启时查询中的bucket参数会优先于数据源配置中的默认桶名见 index.tsconst resolvedQueryOptions: QueryOptions { ...queryOptions, bucket: allowDynamicConnectionParameters ? queryOptions.bucket || sourceOptions.bucket_name : sourceOptions.bucket_name, };这意味着同一数据源可以在运行时针对不同存储桶执行查询非常适合多租户或动态切换桶的场景。总结通过 ToolJet 的Custom Endpoint功能你可以让 S3 数据源对接任意 S3 兼容对象存储而不局限于 AWS 官方服务使用 MinIO Console 生成的标准访问密钥完成认证Secret Key 在 ToolJet 中加密保存以http://host:port形式配置自定义端点底层自动启用forcePathStyle路径风格寻址以保证兼容性通过Test Connection快速验证配置并在连接成功后使用 8 种 S3 操作构建完整的对象存储应用。相关资源官方实操指南s3-custom-endpoint.mdS3 数据源完整文档version-3.0.0-LTS/data-sources/s3.md插件源码plugins/packages/s3/lib/index.ts、plugins/packages/s3/lib/operations.ts、plugins/packages/s3/lib/manifest.json、plugins/packages/s3/lib/types.ts插件测试plugins/packages/s3/tests/s3.test.js【免费下载链接】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），仅供参考
