Apache DolphinScheduler StarRocks 数据源接入指南：参数配置、连接原理与插件部署

Apache DolphinScheduler 通过可插拔的数据源插件体系接入 StarRocks，将其作为工作流中 SQL 任务、数据同步任务的数据来源。本指南以官方数据源文档为主体，结合仓库中 dolphinscheduler-datasource-starrocks 插件源码与部署脚本，完整讲解 StarRocks 数据源的表单参数含义、底层 JDBC 连接原理、驱动依赖安装方式，帮助你在 DolphinScheduler 中正确创建、验证并使用 StarRocks 数据源。

StarRocks 数据源概览

StarRocks 是一款兼容 MySQL 协议的 OLAP 分析型数据库，因此 DolphinScheduler 中的 StarRocks 数据源插件在设计上复用了 MySQL 生态的连接方式：底层驱动为 com.mysql.cj.jdbc.Driver，JDBC URL 前缀为 jdbc:mysql://，连接校验查询为 select 1。这一点可以从插件源码中得到直接印证：

• 驱动类名：DataSourceConstants.COM_MYSQL_CJ_JDBC_DRIVER（值为 com.mysql.cj.jdbc.Driver）
• JDBC 前缀：DataSourceConstants.JDBC_MYSQL（值为 jdbc:mysql://）
• 校验查询：DataSourceConstants.MYSQL_VALIDATION_QUERY（值为 select 1）

以上常量均定义于 DataSourceConstants.java，并在 StarRocksDataSourceProcessor.java 中被引用。这意味着凡是依赖 MySQL 连接器的任务类型（如 SQL 查询类任务）均可在配置了 StarRocks 数据源后正常工作。

Datasource Parameters：表单参数详解

在 DolphinScheduler 的「数据源中心」页面选择 StarRocks 后，需要填写如下参数：

参数项	说明
Datasource（数据源类型）	选择 StarRocks
Datasource name（数据源名称）	为数据源命名，便于在工作流中识别引用
Description（描述）	可选，填写数据源的用途说明
IP/Host Name（主机名/IP）	StarRocks 服务的 IP 地址或主机名
Port（端口）	StarRocks 服务端口，即 FE 的 query_port（默认 9030）
Username（用户名）	连接 StarRocks 使用的用户名
Password（密码）	连接 StarRocks 使用的密码
Database name（数据库名）	要连接的 StarRocks 数据库名
Jdbc connection parameters（JDBC 连接参数）	StarRocks 连接的参数设置，以 JSON 格式填写

参数背后的连接串生成逻辑

从前端表单提交的参数会进入 StarRocksDataSourceParamDTO.java 描述的数据结构，随后由 StarRocksDataSourceProcessor.createConnectionParams(BaseDataSourceParamDTO) 将其组装为连接参数：

address  = jdbc:mysql://{host}:{port}
jdbcUrl  = jdbc:mysql://{host}:{port}/{database}

其中 database 会作为 JDBC URL 的默认库名，后续通过该数据源执行的 SQL 若未显式指定库名，即以该库为默认上下文。若在表单中同时填写了多个主机（以逗号分隔），createDatasourceParamDTO(String) 方法会取第一个地址中的 host 与 port 回填到 DTO 中，用于界面回显。

密码不会以明文落入配置：createConnectionParams 中通过 PasswordUtils.encodePassword(...) 对密码进行加密存储（见 StarRocksDataSourceProcessor.java），实际建立连接时再通过 PasswordUtils.decodePassword(...) 解密，避免敏感信息直接暴露在数据库中。

Jdbc connection parameters（JSON 格式）的使用方法

「Jdbc connection parameters」接收 JSON 格式的键值对，用于追加到 JDBC URL 的查询参数中，例如：

{
  "useUnicode": "true",
  "characterEncoding": "UTF-8",
  "connectTimeout": "10000",
  "socketTimeout": "60000"
}

这些参数会被拼接到 JDBC URL 之后，最终生成的连接串形如：

jdbc:mysql://{host}:{port}/{database}?useUnicode=true&characterEncoding=UTF-8&...&allowLoadLocalInfile=false&autoDeserialize=false&allowLocalInfile=false&allowUrlInLocalInfile=false

需要特别说明的是，插件在拼接连接参数时会自动强制追加四条安全参数，用于抵御恶意 JDBC 连接串攻击（相关常量与拼接逻辑见 StarRocksDataSourceProcessor.java 与 getJdbcUrl 方法）：

• allowLoadLocalInfile=false：禁止从本地文件读取数据
• autoDeserialize=false：禁止自动反序列化对象
• allowLocalInfile=false：禁止本地文件导入
• allowUrlInLocalInfile=false：禁止通过 URL 触发本地文件读取

同时，transformOther 方法会过滤掉表单中与上述四条安全参数同名或包含这些关键词的键，从源头防止用户覆盖默认的安全设置（见 StarRocksDataSourceProcessor.java）。此外，getConnection 在建立连接前还会对用户名和密码字段中的 autoDeserialize 敏感参数进行过滤并记录告警日志，进一步加固连接安全（见 StarRocksDataSourceProcessor.java）。

Native Supported：原生支持状态与驱动依赖安装

