ToolJet 使用 S3 预签名 URL 上传文档：从应用模板到插件源码的完整实战指南

ToolJet 使用 S3 预签名 URL 上传文档从应用模板到插件源码的完整实战指南【免费下载链接】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 file explorer应用模板为主线完整演示如何在 ToolJet 应用中通过S3 预签名 URLpresigned URL实现列出存储桶 → 浏览对象 → 生成下载链接 → 上传文件 → 访问文件的完整链路。读完本文你将掌握 ToolJet S3 数据源的 8 种操作、动态参数绑定{{ }}表达式的写法以及这些操作在开源插件源码plugins/packages/s3中的底层实现原理可直接用于构建自己的云存储管理类内部工具。前置知识什么是 S3 预签名 URLS3 预签名 URLpresigned URL / signed URL是 AWS S3 提供的一种限时授权机制对象所有者使用自己的安全凭据为特定对象生成一个包含签名信息的 URL将其分享给他人后对方可以在有效期内凭该 URL 直接下载或上传对象无需拥有 AWS 安全凭据或权限。Signed URL for Download生成用于下载对象的限时链接Signed URL for Upload生成用于让第三方如你的终端用户直接上传对象到指定存储桶的限时链接。在 ToolJet 中这两类链接都通过 S3 数据源插件封装为查询操作。从源码看其实现基于 AWS SDK 的aws-sdk/s3-request-presignergetSignedUrl(client, command, { expiresIn })对GetObjectCommand/PutObjectCommand生成签名 URLexpiresIn未指定时默认3600秒1 小时见 plugins/packages/s3/lib/operations.ts 与 signedUrlForPut 实现。下面我们基于 ToolJet 内置模板走一遍完整流程。第一步从模板创建应用打开 ToolJet Dashboard点击Create new app按钮右侧的省略号ellipses。在下拉菜单中选择Choose from template从模板选择。在模板列表中选中AWS S3 file explorer点击Create application from template从模板创建应用。模板创建完成后左侧边栏的Data sources中会自动添加好一个 AWS S3 数据源。你不需要从零配置连接只需更新数据源凭据即可。提示关于 S3 数据源的完整连接说明与认证方式选择可参考 AWS S3 数据源参考文档。第二步配置 AWS S3 数据源凭据在Data sources页面打开已自动创建的 AWS S3 数据源更新连接凭据。从插件源码plugins/packages/s3/lib/manifest.json看ToolJet S3 数据源支持四种认证方式instance_metadata_credentials字段认证方式需要提供的参数底层实现Use IAM Access Keys默认Region、Access key、Secret key直接用access_key/secret_key构造S3Client凭据Use AWS Instance CredentialsRegion通过fromInstanceMetadata()使用 EC2/ECS 实例上绑定的 IAM 角色Use AWS ARN RoleRegion、Role ARN先通过 STSAssumeRoleCommand换取临时凭据AccessKeyId SecretAccessKey SessionToken再用其构造客户端Default Credential Provider ChainRegion使用 AWS SDK 默认凭据提供链这些分支在 plugins/packages/s3/lib/index.ts 的getConnection()方法中逐一实现useAWSInstanceProfile、useRoleArn、useDefaultCredentialProviderChain分别对应后三种方式aws_arn_role模式下的角色扮演由getAssumeRoleCredentials()index.ts通过 STS 完成RoleSessionName按s3-角色名-时间戳动态生成。其中Region在界面上以下拉框提供覆盖us-east-1、eu-west-1、ap-southeast-1等全部主流区域完整枚举见 manifest.json 的 region 列表。安全建议官方文档明确提示建议为 ToolJet 单独创建 IAM 用户以便精确控制其访问级别最小权限原则避免使用高权限生产凭据。第三步获取存储桶列表getBuckets数据源连接成功后进入底部的查询管理器Query Manager打开模板自带的getBuckets查询其Operation已设置为List buckets点击Run运行查询返回一个包含所有存储桶的数组并自动加载到应用左侧的存储桶表格中。从源码看listBuckets直接构造ListBucketsCommand({})并发送给S3Client无需任何参数返回 AWS SDK 的原始响应见 operations.ts。同时testConnection()index.ts在测试连接时也复用了listBuckets——也就是说能成功列出存储桶就说明数据源连接是通的。运行后存储桶列表会加载到应用左侧的表格中模板中对应table2组件。第四步列出存储桶内的对象getObjects接下来获取指定存储桶内的文件列表在存储桶表格中选中一个存储桶打开查询管理器中的getObjects查询在Data Source中选择对应的 S3 数据源Operation选择List objects in a bucket将Bucket参数替换为动态表达式{{components.table2.selectedRow.Name}}——这里table2是存储桶表格selectedRow.Name是当前选中行的存储桶名称字段点击Run所选存储桶内的所有文件将列在右侧的文件表格模板中对应table3中。listObjects的底层实现operations.ts使用ListObjectsV2Command其完整参数如下查询参数底层 SDK 字段说明BucketBucket必填目标存储桶PrefixPrefix可选只列出指定前缀目录下的对象Max keysMaxKeys可选单次最多返回的对象数插件默认1000见 operations.jsonOffsetStartAfter可选从指定 key 之后开始列出可用于按前缀过滤如设为a只列出以a开头的对象Next Continuation TokenContinuationToken可选响应被截断时用返回的 token 翻页获取下一批对象关于翻页当存储桶内对象很多、单次响应被截断时API 会返回Next Continuation Token。把该值填入查询参数并再次运行即可从上次结束的位置继续列出实现分页浏览。第五步获取下载签名 URLSigned URL for download对象所有者可以选择性地通过生成预签名 URL 与他人共享对象使用自己的安全凭据授予对方限时下载权限。在查询面板中配置Data Source选择对应的 S3 数据源Operation选择Signed url for downloadBucket{{components.table2.selectedRow.Name}}动态绑定当前选中的存储桶Key{{components.table3.selectedRow.Key}}动态绑定文件表格中选中行的文件名KeyExpires inURL 过期时间秒默认36001 小时。配置完成后点击Run即可在查询结果中拿到签名 URL。从源码看该操作对应signedUrlForGet()operations.ts先用GetObjectCommand构造请求再通过getSignedUrl(..., { expiresIn: options.expiresIn || 3600 })生成 URL返回结构为{ url }。其中Expires in 的默认值3600同时体现在 operations.json 的initialValue见 operations.json界面加载时即预填该值。第六步上传对象到存储桶Upload ObjectUpload Object操作允许用户选择存储桶并上传所选数据。打开模板中的uploadObject查询按如下配置Data Source选择对应的 S3 数据源Operation选择Upload ObjectBucket{{components.table2.selectedRow.Name}}动态选择存储桶Key{{components.textinput2.value}}来自文件名输入框的值即上传后的对象 keyContent Type{{components.filepicker1.file[0].type}}来自文件选择器所选文件的 MIME 类型Upload data{{components.filepicker1.file[0].dataURL}}来自文件选择器所选文件的数据内容Encoding可选上传数据的编码格式界面占位符默认为utf8。底层实现uploadObject()operations.ts会做几件关键事情以options.encoding || utf8作为编码BufferEncoding对ContentType含application/json且数据为对象的情况自动执行JSON.stringify其余情况原样使用通过Buffer.from(data, encoding)构造请求体调用PutObjectCommand并同时携带ContentType与ContentEncoding。配置上传成功反馈可选但推荐为确认文件上传成功可在Events区新建事件处理器点击New event handler新建事件处理器Event下拉选择Query Success查询成功Action下拉选择Show Alert显示提示Message自定义提示文案例如Image uploaded successfully图片上传成功。完成查询配置后在应用中选中目标存储桶点击Upload file上传文件按钮选择要上传的文件即可完成上传。第七步访问签名 URL文件上传到存储桶后回到文件表格在表格的Actions操作列点击Copy signed URL复制签名 URL按钮URL 会被复制到剪贴板打开浏览器新标签页并粘贴该 URL即可直接在浏览器中打开/下载对应文件。进阶用 Signed URL for upload 实现客户端直传除了上传对象 生成下载链接的组合ToolJet S3 数据源还提供Signed url for upload操作适用于希望你的用户/客户直接向你的存储桶上传对象但不需要他们拥有 AWS 安全凭据或权限的场景。其参数为Bucket必填Key必填Expires in默认3600秒Content Type必填用于限定上传内容类型对应源码为signedUrlForPut()operations.ts生成的是针对PutObjectCommand的限时签名 URL。拿到该 URL 后前端即可直接向它发起 PUT 请求完成上传对象数据不经过 ToolJet 服务端中转适合大文件直传场景。动态连接参数让存储桶随查询动态切换整个模板中大量使用{{components.xxx.selectedRow.xxx}}这类表达式其背后是 S3 插件的Allow dynamic connection parameters允许动态连接参数开关。该开关默认开启default: true见 manifest.json由数据源连接配置界面中的allow_dynamic_connection_parameters选项控制。从 index.ts 的 run() 实现看插件在每次执行查询时会先做桶名解析当开关开启默认bucket queryOptions.bucket || sourceOptions.bucket_name即优先采用查询中动态绑定的桶名未填写时才回退到连接配置里填写的默认存储桶当开关关闭bucket sourceOptions.bucket_name即强制使用连接配置中的固定存储桶查询参数中的桶名不生效。因此如果你的应用需要在多个存储桶间切换如本模板保持该开关开启如果希望锁定单一存储桶以降低误操作风险则可关闭它。小结完整链路回顾步骤查询Operation下拉选项关键参数获取存储桶getBucketsList buckets无浏览对象getObjectsList objects in a bucketBucket动态绑定生成下载链接—Signed url for downloadBucket、Key、Expires in默认 3600上传文件uploadObjectUpload objectBucket、Key、Content Type、Upload data客户端直传—Signed url for uploadBucket、Key、Expires in、Content Type除本文涉及的操作外S3 数据源还支持Create a new bucket新建存储桶参数Bucket Name、Read object读取对象参数 Bucket/Key和Remove object删除对象参数 Bucket/Key完整操作清单定义在 plugins/packages/s3/lib/operations.json查询分发逻辑见 plugins/packages/s3/lib/index.ts。你可以基于这些操作组合出更多应用场景例如文件管理后台、素材库、合同归档系统等内部工具。【免费下载链接】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），仅供参考