使用文档
从安装、配置到 Flow JSON 协议、管理接口、隔离与执行鉴权,以及生产部署。示例默认使用 flow.rest-port=8086;部署到 flow-scenario 时为 servlet 单端口模式,统一走 8090 的 /flow-api。
产品概览
Flow Server Starter 是一个把 Flow JSON 编译成 Apache Camel 4 路由的 Spring Boot Starter。它把“流程编排”从代码里搬到 JSON 里:前端设计器、内部低代码平台或脚本都可以生成同一份 Flow JSON,通过管理接口部署,运行时由 Camel 执行。
POST /flow 校验、编译、落库 → Camel 路由立即生效 → 重启自动恢复。
架构
适合谁
- 想给内部系统加一个可视化流程编排层,但不想自己实现运行时。
- 已有 JSON 流程设计器,需要一个可靠的后端编译器与部署接口。
- 需要把 REST、定时任务、文件、消息队列、数据库、Excel 等能力用同一套模型串起来。
能力边界
- 节点由
@FlowNodeDef注解注册,内置 75 个,也支持通过配置扫描自定义节点包。 - 宿主有
DataSource时流程落库到T_FLOWS,没有则退化为内存模式。 - 管理接口与 REST 流程默认共用一个独立 Jetty 端口;也可以切到 servlet 模式,复用宿主
server.port下的/flow-api(单端口部署)。 - Kafka、RabbitMQ、Redis、MinIO、Excel 等组件按需引入,不引入时节点仍可注册,但部署相关流程会失败并回滚。
快速开始
下面用 starter 自带的 demo 在 5 分钟内跑通一条 REST 流程。需要 JDK 21 与 Maven 3.9+。
1. 引入依赖
<dependency>
<groupId>cn.seeyou520</groupId>
<artifactId>flow-server-starter</artifactId>
<version>1.0.0</version>
</dependency>
如果制品还没发布到中央仓库或私服,先在 starter 目录执行 mvn -DskipTests install 安装到本地仓库。
2. 添加配置
flow:
enabled: true
server: demo # 服务标识,参与 routeId,多实例部署时必须唯一
rest-port: 8086 # Jetty 模式端口(rest-component=jetty 时生效)
# rest-component: servlet # 可选:复用宿主 server.port,此时用 rest-context-path 指定基路径
# rest-context-path: /flow-api
# isolation: open # open / owner / tenant,默认 open
admin-token: change-me # 留空则不校验管理接口(open 模式)
allow-script: true
admin:
cors-origin: "*" # 设计器通常跨端口访问
git:
tmpdir: ./flow-drop # 放入 *.json 会自动部署;置空可关闭
spring:
datasource: # 可选;不配则流程只存在内存中
url: jdbc:h2:mem:flow;DB_CLOSE_DELAY=-1;MODE=MySQL
driver-class-name: org.h2.Driver
username: sa
password: ""
sql:
init:
mode: always
schema-locations: classpath:demo/schema.sql
3. 部署第一个流程
{
"id": "demo-hello",
"desc": "示例:GET /demo/hello/{name}",
"group": "示例/问候",
"schemaVersion": 1,
"nodes": [
{
"id": "n1",
"type": "rest",
"props": { "method": "GET", "path": "/demo/hello/{name}" }
},
{
"id": "n2",
"type": "setBody",
"props": { "lang": "simple", "script": "hello, ${header.name}" }
}
]
}
curl -s -X POST 'http://localhost:8086/flow' \
-H 'Content-Type: application/json' \
-H 'X-Flow-Token: change-me' \
--data-binary @hello.json
返回 {"errorCode":0,"msg":"部署完成","routeId":"demo_ZGVtby1oZWxsbw"} 即成功。随后直接访问流程:
curl -s 'http://localhost:8086/demo/hello/bobo'
# hello, bobo
4. 运行自带 demo
mvn -Pdemo spring-boot:run -Dspring-boot.run.profiles=demo
- demo 使用 H2 内存库,启动时加载
demo/flows/demo-hello.json。 server.port=8080是 Spring Boot / Tomcat 端口,管理接口与 REST 流程都在 Jetty 的8086。- 启动日志应出现“已注册节点 75 个”,并开启日志终端
ws://localhost:8080/terminal。
配置参考
所有配置都在 flow.* 下。宿主未配置的项会使用 starter 的默认值。
| 配置项 | 默认值 | 说明 |
|---|---|---|
flow.enabled | true | 关闭后不装配管理接口与运行时。 |
flow.server | null(自动解析) | 服务标识,参与 routeId 生成;多实例共库时必须唯一。未配置时依次尝试 spring.application.name,再 fallback 到 "flow-server"。 |
flow.admin-token | 空 | open 模式的管理接口令牌;空则不校验。owner / tenant 模式改由登录态鉴权,不再要求该令牌。 |
flow.allow-script | true | 是否允许 groovy 等脚本字段;生产可关闭。 |
flow.rest-port | 8086 | Jetty 模式下管理接口与 REST 流程共用的端口。 |
flow.rest-component | jetty | jetty 独立端口;servlet 复用宿主 server.port(需宿主引入 camel-servlet-starter)。 |
flow.rest-context-path | /flow-api | Servlet 模式下的 REST 基路径,必须与宿主 camel.servlet.mapping.context-path 的前缀一致。 |
flow.isolation | open | 流程隔离:open 内网公开 / owner 单用户 / tenant 多租户。详见“隔离与数据安全”。 |
flow.secrets.* | 空 | 执行鉴权密钥表:键为 REST 节点声明的 secretRef,值为真实密钥。真实密钥不进流程 JSON。 |
flow.micrometer-id | 空 | 非空时自动为每条流程插入 micrometer counter/timer,key 前缀为此值。 |
flow.registry-max-size | 2048 | 已部署流程版本缓存上限;超出后 LRU 淘汰。 |
flow.max-flow-json-bytes | 524288 | 单份流程 JSON 大小上限(字节),防止大流程撑爆内存。 |
flow.node-packages | — | 额外扫描的节点包,配合自定义节点使用。 |
flow.admin.cors-origin | * | 管理接口 CORS 来源;多来源用逗号分隔。credentials=true 时不能为 *。 |
flow.admin.cors-headers | Content-Type,Authorization,X-Flow-Token | 管理接口允许的请求头,必须包含 X-Flow-Token 供设计器跨端口调用。 |
flow.admin.allow-credentials | false | 是否允许携带凭证;开启时 cors-origin 不能为 *。 |
flow.git.tmpdir | ./flow-drop | 监听该目录下的 .json 并即时部署(不落库);置空关闭。 |
flow.git.url | 空 | Git 仓库 URL;非空时启动时 clone 到 tmpdir。 |
flow.git.username | 空 | Git 仓库认证用户名。 |
flow.git.password | 空 | Git 仓库认证密码或 Token。 |
flow.terminal.enabled | false | 开启 WebSocket 日志终端,需宿主引入 websocket starter。 |
flow.terminal.backend | AUTO | 日志实现:AUTO(优先 Logback,其次 Log4j2)/ LOGBACK / LOG4J2。 |
flow.terminal.path | /terminal | WebSocket 路径。 |
flow.terminal.queue-capacity | 1024 | 待广播日志的队列容量,满后丢弃并告警。 |
flow.terminal.allowed-origins | * | 允许连接的来源。 |
flow.trace.enabled | false | 开启流程链路追踪,设计器可实时高亮执行节点。 |
flow.trace.path | /trace | WebSocket 路径。 |
flow.trace.queue-capacity | 4096 | 待广播 trace 事件的队列容量。 |
flow.trace.allowed-origins | * | 允许连接的来源。 |
flow.idempotent.redis-ttl | 0(永不过期) | Redis 幂等 key 的过期时间,秒。 |
flow.idempotent.jdbc-table | FLOW_IDEMPOTENT | JDBC 幂等仓库表名。 |
flow.deploy-broadcast.strategy | AUTO | 多实例部署同步策略:AUTO(按 classpath 自动选 KAFKA > REDIS > DB_POLL)/ DB_POLL / REDIS / KAFKA / DISABLED。 |
flow.deploy-broadcast.poll-interval | 5s | DB_POLL 模式轮询间隔;0 表示关闭。 |
flow.deploy-broadcast.poll-window | 30s | DB_POLL 模式每次对比数据库与本机 registry 的时间窗口;30 秒内的变更会被捕获。 |
flow.deploy-broadcast.redis-channel | flow-deploy | REDIS 模式 Pub/Sub channel(实际广播到 flow-deploy:{flow.server})。 |
flow.deploy-broadcast.kafka-topic | flow-deploy | KAFKA 模式 Topic。 |
flow.deploy-broadcast.ignore-self | true | 忽略本机发出的广播事件,防止回环。 |
持久化表
CREATE TABLE IF NOT EXISTS T_FLOWS (
ROUTE_ID VARCHAR(255) NOT NULL PRIMARY KEY,
FLOW_SERVER VARCHAR(255),
FLOW_URI VARCHAR(512),
FLOW_GROUP VARCHAR(255),
FLOW_DESC VARCHAR(512),
FLOW_JSON CLOB,
OWNER_ID VARCHAR(128),
TENANT_ID VARCHAR(128),
CREATE_TIME TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
UPDATE_TIME TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
没有 DataSource 时流程只存在内存里;有 DataSource 时自动使用 JdbcTemplate 读写 T_FLOWS,并在启动时按 flow.server 恢复流程。
OWNER_ID / TENANT_ID 是隔离列,可空、不建外键:owner 是不透明字符串,保证流程数据能随引擎独立迁走。老库升级需要补两列(H2 启动时自动执行,MySQL 需手工执行一次):
ALTER TABLE T_FLOWS ADD COLUMN OWNER_ID VARCHAR(128);
ALTER TABLE T_FLOWS ADD COLUMN TENANT_ID VARCHAR(128);
Flow JSON 协议
一份流程由元信息与节点数组组成。节点按数组顺序串联,容器节点在自己的 props 里嵌套子链。
{
"id": "order-audit", // 流程 id,用于生成 routeId
"desc": "订单审核", // 描述
"group": "业务/订单", // 分组,设计器左侧树按 / 分层
"schemaVersion": 1,
"nodes": [
{ "id": "n1", "type": "rest", "props": { "method": "POST", "path": "/order/audit" } },
{ "id": "n2", "type": "filter", "props": {
"filter": { "lang": "groovy", "script": "body.amount > 1000", "nodes": [
{ "id": "n3", "type": "log", "props": { "message": "大额订单" } }
] }
} }
]
}
字段说明
| 字段 | 必填 | 说明 |
|---|---|---|
id | 是 | 流程唯一标识;routeId = flow.server + "_" + Base64Url(id),不接受外部传入。 |
desc | 否 | 流程描述,展示在设计器与 /flows。 |
group | 否 | 分组路径,支持 / 分层。 |
schemaVersion | 否 | 协议版本,当前为 1。 |
nodes[].id | 建议 | 节点在流程内唯一;校验问题会带上 nodeId 便于定位。 |
nodes[].type | 是 | 节点类型,必须是已注册节点。 |
nodes[].props | 是 | 节点属性;必填项由节点的 requiredProps() 决定。 |
rest 节点进入的 JSON 默认是原始 InputStream。如果要写 body.amount、${body.items} 这类表达式,先在流程最前面加一个 unmarshal 节点:{"format":"json","type":"java.util.Map"}。纯字符串转发、写文件、发消息则不需要转换。容器节点的嵌套位置
choice:props.when[].nodes、props.otherwise.nodesfilter:props.filter.nodessplit/threads:props.nodesloop:props.loop.nodestry:props.tryBlock.nodes、props.catchBlocks[].nodes、props.finallyBlock.nodesdistributedLock/idempotentConsumer:props.nodes
表达式体系
所有表达式字段统一写成 {"lang": "...", "script": "..."}。
校验器会在部署前检查 lang 是否在白名单内,以及 script 是否为空。
完整支持 9 种语言,覆盖取值、条件、计算、Bean 调用四大类场景。
基本语法
{
"lang": "simple",
"script": "hello, ${header.name}!"
}
节点属性里如果直接写字符串("script": "hello")而不是 {"lang","script"} 对象,默认按 simple 语言处理。
语言速查
| lang | 求值类型 | 依赖 | 适用场景 |
|---|---|---|---|
simple | Expression + Predicate | 内置 | 取 Header / body / Property、拼接字符串、简单条件(最常用) |
constant | Expression + Predicate | 内置 | 固定值,完全不参与求值 |
header | Expression + Predicate | 内置 | 直接取某个 Header,等价于 simple: ${header.xxx} |
exchangeProperty | Expression + Predicate | 内置 | 取 Exchange 属性,等价于 simple: ${property.xxx} |
groovy | Expression + Predicate | camel-groovy-starter | 复杂计算、条件判断、Processor 脚本、构造 Map/List |
method | Expression + Predicate | 内置(Spring 容器) | 调用 Spring Bean 的方法 |
jsonpath | Expression + Predicate | camel-jsonpath-starter | 从 JSON 消息体取嵌套字段 |
xpath | Expression + Predicate | camel-xpath-starter | 从 XML 消息体取嵌套字段 |
spel | Expression + Predicate | 内置(Spring) | Spring 表达式语言,可访问 Bean、静态方法 |
Expression(求值返回值)和 Predicate(判断返回布尔)用同一套工厂,同一语言可以两种用法。
simple 语言
Camel Simple Language,最常用的表达式语言。语法是 ${xxx} 插值。
常用内置变量
| 变量 | 说明 | 示例 |
|---|---|---|
${body} | 消息体(原始对象) | body.amount → Map 取字段 |
${body.name} | 消息体的属性(Map 字段 / Bean getter) | body.items → List |
${body['name']} | 消息体的属性(下标形式,兼容特殊字符) | body['user.name'] |
${header.name} | 消息头 | header.tenant / header['X-Request-Id'] |
${property.name} | Exchange 属性(跨节点传递数据) | 配合 property 节点写入 |
${exchangeId} | 当前 Exchange 的唯一 ID | 生成唯一请求追踪 ID |
${routeId} | 当前路由 ID | 日志中标识来源 |
${date:now:yyyy-MM-dd HH:mm:ss} | 当前时间(指定格式) | date:now:yyyyMMdd |
${uuid} | 生成 UUID | uuid → 3b8f2... |
${random:100} | 0~n 的随机整数 | random:1000 |
${header.CamelHttpUri} | REST 入口的完整 URI | 调试用 |
${header.CamelHttpMethod} | REST 入口的 HTTP 方法 | GET / POST ... |
字符串操作
{
"type": "setHeader",
"props": {
"header": [
{ "name": "upperName", "lang": "simple", "script": "${header.name.toUpperCase()}" },
{ "name": "trimName", "lang": "simple", "script": "${header.name.trim()}" },
{ "name": "subName", "lang": "simple", "script": "${header.name.substring(0,5)}" },
{ "name": "now", "lang": "simple", "script": "${date:now:yyyyMMddHHmmss}" }
]
}
}
拼接文本 / 构造 JSON 文本
{
"type": "setBody",
"props": {
"lang": "simple",
"script": "{\"code\":0,\"message\":\"ok\",\"tenant\":\"${header.tenant}\"}"
}
}
rest 节点进入的 JSON 消息默认是原始 InputStream,
${body.amount} 这种写法会取到 null(因为 InputStream 没有 amount 属性)。
解决方法:在流程最前面加一个 unmarshal 节点(type=json)把它转成 java.util.Map,
之后 simple / groovy / jsonpath 都能正常读取 body 字段。简单条件(Predicate 用法)
{
"type": "filter",
"props": {
"filter": {
"lang": "simple",
"script": "${body.amount} > 100"
},
"nodes": [ ... ]
}
}
支持的比较运算符:== != > >= < <=
逻辑运算:&& ||。字符串相等用 == 'xxx'。
groovy 语言
完整 Groovy 语言,适合复杂计算、条件判断、Processor 脚本、构造结构化对象。 比 simple 能力强得多,但需要 Camel Groovy starter(starter 已内置)。
Groovy 里可用的隐式变量
| 变量 | 类型 | 说明 |
|---|---|---|
exchange | Exchange | Camel Exchange 对象,完整 API |
request | Message | 入站消息(exchange.getIn()) |
response | Message | 出站消息(exchange.getOut()) |
body | Object | 消息体(快捷方式,request.getBody()) |
headers | Map | 消息头 Map(request.getHeaders()) |
context | CamelContext | Camel 上下文 |
property | 方法 | property('key') 读 Exchange 属性 |
常用取值
// 读 header(两种写法等价)
headers.get('tenant')
exchange.getIn().getHeader('tenant')
// 读 body 字段(body 是 Map 时)
body.amount
body['user.name']
// 读 Exchange 属性(跨节点传递的数据)
exchange.getProperty('orderId')
// 当前路由 ID
exchange.getFromRouteId()
条件判断(Predicate)
{
"type": "choice",
"props": {
"when": [
{ "lang": "groovy", "script": "body.amount > 1000 && headers.get('tenant') == '2008'", "nodes": [ ... ] },
{ "lang": "groovy", "script": "body.items?.size() > 5", "nodes": [ ... ] }
],
"otherwise": { "nodes": [ ... ] }
}
}
构造返回值(Expression)
Groovy 可以直接返回 Map / List / String / Number,不需要 marshal 也能出 JSON(宿主 Jackson 会自动序列化)。
// 返回 Map(最常见)
return [code: 0, data: body.items, message: "ok"]
// 简写:最后一行自动作为返回值(不需要 return)
[code: 0, data: body.items]
// List 处理(收集/转换)
body.items.collect { item -> [id: item.id, name: item.name?.toUpperCase()] }
// 分组统计
body.items.groupBy { it.category }.collect { k, v -> [category: k, count: v.size()] }
// 访问 Spring Bean
ctx.getBean('demoService').lookup(body.id)
setBody、transform、script 节点里,Groovy 脚本的返回值会通过
exchange.getMessage().setBody(result) 自动写回。
但 process 节点 不会 自动写回,需要脚本内显式调用 exchange.getMessage().setBody(...)。Runtime.getRuntime().exec(...))。
生产环境建议将 flow.allow-script 设为 false 彻底禁用,或在管理接口前置网关鉴权并做脚本审计。其他语言
header / exchangeProperty
这两个是 simple 的快捷形式,语义等价于:
| 快捷写法 | 等价于 simple | script 示例 |
|---|---|---|
header | simple: ${script} | tenant → 读 Header 里的 tenant 值 |
exchangeProperty | simple: ${property.script} | orderId → 读 Exchange 属性里的 orderId |
constant | 完全不求值 | text/plain / hello world / 200 |
适用于 setHeader / property / filter 等节点里明确知道"就是取某个 header / property"的场景, 比写 simple 更简洁。
method(Spring Bean 调用)
调用 Spring 容器里的 Bean 方法,底层是 Camel 的 bean 组件。
{
"type": "setBody",
"props": {
"lang": "method",
"script": "userService.findById"
}
}
script 格式是 beanName.methodName。Bean 名是 Spring Bean 的默认 name(首字母小写的类名),
或者 @Service("xxx") 显式指定的名字。方法参数从当前消息的 body 传入,
返回值作为表达式求值结果。
jsonpath
从 JSON 消息体取嵌套字段,比 simple 的 body.xxx.yyy 更强大(支持过滤、通配、递归)。
消息体需要是 JSON 字符串(原始文本),或者先 unmarshal 成 Map。
| 脚本 | 说明 | 返回值 |
|---|---|---|
$.data.id | 取嵌套字段 | 标量值 |
$.items[*].id | 取数组所有元素的 id | List<Object> |
$.items[-1:] | 取数组最后一个元素 | Object |
$.items[?(@.price > 100)] | 过滤:price > 100 的元素 | List |
$..name | 递归查找所有层级的 name 字段 | List |
xpath
从 XML 消息体取字段,用法和标准 XPath 一致。
{
"lang": "xpath",
"script": "/order/item[price>100]/name"
}
spel(Spring Expression Language)
Spring 原生表达式语言,可以访问 Spring Bean、静态方法、进行类型转换。 # 前缀引用上下文变量,T() 调用静态方法。
// 读 body(#body 等价于 simple 的 ${body})
#body.amount
// 读 header
#headers['tenant']
// 调用静态方法
T(java.lang.Math).random() * 100
// 调用 Spring Bean
@userService.findById(#body.id)
// 条件运算
#body.amount > 1000 ? 'big' : 'small'
哪些节点用表达式
表达式在节点里分两种角色:Expression(求值返回值)和 Predicate(判断返回布尔)。
同一个 {"lang","script"} 对象传进工厂,工厂会根据节点意图自动决定用哪种。
用 Expression 的节点(求值/赋值)
| 节点 | 表达式字段 | 用途 |
|---|---|---|
setBody / transform | props.lang / props.script | 求值结果 → 新消息体 |
setHeader | props.header[].lang / script | 求值结果 → 写入指定 Header |
header | props.header[].lang / script | 同上(旧式) |
property | props.lang / props.script | 求值结果 → 写入 Exchange Property |
script | props.lang / props.script | 求值(Groovy 常用),返回值自动写回 body |
process | props.script | Groovy Processor,脚本里需显式调 exchange.getMessage().setBody(...) |
wireTap | props.body.lang / script | 求值结果 → wireTap 分支的消息体 |
aggregate | props.aggregate.lang / script | correlationKey 表达式(决定哪些消息聚合在一起) |
callSubflow | props.body.lang / script | 子流程入口的消息体 |
enrich / pollEnrich | props.aggregationStrategy | 聚合策略表达式 |
用 Predicate 的节点(条件判断)
| 节点 | 条件字段 | 用途 |
|---|---|---|
filter | props.filter.lang / script | 判断消息是否通过,不通过则停止 |
choice | props.when[].lang / script | 多路分支,第一个为 true 的 when 命中 |
aggregate | props.completion.predicate | 聚合完成条件(可选) |
delay | props.async | 布尔值,是 constant 表达式 |
dynamicRouter | props.lang / props.script | 返回要路由到的下一个节点 type 名称 |
默认 lang 规则
有些节点的表达式字段缺省时会有默认 lang 行为:
property节点:lang 缺省时默认按simple处理- 直接写字符串(不是
{"lang","script"}对象):一律按simple处理 - 显式传了
nulllang:校验器会报"缺少表达式语言 lang"
管理接口
管理接口在 Jetty 模式下监听 flow.rest-port;servlet 模式下挂在宿主 server.port 的 flow.rest-context-path(默认 /flow-api)下。open 模式配置了 flow.admin-token 时,请求需要携带 X-Flow-Token: <token> 或 Authorization: Bearer <token>;owner / tenant 模式改由登录态决定归属,不再要求管理令牌。
GET /nodes 是静态节点元数据,不读库也不暴露流程,默认不校验令牌。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | / | 引导信息:名称、版本、server、restPort、nodeCount、终端 / 追踪状态。 |
| POST | /flow | 解析、校验、部署并落库,返回 routeId。 |
| POST | /flow/validate | 只校验,返回 valid / errors / issues / routeId / uri。 |
| GET | /flow/{routeId} | 查看流程详情。 |
| GET | /flows | 按 group 分级的流程树。 |
| GET | /nodes | 节点元数据:分类、必填、字段类型、枚举、默认值、容器类型。 |
| GET | /subflows | 以 from direct: 为入口的子流程列表。 |
| DELETE | /flow/{routeId} | 删除路由并从库删除。 |
| POST | /groovySyntaxCheck | Groovy 语法检查,成功返回纯文本 OK。 |
校验结果
{
"valid": false,
"errors": ["nodes[1].props.lang 不支持的语言:foo"],
"issues": [
{ "path": "nodes[1].props.lang", "nodeId": "n2", "nodeType": "setBody",
"field": "lang", "message": "不支持的语言:foo" }
]
}
校验覆盖必填 props、节点类型注册、入口合法性、重复 nodeId、表达式 lang 白名单、script 非空、Groovy 语法,以及 flow.allow-script=false 时的脚本拒绝。
部署与删除
# 部署(幂等,重复部署会替换旧路由)
curl -X POST 'http://localhost:8086/flow' \
-H 'Content-Type: application/json' \
-H 'X-Flow-Token: change-me' \
--data-binary @flow.json
# 只校验
curl -X POST 'http://localhost:8086/flow/validate' \
-H 'Content-Type: application/json' \
-H 'X-Flow-Token: change-me' \
--data-binary @flow.json
# 删除
curl -X DELETE 'http://localhost:8086/flow/demo_ZGVtby1oZWxsbw' \
-H 'X-Flow-Token: change-me'
隔离与数据安全
隔离只作用于控制平面:谁能看到、修改、删除哪些流程。数据平面(已经发布出去的 REST 端点)不做归属过滤,鉴权交给网关或流程自身的执行鉴权。
两个平面
| 平面 | 接口 | 规则 |
|---|---|---|
| 控制平面 | GET /flows、GET /flow/{routeId}、POST /flow、POST /flow/test/{routeId}、DELETE /flow/{routeId}、GET /subflows | 按 flow.isolation 过滤;不可见的流程统一返回 404,避免被用来探测。 |
| 数据平面 | 流程 rest 节点发布出去的路径(servlet 模式下形如 /flow-api/api/scenario/member) | 永不过滤,启动时从库全量加载;由网关或执行鉴权保护。 |
三种模式
| flow.isolation | 可见条件 | 典型场景 |
|---|---|---|
open(默认) | 不过滤,所有控制平面接口共享同一视图 | 内网、单团队内部工具;兼容升级前的行为。 |
owner | flow.ownerId 等于当前登录用户 | SaaS、公网体验环境,一人一份流程。 |
tenant | flow.tenantId 等于当前租户 | 多租户平台。租户内的细粒度可见性 starter 不管,由宿主业务控制。 |
行为细节
- owner / tenant 模式下解析不到用户 / 租户标识 → 401;有身份但不是自己的流程 → 404,列表里直接不出现。
- 部署时自动写入归属;同一 routeId 已被其他用户 / 租户占用时拒绝覆盖,避免隔离被绕过。
- 归属存在
T_FLOWS.OWNER_ID/TENANT_ID,重启恢复时从隔离列还原;流程 JSON 本身不保存归属。 - open 模式控制平面沿用
flow.admin-token;owner / tenant 模式不再要求管理令牌,改由登录态决定归属,浏览器端无需持有服务端密钥。 GET /nodes是静态元数据,任何模式都不要求令牌。
接入宿主登录态
starter 不绑定具体认证方案,宿主注册一个 FlowScopeResolver Bean 即可(没有注册时默认返回空范围):
@Bean
FlowScopeResolver flowScopeResolver(JwtTokenProvider jwt) {
return exchange -> {
String authorization = exchange.getMessage().getHeader("Authorization", String.class);
if (authorization == null || !authorization.startsWith("Bearer ")) {
return FlowScope.NONE;
}
Claims claims = jwt.parseToken(authorization.substring(7));
return new FlowScope(String.valueOf(claims.get("userId")), null);
};
}
owner 模式返回 ownerId,tenant 模式返回 tenantId。未注册实现时 owner / tenant 模式下控制平面会一直 401,而不会退化成“谁都能看”。
执行鉴权
执行鉴权管的是数据平面:某个流程的 REST 入口是否允许调用。配置写在 REST 入口节点的 props 里,真实密钥只放宿主配置。
{
"id": "order-audit",
"nodes": [
{
"id": "n1",
"type": "rest",
"props": {
"method": "POST",
"path": "/api/orders",
"auth": "token",
"authHeader": "Authorization",
"secretRef": "order-sign"
}
}
]
}
| props | 默认值 | 说明 |
|---|---|---|
auth | public | public 不鉴权;token 校验请求头里的密钥。 |
authHeader | Authorization | 从哪个请求头取密钥;头名大小写不敏感。 |
secretRef | — | 密钥在 flow.secrets 里的键;auth=token 时必填。 |
密钥配置
flow.secrets 是键值映射(Map),不是数组:键就是节点里声明的 secretRef,值是真实密钥,可以配多个。
flow:
secrets:
order-sign: "9f2c...真实密钥"
partner-a: "另一个密钥"
等价写法是 flow.secrets.order-sign=...。密钥不要写进流程 JSON,也不建议放在命令行参数里(会出现在进程列表)。
行为
- 通过:继续执行业务节点。支持
Bearer <密钥>与裸密钥两种写法。 - 不通过:直接返回 401 与
{"errorCode":401,"msg":"执行鉴权失败"},后续业务节点不会执行。 - 部署校验:
auth=token但没写secretRef,或secretRef在flow.secrets里不存在 → 部署与POST /flow/validate都直接报错,不会静默放行。 - 不写
auth等价public,行为与旧版本一致。
三种流程定义方式
Java Builder 与界面配置最终都产出同一份 Flow JSON,共用节点注册、校验与编译;原生 Camel 路由独立存在。三种方式可以在同一个应用里共存。
| 方式 | 用法 | 是否落库 |
|---|---|---|
| 原生 Camel | 宿主自己写 RouteBuilder | 否,/flows 与设计器不可见 |
| Java Builder | FlowBuilder + NodeBuilder,声明为 Bean 后启动自动部署 | 否,代码即版本 |
| 界面配置 | 设计器生成 JSON 后调 POST /flow | 是 |
@Bean
FlowBuilder helloFlow() {
return FlowBuilder.create("hello")
.desc("示例流程")
.group("示例/问候")
.node(NodeBuilder.rest("GET", "/hello/{name}").prop("desc", "返回一句问候"))
.node(NodeBuilder.setHeader("Content-Type", "constant", "text/plain; charset=UTF-8"))
.node(NodeBuilder.setBody("simple", "hello, ${header.name}"));
}
Builder 在启动阶段(早于从数据库恢复)按 @Order 部署且不写库;同 id 的库内流程随后会覆盖它。容器节点用链式方法表达:choice().when(...).otherwise(...)、filter(...)、split(...)、threads(...)、loopCount(...)、loopWhile(...)、tryNode(...).catchBlock(...).finallyBody(...)。
可视化设计器
flow-designer-web 是配套设计器:React 18 + antd 5 + Redux Toolkit + React Flow。节点面板由后端 GET /nodes 元数据驱动,后端新增节点无需改前端。
本地启动
# 终端 1:启动后端(starter demo,管理接口 8086)
cd camel-flow-server-starter
mvn -Pdemo spring-boot:run -Dspring-boot.run.profiles=demo
# 终端 2:启动设计器
cd flow-designer-web
npm install
npm run dev # http://localhost:5173
连接已有后端
复制 .env.example 为 .env.local,按需修改:
| 变量 | 默认值 | 说明 |
|---|---|---|
VITE_API_BASE | /flow-api | 流程引擎基地址;直连后端时填完整地址(如 http://localhost:8090/flow-api)。 |
VITE_PROXY_API_TARGET | http://localhost:8090 | 开发代理目标;单端口模式下宿主接口与流程接口同源。 |
VITE_TERMINAL_URL | 空 | 日志终端完整地址;留空则用当前 host + 后端返回的路径。 |
使用步骤
- 左侧「节点」页签选择入口节点(
rest、from、timer等)作为链路起点。 - 选中节点后点击其它节点,新节点插入到选中项之后;右侧表单填写必填项。
- Header 填写流程 id / desc / group,点「校验」查看问题,点「保存」走
POST /flow部署并落库。 - 已部署流程在左侧「流程」页签按分组树展示,点击叶子加载到画布继续编辑。
设计器支持撤销重做、校验问题定位、日志终端、链路追踪高亮;登录使用宿主的账号密码(JWT),也保留管理令牌入口。当前画布以线性链路为主,容器节点的子链支持查看与编辑。
扩展自定义节点
实现 FlowNode,用 @FlowNodeDef 声明 type,再把包加入 flow.node-packages 即可。
package com.example.flow.nodes;
import cn.seeyou520.flow.domain.NodeSpec;
import cn.seeyou520.flow.protocol.ExpressionFactory;
import cn.seeyou520.flow.registry.FlowBuildContext;
import cn.seeyou520.flow.registry.FlowNode;
import cn.seeyou520.flow.registry.FlowNodeDef;
import org.apache.camel.model.ProcessorDefinition;
import java.util.List;
@FlowNodeDef(value = "setCorrelationId", order = 200)
@SuppressWarnings("rawtypes")
public class SetCorrelationIdNode implements FlowNode {
@Override
public List<String> requiredProps() {
return List.of("header");
}
@Override
public ProcessorDefinition append(FlowBuildContext ctx, NodeSpec node, ProcessorDefinition current) {
return current.setHeader(node.reqStr("header"),
ExpressionFactory.expression("simple", "${exchangeId}"));
}
}
flow:
node-packages:
- com.example.flow.nodes
启动时会扫描并注册,重复 type 会直接启动失败;扫描期无法加载的节点会被跳过。自定义入口节点额外实现 entryUri(NodeSpec) 并在注解上写 entry = true。
部署指南
推荐把三个部分一起部署:文档站(静态)、设计器(静态)、后端(flow-scenario 或你自己的宿主)。仓库根目录的 deploy/ 已经准备好 Nginx 与 Docker Compose 配置。
方式一:Docker Compose(推荐)
# 在项目根目录执行
cd deploy
cp .env.example .env # 编辑 .env,替换 FLOW_ADMIN_TOKEN
docker compose up -d --build
# 首次初始化:部署 flow-scenario 的 6 条种子流程
FLOW_SCENARIO_AUTO_DEPLOY=true docker compose up -d backend
# 访问(WEB_PORT 默认 8443,云厂商安全组通常只放行少数端口)
# 文档站 http://<服务器IP>:8443/
# 节点目录 http://<服务器IP>:8443/nodes/
# 设计器 http://<服务器IP>:8443/designer/
# 控制平面 http://<服务器IP>:8443/flow-api/flows (需要登录态)
# 业务接口 http://<服务器IP>:8443/flow/ + 流程 rest 节点里的 path
Compose 中包含两个服务:backend 运行 flow-scenario,只监听 8090 一个端口(宿主 Web、控制平面 /flow-api、业务 REST 端点、日志终端与 Trace WebSocket 全在这里);web 用 Nginx 托管文档站与设计器,并把 /api、/flow-api、/flow、/terminal、/trace 反代到后端。
WEB_PORT(默认 8443)。/flow-api/ 是设计器控制平面(原样转发),/flow/ 是流程业务端点(Nginx 改写成 /flow-api/),/api/ 是宿主自己的业务接口。流程里 rest 节点写 /api/scenario/member,外部访问仍是 http://IP:8443/flow/api/scenario/member。8090 只绑定 127.0.0.1,不直接暴露公网。http://IP:端口 访问;安全组只放行 WEB_PORT 一个端口即可。备案通过后再添加域名解析与 443 证书,并把页脚的「备案号:待备案」替换为真实备案号。方式二:JAR + Nginx
# 1. 构建后端(需要 JDK 21 + Maven)
cd camel-flow-server-starter && mvn -DskipTests install
cd ../flow-scenario && mvn -DskipTests package
# 2. 运行
java -Xms256m -Xmx512m -jar flow-scenario/target/flow-scenario-1.0.0.jar \
--flow.admin-token='换成你自己的口令'
# 3. 构建前端静态资源
cd flow-designer-web
npm ci
npx tsc --noEmit
npx vite build --base=/designer/
# 4. 用 deploy/nginx.conf 托管 flow-designer-web/dist
JAR 方式下,把 deploy/nginx.conf 里的 backend:8090 改成 127.0.0.1:8090,并把 root 指向实际的静态目录;没有官网首页时可以把 / 重定向到 /designer/。后端只需要暴露 8090 一个端口。
反向代理路径
| 路径 | 目标 | 说明 |
|---|---|---|
/designer/ | flow-designer-web/dist | 可视化设计器,构建时 --base=/designer/。 |
/api/ | http://backend:8090 | 宿主业务接口(登录 / 注册等),路径原样转发。 |
/flow-api/ | http://backend:8090 | 流程引擎控制平面,路径原样转发。 |
/flow/ | http://backend:8090/flow-api/ | 流程业务端点,Nginx 把 /flow/ 改写成 /flow-api/。 |
/terminal | http://backend:8090 | 日志终端 WebSocket,需要 Upgrade 头。 |
/trace | http://backend:8090 | 链路追踪 WebSocket,需要 Upgrade 头。 |
上线检查清单
- 公网体验环境把
flow.isolation设为owner或tenant,并接入登录态;不要用open。 - owner / tenant 模式下控制平面不再要求
flow.admin-token,但宿主网关必须校验登录态,否则 401 会退化成任何人都能注册登录。 - 需要对外开放的流程入口配置执行鉴权(
auth=token+secretRef),真实密钥放flow.secrets,不要写进流程 JSON。 - 生产环境将
flow.allow-script设为false;公网演示建议给/designer/再加一层 Nginx Basic Auth 或 IP 白名单。 - 日志终端可能包含业务敏感数据,公网部署建议关闭
flow.terminal.enabled。 - H2 仅适合演示;生产请换成 MySQL / PostgreSQL,并提前创建
T_FLOWS表(含OWNER_ID/TENANT_ID)。 - 关闭
spring.h2.console,示例工程默认开启,仅适合本地调试。 - 多实例部署时,
flow.server必须唯一,否则启动恢复会互相覆盖流程。 - 中国大陆服务器绑定域名前需要完成 ICP 备案;未备案可先用
IP:端口或香港 / 海外服务器做测试。
微服务宿主:注册中心与服务发现
starter 自身不引入 Spring Cloud、Nacos、Eureka、Consul 等注册中心依赖——宿主自己选。但 starter 通过 SPI + 反射条件装配,在宿主已引注册中心依赖时自动接上:宿主零改动,starter 零污染。
两个 SPI
| SPI | 方向 | 说明 |
|---|---|---|
FlowServerDiscovery | 读 | 返回当前在线的 flow runtime 实例列表,供设计器 FlowTree 按服务分组展示。 |
FlowServerAutoRegistration | 写 | 宿主启动时把 flow.server 写入注册中心元数据/标签。其他 Discovery 实现据此过滤自己关心的服务。 |
五种注册中心适配器(反射 + 条件装配)
| 注册中心 | 条件 | 宿主需要引什么 |
|---|---|---|
| 默认(无注册中心) | 以上都不是 | 什么都不加 → 空实现返回空列表,单宿主模式 |
| Nacos | classpath 有 com.alibaba.nacos.api.naming.NamingService | spring-cloud-starter-alibaba-nacos-discovery |
| Eureka | classpath 有 com.netflix.discovery.EurekaClient | spring-cloud-starter-netflix-eureka-client |
| Consul | classpath 有 ConsulDiscoveryClient | spring-cloud-starter-consul-discovery |
| ZooKeeper | classpath 有 CuratorFramework | curator-recipes(Dubbo 宿主传递引入) |
| Kubernetes | 环境变量 KUBERNETES_SERVICE_HOST 存在 | 可选:spring-cloud-starter-kubernetes-client,没引时自动用原生 K8s REST API |
自动注册:flow.server 写入注册中心
宿主启动时,FlowServerAutoRegistration.register() 会把 flow.server=xxx 写入当前实例的元数据(Nacos/Eureka/Consul)或标签(K8s labels / ZK 节点数据)。Discovery 实现拉到实例列表后,只过滤 metadata/tags 里有 flow.server 的实例。
FlowServerAutoRegistration.register() 在启动时 patch 自己 Pod 的 labels,加 flow.server=xxx。Discovery 侧读 Pod labels。这需要 ServiceAccount 有 patch pods 权限(默认只读,需要显式 Role/RoleBinding)。宿主零改动接入示例
BladeX 宿主已经引了 Nacos,只需加 starter 依赖:
<dependency>
<groupId>cn.seeyou520</groupId>
<artifactId>flow-server-starter</artifactId>
<version>1.0.0</version>
</dependency>
其他什么都不用做。宿主 Nacos 已注册的实例会被 starter 自动补充 flow.server 元数据,GET /flow-api/servers 会返回所有在线 runtime。
flow.server 自动取值
宿主不显式配 flow.server 时,starter 自动 fallback 到 spring.application.name——和微服务世界对齐。
多实例部署同步
同一个 flow.server 跑多个 Pod 时,一个实例 deploy 了新流程,其他实例还不知道——它们的内存 registry 里没有这条路由。FlowDeploymentBroadcaster 负责把部署变更同步给同 server 的其他实例。
三种策略
| 策略 | 延迟 | 依赖 | 说明 |
|---|---|---|---|
| DB_POLL(默认) | ~5s | 零 | 每 N 秒对比数据库 T_FLOWS 和本机内存 registry。DB 有内存没有 → 部署;内存有 DB 没有 → 删除。 |
| REDIS | 毫秒 | Spring Data Redis | 反射 RedisConnectionFactory,Pub/Sub 广播到 flow-deploy:{flow.server} 独立 channel,自动忽略本机事件。 |
| KAFKA | 毫秒 | spring-kafka | 反射 KafkaTemplate 做生产端;消费端需要宿主自行注册 @KafkaListener(starter 不负责监听器注册)。 |
自动选择(AUTO 策略)
按 classpath 优先级:KAFKA → REDIS → DB_POLL。宿主 classpath 里有 Kafka 依赖就自动用 Kafka,没有 Kafka 有 Redis 就用 Redis,什么都没有就用零依赖的 DB_POLL。
配置示例
flow:
deploy-broadcast:
strategy: AUTO # AUTO / DB_POLL / REDIS / KAFKA / DISABLED
poll-interval: 5s # DB_POLL 轮询间隔
redis-channel: flow-deploy
kafka-topic: flow-deploy
ignore-self: true # 忽略本机发出的事件,防回环
DB_POLL 工作原理
每 poll-interval 毫秒执行一次 diff:
- SELECT
T_FLOWS里当前flow.server的全部流程 - 遍历:DB 有、内存没有 → 调
DeployService.deploy()补部署 - 遍历:内存有、DB 没有 → 调
DeployService.remove()卸载 - 流程内容变了(版本升级)→ 重新 deploy 覆盖
完全零额外依赖,所有 starter 宿主(包括单体)都能用。唯一缺点是有 poll-interval 的延迟(默认 5 秒),对部署实时性要求极高时建议用 Redis/Kafka。
Redis Pub/Sub 工作原理
广播到 flow-deploy:{flow.server} 独立 channel,每个 flow.server 天然隔离,不会互相污染。消息体是 JSON:
{
"flowServer": "scenario-server",
"action": "DEPLOY",
"routeId": "scenario_ZGVtby1oZWxsbw",
"flowJson": "...完整 Flow JSON...",
"sourceInstanceId": "scenario-server:pid-12345",
"timestamp": 1700000000000
}
Kafka 使用注意
starter 只负责生产端(broadcast),消费端需要宿主自行注册 @KafkaListener:
@KafkaListener(topics = "${flow.deploy-broadcast.kafka-topic:flow-deploy}",
groupId = "flow-deploy-${flow.server:flow-server}")
public void onDeployEvent(String json) {
// 反序列化后调 DeployService.deploy() / remove()
deployService.applyBroadcastEvent(event);
}
Kafka 的消费端注册需要 KafkaListenerContainerFactory、反序列化器等,starter 留给宿主掌控。
常见问题
部署成功但访问 404?
先看 flow.rest-component:jetty 模式下 REST 流程与管理接口在 flow.rest-port(默认 8086);servlet 模式下都在宿主 server.port 的 flow.rest-context-path 下(默认 /flow-api)。单端口部署(如 flow-scenario)请访问 http://host:8090/flow-api/api/...。
流程列表是空的 / 看不到别人的流程?
这是 owner / tenant 隔离生效的表现。控制平面只返回当前登录身份创建的流程,访问他人流程统一 404。升级前遗留的无主流程(OWNER_ID 为空)不会出现在任何人的列表里。
部署时提示“执行鉴权密钥未配置”?
入口节点写了 auth=token / secretRef,但宿主 flow.secrets 里没有同名键。补充配置后重启,或改成 auth=public。
节点能注册,但部署时报组件找不到?
节点类只负责拼接 URI,真正执行依赖对应的 Camel 组件。按节点页的“依赖”提示引入 starter,然后重启宿主。
修改流程后重启被覆盖?
检查是否开启了种子自动部署(如 flow-scenario 的 flow.scenario.auto-deploy)。默认关闭时以 T_FLOWS 为准;开启后 jar 内种子会覆盖同 id 流程。
设计器打开后一直弹登录框?
open 模式下配置了 flow.admin-token,需要在登录框的「管理令牌」页签输入;owner / tenant 模式下则需要宿主提供账号密码登录并返回 JWT。令牌保存在 localStorage。
日志终端 / 链路追踪没反应?
分别检查 flow.terminal.enabled 与 flow.trace.enabled,并确认 Nginx 对 /terminal、/trace 配置了 WebSocket Upgrade。
为什么 routeId 和我填的 id 不一样?
routeId 由服务端生成:flow.server + "_" + Base64Url(id),不接受外部传入,避免不同服务之间冲突。
script 节点执行了,但消息体没变?
不同 Camel 版本对脚本返回值的回写行为存在差异。建议在脚本里显式写 exchange.getMessage().setBody(...) 或 setHeader(...),示例也采用这种写法。