DolphinScheduler单机部署实战：从环境配置到跑通首个工作流

说到DolphinScheduler海豚调度器，你大概率已经对它的分布式工作流调度能力有耳闻。不过真正把它跑起来体验一把的人，往往会被集群部署的复杂配置劝退。其实海豚调度器单机部署并不难，一台虚拟机甚至一台本地电脑就能把Master、Worker、API、UI全部装起来，日常测试学习、小规模任务调度完全够用。这篇内容就围绕DolphinScheduler单机部署完整展开，从环境准备、配置修改、启动验证，到跑出第一个工作流，以及我踩过的那些坑，一次性讲清楚。适合刚接触海豚调度器的数据开发、运维同学，也适合想在公司内部先做技术预研的团队参考。

1. 部署前的整体规划与版本选择

1.1 单机部署到底要装哪些组件

海豚调度器分布式部署时，一般会拆成多个角色服务：MasterServer负责任务的分发、容错和调度；WorkerServer负责实际执行工作流里的任务节点；ApiServer提供REST API接口，Web页面和命令行工具都要通过它来操作；LoggerServer用于采集任务执行的日志；AlertServer负责报警通知；最后还有一个前端UI控制台。

很多人误以为单机部署就是把一个jar包扔上去跑起来，实际情况是这些角色全部运行在同一台机器的不同JVM进程里。它们之间通过注册中心和数据库通信，对外体现为一个大一统的调度平台。因为都在一台机器，进程间网络延迟极低，部署复杂度也大幅下降。但这不意味着你可以随意一台机器就跑，核心瓶颈在内存和磁盘IO，多个JVM同时启动，内存占用很容易超过8G。

单机部署解决的核心问题，一句话总结就是：用最低成本先把这个调度系统用起来。它既可以作为学习源码、验证业务逻辑的实验场，也可以承担每天几千个任务的小规模生产调度。如果你的任务量已经到上万级，那还是老老实实走分布式多机部署。

1.2 版本选型与部署方式确认

DolphinScheduler的版本迭代很快，3.x系列是目前的主流，功能性、稳定性和社区活跃度都比较可靠。部署方式上，官方提供了两种路径：一种是standalone模式，下载一个独立精简包，启动一个进程即可体验，适合快速演示但不适合生产；另一种就是本文要讲的伪集群模式，也就是把完整版的二进制包解压后，通过安装脚本把所有角色进程拉起，更接近生产架构，后续若要平滑扩展到多机，只需要调整配置和增加节点即可。

版本选择上，我的建议是选3.1.x或3.2.x的稳定发行版，别追最新，毕竟是基础调度平台，稳比新重要。还要留意和JDK的兼容性，3.2系列一般要求JDK8或者JDK11，我实际使用中JDK8最省心，JDK11偶尔会遇到JVM参数不识别的问题。如果你已经知道自己的业务场景要用到大数据组件，比如Spark或Flink任务，那在下包之前最好确认安装包里的配套组件版本。

选好版本后，把安装包下载到服务器，同时准备好下面几类基础环境：JDK、MySQL、ZooKeeper。很多教程会把ZooKeeper单独列出来，其实在3.x之后的版本中注册中心还支持其它实现，但默认最稳妥的组合仍然是MySQL加ZooKeeper。

2. 环境准备与前置条件

2.1 JDK与数据库的选择

JDK没必要追求高版本，OpenJDK8即可。直接通过包管理器安装，或者手动解压到/usr/local/java然后配置环境变量。安装完记得确认一下：

java -version

如果输出类似openjdk version "1.8.0_xxx"，说明OK。海豚调度器的启动脚本会读取JAVA_HOME，如果这个环境变量没配好，后面启动时日志里会直接报找不到Java，非常劝退。所以先把JAVA_HOME写进/etc/profile里，顺手在dolphinscheduler_env.sh里也显式指定一遍，双保险。

再说数据库。海豚调度器所有的工作流定义、任务实例、调度时间、用户权限都存在元数据库里。生产上常用MySQL，这里也推荐MySQL 8.0。单机部署不需要太复杂的参数，但建议字符集用 utf8mb4，排序规则用 utf8mb4_bin，避免任务名里有中文表情出现乱码。

