ToolJet 集成 Redis 数据源：连接配置、命令查询与编解码实战-港品优选

ToolJet 集成 Redis 数据源：连接配置、命令查询与编解码实战

【免费下载链接】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 内置了 Redis 数据源插件，让你可以在低代码编辑器中直接对 Redis 实例执行任意 Redis 命令，并将查询结果与前端组件联动。本文以官方文档为主线，结合仓库中的插件源码（plugins/packages/redis）与测试文件，系统讲解 Redis 数据源的添加方式、连接参数（含 TLS 三种证书模式）、命令查询流程，以及SET/GET结合encodeURI与 Transformations 处理带空格数据的完整实战方案。读完本文，你将能在 ToolJet 中独立完成 Redis 数据源的接入、测试与常用命令的调试。

Redis 数据源插件总览

在 ToolJet 中，Redis 属于内置的数据库类数据源插件。与通过自定义插件市场安装的扩展不同，Redis 连接器随主仓库一并维护，其核心实现位于 plugins/packages/redis/lib/index.ts，底层基于ioredis客户端驱动：

import Redis from 'ioredis'; import { SourceOptions, QueryOptions } from './types';

插件清单文件 manifest.json 定义了数据源的元数据：类型为database、kind为redis，并声明了连接表单所需的全部字段（host、port、username、password、database、ca_cert、client_key、client_cert 等）。其中password、ca_cert、client_key、client_cert均标记为"encrypted": true，意味着这些敏感信息在存储时会被加密，从表单输入到落库全程受到保护。

连接 Redis：两种入口与全部参数

与 ToolJet 其他数据源一致，连接 Redis 有两条路径：

查询面板入口：在应用编辑器中，点击底部查询面板的+ Add new Data source按钮，从列表中选择 Redis；
数据源管理入口：从 ToolJet 仪表盘左侧导航进入 Data Sources 数据源总览页，在 Databases 分类下找到 Redis 并点击Add。添加成功后，该连接可被工作区内所有应用共享。

连接表单需要填写以下参数：

参数	说明	默认值
Host	Redis 服务器的地址或主机名	`localhost`
Port	Redis 服务器监听的端口	`6379`
Username	用于认证的用户名（Redis 6+ ACL 用户）	空
Password	用于认证的密码	空
Database	连接的逻辑数据库编号（可选字段）	不指定
TLS	开关，启用/禁用 TLS 加密连接	关闭
TLS Certificate	证书类型：None（无）、CA certificate（CA 证书）、Client certificate（客户端证书）	`None`

上述默认值并非凭空而来，它们直接来自 manifest.json 的defaults段：

"defaults": { "host": { "value": "localhost" }, "port": { "value": 6379 }, "username": { "value": "" }, "password": { "value": "" }, "tls_enabled": { "value": false }, "tls_certificate": { "value": "none" } }

TLS 证书的三种模式

开启TLS开关后，还需选择证书类型，不同选择对应不同的附加输入项：

None：不校验服务器证书，仅建立加密通道；
CA certificate（CA 证书）：
- CA Cert：用于 TLS 连接的 CA 证书内容；
Client certificate（客户端证书，即双向 TLS / mTLS）：
- CA Cert：用于 TLS 连接的 CA 证书内容；
- Client Key：客户端私钥；
- Client Cert：客户端证书。

这三个字段在表单中均为文本域（textarea），且与密码一样按加密字段处理。

连接配置的底层实现

从源码看，连接参数如何被消费非常直观。lib/index.ts 中的getConnection方法把表单值透传给 ioredis：

return new Redis(port, host, { maxRetriesPerRequest: 1, username, password, tls: tls, ...(sourceOptions?.database && { db: sourceOptions.database }), });

值得注意的几个实现细节：

maxRetriesPerRequest: 1限制了单条命令的重试次数，避免连接异常时查询长时间挂起；
database字段是可选的，只有填写后才会以db选项传给 ioredis，因此支持连接 Redis 的逻辑数据库（db0–db15）；
TLS 的校验行为与证书类型强相关（lib/index.ts）：

if (sourceOptions.tls_enabled) { tls = {}; tls.rejectUnauthorized = (sourceOptions.tls_certificate ?? 'none') != 'none'; if (sourceOptions.tls_certificate === 'ca_certificate') { tls.ca = sourceOptions.ca_cert; } if (sourceOptions.tls_certificate === 'client_certificate') { tls.ca = sourceOptions.ca_cert; tls.key = sourceOptions.client_key; tls.cert = sourceOptions.client_cert; } }

即：选择CA certificate或Client certificate时，rejectUnauthorized为true（严格校验服务器证书）；选择None时关闭证书校验。选择 Client certificate 时同时加载ca、key、cert三份材料，构成完整的双向认证。

