Activiti 5.22完整包部署指南：用explorer.war快速跑通流程引擎

简介：Activiti 5.22 Explorer WAR 完整部署包面向 Java 开发者与工作流平台建设者，可用于在 Tomcat 等 Servlet 容器中快速运行 Activiti 引擎的可视化管理界面，直接体验流程设计、任务审批与实例监控等核心功能。压缩包共 79 个文件，其中 48 个 jar 覆盖 Activiti 引擎、Spring 4.1.5、MyBatis 3.3.0 等关键依赖，10 个 xml 包含 web.xml 部署描述符及多个 BPMN 2.0 流程示例，另有 properties 配置、class 类文件及若干流程图素材，整体大小约 88.33MB。已有 1190 人学习/下载。资源包内部按 META-INF 与 WEB-INF 标准目录组织，lib 子目录依赖齐全，可直接将 WAR 包交给容器部署；内置的 Helpdesk、VacationRequest、FixSystemFailureProcess 等示例流程配合图形文件，适合初学者对照理解 BPMN 建模、流程引擎配置与 REST 集成。虽为 5.22 早期版本，但结构完整、自包含强，是学习 Activiti 原理及搭建轻量级业务流程管理系统的实用素材。

1. Activiti 5.22完整包：一次部署就能驱动的流程引擎

如果你刚接触工作流开发，或者接下来要在老项目里集成一个工作流引擎，最直接的上手方式不是从零搭一套环境和代码，而是先拿一份现成的、自带动界面的完整发布包。Activiti 5.22完整包里带了activiti-explorer.war，把它丢进Tomcat的webapps目录，启动完成后打开浏览器就能看到流程设计器、流程管理、任务管理、历史记录，几分钟就能把一个BPMN流程从设计跑到结束。这个场景对三类人最有用：刚入门工作流的新手、准备做二次集成的工程师、需要快速验证流程定义是否合法的项目成员。理解这份资源的关键在于先搞清楚引擎启动的前提条件，以及官方自带web应用与你将来自己嵌入引擎到底差在哪。

2. 为什么是5.22：版本定位、完整包构成与war包的存在意义

2.1 Activiti 5.22在版本演进里的位置

Activiti 5.x是工作流引擎进入BPMN 2.0成熟期后被广泛使用的稳定系列，5.22是这个系列后期的一个重要发布版本，API风格和模块结构都已经相当稳定。现在网上能搜到的大量教程、网文、视频课都基于5.x写法，遇到报错时搜索到的解决方案也更容易命中老版本场景。

5.x的引擎入口是ProcessEngine，通过RepositoryService管理流程定义，RuntimeService启动流程实例，TaskService处理待办任务，HistoryService查询历史记录。这套API在6.x和7.x里虽然核心概念没大变，但包结构、依赖管理方式、Spring Boot整合风格都有明显差异。对于接手老项目或者先学原理的人来说，5.22保留了一整套可以直接观察引擎行为的web界面，比纯代码推演直观得多。

我遇到过不止一个同事，在6.x里折腾了一周没搞懂流程实例和任务节点的关系，回头把5.22的explorer跑起来，点几个流程走一遍，立刻就明白引擎在背后做了什么。版本老不意味着过时，它意味着资料密集、坑位明确、行为可预期。

2.2 完整包里有哪些东西，各自负责什么

这份完整包不是只有一个war文件，它更像一个发布集合。常见构成如下表，不同渠道打包时会有细微差异，但核心部件基本一致。

把activiti-explorer.war解压开，能看到WEB-INF/lib下有一整套引擎jar，activiti-engine负责核心调度，activiti-spring负责与Spring容器整合。这个war包本身就是一个标准的、可运行的完整应用，它的存在意义在于：你不用先理解Maven依赖树和Spring配置，就能看到一个真实引擎的完整运行链路。

2.3 为什么需要一个可直接部署的war包