创建一个专门的数据库和用户，SQL大致如下：

CREATE DATABASE dolphinscheduler DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin; CREATE USER 'dolphinscheduler'@'%' IDENTIFIED BY 'Dolphin@123'; GRANT ALL PRIVILEGES ON dolphinscheduler.* TO 'dolphinscheduler'@'%'; FLUSH PRIVILEGES;

千万别用root连接数据库去跑调试，后面换生产库的时候很容易因为权限边界不清楚出问题。

2.2 创建部署用户与目录规划

海豚调度器Worker在执行任务的时候，会以租户对应的系统用户身份去运行Shell、SQL或其他类型的任务。单机部署时最好新建一个操作系统用户，例如dolphinscheduler，直接用这个用户来负责启动服务。

创建用户的命令：

useradd dolphinscheduler passwd dolphinscheduler

之后将安装包放到一个固定目录，我习惯用/opt/dolphinscheduler，然后创建数据目录和日志目录：

mkdir -p /data/dolphinscheduler/{logs,tmp} chown -R dolphinscheduler:dolphinscheduler /opt/dolphinscheduler /data/dolphinscheduler

为什么要单独分数据目录？因为海豚调度器运行过程中会产生大量任务日志和临时文件，如果和安装目录混在一起，升级或重装时很容易残留垃圾文件。把数据目录独立出去，后续清理和备份都方便。

2.3 初始化数据库表结构

环境准备最后一步，是执行数据库初始化脚本。海豚调度器安装包里的sql目录下存放着对应版本的建表SQL，例如dolphinscheduler_mysql.sql。在解压安装包之后，用MySQL客户端执行：

mysql -h127.0.0.1 -P3306 -udolphinscheduler -pDolphin@123 dolphinscheduler < sql/dolphinscheduler_mysql.sql

执行完后，可以用show tables;检查，会看到不少t_ds_开头的表，比如t_ds_user、t_ds_project、t_ds_process_definition等。表结构顺利生成，说明数据库连接和脚本都没问题。

老版本里启动脚本会自带自动建库步骤，但新版本更推荐手动初始化，因为能提前发现权限或字符集问题，免得启动到一半才报错。

3. 安装包准备与配置修改

3.1 下载与解压

从Apache官方下载对应的二进制tar包，例如apache-dolphinscheduler-3.x.x-bin.tar.gz。建议同时下载后缀为.sha512的校验文件，执行：

shasum -a 512 apache-dolphinscheduler-3.x.x-bin.tar.gz

对比校验结果，确认下载无损坏。这一步被很多人忽略，但一旦包损坏，部署过程会出现各种诡异问题，还很难排查。

解压到指定目录：

tar -zxvf apache-dolphinscheduler-3.x.x-bin.tar.gz -C /opt/dolphinscheduler

解压完成后的目录里，你需要关注几个地方：bin目录放启动和安装脚本；conf目录放所有配置文件；sql目录放数据库初始化脚本；logs目录在首次启动后生成。

3.2 修改数据库与注册中心配置

安装包解压之后，核心配置集中在conf/dolphinscheduler_env.sh和conf/application.yaml里。dolphinscheduler_env.sh 主要定义环境级参数，比如JAVA_HOME、数据库连接地址、注册中心地址等。我在3.2.x版本中的实际配置大致如下：

export JAVA_HOME=/usr/local/java export PATH=$JAVA_HOME/bin:$PATH export SPRING_DATASOURCE_URL="jdbc:mysql://127.0.0.1:3306/dolphinscheduler?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai&useSSL=false" export SPRING_DATASOURCE_USERNAME="dolphinscheduler" export SPRING_DATASOURCE_PASSWORD="Dolphin@123" export REGISTRY_TYPE="zookeeper" export REGISTRY_ZOOKEEPER_CONNECT_STRING="127.0.0.1:2181"

如果你是第一次部署，最容易犯的错误是用root机器直接跑，然后发现脚本读取不到环境变量。建议把上面这些变量同时写入/etc/profile.d/dolphinscheduler_env.sh，并确保当前用户能读取。

