跳到主要内容

Flowable 应用

Doubao 中英对照 Flowable applications

Flowable 提供了 flowable-rest.war，其中包含 Flowable REST API。更多内容可阅读 REST API 章节。

该应用是一个基于 Spring Boot 3.1 的应用，这意味着 WAR 文件实际上是可执行的，可以作为普通独立应用运行。
参见 Spring Boot 参考文档中的 The Executable Jar Format。

Flowable REST 应用安装​

如前所述，该应用可以部署在 Tomcat 服务器上；当需要使用额外配置项时，这很可能是最简单的上手方式。在本安装指南中，我们将介绍如何在 Tomcat 服务器中安装该应用。

  1. 下载 Apache Tomcat 的最新稳定版本。它必须兼容 Jakarta Servlet 6（Tomcat 10 或更高版本）
  2. 下载最新稳定的 Flowable 7 版本。
  3. 将 flowable-rest.war 文件从 Flowable 发行版的 wars 文件夹复制到 Tomcat 的 webapps 文件夹。
  4. 运行 bin/startup.sh（Mac OS 和 Linux）或 bin/startup.bat（Windows）脚本来启动 Tomcat 服务器。
  5. 打开 Web 浏览器并访问 http://localhost:8080/flowable-rest/docs。

Flowable REST 应用现在应该已使用 H2 内存数据库运行，Swagger Docs 应该会显示在你的 Web 浏览器中：

Flowable REST 应用现在应该已使用 H2 内存数据库运行。

通常，你会希望把默认的 H2 内存数据库配置改为 MySQL 或 Postgres（或其他持久化数据库）配置。
可以通过修改应用 WEB-INF/classes/ 目录下的 application.properties 文件来实现。
不过，更简单的方式是使用 Spring Boot 的外部化配置。
示例配置可以在 Github 上找到。
要将默认配置改为 MySQL，需要对属性文件做以下修改：

spring.datasource.url=jdbc:mysql://127.0.0.1:3306/flowable?characterEncoding=UTF-8
spring.datasource.username=flowable
spring.datasource.password=flowable

该配置要求 MySQL 服务器中存在一个名为 flowable 的数据库，REST 应用会自动生成必要的数据库表。对于 Postgres，需要做以下修改：

spring.datasource.url=jdbc:postgresql://localhost:5432/flowable
spring.datasource.username=flowable
spring.datasource.password=flowable

除了修改配置外，请确保数据库驱动在 classpath 上可用。同样，你可以把驱动 JAR 文件添加到 Web 应用的 WEB-INF/lib 文件夹，也可以将 JAR 文件复制到 Tomcat 的 lib 文件夹。MySQL 和 Postgres 的数据库驱动可以从以下位置下载：

将 REST 作为独立应用运行时，可以使用 loader.path 属性添加数据库驱动。

java -Dloader.path=/location/to/your/driverfolder -jar flowable-rest.war

更多信息参见 Spring Boot 参考文档中的PropertiesLauncher 特性。

Flowable REST 应用配置​

由于 Flowable REST 应用是一个 Spring Boot 应用，你可以使用 Spring Boot 提供的所有属性。
要为该应用提供自定义配置，请参考 Spring Boot 文档的外部化配置一节。

You can also use YAML based properties.

REST 应用属性

属性名旧属性默认值描述
flowable.rest.app.authentication-moderest.authentication.modeverify-privilege配置调用 REST API 时验证用户凭据的方式：'any-user'：用户必须存在且密码必须匹配，允许任何用户进行调用（这是 6.3.0 之前的行为）。'verify-privilege'：用户必须存在、密码必须匹配，且用户必须具有 'rest-api' 权限。如果未设置，默认为 'verify-privilege'

部分旧属性已改为由 Flowable Spring Boot starter（或 Spring Boot 自身）管理。

由 Flowable Spring Boot Starter 管理的旧属性

