![](https://developer.qcloudimg.com/http-save/yehe-11849333/5fc2630a53fecd4c58f8dd3c2e227d38.jpg)

作者 | 智业软件 张晓宁

本文面向希望在本地阅读和调试 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` 目录。

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

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

然后启动 PostgreSQL 和 ZooKeeper：

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

可选验证命令：

```powershell
docker ps
Test-NetConnection 127.0.0.1 -Port 5432
Test-NetConnection localhost -Port 2181
```

预期结果：

- `5432` 连接成功
- `2181` 连接成功

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

## 2. 编译项目

在仓库根目录执行：

```powershell
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 中执行：

```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 验证：

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

```text
-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. 启动前端

在仓库根目录执行：

```powershell
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` 暴露到宿主机

排查方式：

```powershell
Test-NetConnection localhost -Port 2181
```

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

```yaml
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` 被占用

排查方式：

```powershell
Test-NetConnection localhost -Port 12345
```

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

## 9. 附录

1.docker-compose-windows

```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:
```



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

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

大数据

本文详细介绍在Windows环境下使用IntelliJ IDEA+Docker Desktop+PostgreSQL+ZooKeeper搭建DolphinScheduler本地开发环境的完整流程，包括环境准备、数据库初始化、服务配置和启动顺序等关键步骤，帮助开发者快速搭建可调试的分布式调度系统开发环境。

PostgreSQL

数据库

服务器

Windows

容器

Docker

Java

2026采购季 | AI焕新·智启新局

bigdata-class

postgres

tencentdb-catalog

4核4G3M云服务器 新用户低至38元/年！

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

小白版 | Apache DolphinScheduler 本地启动指南-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