接着是application.yaml，里面管理着各服务的端口、数据库连接池参数、日志等级等。单机部署不需要大改，但要注意api-server和master-server的端口不要和其他服务冲突。默认情况下，API服务端口是12345，Master通信端口和Worker通信端口都是固定值，如果服务器上已经占用了相关端口，需要提前调整。

3.3 配置环境变量与执行安装脚本

配置修改完成后，需要执行一次安装脚本，它会做环境检查、创建目录、自动同步配置到各个子模块。命令如下：

bash bin/install.sh --init

--init参数表示同时初始化数据库和基础元数据，比如内置管理员账号。如果之前已经手动初始化过数据库，可以不传这个参数。安装脚本执行过程中，会打印很多日志，看到类似install success或者create xxxx success的提示就说明这一步完成了。

安装完成之后，可以顺手执行一下环境变量刷新：

source /etc/profile

然后验证进程环境：

env | grep JAVA_HOME

确保配置已经生效再启动。

4. 启动集群与验证

4.1 一键启动所有服务

海豚调度器单机部署最爽的地方在于启动非常统一，全部服务由同一个脚本拉起：

bash bin/start-all.sh

执行完以后，稍等几十秒，然后用jps查看Java进程：

jps

正常情况下可以看到这些进程：MasterServer、WorkerServer、ApiServer、LoggerServer、AlertServer。如果你的安装包版本把UI一起集成了，还会有一个UI相关进程。看到这些进程都活着，说明核心服务已经启动。

之后建议访问一下API服务的健康检查接口：

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

返回状态为UP就说明服务正常。注意端口号可能因版本不同略有差异，具体以安装目录里application.yaml配置为准。

4.2 日志排查与进程状态确认

即使进程活着，也不代表服务完全健康，还需要看日志。日志目录默认在安装包下的logs，每个服务都有一个独立文件，比如master-server.log、api-server.log。我习惯用下面这条命令同时监控所有日志文件：

tail -f logs/*server.log

启动初期最关注的几个点：数据库连接是否成功、ZooKeeper会话是否建立、各服务是否成功注册到注册中心。如果看到Registry connection success或类似关键词，说明注册正常。如果日志里疯狂刷Connection refused，优先检查数据库账号权限和ZooKeeper地址。

还有一种情况是进程起来了，但API请求5秒超时。这多半是内存预算不够，多个JVM同时Full GC，导致API无法及时响应。单机部署时最好给机器至少8G内存，低于这个数建议你把JVM堆参数调小，下面第6节会给出具体建议。

4.3 登录Web控制台

服务全部启动后，打开浏览器访问：

http://你的服务器IP:12345/dolphinscheduler/ui

默认登录账号是admin，密码是admin123。不同版本的初始密码可能不同，安装脚本最后的日志里一般会有提示。如果你下载的是不含UI的精简包，则需要单独部署前端页面，通常做法是用Nginx托管UI静态文件，并把API请求代理到12345端口。

我第一次登录时遇到页面样式加载不出来的问题，排查后发现是Nginx把静态资源的路径搞错了。这里给你一个避坑提示：如果页面空白或者控制台一堆404，优先检查UI静态文件对应的请求路径是否带项目前缀dolphinscheduler/ui，不要急着怀疑后端服务。

登录成功后，你会看到项目管理、工作流定义、任务实例等菜单，说明系统已经就绪。

5. 第一个工作流实战

5.1 创建租户与用户

使用海豚调度器之前，要先理解一个概念：租户。海豚调度器在Worker上执行任务时，会以租户关联的Linux用户身份去跑。这是很多新手忽略的点，如果你不创建租户，或者租户下没有对应的Linux用户，任务执行时会直接报权限错误。

在“安全中心”->“租户管理”中，添加一个租户，租户名称建议直接使用刚才创建的系统用户名dolphinscheduler。然后创建用户，分配租户给这个用户，比如admin用户可以关联到这个租户。这样后续所有工作流都以该租户身份运行。

单机环境里，这个映射关系非常直观：Worker进程是dolphinscheduler用户拉起的，租户也是dolphinscheduler，任务执行时的文件权限就不会出现不可控的情况。

5.2 创建工作流与调度配置

进入“项目管理”，创建一个项目，比如叫模拟项目X。项目创建后进入“工作流定义”，点击“创建工作流”，你会看到可视化拖拽画布。从左侧拖一个Shell节点到画布上。

这里以最简单的Shell任务为例，节点内容填：

echo "hello dolphinscheduler"

点击任务节点右侧的“任务参数”，可以设置运行参数、资源、是否超时报警等。保存之后，还需要设置工作流的调度时间。如果你只想手动执行，可以不配置定时调度；如果想测试调度能力，设置一个每隔5分钟执行一次的Cron表达式：

*/5 * * * * ?

