小白版 | 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 目录。

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 ps
Test-NetConnection 127.0.0.1 -Port 5432
Test-NetConnection localhost -Port 2181

预期结果：

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

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

2. 编译项目

在仓库根目录执行：

cd 某盘:\dolphinscheduler
.\mvnw.cmd spotless:apply
.\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 中执行：

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。

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，请使用：

-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

启动顺序建议如下：

1. MasterServer
2. WorkerServer
3. ApiApplicationServer

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

6. 启动前端

在仓库根目录执行：

cd 某盘:\dolphinscheduler\dolphinscheduler-ui
pnpm install
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 暴露到宿主机

排查方式：

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。

9. 附录

1.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:
      - dolphinscheduler

networks:
  dolphinscheduler:
    driver: bridge

volumes:
  dolphinscheduler-postgresql:
  dolphinscheduler-zookeeper: