企业官网建设流程全解析

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/ToolJet

ToolJet 的 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，其核心调用链如下：

1. 加载 proto 文件：使用@grpc/proto-loader的loadSync()同步解析位于容器内/app/protos/service.proto的 proto 文件，并配置keepCase: true、longs: String、enums: String、defaults: true、oneofs: true等解析选项（其中 long 型字段以字符串返回，避免精度丢失）。
2. 构建客户端存根：通过grpc.loadPackageDefinition()取出指定服务（serviceName），然后以new Service(url, grpc.credentials.createInsecure())创建客户端存根——默认使用非加密（insecure）通道连接。
3. 附加认证元数据：根据auth_type在grpc.Metadata中注入不同的认证信息（详见下文“认证方式”）。
4. 执行 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.proto

service.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 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定义）：

4.2 发起调用的内部流程

当你点击运行查询时，插件会执行以下步骤（见 index.ts）：

1. 将jsonMessage通过JSON.parse解析为对象；解析失败时抛出Invalid JSON message错误。
2. 基于已加载的 proto 定义，以clientStubrpc发起一元 RPC 调用。
3. 回调中若收到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 插件。

六、常见问题排查

总结

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