生产环境里大家通常是把引擎内嵌到自己的业务系统，而不是直接把explorer暴露给用户当工作台。那这个war包的价值在哪？我自己的使用习惯是把它当成一个免费的流程验证工具：在explorer里画流程、部署、跑实例、看历史，确认BPMN文件合法、流程逻辑正确之后，再把这个流程定义文件拿回自己的项目里部署。

这样做能省掉大量反复编译打包的时间。尤其是在你还没有搭好自己系统的工作流模块时，explorer就是最好的调试台。它能直观展示流程走到了哪个节点、待办任务在谁手上、历史记录保留了什么粒度，这些信息比直接翻数据库表高效得多。等自己的系统集成完成，explorer又可以退居二线，作为验证新流程设计和排查异常流程的工具。

3. 部署activiti-explorer.war：从解压到流程跑通的完整步骤

3.1 环境准备：JDK与Tomcat版本搭配

5.22构建时间较早，最稳妥的环境组合是JDK 8加Tomcat 8.5或Tomcat 9.0。Tomcat 10之后Servlet命名空间从javax迁移到jakarta，5.22里的旧代码没法直接运行，这一点后面避坑章节会细说。先确认本机环境：

java -version # 期望输出包含 1.8.0_xxx 或 8uXXX $CATALINA_HOME/bin/version.sh | grep "Server number" # 期望输出包含 8.5.x 或 9.0.x

如果java命令报错或者版本是17、21，需要先安装JDK 8并设置JAVA_HOME指向它。Tomcat下载选择zip或tar.gz压缩包即可，解压到一个没有中文和空格的路径下，避免后续日志出现路径编码问题。

准备完成后，把Tomcat的conf/server.xml里默认端口8080确认没有被占用。如果你本机已经跑了其他服务占了8080，可以先改Connector端口为18080，后面访问地址相应改成http://localhost:18080/activiti-explorer。

3.2 数据库配置：H2默认配置与MySQL切换

activiti-explorer.war默认配好了内嵌H2数据源，不需要额外装数据库就能启动，适合第一次验证。H2的数据文件和TCP服务由Tomcat启动时拉起，重启后流程数据会保留在本地文件里，不会丢。想先把环境跑起来，可以跳过本节，直接做3.3。想从一开始就接自己常用的MySQL，则需要先改配置再部署。

explorer的数据库配置一般在WEB-INF/classes下的db.properties里。完整的处理流程是：先把war包解压到临时目录，修改配置文件后重新打包再放进webapps，或者直接把解压后的目录放到webapps下让Tomcat以exploded方式运行。我一般选择后者，改配置不用重复打war。

切换到MySQL时，db.properties的核心内容如下：

jdbc.driver=com.mysql.jdbc.Driver jdbc.url=jdbc:mysql://localhost:3306/activiti?useUnicode=true&characterEncoding=utf8 jdbc.username=root jdbc.password=yourpassword build.database=jdbc:mysql

这段配置里需要重点说明两个参数：jdbc.driver用的是com.mysql.jdbc.Driver，这是MySQL 5.x驱动jar里的驱动类名。如果你手头只有mysql-connector-java 8.x，驱动类名要改成com.mysql.cj.jdbc.Driver，但5.22引擎配的部分连接池版本对8.x驱动兼容性一般，我建议直接找5.1.x版本的驱动jar放进webapps/activiti-explorer/WEB-INF/lib目录下。build.database这个参数是给引擎识别数据库方言用的，保持jdbc:mysql前缀即可。

MySQL侧还需要手动建一个空数据库，字符集建议utf8。引擎第一次启动时如果设置了建表策略为true，会自动创建ACT_开头的表，不需要手工导入SQL脚本。

3.3 部署war包并完成首次启动

准备好Tomcat和环境变量后，把activiti-explorer.war复制到Tomcat的webapps目录：

