点亮⭐️

https://github.com/apache/

点击蓝字 关注我们

作者 | 智业软件 张晓宁

本文面向希望在本地阅读和调试 DolphinScheduler 核心源码的开发者，示例环境为 Windows + IntelliJ IDEA + Docker Desktop + PostgreSQL + ZooKeeper。

如果你只是想快速体验功能，而不是调试 master / worker / api 的完整链路，优先使用 StandaloneServer。如果你希望调试分布式调度主链路，再按本文使用拆分服务方式启动。

• 在 IntelliJ IDEA 中单独启动 MasterServer、WorkerServer、ApiApplicationServer
• 使用 Docker Desktop 承载 PostgreSQL 和 ZooKeeper
• 在宿主机上调试 Java 服务源码
• 在本地启动前端并联调后端接口

环境要求

• Docker Desktop
• JDK 8 或 11
• Maven 3.8+，或者直接使用仓库自带的 mvnw.cmd
• Node.js 16+
• pnpm 8+
• IntelliJ IDEA

当前仓库根 pom.xml 中的 java.version 为 1.8，本地调试建议优先使用 JDK 8 或 11。

启动PostgreSQL和ZooKeeper

先进入 deploy/docker 目录。

cd 某盘:\dolphinscheduler\deploy\docker

如果你直接使用附录里的 docker-compose-windows.yml，需要先确认 dolphinscheduler-zookeeper 是否暴露了 2181 端口。master、worker、api 都默认连接 localhost:2181，如果 ZooKeeper 只运行在容器内而没有映射到宿主机，IDEA 中启动的 Java 进程会连接失败。

请确保 docker-compose-windows.yml的dolphinscheduler-zookeeper 服务包含如下配置：

dolphinscheduler-zookeeper:  image: zookeeper:3.8  ports:    - "2181:2181"

然后启动 PostgreSQL 和 ZooKeeper：

docker-compose -f docker-compose-windows.yml up -d dolphinscheduler-postgresql dolphinscheduler-zookeeper

可选验证命令：

docker psTest-NetConnection 127.0.0.1 -Port 5432Test-NetConnection localhost -Port 2181

预期结果：

• 5432

  连接成功

• 2181

  连接成功

如果你使用的是本机或远程服务器上安装的 PostgreSQL 或 ZooKeeper，而不是 Docker，可以跳过这一步，但要确保后续配置中的地址、端口、用户名和密码与你本机环境一致。

在仓库根目录执行：

cd 某盘:\dolphinscheduler.\mvnw.cmd spotless:apply.\mvnw.cmd clean install -DskipTests

说明：

• spotless:apply

  用于统一代码格式，避免后续编译或提交时被格式检查卡住
• 第一次全量编译耗时会比较长，属于正常现象

初始化PostgreSQL元数据库

master 和 api 启动前，DolphinScheduler 的元数据库表必须先初始化。当前仓库的 PostgreSQL 初始化脚本位于：

dolphinscheduler-dao/src/main/resources/sql/dolphinscheduler_postgresql.sql

也就是：

某盘:\dolphinscheduler\dolphinscheduler-dao\src\main\resources\sql\dolphinscheduler_postgresql.sql

如果你使用的是 Docker 里的 PostgreSQL，可以直接在 PowerShell 中执行：

Get-Content -Path .\dolphinscheduler-dao\src\main\resources\sql\dolphinscheduler_postgresql.sql -Raw |  docker exec -i -e PGPASSWORD=root docker-dolphinscheduler-postgresql-1 psql -U root -d dolphinscheduler

也可以使用 DataGrip、DBeaver 或 psql 手动执行整份 SQL 文件。

注意：这份 SQL 包含 DROP TABLE IF EXISTS，会重建元数据库表。请不要在已有重要数据的数据库上直接执行。

初始化完成后，可以执行以下 SQL 验证：

select version from t_ds_version;

预期结果是返回一条版本记录，例如 3.4.0。

当前仓库默认已经使用 PostgreSQL 和 ZooKeeper，本地如果采用以下默认值，通常不需要额外改配置：

• PostgreSQL: 127.0.0.1:5432
• 数据库名: dolphinscheduler
• 用户名: root
• 密码: root
• ZooKeeper: localhost:2181

相关配置文件：

• dolphinscheduler-master/src/main/resources/application.yaml

• dolphinscheduler-api/src/main/resources/application.yaml

• dolphinscheduler-worker/src/main/resources/application.yaml

如果你的本地依赖不是以上默认值，再修改这些配置项：

• spring.datasource.url

• spring.datasource.username

• spring.datasource.password

• registry.zookeeper.connect-string

如果你使用 PostgreSQL，不要在 IDEA 的 VM Options 中继续带 -Dspring.profiles.active=mysql。如果你需要显式指定 profile，请使用：

-Dspring.profiles.active=postgresql

配置IntelliJ IDEA启动项

每个启动项都建议统一配置如下：

• JDK 选择 8 或 11

• Use classpath of module

  选择对应模块
• 勾选 Add dependencies with "provided" scope to classpath

• Working directory

  指向仓库根目录

Add dependencies with "provided" scope to classpath 很关键，不勾选时，启动阶段容易出现类找不到或依赖缺失问题。

建议创建以下三个启动项：

MasterServer

• Main class: org.apache.dolphinscheduler.server.master.MasterServer
• Module: dolphinscheduler-master

默认监听端口：

• RPC: 5678
• Spring Boot 端口: 5679

WorkerServer

• Main class: org.apache.dolphinscheduler.server.worker.WorkerServer
• Module: dolphinscheduler-worker

默认监听端口：

• RPC: 1234
• Spring Boot 端口: 1235

ApiApplicationServer

• Main class: org.apache.dolphinscheduler.api.ApiApplicationServer
• Module: dolphinscheduler-api

默认监听端口：

• HTTP: 12345
• Gateway Server: 25333

启动顺序建议如下：

1. MasterServer

2. WorkerServer

3. ApiApplicationServer

AlertServer 可以按需启动。只有当你需要调试告警链路时，再单独启动它。

在仓库根目录执行：

cd 某盘:\dolphinscheduler\dolphinscheduler-uipnpm installpnpm run dev

启动完成后，前端默认访问地址为：

http://localhost:5173

默认账号密码：

• 用户名：admin
• 密码：dolphinscheduler123

启动成功后的验证方式

验证 API

浏览器访问：

• http://localhost:12345/dolphinscheduler/actuator/health

• http://localhost:12345/dolphinscheduler/swagger-ui/index.html

预期结果：

• actuator/health

  返回 UP

• swagger-ui

  页面可以正常打开

验证前端

浏览器访问：

• http://localhost:5173

能够正常打开登录页并完成登录，说明前后端联调基本打通。

验证日志

在 IDEA 中则重点观察各服务控制台输出是否出现致命异常。

1. MasterServer 启动失败，日志提示 zookeeper connect failed to: localhost:2181

原因通常有两个：

• ZooKeeper 没有真正启动
• ZooKeeper 在 Docker 里启动了，但没有把 2181暴露到宿主机

排查方式：

Test-NetConnection localhost -Port 2181

如果连接失败，优先检查 docker-compose-windows.yml 中是否为 dolphinscheduler-zookeeper 配置了：

ports:
  - "2181:2181"

2. ApiApplicationServer 启动失败，日志提示 relation "t_ds_version" does not exist

这说明 PostgreSQL 元数据库还没有初始化，或者初始化到了错误的数据库。

处理方式：

• 重新执行 dolphinscheduler_postgresql.sql
• 确认连接的是 dolphinscheduler 数据库
• 执行 select version from t_ds_version; 验证表是否存在

3. IDEA 中启动时报类找不到或依赖缺失

优先检查是否勾选了：

Add dependencies with "provided" scope to classpath

如果没有勾选，这类问题会非常常见。

4. 启动 api 时端口 12345 被占用

排查方式：

Test-NetConnection localhost -Port 12345

如果已经有进程占用该端口，请先停止原有进程，再重新启动 IDEA 中的 ApiApplicationServer。

Docker-compose-windows

