DolphinScheduler 数据源配置避坑指南：从元数据库到数据源中心的完整实操

DolphinScheduler 数据源配置避坑指南：从元数据库到数据源中心的完整实操

【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinscheduler

一台新机器装好了 Apache DolphinScheduler，你的第一个任务是把 MySQL 业务库接进去。但在"接上第一个数据源"之前，有一个容易忽略的事实：数据源配置其实是两层——一层是给调度系统自己用的元数据库（工作流定义、任务实例、用户权限都存在里面），另一层是你在界面上操作的数据源中心（存的是业务任务要连的库）。本文按"先跑起来、再接业务库、最后上生产"的顺序，把这两层从零配完，并标出每一步最容易踩的坑。

1. 先分清"元数据库"和"数据源中心"

很多排查混乱的根源是把这两层搞混了：服务起不来，多半是元数据库没配好；任务里的 SQL 任务连不上库，多半是数据源中心的配置或驱动有问题。

元数据库目前支持MySQL和PostgreSQL两种；Standalone 模式额外内置了一个 H2，只适合试玩。数据源中心支持的类型则多得多，见第 3 节。

元数据库里长什么样？核心表都以t_ds_为前缀，数据源的连接信息就落在t_ds_datasource表中：

2. 按部署模式分两条线配置元数据库

两条线的差别只在一点：Standalone 默认用 H2，需要先"搬家"到 MySQL；分布式部署一开始就要建外部库。

2.1 Standalone 线：把默认的 H2 换成 MySQL

Standalone 模式开箱即用，默认数据落在 H2 里——服务一停，工作流定义、执行记录全部清零。试玩无所谓，正式使用必须换出去。

1. 放驱动：下载 mysql-connector-java 驱动（建议 8.0.16 及以上版本），放到standalone-server/libs/standalone-server/目录下。 ✅ 验证：ls能看到 jar 文件，且文件名带版本号。

2. 设环境变量，把{address}、{user}、{password}换成真实值：

   export DATABASE=mysql export SPRING_PROFILES_ACTIVE=${DATABASE} export SPRING_DATASOURCE_URL="jdbc:mysql://{address}/dolphinscheduler?useUnicode=true&characterEncoding=UTF-8&useSSL=false" export SPRING_DATASOURCE_USERNAME={user} export SPRING_DATASOURCE_PASSWORD={password}

   ✅ 验证：echo $SPRING_DATASOURCE_URL输出完整 JDBC 串，没有残留花括号占位符。

3. 启动并确认数据落库：启动 standalone-server，建一个测试工作流，然后重启服务。 ✅ 验证：重启后工作流仍在，且 MySQL 中dolphinscheduler库已出现t_ds_开头的表——说明数据已持久化，重启不再丢失。

⚠️ 警告：MySQL 驱动版本有硬性要求——只要把 MySQL 当作元数据库，就必须使用8.0.16 及以上版本的驱动，旧版连接会直接报错。

2.2 分布式线：建库、授权、设环境变量、初始化

分布式部署没有 H2 兜底，顺序是：建库并授权 → 配环境变量 → 初始化表结构，按这个顺序走就不会回头。

2.2.1 创建元数据库并授权

MySQL 5.6 / 5.7（一条 GRANT 同时完成建用户与授权）：

CREATE DATABASE dolphinscheduler DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci; -- 替换 {user} 和 {password} 为实际值 GRANT ALL PRIVILEGES ON dolphinscheduler.* TO '{user}'@'%' IDENTIFIED BY '{password}'; GRANT ALL PRIVILEGES ON dolphinscheduler.* TO '{user}'@'localhost' IDENTIFIED BY '{password}'; FLUSH PRIVILEGES;

MySQL 8.0+（GRANT ... IDENTIFIED BY已被移除，必须分开建用户）：

CREATE DATABASE dolphinscheduler DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci; -- 替换 {user} 和 {password} 为实际值 CREATE USER '{user}'@'%' IDENTIFIED BY '{password}'; GRANT ALL PRIVILEGES ON dolphinscheduler.* TO '{user}'@'%'; CREATE USER '{user}'@'localhost' IDENTIFIED BY '{password}'; GRANT ALL PRIVILEGES ON dolphinscheduler.* TO '{user}'@'localhost'; FLUSH PRIVILEGES;

两者差异一览：

PostgreSQL除了建库，还要改pg_hba.conf放开主机访问：

CREATE DATABASE dolphinscheduler; CREATE USER {user} PASSWORD '{password}'; ALTER DATABASE dolphinscheduler OWNER TO {user};

# 替换 {user} 和 {ip} 为实际账号与 DS 集群服务器 IP 地址段 echo "host dolphinscheduler {user} {ip} md5" >> $PGDATA/pg_hba.conf pg_ctl reload

✅ 验证：用{user}从计划运行 DolphinScheduler 的那台机器上mysql -u{user} -p/psql -U{user}登录成功——这一步验证的是网络和权限，不是密码本身。

⚠️ 警告：pg_hba.conf里的{ip}要覆盖所有 DS 节点的地址段。漏配某台机器的 IP 时，症状是"有的节点连得上、有的连不上"，非常难查。

2.2.2 配置元数据库环境变量