cp activiti-explorer.war $CATALINA_HOME/webapps/ cd $CATALINA_HOME/bin ./startup.sh tail -f $CATALINA_HOME/logs/catalina.out

观察日志输出。正常启动的日志里会出现大量以ACT_开头的表创建记录，类似创建表ACT_RE_DEPLOYMENT、ACT_RU_TASK。看到这类日志，说明引擎初始化已经完成，H2数据源连接成功，流程引擎核心组件没有报错。

启动完成后，浏览器访问http://localhost:8080/activiti-explorer，登录界面会打开。默认账号是admin，密码是kermit。登录后能看到左侧导航里分成Process Management、Tasks、History、Manage等几个功能区域。

首次登录建议先点Manage区域里的Database页面，看一遍引擎自动建了哪些表，这能帮助建立对Activiti数据模型的直观认识：部署信息在ACT_RE_表，运行态任务在ACT_RU_表，历史数据在ACT_HI_表，这些分类后续排查问题会反复用到。

3.4 跑通一个最简单的流程：用自带示例来验证引擎

登录之后，先不急着用设计器画流程，可以用自带示例流程走一遍完整链路。在Process Management区域能找到示例流程列表，选一个最简的流程，点部署并启动一个实例。

如果想自己画一个极简流程验证，打开Activiti Designer在线设计器，拖入一个Start Event、一个User Task、一个End Event，连起来。给User Task设置一个候选人或者直接指定办理人。流程定义key建议起一个好记的名字，例如myFirstProcess。导出后得到BPMN文件，核心XML大致如下：

<definitions id="myFirstProcess" targetNamespace="http://www.activiti.org/test"> <process id="myFirstProcess" name="My First Process"> <startEvent id="startevent1" name="Start"></startEvent> <userTask id="usertask1" name="Approve" activiti:candidateGroups="managers"></userTask> <endEvent id="endevent1" name="End"></endEvent> <sequenceFlow id="flow1" sourceRef="startevent1" targetRef="usertask1"></sequenceFlow> <sequenceFlow id="flow2" sourceRef="usertask1" targetRef="endevent1"></sequenceFlow> </process> </definitions>

在explorer里上传这个文件并部署，然后启动一个流程实例。回到Tasks区域，能看到刚才那个流程实例产生了一个待办任务，说明引擎已经正确走到用户节点的处理逻辑。点完成任务，再去History区域刷新，能看到这个流程实例的状态变成了已完成。

这一步验证了引擎最重要的三个能力：流程定义解析、流程实例启动、任务节点推进。任何一个环节出问题，日志和界面上都会直接暴露，便于定位。验证通过之后，你心里就可以确认这个环境完全可用，后面画多复杂的流程图都只是在加节点和网关而已。

4. 避坑记录：Tomcat、JDK、数据库驱动的硬问题

4.1 Tomcat版本不对导致启动失败

现象：把activiti-explorer.war放进Tomcat 10的webapps启动，日志里报出大量ClassNotFoundError，集中在javax.servlet相关类，或者直接提示Servlet无法实例化。整个web应用根本无法访问。

原因：Tomcat从10.0开始把Servlet API从javax包迁移到了jakarta包。Activiti 5.22的引擎和explorer web应用都是基于javax.servlet编译的，两者不兼容。这个问题不是版本新旧能解决的，属于命名空间层面的硬隔离。

解决：换回Tomcat 9.0或8.5。如果已有的Tomcat 10不能动，可以另装一个Tomcat 8.5，两个Tomcat实例用不同端口同时运行，互不干扰。我一般在开发机上固定装一个Tomcat 8.5当作老版本war的测试容器，不跟现代Spring Boot的内嵌Tomcat混用。

4.2 JDK版本过高导致引擎初始化异常

现象：JDK 17甚至JDK 21环境下，Tomcat能启动，但访问explorer时报引擎初始化失败，日志里有大量反射相关异常，例如IllegalAccessException或InaccessibleObjectException，偶尔伴随cglib代理增强失败。

