企业官网建设流程全解析

简介：Activiti 5.22完整包内含activiti-explorer.war，是一套可直接部署的Activiti Explorer图形化管理应用，面向需要搭建工作流引擎环境、学习BPMN 2.0流程设计或二次开发流程管理系统的Java开发者。压缩包共79个文件，以48个jar依赖为主，覆盖Activiti引擎、Spring集成、REST服务等核心模块，另有10个xml流程定义与配置文件、properties配置、class文件以及png/jpg设计图、svg图标等，整体大小88.33MB；META-INF与WEB-INF目录结构完整，便于直接部署至Tomcat等Servlet容器。包内自带的Explorer界面支持流程定义部署、流程实例启停与监控、任务审批以及用户与组权限管理，并内置请假、设备维修、销售线索等示例BPMN流程，可对照案例快速掌握Activiti 5.x的常见操作；作为经典版本，用于理解工作流引擎的核心原理仍非常合适。目前已有1188人学习/下载，尤其适合希望边用边学Activiti的开发者。 如果你手头还维护着几个用 Activiti 5.x 写的老系统，一定对activiti-explorer.war这个名字不陌生。这是 Activiti 官方在 5.22 时代随完整包一起分发的 Web 端流程设计器和管理控制台，解压到 Tomcat 就能跑，内置流程绘制、部署、发起、任务审批一整套体验。这几天帮一个老项目搭演示环境，正好把 Activiti 5.22 完整包下载、activiti-explorer.war部署、切 MySQL、补任务监听器这些事完整走了一遍，踩了不少坑，也摸清了一些老版本才有的脾气。这篇就按实际操作的顺序，把从下载到跑通的全过程写清楚，给还在跟 5.22 打交道的朋友做个参考。

1. 为什么还在用 5.22：老项目的活儿，新入门的课

Activiti 5.22 是 5.x 系列里的收尾版本，之后再往上升就是 Activiti 6、7 那一套完全不同的体系。很多公司早年的审批流、工单流、OA 系统，底座就是 5.x。项目能跑就不动，这是老系统的铁律，所以哪怕新版本出了好几年，生产环境里 Activiti 5.22 的存量依然不小。

对刚接触工作流的人来说，5.22 反而是一个特别好的入门选择。它的核心模型——流程定义、流程实例、任务、执行实例、历史——在 5.x 里表达得最直观，网上的资料、老项目的代码、各种 demo 也几乎都基于这一代版本。更重要的是，5.22 完整包里自带的activiti-explorer.war是一个开箱即用的 Web 应用，它把流程引擎、流程设计器、用户管理、任务管理全部打包在一起，不需要你自己写一行代码，部署上去就能在浏览器里画流程图、部署流程、发起流程、处理任务。

我这次做的事情，简单说就是三件事：把 5.22 完整包下载下来，把activiti-explorer.war部署到 Tomcat 跑起来，然后再把它默认的 H2 内存数据库换成 MySQL，顺带解决设计器里任务监听器缺失的问题。整个过程大概一个小时能走完，但中间有几个点不提前搞清楚，能卡一下午。下面按实际操作的顺序来拆。

2. 完整包下载与部署：先让 Explorer 跑起来

2.1 从哪找 5.22 完整包

先说下载。Activiti 5.22 官方完整包的名字通常是activiti-5.22.0.zip，里面包含了activiti-explorer.war、activiti-rest.war、依赖 jar、官方文档、数据库建表 SQL 脚本等。找的时候不要直接在搜索引擎里乱翻，优先去两个地方：

• Maven 中央仓库：groupId 是org.activiti，搜activiti-5.22.0，能拿到完整包的 zip 以及所有模块的 jar 和 war。这是最靠谱的渠道，文件完整、来源可信。
• 官方文档归档：Activiti 老版本文档站点里有 5.22 的下载入口，指向的也是归档文件。

如果你是想在新项目里用 Maven 管理依赖，那不需要下载 zip，直接引坐标就行：

<dependency> <groupId>org.activiti</groupId> <artifactId>activiti-engine</artifactId> <version>5.22.0</version> </dependency> <dependency> <groupId>org.activiti</groupId> <artifactId>activiti-explorer</artifactId> <version>5.22.0</version> <type>war</type> </dependency>

activiti-engine是引擎核心，activiti-explorer就是那个 Web 应用。基于 Maven 拿到的 war 和完整包里的activiti-explorer.war是同一个东西，后面部署完全一致。

2.2 部署几步走，重点在环境匹配

拿到activiti-explorer.war之后，部署本身不难，难的是环境匹配。我测试时用的组合是JDK 8 + Tomcat 8.5，这个组合跑 5.22 非常稳。如果你用 Tomcat 9 或更高版本，可能会遇到 Servlet API 版本不兼容的问题，不建议在这上面花时间，直接退回 Tomcat 8.5 最省事。

部署步骤就三步：

1. 把activiti-explorer.war复制到 Tomcat 的webapps目录。
2. 启动 Tomcat（bin/startup.sh或双击startup.bat），第一次启动会自动解压 war 包。
3. 浏览器访问http://localhost:8080/activiti-explorer。