在每个节点的服务启动脚本生效前设置（写进/etc/profile.d或启动脚本均可）：

MySQL：

export DATABASE=${DATABASE:-mysql} export SPRING_PROFILES_ACTIVE=${DATABASE} export SPRING_DATASOURCE_URL="jdbc:mysql://127.0.0.1:3306/dolphinscheduler?useUnicode=true&characterEncoding=UTF-8&useSSL=false&serverTimezone={your_timezone}" export SPRING_DATASOURCE_USERNAME={user} export SPRING_DATASOURCE_PASSWORD={password}

PostgreSQL：

export DATABASE=${DATABASE:-postgresql} export SPRING_PROFILES_ACTIVE=${DATABASE} export SPRING_DATASOURCE_URL="jdbc:postgresql://127.0.0.1:5432/dolphinscheduler" export SPRING_DATASOURCE_USERNAME={user} export SPRING_DATASOURCE_PASSWORD={password}

✅ 验证：启动任一服务，日志中出现对应的数据源初始化信息且无Access denied/connection refused类报错。

⚠️ 警告：serverTimezone不要用CST这类模糊标识符，可能导致调度时间整体偏移。明确写serverTimezone=Asia/Shanghai。

💡 提示：DATABASE与SPRING_PROFILES_ACTIVE取值必须一致（mysql或postgresql），前者选驱动 profile，后者选 Spring 配置 profile，两者错位会导致"连上了错误的库"这类怪现象。

2.2.3 初始化元数据库表结构

库是空的，最后一步是让 DolphinScheduler 把表建进去：

bash tools/bin/upgrade-schema.sh

✅ 验证：脚本正常跑完后，库里出现一批t_ds_前缀的表（t_ds_process_definition、t_ds_task_definition、t_ds_user等），表数量在百张量级。

💡 提示：这个脚本在版本升级时同样适用——升级新版本后重跑一次，即可把旧库结构升级到新 schema。

3. 配置数据源中心：给业务任务接库

3.1 支持哪些类型

数据源中心按场景大致分三类，具体字段以各类型文档为准：

各类型的字段说明可以在官方文档中按库名查，例如 数据源文档目录。

3.2 标准创建流程

进入顶部导航的"Datasource（数据源中心）"，流程固定四步：

1. 点Create DataSource（创建数据源），在下拉里选择数据源类型；
2. 填写连接信息：名称、IP/主机、端口、用户名、密码、库名，部分类型还有 JSON 形式的 JDBC 连接参数；
3. 点Test Connect（测试连接）——测试不通过，保存按钮不会放行；
4. 测试通过后点Confirm保存，列表中出现该数据源条目。

以 MySQL 为例的创建界面：

3.3 给数据源中心补 JDBC 驱动

有一类数据源会"测试连接必失败"，原因不是配置错，而是驱动缺失：MySQL、Oracle、SQL Server 等数据库的 JDBC 驱动与 Apache License V2 不兼容，官方分发包里不带。需要手动补：

1. 从官方 Maven 仓库下载对应版本的 JDBC 驱动 jar；
2. 同时放入api-server/libs和worker-server/libs两个目录——前者负责"测试连接"，后者负责任务实际执行时的连接，缺一不可；
3. 重启api-server和worker-server两个服务。

✅ 验证：重启后回到数据源中心，测试连接变绿，且 worker 日志中可见驱动类加载信息，没有ClassNotFoundException/No suitable driver。

⚠️ 警告：两处要求要分清——只把某库当业务数据源用，驱动版本没有强制要求；把MySQL 当元数据库，则必须 8.0.16 及以上版本驱动（第 2.1 节）。容器部署时同理：把驱动挂载进上述两个服务的对应路径，再重启即可。

4. 上生产前自检清单 + 避坑速查

4.1 自检清单

上生产前逐条打勾，缺一条都可能变成线上事故：

• 元数据库已换掉 H2，MySQL / PostgreSQL 均可通过独立连接验证连通
• 元数据库使用专用账号，权限仅限dolphinscheduler库，未用 root 挂生产
• 生产链路已启用 SSL/TLS，JDBC URL 中useSSL等参数与 DBA 约定一致
• serverTimezone写的是明确时区，全集群节点配置一致
• 连接池参数（最大连接数、超时）按并发量评估过，未用默认值硬扛
• 已建立元数据库的定期备份，并演练过一次恢复
• 慢 SQL 与索引有例行维护动作（统计信息更新、索引优化）
• 不兼容数据源的 JDBC 驱动已放进api-server/libs与worker-server/libs，版本与驱动提供方兼容
• 升级流程中保留"测试环境先跑upgrade-schema.sh验证，再上生产"的步骤

4.2 避坑速查

💡 提示：完整的元数据库初始化步骤与变量说明，仓库内有官方文档可对照：数据源配置；各业务数据源的字段与驱动要求见 数据源文档目录，各类型插件实现位于 dolphinscheduler-datasource-plugin/。

把这两层各自配好后，DolphinScheduler 才算真正"通电"：元数据库保它自己不丢状态，数据源中心保你的任务够得着业务数据。剩下的事情——建工作流、挂调度——都是在这块地基上盖楼了。

【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinscheduler