Flow ServerStarter

使用文档

从安装、配置到 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 执行。

一句话理解:设计器产出 JSON → POST /flow 校验、编译、落库 → Camel 路由立即生效 → 重启自动恢复。

架构

设计器 / 低代码平台React + 元数据表单
Flow JSON
Flow Server Starter解析 · 校验 · 编译 · 路由
运行时
Apache Camel 475 个内置节点

适合谁

  • 想给内部系统加一个可视化流程编排层,但不想自己实现运行时。
  • 已有 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. 引入依赖

pom.xml
<dependency>
  <groupId>cn.seeyou520</groupId>
  <artifactId>flow-server-starter</artifactId>
  <version>1.0.0</version>
</dependency>

如果制品还没发布到中央仓库或私服,先在 starter 目录执行 mvn -DskipTests install 安装到本地仓库。

2. 添加配置

application.yml
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. 部署第一个流程

hello.json
{
  "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.enabledtrue关闭后不装配管理接口与运行时。
flow.servernull(自动解析)服务标识,参与 routeId 生成;多实例共库时必须唯一。未配置时依次尝试 spring.application.name,再 fallback 到 "flow-server"。
flow.admin-token空open 模式的管理接口令牌;空则不校验。owner / tenant 模式改由登录态鉴权,不再要求该令牌。
flow.allow-scripttrue是否允许 groovy 等脚本字段;生产可关闭。
flow.rest-port8086Jetty 模式下管理接口与 REST 流程共用的端口。
flow.rest-componentjettyjetty 独立端口;servlet 复用宿主 server.port(需宿主引入 camel-servlet-starter)。
flow.rest-context-path/flow-apiServlet 模式下的 REST 基路径,必须与宿主 camel.servlet.mapping.context-path 的前缀一致。
flow.isolationopen流程隔离:open 内网公开 / owner 单用户 / tenant 多租户。详见“隔离与数据安全”。
flow.secrets.*空执行鉴权密钥表:键为 REST 节点声明的 secretRef,值为真实密钥。真实密钥不进流程 JSON。
flow.micrometer-id空非空时自动为每条流程插入 micrometer counter/timer,key 前缀为此值。
flow.registry-max-size2048已部署流程版本缓存上限;超出后 LRU 淘汰。
flow.max-flow-json-bytes524288单份流程 JSON 大小上限(字节),防止大流程撑爆内存。
flow.node-packages—额外扫描的节点包,配合自定义节点使用。
flow.admin.cors-origin*管理接口 CORS 来源;多来源用逗号分隔。credentials=true 时不能为 *。
flow.admin.cors-headersContent-Type,Authorization,X-Flow-Token管理接口允许的请求头,必须包含 X-Flow-Token 供设计器跨端口调用。
flow.admin.allow-credentialsfalse是否允许携带凭证;开启时 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.enabledfalse开启 WebSocket 日志终端,需宿主引入 websocket starter。
flow.terminal.backendAUTO日志实现:AUTO(优先 Logback,其次 Log4j2)/ LOGBACK / LOG4J2。
flow.terminal.path/terminalWebSocket 路径。
flow.terminal.queue-capacity1024待广播日志的队列容量,满后丢弃并告警。
flow.terminal.allowed-origins*允许连接的来源。
flow.trace.enabledfalse开启流程链路追踪,设计器可实时高亮执行节点。
flow.trace.path/traceWebSocket 路径。
flow.trace.queue-capacity4096待广播 trace 事件的队列容量。
flow.trace.allowed-origins*允许连接的来源。
flow.idempotent.redis-ttl0(永不过期)Redis 幂等 key 的过期时间,秒。
flow.idempotent.jdbc-tableFLOW_IDEMPOTENTJDBC 幂等仓库表名。
flow.deploy-broadcast.strategyAUTO多实例部署同步策略:AUTO(按 classpath 自动选 KAFKA > REDIS > DB_POLL)/ DB_POLL / REDIS / KAFKA / DISABLED。
flow.deploy-broadcast.poll-interval5sDB_POLL 模式轮询间隔;0 表示关闭。
flow.deploy-broadcast.poll-window30sDB_POLL 模式每次对比数据库与本机 registry 的时间窗口;30 秒内的变更会被捕获。
flow.deploy-broadcast.redis-channelflow-deployREDIS 模式 Pub/Sub channel(实际广播到 flow-deploy:{flow.server})。
flow.deploy-broadcast.kafka-topicflow-deployKAFKA 模式 Topic。
flow.deploy-broadcast.ignore-selftrue忽略本机发出的广播事件,防止回环。

持久化表

T_FLOWS
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 里嵌套子链。

Flow JSON
{
  "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 请求体不是 Map:通过 rest 节点进入的 JSON 默认是原始 InputStream。如果要写 body.amount、${body.items} 这类表达式,先在流程最前面加一个 unmarshal 节点:{"format":"json","type":"java.util.Map"}。纯字符串转发、写文件、发消息则不需要转换。

容器节点的嵌套位置

  • choice:props.when[].nodes、props.otherwise.nodes
  • filter:props.filter.nodes
  • split / threads:props.nodes
  • loop:props.loop.nodes
  • try:props.tryBlock.nodes、props.catchBlocks[].nodes、props.finallyBlock.nodes
  • distributedLock / idempotentConsumer:props.nodes

表达式体系

所有表达式字段统一写成 {"lang": "...", "script": "..."}。 校验器会在部署前检查 lang 是否在白名单内,以及 script 是否为空。 完整支持 9 种语言,覆盖取值、条件、计算、Bean 调用四大类场景。

基本语法

表达式结构
{
  "lang": "simple",
  "script": "hello, ${header.name}!"
}

节点属性里如果直接写字符串("script": "hello")而不是 {"lang","script"} 对象,默认按 simple 语言处理。

语言速查

lang求值类型依赖适用场景
simpleExpression + Predicate内置取 Header / body / Property、拼接字符串、简单条件(最常用)
constantExpression + Predicate内置固定值,完全不参与求值
headerExpression + Predicate内置直接取某个 Header,等价于 simple: ${header.xxx}
exchangePropertyExpression + Predicate内置取 Exchange 属性,等价于 simple: ${property.xxx}
groovyExpression + Predicatecamel-groovy-starter复杂计算、条件判断、Processor 脚本、构造 Map/List
methodExpression + Predicate内置(Spring 容器)调用 Spring Bean 的方法
jsonpathExpression + Predicatecamel-jsonpath-starter从 JSON 消息体取嵌套字段
xpathExpression + Predicatecamel-xpath-starter从 XML 消息体取嵌套字段
spelExpression + 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}生成 UUIDuuid → 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 文本

用 simple 拼 JSON 文本(注意双引号转义)
{
  "type": "setBody",
  "props": {
    "lang": "simple",
    "script": "{\"code\":0,\"message\":\"ok\",\"tenant\":\"${header.tenant}\"}"
  }
}
REST 进来的 body 是 InputStream: 通过 rest 节点进入的 JSON 消息默认是原始 InputStream, ${body.amount} 这种写法会取到 null(因为 InputStream 没有 amount 属性)。 解决方法:在流程最前面加一个 unmarshal 节点(type=json)把它转成 java.util.Map, 之后 simple / groovy / jsonpath 都能正常读取 body 字段。

简单条件(Predicate 用法)

filter 里用 simple 做条件判断
{
  "type": "filter",
  "props": {
    "filter": {
      "lang": "simple",
      "script": "${body.amount} > 100"
    },
    "nodes": [ ... ]
  }
}

支持的比较运算符:== != > >= < <= 逻辑运算:&& ||。字符串相等用 == 'xxx'。

groovy 语言

完整 Groovy 语言,适合复杂计算、条件判断、Processor 脚本、构造结构化对象。 比 simple 能力强得多,但需要 Camel Groovy starter(starter 已内置)。

Groovy 里可用的隐式变量

变量类型说明
exchangeExchangeCamel Exchange 对象,完整 API
requestMessage入站消息(exchange.getIn())
responseMessage出站消息(exchange.getOut())
bodyObject消息体(快捷方式,request.getBody())
headersMap消息头 Map(request.getHeaders())
contextCamelContextCamel 上下文
property方法property('key') 读 Exchange 属性

常用取值

Groovy 取值
// 读 header(两种写法等价)
headers.get('tenant')
exchange.getIn().getHeader('tenant')

// 读 body 字段(body 是 Map 时)
body.amount
body['user.name']

// 读 Exchange 属性(跨节点传递的数据)
exchange.getProperty('orderId')

// 当前路由 ID
exchange.getFromRouteId()

条件判断(Predicate)

Groovy 条件分支(?. 安全调用避免 null 指针)
{
  "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 会自动序列化)。

Groovy 返回值构造
// 返回 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)
Groovy 的 return 值会自动写回消息体: 在 setBody、transform、script 节点里,Groovy 脚本的返回值会通过 exchange.getMessage().setBody(result) 自动写回。 但 process 节点 不会 自动写回,需要脚本内显式调用 exchange.getMessage().setBody(...)。
安全提示:Groovy 脚本可以执行任意代码(包括 Runtime.getRuntime().exec(...))。 生产环境建议将 flow.allow-script 设为 false 彻底禁用,或在管理接口前置网关鉴权并做脚本审计。

其他语言

header / exchangeProperty

这两个是 simple 的快捷形式,语义等价于:

快捷写法等价于 simplescript 示例
headersimple: ${script}tenant → 读 Header 里的 tenant 值
exchangePropertysimple: ${property.script}orderId → 读 Exchange 属性里的 orderId
constant完全不求值text/plain / hello world / 200

适用于 setHeader / property / filter 等节点里明确知道"就是取某个 header / property"的场景, 比写 simple 更简洁。

method(Spring Bean 调用)

调用 Spring 容器里的 Bean 方法,底层是 Camel 的 bean 组件。

method 调用示例
{
  "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取数组所有元素的 idList<Object>
$.items[-1:]取数组最后一个元素Object
$.items[?(@.price > 100)]过滤:price > 100 的元素List
$..name递归查找所有层级的 name 字段List

xpath

从 XML 消息体取字段,用法和标准 XPath 一致。

xpath 示例
{
  "lang": "xpath",
  "script": "/order/item[price>100]/name"
}

spel(Spring Expression Language)

Spring 原生表达式语言,可以访问 Spring Bean、静态方法、进行类型转换。 # 前缀引用上下文变量,T() 调用静态方法。

SpEL 示例
// 读 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 / transformprops.lang / props.script求值结果 → 新消息体
setHeaderprops.header[].lang / script求值结果 → 写入指定 Header
headerprops.header[].lang / script同上(旧式)
propertyprops.lang / props.script求值结果 → 写入 Exchange Property
scriptprops.lang / props.script求值(Groovy 常用),返回值自动写回 body
processprops.scriptGroovy Processor,脚本里需显式调 exchange.getMessage().setBody(...)
wireTapprops.body.lang / script求值结果 → wireTap 分支的消息体
aggregateprops.aggregate.lang / scriptcorrelationKey 表达式(决定哪些消息聚合在一起)
callSubflowprops.body.lang / script子流程入口的消息体
enrich / pollEnrichprops.aggregationStrategy聚合策略表达式

用 Predicate 的节点(条件判断)

节点条件字段用途
filterprops.filter.lang / script判断消息是否通过,不通过则停止
choiceprops.when[].lang / script多路分支,第一个为 true 的 when 命中
aggregateprops.completion.predicate聚合完成条件(可选)
delayprops.async布尔值,是 constant 表达式
dynamicRouterprops.lang / props.script返回要路由到的下一个节点 type 名称

默认 lang 规则

有些节点的表达式字段缺省时会有默认 lang 行为:

  • property 节点:lang 缺省时默认按 simple 处理
  • 直接写字符串(不是 {"lang","script"} 对象):一律按 simple 处理
  • 显式传了 null lang:校验器会报"缺少表达式语言 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/groovySyntaxCheckGroovy 语法检查,成功返回纯文本 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
# 部署(幂等,重复部署会替换旧路由)
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(默认)不过滤,所有控制平面接口共享同一视图内网、单团队内部工具;兼容升级前的行为。
ownerflow.ownerId 等于当前登录用户SaaS、公网体验环境,一人一份流程。
tenantflow.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 即可(没有注册时默认返回空范围):

FlowScopeResolver
@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,而不会退化成“谁都能看”。

公网不要用 open:open 的前提是内网可信。任何能访问端口的人都能列出、覆盖、删除全部流程。

执行鉴权

执行鉴权管的是数据平面:某个流程的 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默认值说明
authpublicpublic 不鉴权;token 校验请求头里的密钥。
authHeaderAuthorization从哪个请求头取密钥;头名大小写不敏感。
secretRef—密钥在 flow.secrets 里的键;auth=token 时必填。

密钥配置

flow.secrets 是键值映射(Map),不是数组:键就是节点里声明的 secretRef,值是真实密钥,可以配多个。

application.yml
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 BuilderFlowBuilder + NodeBuilder,声明为 Bean 后启动自动部署否,代码即版本
界面配置设计器生成 JSON 后调 POST /flow是
Java Builder
@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_TARGEThttp://localhost:8090开发代理目标;单端口模式下宿主接口与流程接口同源。
VITE_TERMINAL_URL空日志终端完整地址;留空则用当前 host + 后端返回的路径。

使用步骤

  1. 左侧「节点」页签选择入口节点(rest、from、timer 等)作为链路起点。
  2. 选中节点后点击其它节点,新节点插入到选中项之后;右侧表单填写必填项。
  3. Header 填写流程 id / desc / group,点「校验」查看问题,点「保存」走 POST /flow 部署并落库。
  4. 已部署流程在左侧「流程」页签按分组树展示,点击叶子加载到画布继续编辑。

设计器支持撤销重做、校验问题定位、日志终端、链路追踪高亮;登录使用宿主的账号密码(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}"));
    }
}
application.yml
flow:
  node-packages:
    - com.example.flow.nodes

启动时会扫描并注册,重复 type 会直接启动失败;扫描期无法加载的节点会被跳过。自定义入口节点额外实现 entryUri(NodeSpec) 并在注解上写 entry = true。

部署指南

推荐把三个部分一起部署:文档站(静态)、设计器(静态)、后端(flow-scenario 或你自己的宿主)。仓库根目录的 deploy/ 已经准备好 Nginx 与 Docker Compose 配置。

方式一:Docker Compose(推荐)

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

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/。
/terminalhttp://backend:8090日志终端 WebSocket,需要 Upgrade 头。
/tracehttp://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 实现据此过滤自己关心的服务。

五种注册中心适配器(反射 + 条件装配)

注册中心条件宿主需要引什么
默认(无注册中心)以上都不是什么都不加 → 空实现返回空列表,单宿主模式
Nacosclasspath 有 com.alibaba.nacos.api.naming.NamingServicespring-cloud-starter-alibaba-nacos-discovery
Eurekaclasspath 有 com.netflix.discovery.EurekaClientspring-cloud-starter-netflix-eureka-client
Consulclasspath 有 ConsulDiscoveryClientspring-cloud-starter-consul-discovery
ZooKeeperclasspath 有 CuratorFrameworkcurator-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 的实例。

K8s 特殊处理:K8s 没有传统意义的“注册”——Pod 创建时就存在。FlowServerAutoRegistration.register() 在启动时 patch 自己 Pod 的 labels,加 flow.server=xxx。Discovery 侧读 Pod labels。这需要 ServiceAccount 有 patch pods 权限(默认只读,需要显式 Role/RoleBinding)。

宿主零改动接入示例

BladeX 宿主已经引了 Nacos,只需加 starter 依赖:

pom.xml
<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。

配置示例

application.yml
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:

  1. SELECT T_FLOWS 里当前 flow.server 的全部流程
  2. 遍历:DB 有、内存没有 → 调 DeployService.deploy() 补部署
  3. 遍历:内存有、DB 没有 → 调 DeployService.remove() 卸载
  4. 流程内容变了(版本升级)→ 重新 deploy 覆盖

完全零额外依赖,所有 starter 宿主(包括单体)都能用。唯一缺点是有 poll-interval 的延迟(默认 5 秒),对部署实时性要求极高时建议用 Redis/Kafka。

Redis Pub/Sub 工作原理

广播到 flow-deploy:{flow.server} 独立 channel,每个 flow.server 天然隔离,不会互相污染。消息体是 JSON:

Redis 消息体
{
  "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 留给宿主掌控。

单宿主不需要开多实例同步:单 Pod 场景下 DB_POLL 的 diff 结果永远是空集(DB 和内存一致),Redis/Kafka 订阅也收不到其他实例的消息。只有真正跑多个 Pod 时才生效。

常见问题

部署成功但访问 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(...),示例也采用这种写法。