小白版 | Apache DolphinScheduler 本地启动指南

作者 | 智业软件 张晓宁
本文面向希望在本地阅读和调试 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。

1. 启动 PostgreSQL 和 ZooKeeper

先进入 deploy/docker 目录。

1. 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 服务包含如下配置：

1. dolphinscheduler-zookeeper:
2.   image: zookeeper:3.8
3.   ports:
4.     - "2181:2181"

复制代码

然后启动 PostgreSQL 和 ZooKeeper：

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

复制代码

可选验证命令：

1. docker ps
2. Test-NetConnection 127.0.0.1 -Port 5432
3. Test-NetConnection localhost -Port 2181

复制代码

预期结果：

• 5432 连接成功
  
• 2181 连接成功
  

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

在仓库根目录执行：

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

复制代码

说明：

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

3. 初始化 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 中执行：

1. Get-Content -Path .\dolphinscheduler-dao\src\main\resources\sql\dolphinscheduler_postgresql.sql -Raw |
2.   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 验证：

1. select version from t_ds_version;

复制代码

预期结果是返回一条版本记录，例如 3.4.0。
4. 核对本地配置

当前仓库默认已经使用 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，请使用：

1. -Dspring.profiles.active=postgresql

复制代码

5. 配置 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
  

启动顺序建议如下：

• MasterServer
  
• WorkerServer
  
• ApiApplicationServer
  

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

在仓库根目录执行：

1. cd 某盘:\dolphinscheduler\dolphinscheduler-ui
2. pnpm install
3. pnpm run dev

复制代码

启动完成后，前端默认访问地址为：
http://localhost:5173
默认账号密码：

• 用户名：admin
  
• 密码：dolphinscheduler123
  

7. 启动成功后的验证方式

验证 API

浏览器访问：

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

预期结果：

• actuator/health 返回 UP
  
• swagger-ui 页面可以正常打开
  

验证前端

浏览器访问：

• http://localhost:5173
  

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

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

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

原因通常有两个：

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

排查方式：

1. Test-NetConnection localhost -Port 2181

复制代码

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

1. ports:
2.   - "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 被占用

排查方式：

1. Test-NetConnection localhost -Port 12345

复制代码

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

1.docker-compose-windows

1. # Licensed to the Apache Software Foundation (ASF) under one
2. # or more contributor license agreements.  See the NOTICE file
3. # distributed with this work for additional information
4. # regarding copyright ownership.  The ASF licenses this file
5. # to you under the Apache License, Version 2.0 (the
6. # "License"); you may not use this file except in compliance
7. # with the License.  You may obtain a copy of the License at
8. #
9. #     http://www.apache.org/licenses/LICENSE-2.0
10. #
11. # Unless required by applicable law or agreed to in writing, software
12. # distributed under the License is distributed on an "AS IS" BASIS,
13. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14. # See the License for the specific language governing permissions and
15. # limitations under the License.
17. version: "3.8"
19. services:
20.   dolphinscheduler-postgresql:
21.     image: bitnami/postgresql:latest
22.     ports:
23.       - "5432:5432"
24.     environment:
25.       POSTGRESQL_USERNAME: root
26.       POSTGRESQL_PASSWORD: root
27.       POSTGRESQL_DATABASE: dolphinscheduler
28.     volumes:
29.       - dolphinscheduler-postgresql:/bitnami/postgresql
30.     healthcheck:
31.       test: ["CMD", "bash", "-c", "cat < /dev/null > /dev/tcp/127.0.0.1/5432"]
32.       interval: 5s
33.       timeout: 60s
34.       retries: 120
35.     networks:
36.       - dolphinscheduler
38.   dolphinscheduler-zookeeper:
39.     image: zookeeper:3.8
40.     ports:
41.       - "2181:2181"
42.     environment:
43.       ALLOW_ANONYMOUS_LOGIN: "yes"
44.       ZOO_4LW_COMMANDS_WHITELIST: srvr,ruok,wchs,cons
45.     volumes:
46.       - dolphinscheduler-zookeeper:/bitnami/zookeeper
47.     healthcheck:
48.       test: ["CMD", "bash", "-c", "cat < /dev/null > /dev/tcp/127.0.0.1/2181"]
49.       interval: 5s
50.       timeout: 60s
51.       retries: 120
52.     networks:
53.       - dolphinscheduler
55. networks:
56.   dolphinscheduler:
57.     driver: bridge
59. volumes:
60.   dolphinscheduler-postgresql:
61.   dolphinscheduler-zookeeper:

复制代码

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！