原因：5.22内部使用的cglib和反射调用方式比较老旧。高版本JDK对模块化访问限制严格，导致动态代理和反射生成类失败。这不是引擎逻辑错误，而是运行环境对老代码不够宽容。

解决：安装JDK 8并把它设为Tomcat启动使用的JAVA_HOME，重新启动Tomcat即可。需要注意的是别只在shell里临时export JAVA_HOME，还要把setclasspath.bat或catalina.sh里默认的JAVA_HOME指对位置。之后再用jinfo或者启动日志确认Tomcat进程实际跑在JDK 8上。

4.3 MySQL驱动缺失与驱动类名混淆

现象：修改db.properties指向MySQL后启动，日志出现Cannot create JDBC driver of class for connect URL或者ClassNotFoundException: com.mysql.jdbc.Driver，应用无法初始化数据源。

原因：war包自带的lib目录里没有MySQL驱动jar，或者驱动版本不对导致类名加载失败。另外一个常见情况是手头只有8.x驱动，却仍写了com.mysql.jdbc.Driver这个类名，8.x默认类名是com.mysql.cj.jdbc.Driver。

解决：去下载mysql-connector-java 5.1.x的jar，放入webapps/activiti-explorer/WEB-INF/lib目录下，然后重启Tomcat。如果网络条件有限，也可以用Maven拉取后从本地仓库复制出来。驱动路径放好后，建议写一个最简单的JDBC连接测试类先确认驱动类能被Class.forName加载，再启动explorer，这样能隔离数据源配置和引擎初始化两个问题。

4.4 切换到MySQL后找不到ACT_表

现象：数据源配置看起来没问题，MySQL也建了库，但启动后访问流程管理页面时报Table 'activiti.ACT_GE_PROPERTY' doesn't exist，或者数据库里只有空库，没有任何表。

原因：Activiti引擎不会自动为多数据库做全部建表操作。explorer默认配置针对H2，切换数据库后如果数据库脚本没有执行，数据字典就会缺失。

解决：两个途径任选其一。一是在引擎配置里把databaseSchemaUpdate设置为true，引擎启动时自动创建表；二是手动执行sql/create目录下对应的数据库脚本。手动执行更可控，推荐用mysql客户端执行sql/create/mysql/activiti.mysql.createEngine.sql，这个脚本会创建完整的数据字典。注意执行前先use到目标数据库，否则不知道表建到哪去了。

4.5 下载包里的lib与Maven坐标版本不一致

现象：在explorer里流程一切正常，但把自己工程里的Maven依赖换成activiti 5.22后，跑同样的BPMN文件却报解析异常或行为不一致。

原因：explorer war包内的jar是完整发布包自带的固定版本集合。而Maven坐标拉取依赖时，很可能通过传递依赖把mybatis、spring等间接依赖替换成了新版本，导致引擎运行期行为差异。

解决：以war包内WEB-INF/lib下的jar清单为准，把自己工程里对应的activiti相关坐标显式固定，把可能冲突的传递依赖用exclusion排除掉。我习惯把war包lib目录里的jar做一个txt清单，然后逐个核对Maven依赖树diff，这样能快速找到不一致点。

5. 核心配置解析：数据源、流程引擎参数与常见误用

5.1 activiti-context.xml里的数据源与建表策略

explorer的引擎配置集中在WEB-INF/classes下的activiti-context.xml里。一个典型的processEngineConfiguration配置如下：

<bean id="processEngineConfiguration" class="org.activiti.spring.SpringProcessEngineConfiguration"> <property name="dataSource" ref="dataSource"/> <property name="databaseSchemaUpdate" value="true"/> <property name="historyLevel" value="audit"/> <property name="jobExecutorActivate" value="true"/> <property name="processEngineName" value="defaultEngine"/> </bean>

