简介这份《WSO2 Enterprise Integrator 6.6.0 使用手册》面向企业集成开发人员、ESB 架构师及中间件运维人员聚焦 WSO2 ESB 升级版 EI 6.6.0 的落地实践帮助读者理解企业级集成方案的整体架构与配置思路。手册系统梳理了 WSO2 三款核心产品——API Manager、Enterprise Integrator 与 Identity Server 的定位与协作关系并深入讲解 EI 的集成架构、ESB 概要文件、业务流程概要文件及 Analytics 分析配置文件的分工。内容涵盖 REST 代理与路由转发、REST 与 WebService 互转、TCP 转 WebService 等典型集成场景同时展开短期无状态集成流与基于 BPMN 2.0、WS-BPEL 的长期业务流程涉及中介框架、消息管道、传输层协议转换等关键机制。资源包为 1 个 doc 文档大小约 1.43MB结构完整、条理清晰便于按章节查阅与对照实践。目前已有 2041 人学习适合需要快速掌握 WSO2 EI 集成能力、搭建企业集成平台的读者参考。1. 从一份 6.6.0 手册说起WSO2 EI 到底解决什么集成问题手里这份《WSO2-ESB、WSO2 Enterprise Integrator 6.6.0 使用手册.doc》不是那种翻两页就扔的官方 PDF 搬运而是一份把 ESB 概要文件、业务流程概要文件、Analytics 三套运行时讲清楚并且配了 REST 代理、内容路由、REST2SOAP、SOAP2REST、TCP2SOAP 五类可复现案例的实操文档。如果你正在做企业系统对接面对的是老系统只吐 SOAP、新前端只要 REST、还有一堆 TCP 长连接设备要接进来的局面这份手册的价值在于它把 WSO2 EI 6.6.0 这个ESB的定位落到了具体配置上——不是让你从零啃 Apache Synapse 源码而是告诉你 Proxy Service 的 InSequence/OutSequence 怎么切、Property Mediator 怎么取值、axis2.xml 什么时候必须改。适合谁做 SOA 集成、ESB 选型、或者手上已经有一堆异构系统要拉通的中间件工程师新手能照着案例走通第一条消息流熟手能直接翻到 TCP 传输和注册表缓存那几段看边界。2. WSO2 EI 6.6.0 的运行时拆解ESB、BPS、MB、SP 四合一怎么选2.1 四个 Profile 不是四个产品是同一份 Carbon 底座WSO2 EI 6.6.0 把原来四个独立产品塞进了一个发行包WSO2 ESB企业服务总线、WSO2 MB消息代理、WSO2 BPS业务流程服务器、WSO2 SP流处理器。它们共享同一套 Carbon 平台OSGi 框架启动时通过-Dprofilexxx参数决定拉起哪套运行时。这一点很关键——很多人第一次解压完 EI看到bin/下只有一个integrator.sh以为装错了其实是没理解 Profile 机制。常见做法是短期无状态集成流走 ESB Profile长期有状态业务流程BPMN 2.0、WS-BPEL 2.0走 Business Process Profile需要消息可靠投递走 MB Profile要做实时统计和消息追踪走 Analytics Profile。四个 Profile 可以分开部署也可以合并但生产环境我一般建议至少把 Analytics 拆出去否则 ESB 本身的吞吐会被统计写入拖累。2.2 短期集成流消息管道与中介框架的边界ESB Profile 处理的是 short-running integration flow消息从客户端进来经过 transport 拾取进入消息管道做 QoS 处理安全、可靠消息传输然后交给中介框架Mediation Framework做转换和路由。这里有个容易混淆的点手册里明确写了消息转换组件和路由组件之间没有明确的分隔也就是说转换可能发生在路由决策之前也可能发生在之后具体取决于你的 Sequence 怎么编排。这是 Synapse 的实现方式和某些把转换和路由严格分层的 ESB 不一样。实际配置时一个 Proxy Service 至少有两个消息流InSequence 负责消息进入 ESB 到发送到 endpoint 之前的编排OutSequence 负责 endpoint 响应回到 ESB 再返回给客户端的编排。如果出错fault sequence 被调用。WSO2 ESB 4.x 之后还引入了 Receiving Sequence 的概念允许你指定外部请求走哪个序列处理而不是默认走 OutSequence。2.3 长期业务流程BPEL、BPMN、人工任务三套运行时Business Process Profile 下面有三套运行时并行BPEL Runtime 基于 Apache ODE 引擎BPMN Runtime 基于 Activiti 5.21.0 引擎人工任务Human Task运行时把人的交互集成进工作流。BPEL 流程和人工任务以 SOAP 服务暴露走 Axis2 传输层BPMN 流程以安全的 REST API 暴露部署在嵌入式 Tomcat 里。数据持久化统一走 DAO 层落数据库。选型上如果你的流程是提交申请→审批→归档这种有人工介入的长流程用 BPMN Human Task如果是纯服务编排、没有人工节点用 ESB Profile 的 Sequence 就够了没必要上 BPS否则运维复杂度翻倍。2.4 版本定位6.6.0 在 6.xx 系列里处于什么位置手册里写得很清楚6.6.0 是 6.xx 系列的最新版本集成了 ESB、MB、BPS、SP 四款产品的功能。它基于 Apache Synapse 和 Apache Axis2 构建100% 开源Apache License 2.0。这意味着你可以自由修改和商用但也要接受社区版没有官方 SLA 支持的现实。对于内部系统集成这个许可足够友好对于对外暴露的关键业务 API建议还是评估一下商业支持的必要性。3. 从 Integration Studio 到第一条消息流REST 代理与内容路由实操3.1 环境准备EI 6.6.0 与 Integration Studio 的版本对齐第一步是下载 EI 6.6.0 的 Zip Archive 和 Integration Studio 的 Zip Archive。注意版本对齐——Integration Studio 的插件版本要和 EI 运行时版本匹配否则部署 Carbon 应用时会报 bundle 版本冲突。解压后EI 的目录结构里bin/放启动脚本repository/放 Carbon 应用和配置conf/放 axis2.xml、carbon.xml 等核心配置。启动 ESB Profile 的命令# Linux/macOS 下启动 ESB Profile默认端口 9443HTTPS 管理控制台 sh bin/integrator.sh -Dprofileesb # Windows 下 bin\integrator.bat -Dprofileesb启动后访问https://localhost:9443/carbon默认账号密码 admin/admin。如果端口被占用改conf/carbon.xml里的Offset值比如设成 1所有端口整体偏移。3.2 创建 REST 代理服务InSequence 与 send mediator在 Integration Studio 的 Getting Started 界面可以直接创建案例模板。一个最简单的 REST 代理服务核心是定义一个 Proxy Service指定 transports 为 http/https然后写 InSequenceproxy nameSimpleRESTProxy startOnLoadtrue transportshttp https target inSequence !-- 接收 REST 请求直接转发到后端 SOAP 服务 -- send endpoint address urihttp://localhost:9000/services/SimpleStockQuoteService formatsoap11/ /endpoint /send /inSequence outSequence !-- 后端响应回到 ESB直接回给客户端 -- send/ /outSequence /target /proxy这段配置的逻辑transports指定代理服务监听 HTTP 和 HTTPSinSequence里的sendmediator 把消息发到指定的 address endpointformatsoap11表示把进来的 REST 消息转换成 SOAP 1.1 格式再发给后端。outSequence里的空send表示把后端响应原样返回给客户端。参数上format可选值有soap11、soap12、pox、get、leave-as-is选错了会出现后端收到空消息体或者格式解析失败。3.3 基于消息内容的路由XPath 与 Switch mediator手册里第二个案例是基于请求内容进行服务编排和路由转发。核心是用 XPath 表达式从消息体里取值然后根据值走不同的分支inSequence !-- 从 SOAP 消息体中提取 Hospital 元素的值 -- switch source//getCustomer/hospital case regexA send endpoint address urihttp://hospital-a.example.com/service/ /endpoint /send /case case regexB send endpoint address urihttp://hospital-b.example.com/service/ /endpoint /send /case default send endpoint address urihttp://hospital-default.example.com/service/ /endpoint /send /default /switch /inSequenceswitchmediator 的source属性接受 XPath 表达式case的regex属性做正则匹配。这里有个坑XPath 的命名空间处理。如果 SOAP 消息体带了 namespace//getCustomer/hospital可能匹配不到需要写成//ns:getCustomer/ns:hospital并在配置里声明命名空间前缀。手册里给的表达式示例是//getCustomer、//getCustomer/id实际用的时候先拿一条真实消息在 ESB 的 Try-It 工具里测一下 XPath 能不能取到值。3.4 REST2SOAP 与 SOAP2REST格式转换的配置差异REST2SOAP 的场景是客户端发 REST/JSON后端只认 SOAP。除了上面formatsoap11的 address endpoint 配置还需要在 InSequence 里做消息体转换。常见做法是用 PayloadFactory mediator 构造 SOAP 信封payloadFactory media-typexml format soapenv:Envelope xmlns:soapenvhttp://schemas.xmlsoap.org/soap/envelope/ soapenv:Body p:getCustomer xmlns:phttp://example.com/customer p:id$1/p:id /p:getCustomer /soapenv:Body /soapenv:Envelope /format args arg evaluatorjson expression$.customerId/ /args /payloadFactorymedia-typexml表示输出 XML 格式$1是占位符对应args里第一个参数。evaluatorjson表示从 JSON 消息体里取值expression$.customerId是 JSONPath。SOAP2REST 反过来后端返回 SOAP客户端要 JSON就在 OutSequence 里用 PayloadFactory 把 XML 转成 JSON或者用 Script mediator 写 JavaScript 转换逻辑。3.5 TCP2SOAP改 axis2.xml 才能启用的传输TCP 传输不是默认开启的必须在conf/axis2/axis2.xml里添加 TCP transport receiver 和 sender 的配置。手册里特别提醒了这一点。WSO2 接受 TCP 三种类型消息字节、字符、字符串并且以指定分隔符或者定长字节来区分是否为一个完整 TCP 请求。!-- 在 axis2.xml 的 transportReceiver 区域添加 -- transportReceiver nametcp classorg.apache.axis2.transport.tcp.TCPServer parameter nameport6060/parameter parameter namecontentTypetext/plain/parameter !-- 分隔符方式以换行符作为消息边界 -- parameter namerecordDelimiter\n/parameter /transportReceiver配置完重启 ESB Profile 才生效。JMS 传输同样需要改 axis2.xml具体参数参考官网文档。TCP 场景最容易翻车的地方是消息边界识别——如果客户端发的消息里本身包含分隔符就会把一条消息拆成两条。这时候要么改用定长字节模式要么在客户端做转义。4. 避坑与排查WSO2 EI 6.6.0 实操中容易翻车的五个点4.1 代理服务启动时 WSDL 获取失败导致服务被忽略现象ESB 启动日志里出现 WSDL not found, ignoring proxy service 之类的警告代理服务在管理控制台里看不到。原因ESB 启动时会尝试获取所有代理服务关联的 WSDL。如果代理服务配置里引用了外部 WSDL 地址而那个地址在启动时不可达ESB 会跳过这个服务继续启动。解决检查代理服务的 WSDL 配置如果是外部地址确保启动时可达或者把 WSDL 文件放到本地 registry 里用key引用而不是uri。生产环境建议把 WSDL 固化到 registry避免启动时依赖外部服务。4.2 Registry 缓存导致配置更新不生效现象在管理控制台修改了 Sequence 或 Endpoint 配置保存成功但消息流还是走旧逻辑。原因ESB 从 registry 获取资源后会缓存cachableDuration参数控制缓存生命周期默认 15000 毫秒。缓存未过期时registry 资源变化不会反映到运行时。解决临时把cachableDuration改小比如 1000或者重启 ESB。生产环境调大这个值可以改善性能但配置变更后要有等待缓存过期的预期。手册里明确写了cachableDuration 增大可以改善消息处理的速度减少可以确保 registry 的资源及时更新这是个取舍。4.3 XPath 表达式取不到值现象Switch mediator 的 case 分支永远走 default或者 Property mediator 的 XPath 表达式返回空。原因SOAP 消息体带了 namespaceXPath 表达式没有加命名空间前缀或者消息体格式和预期不符比如实际是 JSON 但用了 XML 的 XPath。解决先用 ESB 管理控制台的 Try-It 工具或者日志 mediator 打印完整消息体确认消息格式和 namespace。XPath 表达式加上 namespace 前缀JSON 消息用json-eval($.field)而不是 XPath。手册里给的表达式示例JSON 取值用json-eval($.name)Property 取值用get-property(name)或$ctx:nameXPath 用//getCustomer或//getCustomer/idConcat 用fn:concat(Routing to , get-property(Hospital))。4.4 TCP 传输消息被截断或粘包现象TCP 客户端发了一条消息ESB 侧收到两条或者两条消息被合并成一条。原因TCP 是字节流协议没有消息边界。ESB 依赖分隔符或定长字节来切分消息。如果消息内容本身包含分隔符或者客户端发送频率和分隔符不匹配就会出问题。解决改用定长字节模式或者在客户端做消息转义确保分隔符不出现在消息体中。测试阶段可以用nc或telnet手动发消息验证边界识别逻辑。4.5 Integration Studio 部署 Carbon 应用时报 bundle 版本冲突现象在 Integration Studio 里点Deploy to EI控制台报 bundle 版本不匹配或者 ClassNotFoundException。原因Integration Studio 的插件版本和 EI 运行时版本不一致或者项目 pom.xml 里依赖的 Carbon 组件版本和 EI 自带的不一致。解决确认 Integration Studio 版本和 EI 6.6.0 匹配检查项目 pom.xml 里的依赖版本尽量用 EI 自带的组件版本。如果还是冲突把 Carbon 应用手动导出为 .car 文件放到 EI 的repository/deployment/server/carbonapps/目录下热部署。5. 进阶技巧用 Property Mediator 和 Enrich Mediator 做消息上下文管理5.1 Property Mediator 的三种作用域Property mediator 是 WSO2 ESB 里最常用的组件之一但很多人只用了它的默认作用域synapse。实际上它支持三种作用域synapse默认当前消息流内有效、axis2Axis2 消息上下文跨消息流有效、transport传输层头部比如 HTTP header。作用域选错了值取不到或者被意外覆盖。!-- 把 HTTP 请求头里的 Authorization 值存到 transport 作用域 -- property nameAuthHeader expression$trp:Authorization scopetransport/ !-- 把后端响应里的某个值存到 synapse 作用域供后续 mediator 使用 -- property nameResponseCode expressionget-property(axis2, HTTP_SC) scopesynapse/ !-- 设置 HTTP 响应状态码 -- property nameHTTP_SC value200 scopeaxis2/$trp:前缀表示取 transport headerget-property(axis2, HTTP_SC)表示从 axis2 作用域取 HTTP 状态码。这些在手册的常用组件章节里有链接但实际用的时候要结合具体场景试。5.2 Enrich Mediator 做消息体替换与属性注入Enrich mediator 用来在消息流中修改消息体或属性。常见用法是把某个 Property 的值注入到消息体的某个节点或者用一个新的 XML 片段替换整个消息体。!-- 把 Property 的值注入到消息体的指定 XPath 位置 -- enrich source typeproperty propertyCustomerId/ target typebody actionreplace xpath//customer/id/ /enrich !-- 用一个新的 XML 片段替换整个 SOAP Body -- enrich source typeinline statussuccess/status /source target typebody/ /enrichsource的type可以是property、inline、body、envelopetarget的action可以是replace、child、sibling。xpath属性指定目标位置。这里有个血泪经验actionreplace配合xpath时如果 XPath 匹配到多个节点只会替换第一个要替换所有匹配节点得用actionchild或者写循环。5.3 验证消息流是否按预期执行调试 ESB 消息流最直接的方法是在关键节点加 log mediator打印消息体和属性值log levelcustom property nameMessageBody expression$body/ property nameCustomerId expressionget-property(CustomerId)/ property nameDirection valueAfter-Routing/ /loglevelcustom表示自定义日志property的expression取运行时值value写固定值。日志输出在repository/logs/wso2carbon.log里。生产环境记得把日志级别调回否则大量消息体打印会拖慢性能。另一个验证手段是 EI-Analytics Profile 的消息追踪功能。启动 Analytics Profile 后在 ESB 侧配置好 Analytics 发布器就能在 Analytics 控制台里看到每条消息经过的 mediator 链路和耗时。这个对排查消息到底走到哪一步丢了特别有用。5.4 一个我常用的排查习惯从那以后我每次配完新的 Proxy Service 或 Sequence都强制走一遍三查一查 ESB 启动日志有没有 WSDL 忽略或 bundle 冲突二查 Try-It 工具能不能打通端到端三查wso2carbon.log里有没有异常堆栈。这三步走完基本能拦住八成以上的配置问题。希望帮到你。本文还有配套的精品资源点击获取