默认账号是kermit / kermit，这个账号是内置的超级管理员，登录后能看到整个 Explorer 的操作界面。左边是流程管理菜单，中间是设计器画布，右边是属性面板。

这里有一个容易被忽略的点：Tomcat 启动后如果日志里出现java.lang.OutOfMemoryError或者部署超时，多半是内存参数问题。建议在bin/catalina.sh（或.bat）里把启动内存调大一点：

JAVA_OPTS="-Xms512m -Xmx1024m -XX:MaxPermSize=256m"

注意MaxPermSize在 JDK 8 里已经废弃，带上也不报错，但没必要；用 JDK 7 时它还有意义。总之内存给足，Explorer 用起来才不卡。

3. 默认 H2 与切换 MySQL：数据库版本那些事

3.1 为什么能“开箱即用”

activiti-explorer.war默认自带一个 H2 内存数据库，这是它能免配置直接跑起来的原因。H2 作为 embedded 数据库，数据写在内存里，所以 Tomcat 一重启，所有的流程定义、用户数据、历史记录全部清空。对写 Demo、测功能来说很方便，但稍微正式一点的场景就不行了——你辛辛苦苦画的流程、建的代理人、跑了一部分的任务，一次重启全没，这谁都受不了。

所以实际项目里，拿到 war 包后的第一件事基本都是切数据库。Activiti 5.22 官方支持的数据库有 MySQL、Oracle、PostgreSQL、H2 等，国内用的最多的就是 MySQL。

3.2 切换 MySQL 的完整操作

切 MySQL 的操作核心是改两处：连接配置和驱动。具体步骤我走的这一套，比较稳妥：

第一步，在 MySQL 里先建库。官方推荐使用 utf8 字符集，避免以后流程参数里有中文出现乱码：

CREATE DATABASE activiti DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci;

第二步，把 MySQL 驱动 jar 复制到webapps/activiti-explorer/WEB-INF/lib目录下。注意 5.22 时代的驱动很老，如果你连的是 MySQL 5.7，用mysql-connector-java-5.1.49.jar足够；如果连的是 MySQL 8.x，请务必用 8.x 的驱动（比如mysql-connector-java-8.0.33.jar），否则启动直接报错。

第三步，修改数据库连接配置。配置文件在webapps/activiti-explorer/WEB-INF/classes/db.properties，打开后改成你自己数据库的信息：

jdbc.driver=com.mysql.cj.jdbc.Driver jdbc.url=jdbc:mysql://localhost:3306/activiti?useUnicode=true&characterEncoding=utf8&useSSL=false&allowPublicKeyRetrieval=true&nullCatalogMeansCurrent=true jdbc.username=root jdbc.password=yourpassword

这里有几个参数我要重点解释一下。MySQL 8 的驱动类名是com.mysql.cj.jdbc.Driver，不是老的com.mysql.jdbc.Driver，写错就报ClassNotFoundException。useSSL=false是避免本地开发环境没有 SSL 证书时报SSL connection error。allowPublicKeyRetrieval=true是 MySQL 8 驱动在非 SSL 连接下必须加的，不加会报Public Key Retrieval is not allowed。最后一个nullCatalogMeansCurrent=true是 Activiti 5.22 连新版 MySQL 时容易出现表重复创建问题的关键参数，这个坑比较冷门，但很实用。

第四步，处理建表。把数据库切到正式库之后还有最后一关——表结构从哪来。最简单的方式是第一次启动时让引擎自动建表，前提是要把引擎配置里的databaseSchemaUpdate设为true。如果你不太想改引擎配置，也可以手动执行官方 SQL 脚本，完整包的database/create目录下有activiti.mysql.create-engine.sql、activiti.mysql.create-identity.sql等一整套脚本，按顺序执行就行。我一般选自动建表，省心，生产环境才用手动脚本求可控。

第五步，重启 Tomcat，再次访问 Explorer。登录进去随便建个流程试试，如果没问题，说明数据库已经切换成功。

3.3 数据库版本字段与常见报错

Activiti 引擎启动时会检查数据库里的版本号，这个版本号存在ACT_GE_PROPERTY表里，NAME字段是schema.version，VALUE_字段是版本值。5.22.0 引擎对应的一一般是5.22.0.0这样的格式。如果你把高版本引擎连到低版本库上，启动日志就会报：

Activiti database schema version 5.21.0.0 is older than engine version 5.22.0.0

反过来，高版本库连低版本引擎会报“newer than engine version”。这类版本不一致的问题，处理方式就是统一版本：要么升级库，要么降级引擎，不要硬凑。另外网上搜“activiti 数据库版本”时经常看到有人问ACT_GE_PROPERTY里其他字段的意义，其实这个表在引擎里只存两类东西：schema 版本和下一次执行 ID 最大值，平时不需要动它。

4. 流程设计器没有任务监听器：老设计器的短板与补法

4.1 设计器的真实体验