当前版本中 StarRocks 数据源默认不随二进制发行包提供，属于“非原生内置”的数据源。若未完成驱动安装，创建连接或运行相关任务时会因缺少驱动类而失败（典型报错为 ClassNotFoundException）。需要按照以下步骤激活该数据源。

方式一：安装插件依赖包（推荐）

自 3.3.0 版本起，DolphinScheduler 二进制包不再内置插件依赖，需手动下载安装。伪集群部署的官方步骤见 pseudo-cluster.md 中 Download Plugins Dependencies 一节，核心操作如下：

bash ./bin/install-plugins.sh 3.3.0

该脚本按 conf/plugins_config 中声明的插件清单下载对应依赖包。plugins_config 是插件解析的映射清单，用于将用户配置的插件模块名解析为不带版本号的 Jar 包 artifactId，其结构示例（仓库中的完整内容见 plugins_config）：

--alert-plugins--
dolphinscheduler-alert-email
--end--

--datasource-plugins--
dolphinscheduler-datasource-starrocks
--end--

--storage-plugins--
dolphinscheduler-storage-hdfs
--end--

--task-plugins--
dolphinscheduler-task-shell
--end--

若只想启用 StarRocks 数据源，可将 --datasource-plugins-- 段精简为：

--datasource-plugins--
dolphinscheduler-datasource-starrocks
--end--

注意：插件依赖包通常不包含在二进制发行包中。如果服务启动时出现 ClassNotFoundException，请参照相应插件类型的文档检查插件依赖是否缺失；例如 dolphinscheduler-datasource-mysql 本身不内置 mysql-connector-java.jar，StarRocks 数据源同理依赖 MySQL 连接器。

方式二：手动放置 MySQL 驱动 Jar

StarRocks 数据源依赖 MySQL Connector/J 驱动，官方文档给出的驱动下载地址为 mysql-connector-j-8.0.33（Maven 中央仓库中 com/mysql/mysql-connector-j/8.0.33/ 的 mysql-connector-j-8.0.33.jar）。下载后将 Jar 放置到 DolphinScheduler 各服务（api、master、worker 等）的 libs 或插件目录下，并重启服务使其生效。

这一依赖关系同样体现在插件构建配置中：pom.xml 声明了对 com.mysql:mysql-connector-j 的依赖，插件模块的 plugin.name 属性为 datasource.starrocks，并在打包阶段使用 maven-shade-plugin 将依赖一并打入插件 Jar。

验证驱动加载

安装完成后，可通过数据源中心新建 StarRocks 数据源并点击「测试连接」验证。底层连接由 JdbcDriverConnectionProvider 完成驱动类加载与 DriverManager 连接建立（见 StarRocksDataSourceProcessor.java）；若驱动缺失，测试连接将直接失败并提示驱动类无法加载。

插件实现架构：从工厂到连接池

StarRocks 数据源插件遵循 DolphinScheduler 数据源 SPI 规范，共由六个类组成，职责划分清晰：

类名	职责
StarRocksDataSourceChannelFactory	通过 @AutoService(DataSourceChannelFactory.class) 注册插件，getName() 返回 DbType.STARROCKS 的类型名（见 StarRocksDataSourceChannelFactory.java）
StarRocksDataSourceChannel	创建即席（AdHoc）与池化（Pooled）两类数据源客户端（见 StarRocksDataSourceChannel.java）
StarRocksAdHocDataSourceClient	继承 BaseAdHocDataSourceClient，用于一次性临时连接场景（见 StarRocksAdHocDataSourceClient.java）
StarRocksPooledDataSourceClient	继承 BasePooledDataSourceClient，提供基于连接池的复用连接（见 StarRocksPooledDataSourceClient.java）
StarRocksConnectionParam	连接参数模型，继承 BaseConnectionParam，承载 user/address/database/jdbcUrl/driverLocation/driverClassName/validationQuery/other 等字段（见 StarRocksConnectionParam.java）
StarRocksDataSourceProcessor	核心处理器，负责参数 DTO/连接参数间的转换、JDBC URL 组装、驱动与校验查询提供、连接建立（见 StarRocksDataSourceProcessor.java）

其中 StarRocksDataSourceProcessor 通过 @AutoService(DataSourceProcessor.class) 注解自动注册到数据源处理链，getDbType() 返回 DbType.STARROCKS，DolphinScheduler 在运行 SQL 类任务时会根据数据源类型路由到对应的 Processor，完成从表单配置到真实数据库连接的完整闭环。

连接流程小结

一次 StarRocks 数据源连接的完整链路如下：

1. 用户在前端表单填写 StarRocks 参数，前端提交 StarRocksDataSourceParamDTO；
2. StarRocksDataSourceProcessor.createConnectionParams(DTO) 生成 jdbc:mysql://{host}:{port}/{database} 形式的连接参数并加密存储密码；
3. 任务执行时调用 getJdbcUrl() 拼接用户自定义 JSON 参数并强制追加四条安全参数；
4. getConnection() 通过 JdbcDriverConnectionProvider 加载 com.mysql.cj.jdbc.Driver 建立真实连接（池化场景交由 StarRocksPooledDataSourceClient 复用）；
5. 连接建立后以 select 1 作为有效性校验，保证连接池中连接的健康状态。

理解上述参数与实现细节后，即可在 DolphinScheduler 数据源中心创建可靠的 StarRocks 数据源，并将其用于工作流中的 SQL 查询、数据抽取等任务场景。