# Licensed to the Apache Software Foundation (ASF) under one# or more contributor license agreements.  See the NOTICE file# distributed with this work for additional information# regarding copyright ownership.  The ASF licenses this file# to you under the Apache License, Version 2.0 (the# "License"); you may not use this file except in compliance# with the License.  You may obtain a copy of the License at##     http://www.apache.org/licenses/LICENSE-2.0## Unless required by applicable law or agreed to in writing, software# distributed under the License is distributed on an "AS IS" BASIS,# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.# See the License for the specific language governing permissions and# limitations under the License.version: "3.8"services:  dolphinscheduler-postgresql:    image: bitnami/postgresql:latest    ports:      - "5432:5432"    environment:      POSTGRESQL_USERNAME: root      POSTGRESQL_PASSWORD: root      POSTGRESQL_DATABASE: dolphinscheduler    volumes:      - dolphinscheduler-postgresql:/bitnami/postgresql    healthcheck:      test: ["CMD", "bash", "-c", "cat < /dev/null > /dev/tcp/127.0.0.1/5432"]      interval: 5s      timeout: 60s      retries: 120    networks:      - dolphinscheduler  dolphinscheduler-zookeeper:    image: zookeeper:3.8    ports:      - "2181:2181"    environment:      ALLOW_ANONYMOUS_LOGIN: "yes"      ZOO_4LW_COMMANDS_WHITELIST: srvr,ruok,wchs,cons    volumes:      - dolphinscheduler-zookeeper:/bitnami/zookeeper    healthcheck:      test: ["CMD", "bash", "-c", "cat < /dev/null > /dev/tcp/127.0.0.1/2181"]      interval: 5s      timeout: 60s      retries: 120    networks:      - dolphinschedulernetworks:  dolphinscheduler:    driver: bridgevolumes:  dolphinscheduler-postgresql:  dolphinscheduler-zookeeper:

END

用户案例

Cisco Webex天翼云Zoom网易邮箱 每日互动 惠生工程作业帮 博世智驾蔚来汽车 长城汽车集度长安汽车思科网讯食行生鲜联通医疗联想新网银行兴业证券唯品富邦消费金融 自如有赞伊利当贝大数据珍岛集团传智教育BigoYY直播 拈花云科太美医疗深圳某智能制造企业

迁移实战

Azkaban Ooize（当贝迁移案例） （有赞迁移案例）Air2phin（迁移工具）Airflow

最新发版消息

Apache DolphinScheduler 3.4.1 发布，新增任务分发超时检测

加入社区

关注社区的方式有很多：

• GitHub: https://github.com/apache/dolphinscheduler
• 官网：https://dolphinscheduler.apache.org/en-us
• 订阅开发者邮件：dev@dolphinscheduler@apache.org（向邮箱发送任意内容，收到邮件后回复同意订阅即可）
• X.com：@DolphinSchedule
• YouTube：https://www.youtube.com/@apachedolphinscheduler
• Slack：https://join.slack.com/t/asf-dolphinscheduler/shared_invite/zt-1cmrxsio1-nJHxRJa44jfkrNL_Nsy9Qg

同样地，参与Apache DolphinScheduler 有非常多的参与贡献的方式，主要分为代码方式和非代码方式两种。

非代码方式包括：

完善文档、翻译文档；翻译技术性、实践性文章；投稿实践性、原理性文章；成为布道师；社区管理、答疑；会议分享；测试反馈；用户反馈等。

‍代码方式包括：

查找Bug；编写修复代码；开发新功能；提交代码贡献；参与代码审查等。

贡献第一个PR(文档、代码) 我们也希望是简单的，第一个PR用于熟悉提交的流程和社区协作以及感受社区的友好度。

社区汇总了以下适合新手的问题列表：https://github.com/apache/dolphinscheduler/pulls?q=is%3Apr+is%3Aopen+label%3A%22first+time+contributor%22

优先级问题列表：https://github.com/apache/dolphinscheduler/pulls?q=is%3Apr+is%3Aopen+label%3Apriority%3Ahigh

如何参与贡献链接：https://dolphinscheduler.apache.org/zh-cn/docs/3.2.2/%E8%B4%A1%E7%8C%AE%E6%8C%87%E5%8D%97_menu/%E5%A6%82%E4%BD%95%E5%8F%82%E4%B8%8E_menu

如果你❤️小海豚，就来为我点亮Star吧！

https://github.com/apache/dolphinscheduler

你的好友秀秀子拍了拍你

并请你帮她点一下“分享”