activiti-explorer.war自带的流程设计器，在 5.22 这一代里是主流操作界面。它基于 Web 方式绘制 BPMN 2.0 流程图，你可以从左边拖拽 start event、user task、exclusive gateway、end event 这些节点，右边属性面板里填写节点名称、负责人候选人表达式。画完之后点保存，流程定义就自动部署到引擎里，不需要额外的部署动作。

但用过的朋友都知道，这个设计器有个明显的坑：节点属性面板里没有任务监听器（Task Listener）的配置入口。网上搜“activity 5.22 流程设计器没有任务监听器”，能搜出一堆提问，基本都是在设计器里选中 User Task 节点，翻遍属性面板也找不到监听器设置项。这其实是 5.22 设计器的功能裁剪，不是你不会用。

任务监听器在工作流里非常常用，比如在任务创建时自动给处理人发通知、任务完成后自动回写业务表，都靠它。没有可视化入口，不代表做不到，方法有两个。

4.2 补法一：手改流程 XML 加监听器

设计器虽然不能可视化加监听器，但它支持查看和导出 XML。你可以先用设计器画好流程图，然后切到 XML 视图，手动把监听器配置写进去。

一个包含任务监听器的 User Task 节点 XML 长这样：

<userTask id="usertask1" name="部门审批" activiti:assignee="${approver}"> <extensionElements> <activiti:taskListener event="create" class="com.example.MyTaskCreateListener" /> <activiti:taskListener event="complete" expression="${myBean.doComplete(execution)}" /> </extensionElements> </userTask>

event有三个常用取值：create表示任务创建时触发，assignee表示处理人变更时触发，complete表示任务完成时触发。监听器可以配class指定 Java 类，也可以配expression调 Spring 容器里的 bean。注意一定要在流程定义的根节点<definitions>上声明activiti命名空间，否则解析器不认这个标签：

<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:activiti="http://activiti.org/bpmn">

手改 XML 的方式看着原始，但胜在可控。改完保存，Explorer 会重新部署流程定义，新版本的流程定义会生效。要注意的是，流程引擎部署时会校验 XML 合法性，如果监听器类不存在或者类名写错，部署会失败，日志里会看得清清楚楚。

4.3 补法二：IDEA 插件离线安装，建模更顺手

如果你不想被 Explorer 设计器绑住手脚，更推荐用 IDEA 里的 Activiti BPMN 插件来画流程图。这个插件支持可视化配置 task listener，在界面右侧面板里就可以直接添加 create、complete 等事件，还能选择 class 或 expression，导出的 bpmn 文件和引擎完全兼容。

但有个现实问题：IDEA 插件市场经常搜不到老版本的 Activiti 插件，或者下载速度很慢。这时候就要走离线安装。

离线安装的步骤是：先从插件仓库下载插件 zip 包，然后打开 IDEA，进入File -> Settings -> Plugins，点击右上角的齿轮图标，选Install Plugin from Disk...，选中下载好的 zip，重启 IDEA 即可。装完后，在resources目录右键New -> BPMN File，就能创建一个可视化的流程文件。

有一点要提醒：插件版本和 IDEA 版本要匹配。你用 2023 或 2024 版的 IDEA 装老版插件，大概率装不上或装完按钮不显示。我自己的做法是先看插件页面标注的兼容版本范围，再对一下自己的 IDEA 版本，宁可低一个版本也不要高。离线包装好后，画流程的效率比 Explorer 里拖拽高很多，尤其是配监听器、写表达式这些操作，体验差距非常明显。

5. 典型报错速查与避坑心得

整个流程走下来，我把容易踩的坑汇总成一张表，方便后面遇到问题快速定位。这些都是我实际碰到过、并且验证过解决方式的问题。

再说几个个人体会比较深的小细节。

第一，activiti-explorer.war里的 H2 默认配置，导致很多人以为工作流是开箱即用的，结果切库之后才发现表结构要单独处理。建议下载完整包后，直接去database/create目录下看看官方 SQL 脚本，这些脚本是理解 Activiti 表结构最好的入口，比只看文档直观得多。

第二，任务监听器这种配置，在新版设计器里可能就是一个按钮的事，但在 5.22 里就是没有。不要跟老版本死磕，要么用 XML 补，要么换 IDEA 插件建模，两条路我都试过，最终团队统一用的是 IDEA 插件。原因很简单：XML 手写监听器时，一个字母写错排查半天，可视化面板至少能保证语法正确。

第三，如果是在老项目上做功能扩展，尽量保持activiti-engine的版本和数据库表版本一致。很多“莫名其妙”的异常，追根溯源都是启动时引擎把版本校验当成错误抛了。你用 5.22 的包，就一定用 5.22 的库，不要拿新库连旧引擎。

我自己的经验是，把 Activiti 5.22 这套老环境搭建一次，才真正理解了它的引擎初始化流程、建表策略和版本管理方式。现在遇到问题，已经不会一上来就怀疑框架有 bug，而是能顺着日志、配置文件、库表版本一步步排查。如果你也卡在下载、部署或者设计器功能不全的某个环节，希望这份记录能帮你少走点弯路。

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