逐个参数说清楚：dataSource指向当前数据源，可以是H2也可以是MySQL或Oracle。databaseSchemaUpdate有三个常用值，false表示不做任何自动建表，true表示启动时检查并自动建表，create-drop表示启动创建、销毁时删掉表，这个只适合测试。historyLevel决定流程历史数据的详细程度，none不记录历史，activity记录流程实例与活动节点的历史，audit在activity基础上再记录变量更新，full则连流程变量初始值、任务表单数据都完整保留。

jobExecutorActivate是另一个容易踩的开关。它控制引擎内置的定时任务执行器是否激活。如果流程图里有边界定时事件、定时开始事件、异步延续，这个必须保持true。如果所有流程都是普通同步节点，关掉可以减少无用线程开销。但如果你不确定流程里会不会有人加定时器，我建议保持默认打开。

5.2 引擎常用参数速查表

下面这张表是我在配置多个工作流项目时整理的常用参数，可以直接当作参照。

多引擎场景下，processEngineName必须唯一。如果同一个Spring容器里加载了多份引擎配置，漏配这个参数会直接导致启动冲突。生成流程图的乱码问题也很常见，activityFontName不设置为中文字体时会输出一堆方块，排查时先看这两个字体参数。

5.3 常见误用：把explorer当生产环境、直接解压改war

常见误用有三个，都在实际项目里见过。第一个是把explorer直接部署在生产服务器上给业务人员当工作台用。explorer本身没有完善的权限审批流、操作审计、单点登录体系，它的定位是调试与验证工具，真当成业务系统用会埋下巨大的权限漏洞。

第二个是直接解压war包改配置后不重新打包就跑。Tomcat对exploded目录的加载顺序和war包的包结构不一致，改错目录层级会导致配置没生效，排查时还容易跟Tomcat自动解压产生的副本混淆。我建议要么直接改exploded目录下文件再重启，要么改完后重新打成war包放到webapps下，别混着用。

第三个是数据库连接参数漏了characterEncoding。MySQL部署时只写jdbc:mysql://localhost:3306/activiti，中文流程变量和任务名称会出现乱码，而且这个乱码在H2环境测不出来，只有切到MySQL才会暴露。连接串里加上useUnicode=true&characterEncoding=utf8，可以避免一大批编码问题。

6. 进阶：把explorer当设计器，快速产出BPMN并部署到自己的环境

explorer里自带的在线设计器虽然不如桌面端设计器功能复杂，但胜在零安装。画完流程后直接下载BPMN文件，这个文件就能直接用作自己项目里的流程定义。以请假流程为例，在设计器里设定流程key为vacationProcess，候选人组为managers，导出后在自己项目里用引擎API部署：

@Autowired private RepositoryService repositoryService; public String deployVacationProcess(String bpmnXml) { Deployment deployment = repositoryService.createDeployment() .addString("vacationProcess.bpmn20.xml", bpmnXml) .name("请假流程") .deploy(); return deployment.getId(); }

部署完成后，验证一下流程定义是否注册成功，并启动一个示例流程：

long count = repositoryService.createProcessDefinitionQuery() .processDefinitionKey("vacationProcess") .count(); ProcessInstance instance = runtimeService.startProcessInstanceByKey("vacationProcess");

这样的做法最核心的价值在于，explorer设计器输出的BPMN文件是经过真实引擎跑通的，拿回自己工程后出问题的概率大幅下降。我自己的习惯是每次从explorer导出流程文件后，先做一个三连验证：查流程定义key是否存在、启动一个实例、把待办任务走完。这个流程能挡掉大部分流程定义解析问题和节点配置错误。从有次画了一个带定时边界事件的复杂流程，部署到自己项目里跑起来却始终不触发，后来才发现是漏了jobExecutorActivate参数，从那以后我每次拿到新环境、新流程都会强制走一遍explorer冒烟测试，再动手改业务代码。希望帮到你。

本文还有配套的精品资源，点击获取