ToolJet 接入 gRPC 数据源从 proto 文件挂载到 RPC 查询的完整实战指南【免费下载链接】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/ToolJetToolJet 的 gRPC 数据源允许你在自托管实例中直接连接 gRPC 服务端通过加载.proto文件Protocol Buffers 服务定义并调用其公开的 RPC 方法将 gRPC 服务能力融入低代码应用与工作流。本文将基于官方数据源文档结合仓库中plugins/packages/grpc插件的源码实现完整讲解自托管部署下的环境准备、proto 文件挂载、数据源连接认证以及如何在查询面板中对任意 RPC 方法发起调用并附带连接测试与常见问题分析。注意gRPC 数据源仅适用于自托管Self-hosted部署且当前版本仅支持处理一元请求与响应unary request/response不支持流式 RPC。一、gRPC 数据源的工作原理在深入配置之前先理解 ToolJet 是如何将 proto 文件变成可调用的 RPC 方法的。插件源码位于 plugins/packages/grpc/lib/index.ts其核心调用链如下加载 proto 文件使用grpc/proto-loader的loadSync()同步解析位于容器内/app/protos/service.proto的 proto 文件并配置keepCase: true、longs: String、enums: String、defaults: true、oneofs: true等解析选项其中 long 型字段以字符串返回避免精度丢失。构建客户端存根通过grpc.loadPackageDefinition()取出指定服务serviceName然后以new Service(url, grpc.credentials.createInsecure())创建客户端存根——默认使用非加密insecure通道连接。附加认证元数据根据auth_type在grpc.Metadata中注入不同的认证信息详见下文“认证方式”。执行 RPC 调用解析查询面板传入的 JSON 消息体queryOptions.jsonMessage必须是合法 JSON否则抛出Invalid JSON message错误调用clientStubrpc发起一元调用最终返回{ status: ok, data: response }。从源码可以看出ToolJet 的 gRPC 插件本质上是grpc/grpc-js的封装serviceName服务名与rpc方法名都来自查询参数proto 文件路径固定为protos/service.proto因此服务端与方法的可用性完全取决于你挂载的 proto 文件内容。二、环境准备自托管实例的配置步骤2.1 前提条件升级到 ToolJet 2.5 及以上版本gRPC 数据源需要 ToolJet2.5 或更高版本。如果你的实例版本较旧请先参照 ToolJet Setup 指南 完成版本升级再继续后续步骤。2.2 Step 2创建 protos 目录并添加 service.proto在 ToolJet 仓库/部署根目录下创建名为protos的目录并在其中添加service.proto文件mkdir protos # 将你的 gRPC 服务定义写入 protos/service.protoservice.proto是标准的 Protocol Buffers 服务定义文件示例内容大致如下syntax proto3; package helloworld; service Greeter { rpc SayHello (HelloRequest) returns (HelloReply) {} } message HelloRequest { string name 1; } message HelloReply { string message 1; }2.3 Step 3在 docker-compose.yml 中挂载卷编辑docker-compose.yml在plugins和server两个服务的volumes段中分别添加以下挂载参考仓库根目录 docker-compose.yaml 中plugins与server服务的volumes配置结构./protos:/app/protos挂载完成后plugins服务才能读取 proto 文件并构建客户端存根server服务才能解析 proto 并暴露给查询面板。这正是源码中protoFilePath ${rootDir}/protos/service.proto所依赖的容器内路径/app/protos/service.proto。2.4 Step 4重启实例使配置生效完成卷挂载后重启 Docker 服务docker-compose up -d重启后插件服务即会加载/app/protos/service.proto此时就可以在全局数据源页面创建 gRPC 连接了。三、连接 gRPC 数据源进入 全局数据源页面选择 gRPC 即可创建数据源。根据官方文档ToolJet 连接 gRPC 服务器需要以下信息配置项说明Server URLgRPC 服务器地址格式为host:port例如0.0.0.0:50051见 manifest.json 中url字段的 descriptionAuthentication type认证方式支持None无认证、Basic、Bearer、API key四种其中 Server URL 为必填项manifest 中required: [url]其余字段按所选认证方式填写。3.1 认证方式详解源码级结合 plugins/packages/grpc/lib/index.ts 的实现四种认证方式的实际行为如下None默认auth_type缺省时取none不向 metadata 注入任何认证信息直接以裸连接发起 RPC 调用。Basic向 gRPC metadata 添加username与password两个键值对注意Basic 认证在此实现中是以自定义 metadata 字段传递而非 HTTP Basic 头。Bearer向 metadata 添加Authorization: Bearer bearer_token头。API key向 metadata 添加自定义键值对键名为grpc_apikey_key值为grpc_apikey_value即“自定义 Header 名 密钥值”的灵活组合。其中password、bearer_token、grpc_apikey_value在 manifest.json 中被标记为encrypted: true意味着这些敏感字段会在服务端加密存储连接时再解密使用。3.2 在应用查询面板中使用 gRPC 数据源连接创建成功后在应用的查询面板左侧数据源列表中选择该 gRPC 数据源即可开始编写查询。四、创建 gRPC 查询并调用 RPC 方法4.1 查询参数说明在查询编辑器中你需要填写以下参数对应 types.ts 中的QueryOptions定义参数类型说明serviceNamestring要调用的 gRPC 服务名取自 proto 文件中的service定义rpcstring要调用的 RPC 方法名取自该服务下的rpc定义jsonMessagestring请求消息体必须是合法的 JSON 字符串为空时按空对象{}处理4.2 发起调用的内部流程当你点击运行查询时插件会执行以下步骤见 index.ts将jsonMessage通过JSON.parse解析为对象解析失败时抛出Invalid JSON message错误。基于已加载的 proto 定义以clientStubrpc发起一元 RPC 调用。回调中若收到err将错误信息包装为QueryError抛出成功则返回响应对象。调用成功后返回结果{ status: ok, data: response }中的data即为 gRPC 服务器返回的消息对象可直接在下游组件中通过{{queries.queryName.data}}引用。五、进阶连接测试与新版 gRPC v2 插件5.1 连接测试逻辑老版 gRPC 插件在 manifest.json 中声明了customTesting: true即连接测试由插件自定义逻辑完成通过加载 proto 并尝试与服务端建立通道来验证连通性。仓库中 plugins/packages/grpc/tests/index.js 预留了测试骨架it.todo(needs tests)说明该插件的自动化测试用例仍在补充中。5.2 新版 gRPC v2 插件的能力扩展仓库中还提供了功能更完整的gRPC v2插件plugins/packages/grpcv2从源码结构看它相比旧版增加了以下能力可作为自托管部署的替代方案参考三种 proto 来源模式proto_files选项server_reflection通过 gRPC 服务器反射自动发现服务与方法、import_proto_file从远程 URL 加载 proto 文件、import_protos_from_filesystem从文件系统目录按 glob 模式扫描 proto 文件TLS/SSL 支持通过ssl_enabled选项构建安全通道buildChannelCredentials/sanitizeGrpcServerUrl更完整的连接测试testConnection会对不同模式分别验证服务发现、proto 文件解析与 TCP 连通性基于waitForReady通道级检查请求消息使用 JSON5 解析raw_message字段容错性更强服务发现接口通过listServices、getServiceDefinitions等暴露方法为配置页与查询编辑器提供动态服务/方法下拉选择。如果你的 gRPC 服务端支持服务器反射或需要 TLS 加密连接、多 proto 文件场景可以优先评估 gRPC v2 插件。六、常见问题排查现象可能原因与处理方式查询报Missing URL数据源未填写 Server URL该字段为必填项查询报Invalid JSON messagejsonMessage不是合法 JSON请检查花括号、引号与转义提示找不到服务或方法serviceName/rpc与 proto 文件中定义不一致或 proto 文件未正确挂载到/app/protos/service.proto连接失败/超时确认 Server URL 的host:port可达且 gRPC 服务端监听地址与端口正确流式 RPC 无法工作当前版本仅支持 unary一元请求与响应流式方法需等待后续版本或使用其他方案总结ToolJet 的 gRPC 数据源为自托管实例提供了一条低成本的 gRPC 服务接入路径只需三步——升级版本、放置service.proto、挂载卷并重启——即可在查询面板中按serviceName rpc jsonMessage三元组调用任意一元 RPC 方法并支持 None/Basic/Bearer/API key 四种认证方式。透过 plugins/packages/grpc/lib/index.ts 的源码可以看到其底层完全基于grpc/grpc-js实现理解这一封装逻辑有助于你在遇到连接问题时快速定位原因。如需更高级的反射发现、TLS 支持与多文件场景可进一步研究仓库中的 gRPC v2 插件实现。【免费下载链接】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），仅供参考
ToolJet 接入 gRPC 数据源：从 proto 文件挂载到 RPC 查询的完整实战指南
ToolJet 接入 gRPC 数据源从 proto 文件挂载到 RPC 查询的完整实战指南【免费下载链接】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/ToolJetToolJet 的 gRPC 数据源允许你在自托管实例中直接连接 gRPC 服务端通过加载.proto文件Protocol Buffers 服务定义并调用其公开的 RPC 方法将 gRPC 服务能力融入低代码应用与工作流。本文将基于官方数据源文档结合仓库中plugins/packages/grpc插件的源码实现完整讲解自托管部署下的环境准备、proto 文件挂载、数据源连接认证以及如何在查询面板中对任意 RPC 方法发起调用并附带连接测试与常见问题分析。注意gRPC 数据源仅适用于自托管Self-hosted部署且当前版本仅支持处理一元请求与响应unary request/response不支持流式 RPC。一、gRPC 数据源的工作原理在深入配置之前先理解 ToolJet 是如何将 proto 文件变成可调用的 RPC 方法的。插件源码位于 plugins/packages/grpc/lib/index.ts其核心调用链如下加载 proto 文件使用grpc/proto-loader的loadSync()同步解析位于容器内/app/protos/service.proto的 proto 文件并配置keepCase: true、longs: String、enums: String、defaults: true、oneofs: true等解析选项其中 long 型字段以字符串返回避免精度丢失。构建客户端存根通过grpc.loadPackageDefinition()取出指定服务serviceName然后以new Service(url, grpc.credentials.createInsecure())创建客户端存根——默认使用非加密insecure通道连接。附加认证元数据根据auth_type在grpc.Metadata中注入不同的认证信息详见下文“认证方式”。执行 RPC 调用解析查询面板传入的 JSON 消息体queryOptions.jsonMessage必须是合法 JSON否则抛出Invalid JSON message错误调用clientStubrpc发起一元调用最终返回{ status: ok, data: response }。从源码可以看出ToolJet 的 gRPC 插件本质上是grpc/grpc-js的封装serviceName服务名与rpc方法名都来自查询参数proto 文件路径固定为protos/service.proto因此服务端与方法的可用性完全取决于你挂载的 proto 文件内容。二、环境准备自托管实例的配置步骤2.1 前提条件升级到 ToolJet 2.5 及以上版本gRPC 数据源需要 ToolJet2.5 或更高版本。如果你的实例版本较旧请先参照 ToolJet Setup 指南 完成版本升级再继续后续步骤。2.2 Step 2创建 protos 目录并添加 service.proto在 ToolJet 仓库/部署根目录下创建名为protos的目录并在其中添加service.proto文件mkdir protos # 将你的 gRPC 服务定义写入 protos/service.protoservice.proto是标准的 Protocol Buffers 服务定义文件示例内容大致如下syntax proto3; package helloworld; service Greeter { rpc SayHello (HelloRequest) returns (HelloReply) {} } message HelloRequest { string name 1; } message HelloReply { string message 1; }2.3 Step 3在 docker-compose.yml 中挂载卷编辑docker-compose.yml在plugins和server两个服务的volumes段中分别添加以下挂载参考仓库根目录 docker-compose.yaml 中plugins与server服务的volumes配置结构./protos:/app/protos挂载完成后plugins服务才能读取 proto 文件并构建客户端存根server服务才能解析 proto 并暴露给查询面板。这正是源码中protoFilePath ${rootDir}/protos/service.proto所依赖的容器内路径/app/protos/service.proto。2.4 Step 4重启实例使配置生效完成卷挂载后重启 Docker 服务docker-compose up -d重启后插件服务即会加载/app/protos/service.proto此时就可以在全局数据源页面创建 gRPC 连接了。三、连接 gRPC 数据源进入 全局数据源页面选择 gRPC 即可创建数据源。根据官方文档ToolJet 连接 gRPC 服务器需要以下信息配置项说明Server URLgRPC 服务器地址格式为host:port例如0.0.0.0:50051见 manifest.json 中url字段的 descriptionAuthentication type认证方式支持None无认证、Basic、Bearer、API key四种其中 Server URL 为必填项manifest 中required: [url]其余字段按所选认证方式填写。3.1 认证方式详解源码级结合 plugins/packages/grpc/lib/index.ts 的实现四种认证方式的实际行为如下None默认auth_type缺省时取none不向 metadata 注入任何认证信息直接以裸连接发起 RPC 调用。Basic向 gRPC metadata 添加username与password两个键值对注意Basic 认证在此实现中是以自定义 metadata 字段传递而非 HTTP Basic 头。Bearer向 metadata 添加Authorization: Bearer bearer_token头。API key向 metadata 添加自定义键值对键名为grpc_apikey_key值为grpc_apikey_value即“自定义 Header 名 密钥值”的灵活组合。其中password、bearer_token、grpc_apikey_value在 manifest.json 中被标记为encrypted: true意味着这些敏感字段会在服务端加密存储连接时再解密使用。3.2 在应用查询面板中使用 gRPC 数据源连接创建成功后在应用的查询面板左侧数据源列表中选择该 gRPC 数据源即可开始编写查询。四、创建 gRPC 查询并调用 RPC 方法4.1 查询参数说明在查询编辑器中你需要填写以下参数对应 types.ts 中的QueryOptions定义参数类型说明serviceNamestring要调用的 gRPC 服务名取自 proto 文件中的service定义rpcstring要调用的 RPC 方法名取自该服务下的rpc定义jsonMessagestring请求消息体必须是合法的 JSON 字符串为空时按空对象{}处理4.2 发起调用的内部流程当你点击运行查询时插件会执行以下步骤见 index.ts将jsonMessage通过JSON.parse解析为对象解析失败时抛出Invalid JSON message错误。基于已加载的 proto 定义以clientStubrpc发起一元 RPC 调用。回调中若收到err将错误信息包装为QueryError抛出成功则返回响应对象。调用成功后返回结果{ status: ok, data: response }中的data即为 gRPC 服务器返回的消息对象可直接在下游组件中通过{{queries.queryName.data}}引用。五、进阶连接测试与新版 gRPC v2 插件5.1 连接测试逻辑老版 gRPC 插件在 manifest.json 中声明了customTesting: true即连接测试由插件自定义逻辑完成通过加载 proto 并尝试与服务端建立通道来验证连通性。仓库中 plugins/packages/grpc/tests/index.js 预留了测试骨架it.todo(needs tests)说明该插件的自动化测试用例仍在补充中。5.2 新版 gRPC v2 插件的能力扩展仓库中还提供了功能更完整的gRPC v2插件plugins/packages/grpcv2从源码结构看它相比旧版增加了以下能力可作为自托管部署的替代方案参考三种 proto 来源模式proto_files选项server_reflection通过 gRPC 服务器反射自动发现服务与方法、import_proto_file从远程 URL 加载 proto 文件、import_protos_from_filesystem从文件系统目录按 glob 模式扫描 proto 文件TLS/SSL 支持通过ssl_enabled选项构建安全通道buildChannelCredentials/sanitizeGrpcServerUrl更完整的连接测试testConnection会对不同模式分别验证服务发现、proto 文件解析与 TCP 连通性基于waitForReady通道级检查请求消息使用 JSON5 解析raw_message字段容错性更强服务发现接口通过listServices、getServiceDefinitions等暴露方法为配置页与查询编辑器提供动态服务/方法下拉选择。如果你的 gRPC 服务端支持服务器反射或需要 TLS 加密连接、多 proto 文件场景可以优先评估 gRPC v2 插件。六、常见问题排查现象可能原因与处理方式查询报Missing URL数据源未填写 Server URL该字段为必填项查询报Invalid JSON messagejsonMessage不是合法 JSON请检查花括号、引号与转义提示找不到服务或方法serviceName/rpc与 proto 文件中定义不一致或 proto 文件未正确挂载到/app/protos/service.proto连接失败/超时确认 Server URL 的host:port可达且 gRPC 服务端监听地址与端口正确流式 RPC 无法工作当前版本仅支持 unary一元请求与响应流式方法需等待后续版本或使用其他方案总结ToolJet 的 gRPC 数据源为自托管实例提供了一条低成本的 gRPC 服务接入路径只需三步——升级版本、放置service.proto、挂载卷并重启——即可在查询面板中按serviceName rpc jsonMessage三元组调用任意一元 RPC 方法并支持 None/Basic/Bearer/API key 四种认证方式。透过 plugins/packages/grpc/lib/index.ts 的源码可以看到其底层完全基于grpc/grpc-js实现理解这一封装逻辑有助于你在遇到连接问题时快速定位原因。如需更高级的反射发现、TLS 支持与多文件场景可进一步研究仓库中的 gRPC v2 插件实现。【免费下载链接】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），仅供参考