属性名旧属性默认值描述
flowable.async-executor-activateengine.process.asyncexecutor.activatetrue是否应激活异步执行器。
flowable.database-schema-updateengine.process.schema.updatetrue数据库模式应使用的更新策略。
flowable.history-levelengine.process.history.level-需要使用的历史级别。
flowable.process.servlet.nameflowable.rest-api-servlet-nameFlowable BPMN Rest APIProcess servlet 的名称。
flowable.process.servlet.pathflowable.rest-api-mapping/process-apiProcess REST servlet 的上下文路径。
flowable.idm.enabledflowable.db-identity-usedtrue是否需要启动 idm 引擎。
flowable.idm.password-encodersecurity.passwordencoder-需要使用的密码编码器类型。
flowable.idm.ldap.base-dnldap.basedn-搜索用户和组时作为起点的基础 'distinguished name'（DN）。需要区分用户和组的基础 DN 时，使用 'user-base-dn' 或 'group-base-dn'。
flowable.idm.ldap.enabledldap.enabledfalse是否启用 LDAP IDM Service。
flowable.idm.ldap.passwordldap.password-用于连接 LDAP 系统的密码。
flowable.idm.ldap.portldap.port-1LDAP 系统运行的端口。
flowable.idm.ldap.serverldap.server-可访问 LDAP 系统的服务器主机。例如 'ldap://localhost'。
flowable.idm.ldap.userldap.user-用于连接 LDAP 系统的用户 id。
flowable.idm.ldap.attribute.emailldap.attribute.email-与用户邮箱匹配的属性名。该属性用于查找 'org.flowable.idm.api.User' 对象，以及完成 LDAP 对象与 Flowable 'org.flowable.idm.api.User' 对象之间的映射。
flowable.idm.ldap.attribute.first-nameldap.attribute.firstname-与用户名字匹配的属性名。该属性用于查找 'org.flowable.idm.api.User' 对象，以及完成 LDAP 对象与 Flowable 'org.flowable.idm.api.User' 对象之间的映射。
flowable.idm.ldap.attribute.group-idldap.attribute.groupid-与组 id 匹配的属性名。该属性用于查找 'org.flowable.idm.api.Group' 对象，以及完成 LDAP 对象与 Flowable 'org.flowable.idm.api.Group' 对象之间的映射。
flowable.idm.ldap.attribute.group-nameldap.attribute.groupname-与组名匹配的属性名。该属性用于查找 'org.flowable.idm.api.Group' 对象，以及完成 LDAP 对象与 Flowable 'org.flowable.idm.api.Group' 对象之间的映射。
flowable.idm.ldap.attribute.last-nameldap.attribute.lastname-与用户姓氏匹配的属性名。该属性用于查找 'org.flowable.idm.api.User' 对象，以及完成 LDAP 对象与 Flowable 'org.flowable.idm.api.User' 对象之间的映射。
flowable.idm.ldap.attribute.user-idldap.attribute.userid-与用户 id 匹配的属性名。该属性用于查找 'org.flowable.idm.api.User' 对象，以及完成 LDAP 对象与 Flowable 'org.flowable.idm.api.User' 对象之间的映射。该属性是可选的，仅在使用 Flowable API 搜索 'org.flowable.idm.api.User' 对象时需要。
flowable.idm.ldap.cache.group-sizeldap.cache.groupsize-1允许设置 'org.flowable.ldap.LDAPGroupCache' 的大小。这是一个 LRU 缓存，为用户缓存组信息，从而避免每次需要获知某用户的组时都访问 LDAP 系统。如果该值小于零，则不会实例化缓存。默认为 -1，即不进行缓存。请注意，组缓存是在 'org.flowable.ldap.LDAPIdentityServiceImpl' 上实例化的。因此，如果你有 'org.flowable.ldap.LDAPIdentityServiceImpl' 的自定义实现，别忘了添加组缓存功能。
flowable.idm.ldap.query.all-groupsldap.query.groupall-搜索所有组时执行的查询。
flowable.idm.ldap.query.all-usersldap.query.userall-搜索所有用户时执行的查询。
flowable.idm.ldap.query.groups-for-userldap.query.groupsforuser-搜索特定用户的组时执行的查询。例如：(&(objectClass=groupOfUniqueNames)(uniqueMember=\{0})) 此时将返回 LDAP 中所有类别为 'groupOfUniqueNames' 且所提供 DN 是其 'uniqueMember' 的对象。如示例所示，用户 id 通过典型的 {@link java.text.MessageFormat} 注入，即使用 {0}。如果仅设置查询不足以满足你的特定 LDAP 配置，可以换用不同的 org.flowable.ldap.LDAPQueryBuilder，从而获得比仅设置查询更多的定制能力。
flowable.idm.ldap.query.user-by-full-name-likeldap.query.userbyname-按全名搜索用户时执行的查询。例如：`(&(objectClass=inetOrgPerson)(
flowable.idm.ldap.query.user-by-idldap.query.userbyid-按 userId 搜索用户时执行的查询。例如：(&(objectClass=inetOrgPerson)(uid=\{0})) 此时将返回 LDAP 中所有类别为 'inetOrgPerson' 且 'uid' 属性值匹配的对象。如示例所示，用户 id 通过典型的 {@link java.text.MessageFormat} 注入，即使用 {0}。如果仅设置查询不足以满足你的特定 LDAP 配置，可以换用不同的 'org.flowable.ldap.LDAPQueryBuilder'，从而获得比仅设置查询更多的定制能力。
flowable.mail.server.hostemail.hostlocalhost邮件服务器的主机。
flowable.mail.server.passwordemail.password-邮件服务器认证使用的密码。
flowable.mail.server.portemail.port1025邮件服务器的端口。
flowable.mail.server.ssl-portemail.ssl-port1465邮件服务器的 SSL 端口。
flowable.mail.server.use-sslemail.use-sslfalse设置是否在连接时为 SMTP 传输启用 SSL/TLS 加密（SMTPS/POPS）。
flowable.mail.server.use-tlsemail.use-tlsfalse启用或禁用 STARTTLS 加密。
flowable.mail.server.usernameemail.username-邮件服务器认证需要使用的用户名。如果为空，则不使用认证。
flowable.process.definition-cache-limitflowable.process-definitions.cache.max-1流程定义缓存中可用的流程定义最大数量。默认为 -1（所有流程定义）。

由 Spring Boot 管理的旧属性

属性名旧属性默认值描述
spring.datasource.driver-class-namedatasource.driver-JDBC 驱动的全限定名。默认根据 URL 自动检测。
spring.datasource.jndi-namedatasource.jndi.name-数据源的 JNDI 位置。设置后，class、url、username 和 password 将被忽略。
spring.datasource.passworddatasource.password-数据库的登录密码。
spring.datasource.urldatasource.url-数据库的 JDBC URL。
spring.datasource.usernamedatasource.username-数据库的登录用户名。
spring.datasource.hikari.connection-test-querydatasource.preferred-test-query-用于测试连接有效性的 SQL 查询。
spring.datasource.hikari.connection-timeoutdatasource.connection.timeout-客户端从连接池等待一个连接的最大毫秒数。如果超过该时间仍无可用连接，获取连接时将抛出 SQLException。
spring.datasource.hikari.idle-timeoutdatasource.connection.idletimeout-连接在连接池中允许空闲的最长时间（毫秒）。连接是否作为空闲被回收最多有 +30 秒的最大偏差、+15 秒的平均偏差。在该超时之前，连接绝不会因空闲被回收。值为 0 表示空闲连接永远不会从池中移除。
spring.datasource.hikari.max-lifetimedatasource.connection.maxlifetime-该属性控制连接池中连接的最大生命周期。当连接达到该超时时间时，即使最近被使用过，也会从池中回收。正在使用的连接绝不会被回收，只有空闲时才会被移除。
spring.datasource.hikari.maximum-pool-sizedatasource.connection.maxpoolsize-该属性控制连接池允许达到的最大规模，包括空闲连接和正在使用的连接。该值基本决定了到数据库后端的实际最大连接数。当连接池达到该规模且没有空闲连接可用时，对 getConnection() 的调用将阻塞最多 connectionTimeout 毫秒后超时。
spring.datasource.hikari.minimum-idledatasource.connection.minidle-该属性控制 HikariCP 尝试在连接池中保持的最小空闲连接数，包括空闲连接和正在使用的连接。如果空闲连接数低于该值，HikariCP 会尽最大努力快速高效地恢复它们。
spring.servlet.multipart.max-file-sizefile.upload.max.size10MB最大文件大小。值可以使用 "MB" 或 "KB" 后缀分别表示兆字节或千字节。

Flowable LDAP 配置​

除了默认的身份表之外，IDM 组件也可以配置为使用 LDAP 服务器。
要连接 LDAP 服务器，需要在 application.properties 文件（或配置应用的任何其他方式）中提供额外的属性：

#
# LDAP
#
flowable.idm.ldap.enabled=true
flowable.idm.ldap.server=ldap://localhost
flowable.idm.ldap.port=10389
flowable.idm.ldap.user=uid=admin, ou=system
flowable.idm.ldap.password=secret
flowable.idm.ldap.base-dn=o=flowable
flowable.idm.ldap.query.user-by-id=(&(objectClass=inetOrgPerson)(uid={0}))
flowable.idm.ldap.query.user-by-full-name-like=(&(objectClass=inetOrgPerson)(|({0}=*{1}*)({2}=*{3}*)))
flowable.idm.ldap.query.all-users=(objectClass=inetOrgPerson)
flowable.idm.ldap.query.groups-for-user=(&(objectClass=groupOfUniqueNames)(uniqueMember={0}))
flowable.idm.ldap.query.all-groups=(objectClass=groupOfUniqueNames)
flowable.idm.ldap.query.group-by-id=(&(objectClass=groupOfUniqueNames)(uniqueId={0}))
flowable.idm.ldap.attribute.user-id=uid
flowable.idm.ldap.attribute.first-name=cn
flowable.idm.ldap.attribute.last-name=sn
flowable.idm.ldap.attribute.group-id=cn
flowable.idm.ldap.attribute.group-name=cn
flowable.idm.ldap.cache.group-size=10000
flowable.idm.ldap.cache.group-expiration=180000

当 flowable.idm.ldap.enabled 属性设置为 true 时，REST 应用会期望其他 LDAP 属性都已填写。
本示例配置提供了 Apache Directory Server 的服务器配置和 LDAP 查询。
对于其他 LDAP 服务器（如 Active Directory），则需要其他配置值。

配置 LDAP 后，用户的认证和组检索将通过 LDAP 服务器完成。只有权限仍从 Flowable 身份表中检索。因此，请确保每个 LDAP 用户都在 IDM 应用中定义了正确的权限。

如果应用是以 LDAP 配置启动的，引导逻辑会检查 Flowable 身份表中是否已存在权限。
如果没有权限（仅在首次启动时），将创建 4 个默认权限，并使用 flowable.rest.app.admin.user-id 属性值（来自 application.properties 或在环境中配置）作为获取全部权限的用户 id。
因此，请确保 flowable.rest.app.admin.user-id 属性值被设置为一个有效的 LDAP 用户，否则将没有人能够使用 Flowable REST 应用。

生产就绪端点​

应用中包含 Spring Boot 的生产就绪端点。
要查看所有可用端点的概览，请参考 Actuator Web API 文档。

这些属性是默认设置：

# Expose all actuator endpoints to the web
# They are exposed, but only authenticated users can see /info and /health abd users with access-admin can see the others
management.endpoints.web.exposure.include=*
# Full health details should only be displayed when a user is authorized
management.endpoint.health.show-details=when_authorized
# Only users with role access-admin can access full health details
management.endpoint.health.roles=access-admin

安全配置方式为：info 和 health 端点对所有已认证用户暴露。
health 端点的完整详情只能由具有 access-admin 权限的用户查看。
如果想更改这一点，需要配置 management.endpoint.health.show-details。
其余所有端点仅允许具有 access-admin 权限的用户访问。

自定义 Bean 部署​

向 Flowable 应用提供自定义 bean 有多种方式。

使用 Spring Boot 自动配置​

Flowable 应用是一个 Spring Boot 2 应用。
这意味着可以使用常规的 Spring Boot 自动配置来向 Flowable 提供 bean。
可以按以下方式进行：

package com.your.own.package.configuration;

@Configuration
@AutoConfigureOrder(Ordered.LOWEST_PRECEDENCE) // Makes sure that this configuration will be processed last by Spring Boot
@ConditionalOnBean(type = "org.flowable.engine.ProcessEngine") // The configuration will only be used when the ProcessEngine bean is present
public class YourOwnConfiguration {

    @Configuration
    @ComponentScan ("com.your.own.package.beans")
    public static class ComponentScanConfiguration {
        // This class is needed in order to conditionally perform the component scan (i.e. when the ProcessEngine bean is present)
        // It is an optional class, in case you don't need component scanning then you don't need to do this
    }

    @Bean
    public CustomBean customBean() {
        // create your bean
    }

    @Bean
    public EngineConfigurationConfigurer<SpringProcessEngineConfiguration> customProcessEngineConfigurationConfigurer() {
        return engineConfiguration -> {
            // You can use this to add extra configuration to the process engine
        }
    }
}

请注意，使用 Spring Boot 时，配置类可以放在你自己的包下，而不必放在某个 Flowable 包下。

为了将该类做成自动配置类，需要在你的 jar 的 META-INF/spring 文件夹中创建一个名为 org.springframework.boot.autoconfigure.AutoConfiguration.imports 的文件。
在该文件中添加：

com.your.own.package.configuration.YourOwnCustomConfiguration

要使用这种方式，你需要将自己的 jar 放入解压后 war 的 WEB-INF/lib 文件夹。
由于 Spring 代理 @Configuration 类的方式，把该 jar 放在 servlet 容器（如 Tomcat）的 lib 文件夹中将无法工作。

组件扫描​

向 Flowable 引擎提供自定义 Spring bean 的另一种方式，是将它们放在某个包下，并让 Flowable 应用组件扫描该包。
根据所使用的应用不同，这个包也不同：

  • 对于 flowable-rest.war，使用 org.flowable.rest.app。

自定义 bean 可以放在单个 JAR 中，并且该 JAR 在应用启动时必须位于 classpath 上。
根据 JAR 放置的位置（servlet 容器的 lib 文件夹，如 Tomcat，或解压后 war 的 WEB-INF/lib 文件夹），可用的方式有所不同。

当使用 servlet 容器的 lib 文件夹时，创建的类应当是自包含的，即它们只能使用该 JAR 内部的类。
你可以使用任何 Spring 的 @Component 注解（@Configuration 除外）。
之所以不能使用 @Configuration 类，是因为每个配置类都会由 Spring 借助 ConfigurationClassPostProcessor 进行代理。
然而，加载 @Configuration 类的类路径无法访问 Spring 所需的类。

当把 JAR 包含在解压后 war 的 WEB-INF/lib 文件夹中时，就可以使用 @Configuration 类以及对其他 JAR 的依赖。

创建你自己的 Spring Boot 应用​

这种方式是所有方式中最灵活、最强大的。
要采用这种方式，请参考本文档的Spring Boot 入门一节。