SpringBoot2.6.13+MySQL8+Flowable6.8.1工作流项目搭建与避坑指南

简介面向企业级Java开发者的工作流整合资源包基于Spring Boot 2.6.13、MySQL 8与Flowable 6.8.1构建内置MySQL 8安装程序解决开发环境搭建繁琐、流程引擎与业务系统集成困难等问题。资源共29个文件涵盖java源代码、xml流程定义与配置、yml配置文件、class编译产物、jar依赖以及msi数据库安装包压缩包约382.9MB目录结构清晰便于按模块定位和使用。已有108人学习下载。通过该包可省去单独安装配置MySQL的步骤直接获得可运行的开发框架借助Flowable对BPMN 2.0的支持可快速设计并执行审批、会签、请假等典型业务流程同时提供任务管理、表单管理和丰富API方便开发者根据业务需求扩展流程节点与事件监听。自带MySQL安装程序还有助于保持开发环境一致降低团队协作与演示部署的成本适合具备Spring Boot基础、希望提升工作流开发效率的中级及以上Java开发者。1. springboot2.6.13mysql8flowable6.8.1一套能直接照做的工作流落地组合做过审批系统的人都有同感真正拖慢进度的往往不是业务代码而是把工作流引擎、数据库和 Spring Boot 的版本关系理顺。springboot2.6.13mysql8flowable6.8.1 是一套被大量内部管理系统验证过的组合——Flowable 6.8.1 是 6.x 里与 Spring Boot 2.6 匹配最稳的版本MySQL 8 提供 utf8mb4 存储和多版本并发控制而标题里那句“自带 mysql8 安装程序”把环境准备从四处翻教程的半天压缩成解压、初始化、启动三步。这篇笔记想把四件事讲清楚这个版本组合为什么成立、最小工程怎么跑、数据库怎么一次配好、还有哪些坑要绕开。适合要给老系统加审批流、正在选工作流引擎、或者被自动建表折磨过的人。2. 版本基线为什么这么定Flowable 6.8.1 与 Spring Boot 2.6 的兼容边界2.1 Flowable 6.8.1 与 Spring Boot 2.6.13快速入门时最容易踩的版本坑Flowable 的版本号看着规整实际踩过的人都知道它和 Spring Boot 的搭配有严格区间。6.8.1 这个版本官方兼容 Spring Boot 2.6.x而 Spring Boot 2.6.13 又是 2.6 系列的最后一个补丁版本安全修复和依赖升级都收得比较完整所以很多企业内部系统把这一对当成默认基线。如果你非要在这个标题下换成 Spring Boot 3.x那就得把 Flowable 升到 7.x同时把 javax.* 命名空间整体改成 jakarta.*老代码里但凡出现 import javax.servlet 的地方全要动一次升级足够让一个中小型项目改上一周。所以日常做技术选型时我一般不会把“要新”放在第一位而是把“兼容关系已经有人验证过”放在第一位。Flowable 6.8.1 内部基于 MyBatis 3.5 做持久化事务完全交给 Spring 管理和 Spring Boot 2.6 的自动配置机制没有冲突它的流程引擎核心、任务服务、历史服务都打包在flowable-spring-boot-starter-process里这个 starter 是快速入门 Flowable 最省心的入口。你不需要把 flowable-ui、flowable-rest、flowable-cmmn 全部塞进来缺什么再补什么依赖少了翻车概率就低。这里有一个很容易让新手绕路的点Flowable 的 Maven 坐标里既有flowable-spring-boot-starter也有flowable-spring-boot-starter-process前者更像全家桶后者明确只包含流程引擎。用 6.8.1 做审批流process这一个就够后面要接 REST 接口再加flowable-spring-boot-starter-rest。版本号建议在 properties 里显式声明为 6.8.1不要省略否则依赖传递可能把某个子模块带到 6.7 或其他小版本最后出现“引擎起来了但表结构对不上”的怪问题。组件建议版本职责说明Spring Boot2.6.13应用框架对应 JDK 8 或 11Flowable6.8.1工作流引擎兼容 Spring Boot 2.6.xMySQL8.0.x存储层注意默认认证插件mysql-connector-java8.0.xJDBC 驱动由 Spring Boot BOM 管理2.2 MySQL 8 作为工作流存储层认证插件、字符集与大小写三道门槛MySQL 8 相对 5.7 带来的第一个变化是默认认证插件从 mysql_native_password 换成了 caching_sha2_password。这个改动的本意是提高安全性但对老驱动非常不友好。Flowable 6.8.1 连接 MySQL 8 时如果数据库账号还是默认认证方式连接串里又没配allowPublicKeyRetrievaltrue非 SSL 连接第一次握手就会直接失败错误信息藏在 Communications link failure 后面很容易让人误以为是网络问题。第二个变化是字符集语义。MySQL 8 里的 utf8 实际是 utf8mb3只能存基本的多语言字符存不了生僻字和 emoji。审批流里最常见的场景是审批意见栏有人粘贴一段带 emoji 的文字进来如果库表字符集不是 utf8mb4写入时就报错或者静默截断。Flowable 会自动建几十张 ACT_ 表这些表的字符集默认跟着库走所以建库那一步指定 utf8mb4 最省事而不是建完表再一张张去改。第三个变化是大小写敏感策略。Linux 上 MySQL 的lower_case_table_names默认是 0表名区分大小写Windows 上默认是 1不区分。Flowable 的建表脚本里表名都是 ACT_ 大写如果你的 MySQL 实例在初始化时把大小写参数改过就会出现一种很诡异的现场SHOW TABLES能看到 ACT_RU_TASK但引擎启动时通过元数据查询却判断“表不存在”然后尝试再建一次撞上 already exists。自带安装程序初始化的实例一般保持默认但交付到客户服务器时对方可能魔改过 my.cnf所以部署前先执行SHOW VARIABLES LIKE lower_case_table_names;确认一下。2.3 自带 MySQL 8 安装程序把环境准备从半天压缩到十分钟网上 mysql 安装教程一搜一大把但在真实的内网交付场景里最卡人的不是“不知道怎么装”而是“目标服务器不能上网、没有现成数据库、又不允许随便动系统环境”。标题里这个“自带 mysql8 安装程序”本质是把一个免安装的 MySQL 8 实例随项目一起分发解压后通过脚本初始化数据目录、创建默认账号、把业务库建好。它省掉的不只是下载安装的半小时还有为适配各种系统环境反复调参数的半天。不过要清醒自带安装程序解决的是“能不能跑起来”不是“跑得安不安全”。我拿到这类安装包后的第一件事是检查初始化脚本里有没有写死 root 密码、建了哪些默认用户、数据目录落在哪里。如果 root 是空密码或者脚本里明文密码交付前必须改掉再单独创建业务账号不能拿 root 去连应用。还有一点容易被忽略安装程序里的 MySQL 版本不一定和 Flowable 官方 CI 测过的最新补丁一致但大版本是 8.0 就行驱动和认证插件兼容性不会有结构性问题。另一个实际经验是装好之后先不要急着启动 Spring Boot 工程先在命令行用mysql -h127.0.0.1 -P3306 -uflowable -p连通一次确认 TCP 端口可用。很多后来查了半天的问题其实在第一步就能暴露。3. 从零跑通最小工程Spring Boot 配置、依赖与第一个流程定义3.1 pom.xml 里的三个关键坐标新建一个空工程pom.xml 里最核心的部分就是这三个坐标。parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.6.13/version relativePath/ /parent properties java.version1.8/java.version flowable.version6.8.1/flowable.version /properties dependencies dependency groupIdorg.flowable/groupId artifactIdflowable-spring-boot-starter-process/artifactId version${flowable.version}/version /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId scoperuntime/scope /dependency /dependencies第一处不能写错的是flowable.version。这个值直接决定引擎内部各模块版本一致我见过有人只把 starter 的版本写成 6.8.1但 transitively 引入的 flowable-engine 是 6.7跑起来后某些新 API 直接 NoSuchMethodError。第二处是 mysql-connector-java 不要手动加 versionSpring Boot 2.6.13 的依赖管理已经把它固定在 8.0.x你手写一个 5.1.49 进去caching_sha2_password 认证就一定连不上。第三处是 JDK 版本用 1.8 最稳JDK 11 也可以JDK 17 虽然能启动但 Flowable 6.8.1 有反射代码需要额外加 JVM 参数没必要在入门阶段增加变量。3.2 application.yml数据源与 Flowable 参数逐项拆解依赖引进来之后配置是成败关键。我给出的最小配置如下spring: datasource: url: jdbc:mysql://localhost:3306/flowable?useSSLfalseserverTimezoneAsia/ShanghaicharacterEncodingutf8nullCatalogMeansCurrenttrueallowPublicKeyRetrievaltrueconnectTimeout5000socketTimeout60000 username: flowable password: flowable123 driver-class-name: com.mysql.cj.jdbc.Driver hikari: maximum-pool-size: 20 minimum-idle: 5 connection-timeout: 30000 flowable: database-schema-update: true db-history-used: true async-executor-activate: true process-definition-location-prefix: classpath*:/processes/连接串里的参数一个都不能删。useSSLfalse表示内网开发不启用 SSL如果生产要求加密传输再改成 true 并配证书serverTimezoneAsia/Shanghai是解决时区报错的关键MySQL 8 的驱动拿不到显式时区时常把本地时区错报成乱码characterEncodingutf8要和建库时的 utf8mb4 对应建议直接写 utf8驱动会自动映射到 utf8mb4nullCatalogMeansCurrenttrue是给 Flowable 的建表检测逻辑用的没有这个参数JDBC 元数据查询会扫描所有库把别的库里同名表误判成当前库的表导致建表跳过allowPublicKeyRetrievaltrue解决 caching_sha2_password 的首次连接问题这个参数在 MySQL 5.7 时代不存在所以很多老教程根本不会提。Flowable 自己的配置里database-schema-update: true让引擎启动时自动建表这是第一遍跑通时最需要的“后悔药”db-history-used: true开启历史表否则流程走完只能看到运行时数据查不到历史轨迹async-executor-activate: true启动异步执行器处理定时器、异步延续这些场景最小请假流程用不上但一旦流程里加了边界事件而没开它流程就会卡住不动process-definition-location-prefix指向 classpath 下的流程文件目录这是 Flowable 约定大于配置的核心机制。3.3 启动类与请假流程用最小模型验证引擎真的在跑package com.example.flowable; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class FlowableApplication { public static void main(String[] args) { SpringApplication.run(FlowableApplication.class, args); } }启动类不需要任何额外注解Flowable 的 starter 会在 Spring 容器刷新后自动扫描并部署流程定义。接着在src/main/resources/processes/leave.bpmn20.xml放一个最简单的流程?xml version1.0 encodingUTF-8? definitions xmlnshttp://www.omg.org/spec/BPMN/20100524/MODEL xmlns:flowablehttp://flowable.org/bpmn targetNamespacehttp://flowable.org/bpmn process idleaveProcess name请假审批 isExecutabletrue startEvent idstartEvent/ userTask idapproveTask name部门经理审批 flowable:assignee${approver}/ endEvent idendEvent/ sequenceFlow idflow1 sourceRefstartEvent targetRefapproveTask/ sequenceFlow idflow2 sourceRefapproveTask targetRefendEvent/ /process /definitions这个文件有三个关键点。process标签的id是流程定义键发起流程时用leaveProcess这个字符串来指定流程isExecutabletrue表示这是一个可执行流程如果漏掉Flowable 会把它当成描述性流程直接忽略部署成功却永远无法发起flowable:assignee${approver}指定任务处理人发起流程时传入变量approver审批任务就会挂在这个人名下。启动工程后第一次跑会输出大量建表日志几十张 ACT_ 表建完需要十几秒这个过程中千万不要因为日志里出现 Exception 字样就以为失败要看最后有没有ProcessEngine created和流程定义部署成功的关键行。看到这两行第一个闭环就通了。4. MySQL 8 安装程序与数据库准备初始化、建库和连接串细节点4.1 解压初始化与启动附带安装程序的隐藏前提自带安装程序解压后目录结构一般是 data、bin、share、lib 这几个。data 是数据目录bin 里放 mysqld 和 mysql 客户端。第一次启动必须先初始化数据目录命令如下。cd /path/to/mysql mkdir -p data bin/mysqld --initialize-insecure --basedir/path/to/mysql --datadir/path/to/mysql/data bin/mysqld --console --basedir/path/to/mysql --datadir/path/to/mysql/data --port3306--initialize-insecure表示初始化一个 root 空密码账号对本地交付环境最省事。很多安装程序自带封装好的启动脚本但你要清楚它在跑什么才能在报错时定位。--console让日志打到前台开发机上直接能看到启动报错生产环境建议注册成系统服务Windows 上是bin/mysqld --install MySQL8然后net start MySQL8Linux 上如果安装程序自带mysql.server脚本就把它放到 /etc/init.d/ 并配好路径再启动。网上大多数“linux 安装 mysql”的教程会教你编源码或配 yum 源自带安装程序的价值就是跳过这些步骤但服务注册和开机自启还是要自己处理。这里要区分一个经典误解很多人启动后直接用mysql -uroot -p连本地报ERROR 2002 (HY000): Cant connect to local MySQL server through socket /tmp/mysql.sock第一反应是驱动配置错了。这个报错其实发生在 MySQL 本地客户端和 mysqld 之间的 socket 连接上和 JDBC 走 TCP 3306 端口是两条路径。看到 2002 时先确认 mysqld 进程是否真的起来再检查 socket 文件路径而 Spring Boot 连不上时通常报的是 Communications link failure日志里能看出连接的是 3306 端口方向别搞混。4.2 建库与字符集给 Flowable 一个不会返工的地基MySQL 起来后先不要急着把 Spring Boot 工程指向它。我一般先用 mysql 客户端执行这一段 SQL把专用库、专用账号一次性建好CREATE DATABASE IF NOT EXISTS flowable DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER IF NOT EXISTS flowable% IDENTIFIED BY flowable123; ALTER USER flowable% IDENTIFIED BY flowable123; GRANT ALL PRIVILEGES ON flowable.* TO flowable%; FLUSH PRIVILEGES;为什么用 utf8mb4 而不是 utf8MySQL 8 里的 utf8 实际是 utf8mb3存不下生僻字和 emoji审批意见里出现一个表情符号就可能导致整条写入失败。utf8mb4_general_ci是通用排序规则审批流这种场景够用如果对排序严谨性有更高要求可以换utf8mb4_0900_ai_ci但要注意非常老的驱动版本不识别 0900 系列 collation会报 unknown collation。字符集的坑还会延续到表上。Flowable 建表时默认继承库的字符集所以建库这步指定好后面就不用一张张改表。我见过有人建库时漏了字符集等流程变量写入中文才发现想 ALTER DATABASE 补救结果已存在的表还是旧字符集最后只能 DROP 库重建。测试环境可以这样干有真实流程数据时就会很痛苦。4.3 JDBC 连接串与连接池参数useSSL、超时和连接数回到 Spring Boot 配置连接串我建议把参数写全哪怕现在用不上也不要让驱动去猜spring: datasource: url: jdbc:mysql://localhost:3306/flowable?useSSLfalseserverTimezoneAsia/ShanghaicharacterEncodingutf8nullCatalogMeansCurrenttrueallowPublicKeyRetrievaltrueconnectTimeout5000socketTimeout60000connectTimeout5000是建立 TCP 连接的超时。目标库没启动时默认行为会卡在 30 秒左右才抛异常设短一点能快速暴露网络问题socketTimeout60000是执行 SQL 的读超时Flowable 有部分历史查询会扫表设太小容易误报超时60 秒是个稳妥的起点。连接池参数值得单独调。Hikari 的maximum-pool-size至少要 20因为 Flowable 的异步执行器默认有多个线程每个线程执行 job 时都要拿一个数据库连接。如果连接池最大连接数比“业务连接 异步执行器线程数”还小就会出现连接等待超时表现就是流程卡住、任务不继续走。minimum-idle保持 5 就行避免空闲时也占着一大堆连接connection-timeout30000默认 30 秒一般不需要动。参数useSSL还有一个连带问题如果 MySQL 服务端把require_secure_transport打开了即使连接串写 useSSLfalse 也会报错因为服务端强制要求加密连接。这时要么修改 my.cnf 关闭该参数要么把 useSSL 改 true 并配证书。最简单的判断方法是用 MySQL 命令行客户端能连上而 JDBC 报 SSL 相关错误基本就是这种服务端强制要求的场景。5. 避坑现场Flowable 6.8.1 与 MySQL 8 集成最常见的 5 个翻车点5.1 建表已存在database-schema-update 不是后悔药现象启动到一半日志抛Table ACT_RE_DEPLOYMENT already exists或者干脆是一串外键约束错误。原因这个 flowable 库之前被别的 Flowable 版本建过表。6.x 内部各小版本之间表结构有增量变化旧表和新版建表语句对不上database-schema-update: true执行建表 SQL 时自然撞表。解决测试环境直接 drop 掉 flowable 库重建让引擎重新走一遍建表如果是已有流程数据的升级先把库备份好再按官方升级脚本一站一站执行不要指望自动建表能帮你改表结构。我吃过一次亏以为自动建表能自动迁移结果启动成功但流程数据查询全乱最后靠备份才恢复。注意database-schema-update: true只在开发环境好用。涉及生产或已有数据时改成 false手动执行 SQL 脚本。5.2 认证插件不兼容caching_sha2_password 与驱动版本现象应用启动后第一次连库报Communications link failure堆栈里有caching_sha2_password字样但在命令行用同一个账号却能连上。原因MySQL 8 默认认证插件是 caching_sha2_password老驱动不认识或者新驱动在非 SSL 连接下拿不到服务端公钥完成首次认证。解决连接串补上allowPublicKeyRetrievaltrue确认驱动是 8.0.x。如果系统里确实有改不掉的老驱动也可以把账号改成 mysql_native_passwordALTER USER flowable% IDENTIFIED WITH mysql_native_password BY flowable123;但这不是长久之计MySQL 8.4 已经默认移除 mysql_native_password新项目直接用兼容驱动加公钥参数不要在认证插件上走回头路。5.3 时区与乱码serverTimezone 和 characterEncoding 缺一不可现象启动时异常信息里出现The server time zone value CST is unrecognized or represents more than one time zone或者中文写入后变成问号。原因MySQL 服务端和 JDBC 驱动所在机器时区不一致驱动又拿不到明确值字符集问题则是连接串没配 characterEncoding或库表字符集不是 utf8mb4。解决连接串写死serverTimezoneAsia/Shanghai和characterEncodingutf8不要依赖系统默认。同时 MySQL 侧执行SELECT NOW();看返回时间是否相差 8 小时如果差在 my.cnf 里加default-time-zone08:00再重启。中文乱码则回到建库字符集检查把 flowable 库和已建表都确认成 utf8mb4。5.4 流程发起成功任务却查不到CommandExecutor 与 assignee 的坑现象runtimeService.startProcessInstanceByKey(leaveProcess)返回了流程实例 ID但taskService.createTaskQuery().list()是空列表。原因大概率有两个。第一个是 BPMN 里的用户任务没有flowable:assignee任务创建了但没有处理人按 assignee 查询自然查不到第二个是流程里有异步延续节点而spring.flowable.async-executor-activate没有开启流程实例停在半路任务根本没有创建出来。解决先确认每个 userTask 都配了 assignee 或 candidateGroups再看historyService.createHistoricProcessInstanceQuery()查到的实例停留在哪个节点。Flowable 的执行体系里有一个 CommandExecutor所有 API 调用都被包装成命令交给它执行如果怀疑异步命令卡住可以把 org.flowable 包的日志级别调到 DEBUGlogging: level: org.flowable: DEBUG看到Execute command ... ContinueProcessJobCmd这类日志说明异步执行器在正常跑如果连这类日志都没有就去查异步线程池配置。5.5 连接池耗尽与集成 UI异步执行器线程和连接数互相掐架现象运行一段时间后日志出现HikariPool-1 - Connection is not available, request timed out after 30000ms或者流程实例越积越多全部卡在等待状态。原因Flowable 异步执行器默认多个线程同时执行 job每个 job 持有一个数据库连接业务线程也要从同一个 Hikari 池拿连接两边一起抢连接池就空了。解决把 Hikari 的maximum-pool-size调到 20 以上并用SHOW PROCESSLIST;检查有没有大量 Sleep 连接积压。与此同时Flowable 异步线程池有自己的参数spring.flowable.async-executor-core-pool-size默认是 4并发流程多时要把核心线程数和 Hikari 连接数放在一起评估别一个调到很大另一个原地不动。另外如果想把流程设计器这类 UI 集成进来常见做法是单独部署 Flowable UI 前端不要和后端业务塞进同一个 Spring Boot 工程前端调用/process-api时跨域是绕不开的后端要显式配 CORS否则保存模型、部署流程这些操作都会在浏览器里失败。6. 验证与进阶用 REST API 和流程外置把引擎真正用起来6.1 最小 REST 验证部署、发起、查任务的一串 curl在已有flowable-spring-boot-starter-process的基础上再加flowable-spring-boot-starter-rest然后在配置里声明认证方式spring: flowable: rest: app: authentication: enabled: trueFlowable 6.8.1 的 REST 接口根路径是/process-api。部署流程定义和发起流程实例用两个 curl 就能验证curl -u admin:admin123 -F fileleave.bpmn20.xml \ http://localhost:8080/process-api/repository/deployments curl -u admin:admin123 -H Content-Type: application/json \ -d {processDefinitionKey:leaveProcess,variables:[{name:approver,value:manager}]} \ http://localhost:8080/process-api/runtime/process-instances第一条命令把流程定义部署到引擎返回值里有 deploymentId第二条根据流程定义 key 发起实例并把变量approvermanager传给任务。走通这两条说明引擎的部署与运行时链路都没问题。提示/process-api暴露了流程定义、实例、任务、历史全量接口只建议在内网开放不要直接放到公网网关后面。6.2 流程文件外置与三张状态表部署后先看这里流程定义文件放在src/main/resources/processes/下Flowable 启动时会自动部署这是它约定好的行为。好处是流程改动不需要改 Java 代码替换文件后重启就生效。要验证整个链路除了看日志我更习惯直接查这三张表SELECT * FROM ACT_RE_DEPLOYMENT; SELECT * FROM ACT_RE_PROCDEF; SELECT * FROM ACT_RU_TASK;ACT_RE_DEPLOYMENT有记录说明部署成功ACT_RE_PROCDEF看流程定义是否处于激活状态ACT_RU_TASK有记录说明流程实例正停在用户任务上。调用taskService.complete(taskId)后任务消失历史数据进入ACT_HI_TASKINST。我现在的习惯是把这三条查询固化成一个 status.sql每次部署完先跑一遍确认状态再交给测试。早期有一次 BPMN 文件部署失败就是靠这三张表定位到的比翻日志快得多。希望这条排查路径能帮到你也祝你在 springboot2.6.13mysql8flowable6.8.1 这条路上少花冤枉时间。本文还有配套的精品资源点击获取