保存工作流后，别忘了点击“上线”，只有上线状态的工作流才会被调度器按计划触发。这是实际操作中特别容易踩的点，很多人配置完定时调度但忘了点上线，任务一直不执行。

5.3 查看运行结果和日志

上线后，手工点击“运行一次”，然后到“工作流实例”页面观察。实例状态会从“等待执行”变为“运行中”，Shell任务很快会跑完进入“成功”状态。

点击实例名称可以查看任务节点，再点击任务节点右侧的“查看日志”，能看到任务的实际输出。这里的日志是LoggerServer采集回来的，和你直接在服务器命令行执行脚本后看到的输出一致。如果脚本里有print或echo，都可以在这里查到。

我第一次跑通的时候还是有点小激动，因为从零开始搭一个调度系统到落地执行，中间每一个环节都是环环相扣的。这个简单的工作流验证的是“链路通畅”，后面再逐步加上依赖、条件分支、子流程、告警通知，都是一个套路。

6. 常见问题排查与调优建议

6.1 常见问题速查

列这个表格是想帮你快速定位问题。实际部署中最常见的其实不是某一个服务挂掉，而是系统层面存在隐性缺口，比如数据库账号权限没问题但连接串里字符集参数写错，导致中文字符乱码，任务定义明明存在却查询不到。

6.2 单机资源限制与JVM调优

单机部署所有角色挤在一台机器，内存是要重点盯的。海豚调度器启动时会为每个服务设置默认JVM参数，默认堆可能比较大，比如Master和Worker都给了1G以上。如果机器只有8G内存，建议调低一点。

以dolphinscheduler_env.sh为例，可以通过环境变量覆盖默认JVM参数，思路如下：

export MASTER_JVM_OPTS="-Xms512m -Xmx512m -XX:MaxMetaspaceSize=256m" export WORKER_JVM_OPTS="-Xms512m -Xmx512m -XX:MaxMetaspaceSize=256m" export API_JVM_OPTS="-Xms512m -Xmx512m -XX:MaxMetaspaceSize=256m"

配置后重启所有服务，再用jstat -gcutil观察GC情况。如果Full GC频繁，就把对应服务的堆再往上加，但前提是机器物理内存足够。调优不是固定套路，而是根据实际任务量反复磨合。

之后如果任务量上来了，单机扛不住，也不用推翻重来。海豚调度器设计上支持水平扩展，只需要把新机器安装包解压、配置同一个数据库和同一个ZooKeeper，然后单独启动Worker或Master，就能把负载分布出去。单机部署和后期的多机扩展并不冲突，这也是我始终推荐用伪集群模式而不是standalone模式的原因。

6.3 部署过程中的几个实用经验

最后分享几个我实际用下来很受益的小经验。

第一，保存好一份完全可复现的部署文档。不要只在服务器上装完就不管，修改过的环境变量、数据库连接串、目录结构，都要记下来。这东西一旦要迁移或升级，能帮你省掉大半天时间。

第二，定期备份元数据库。工作流定义和实例数据都在MySQL里，每天备份一次dolphinscheduler库，数据量不大但价值很高。调度平台挂了可以重新部署，元数据丢了就得重新画工作流，那个代价你肯定不想承受。

第三，新手刚上手时不要一上来就开发复杂的依赖工作流。先用一个Shell任务跑通完整链路，再加一个SQL查询，然后再尝试跨任务传参。循序渐进能让你把每个核心概念都吃透，后面遇到报错不会慌。

单机部署虽然规模小，但它覆盖了海豚调度器几乎所有的核心机制：服务之间如何注册发现、任务如何被调度、租户权限如何映射、元数据如何持久化。把这一套跑熟后，你对架构的理解会实打实地提升一个台阶。