企业官网建设流程全解析

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 Endpoint

ToolJet 的 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为例演示完整接入流程。

前置准备

在开始配置之前，请确认：

1. 你有一个可访问的 ToolJet 实例（自托管部署或云端版本均可），并已登录 Dashboard；
2. 目标 MinIO（或同类 S3 兼容服务）已启动，且其API 端口对 ToolJet 实例可达；
3. 已从 MinIO 控制台生成一对Access Key与Secret Key（MinIO 中称为 Access Key / Secret Key，等价于 AWS 的 Access Key ID / Secret Access Key）。

提示：如果 MinIO 服务未对公网开放，ToolJet 连接弹窗中会给出提示——需要将 ToolJet 的出口 IP 加入白名单，确保数据源可达（见下方截图中的提示框）。

创建应用并添加 AWS S3 数据源

1. 打开 ToolJet Dashboard，点击Create new application（创建新应用）进入应用编辑器；
2. 在左侧边栏中切换到Sources（数据源）面板；
3. 点击+ Add添加新数据源，在数据源列表中搜索并选择AWS S3；
4. 此时会弹出数据源连接配置弹窗（对应下图），所有连接参数的填写都在这个弹窗中完成。

上图展示的是版本 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 等自建服务最直接的认证方式，随后填写：

• Region：S3 兼容服务通常不强校验区域，但该字段为必填，可任选一个 AWS 区域（如us-east-1）。从源码可见，区域值会直接传给S3Client（见 S3 插件入口）；
• Access key：MinIO 控制台生成的 Access Key；
• Secret key：MinIO 控制台生成的 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 开关并填写端点地址

这是本指南的核心步骤：

1. 在弹窗中找到Custom Endpoint开关并将其打开；
2. 在下方的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): Promise<ConnectionTestResult> { 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 });

这里有三个关键点值得注意：

1. endpoint：将 AWS SDK 的 S3 客户端请求目标指向自定义地址，这是连接 MinIO 等服务的核心；
2. 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 默认的虚拟主机风格会导致请求失败；
3. 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），主要包括：

这些操作的具体实现集中在 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