测试连接

连接表单通常提供Test connection按钮，其对应插件源码中的testConnection方法（lib/index.ts），实现是对服务器执行一次PING：

async testConnection(sourceOptions: SourceOptions): Promise<ConnectionTestResult> { const client = await this.getConnection(sourceOptions); try { await client.ping(); } catch (err) { client.disconnect(); throw new QueryError('Connection could not be established', err.message, {}); } return { status: 'ok' }; }

PING 成功即返回status: 'ok'，失败则抛出Connection could not be established并携带底层错误信息，可作为排查主机、端口、认证与 TLS 配置是否正确的第一道验证。

查询 Redis：编辑器中执行任意命令

连接建立后即可在应用中查询 Redis，操作步骤如下：

点击编辑器底部查询管理器的+ Add按钮；
选择上一步添加的Redis数据源；
在查询编辑器中输入命令；
点击Preview预览输出，或点击Run执行查询。

查询输入框的类型定义在 operations.json 中：它是一个codehinter类型的编辑器，placeholder为PING，默认查询内容即为PING，这意味着你可以在查询中直接书写任意 Redis 命令，并能内嵌 ToolJet 的变量表达式。

命令解析的底层原理

为什么能支持任意 Redis 命令？关键在于 lib/index.ts 中run方法的解析逻辑：

const splitQuery = query.split(' '); const command = splitQuery[0]; const args = splitQuery.length > 0 ? splitQuery.slice(1) : []; result = await client.call(command, args);

查询文本按空格切分：第一个 token 作为命令名，其余 token 作为参数数组，最终通过 ioredis 的client.call(command, args)动态执行。因此PING、SET、GET、EXPIRE、HSET、LPUSH乃至EVAL等命令均可直接使用，无需在插件中逐一枚举。

但这也带来一个关键约束：命令与参数之间、以及多参数之间只能以空格分隔。一旦某个值本身包含空格（例如人名 "John Doe"），直接写入会被切分成多个参数，导致命令语义错误——这正是原文档反复强调需要对值进行编码的根本原因。

常用命令实战

PING：连通性自检

PING用于测试与 Redis 的连接，执行成功后服务器返回PONG：

PING

在查询返回的数据中，PONG即代表通道畅通，这也是连接测试与日常排障中最常用的命令。

SET：写入键值

SET用于为指定 key 赋值：

SET key value

处理带空格的值

当待写入的值包含空格时，必须先编码再作为输入，ToolJet 的编辑器支持内嵌 JS 表达式：

SET products {{encodeURI('John Doe')}}

{{...}}是 ToolJet 的表达式语法，这里用encodeURI将John Doe编码为John%20Doe，从而避免空格破坏命令解析。下图展示了该查询在编辑器中的实际效果：

GET：读取键值

GET用于获取指定 key 的值：

GET key

配合 Transformations 解码

对于上一步用encodeURI写入的编码值，直接读取会得到John%20Doe这种带百分号编码的字符串。要还原为可读的原始内容，可利用查询的Transformations (JS)功能：

在编辑器中输入 GET 命令：
```
GET products
```
开启 Transformations（JS），写入解码逻辑：
```
return JSON.parse(decodeURI(data));
```

这里data是查询返回的原始数据，decodeURI将编码还原，JSON.parse再把字符串解析为对象，实现"写入时编码、读取时解码"的完整闭环。若写入的是纯字符串而非 JSON 序列化对象，可直接写return decodeURI(data)。

排障与进阶提示

连接失败：优先使用连接表单的 Test connection 触发 PING，若返回Connection could not be established，按顺序检查 Host/Port 可达性、ACL 用户名与密码、TLS 开关与证书内容（尤其注意证书文本是否完整、含头尾标记）。
命令报错Query could not be completed：该错误来自run方法对命令执行异常的包装（lib/index.ts）。常见诱因是参数含空格被错误切分——此时应回到encodeURI编码方案；也可能是命令名拼写错误或参数类型不符。
查询输入框的本质：query 字段是codehinter（代码高亮编辑器），因此可以直接引用组件值、查询结果等运行时变量，例如SET session:{{globals.currentUser.email}} {{encodeURI(components.textarea1.value)}}，让 Redis 写入完全动态化。
敏感字段保护：密码与三类证书材料均按加密字段存储（见 manifest.json 的encrypted标记），涉及生产环境凭证时无需担心明文落库。

掌握以上连接与查询方法后，你就可以在 ToolJet 中把 Redis 作为缓存、会话存储或临时队列使用，并与表格、文本输入等组件无缝联动。关于数据源的通用添加流程与多环境配置，可继续阅读 Data Sources 数据源总览；完整的 Redis 命令清单可参考 Redis 官方命令文档（redis.io/commands）。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析