简介这是一份WSO2 Enterprise Integrator 6.6.0系统级使用手册面向企业集成架构师、中间件运维人员以及从传统ESB向新一代EI迁移的开发者。手册先梳理WSO2三款核心产品API Manager、Enterprise Integrator、Identity Server的定位再深入EI 6.xx集成架构介绍ESB配置文件中的消息流管道、中介框架如何进行消息转换与路由以及业务流程配置文件如何支撑BPMN 2.0和WS-BPEL长期流程并演示了REST代理路由、REST转WebService、WebService转REST、TCP转WebService等典型集成场景。压缩包仅含1个doc文档大小1.43MB结构完整、图文结合适合作为案头参考。目前已有2041人学习浏览是快速掌握WSO2 EI 6.6.0核心能力与集成模式的高质量资料。1. 先搞清楚 6.6.0 是什么ESB 集成运行时到底管哪块WSO2 Enterprise Integrator 6.6.0 这个名字看着新其实它就是原来的 WSO2 ESB 扩展之后的整合版本代理服务、消息路由、协议转换这些 ESB 时代的核心能力在 6.6.0 里全部收进集成运行时默认提供。这意味着你拿这份使用手册去干活八成时间在跟代理服务、调解序列、端点、API 这些老概念打交道只是部署形态和配置目录变了。它要解决的问题非常具体让 SOAP、HTTP、JSON、数据库这些不同协议和格式的系统互相对话把对接逻辑从业务代码里剥出来交给中间件。适合做接口网关、集成平台的研发和运维也适合刚接手老项目、需要在现有 EI 环境上改配置的新人。6.6.0 尤其值得学它是老一代 Carbon 平台里配置最全、资料最多的版本之一把这套东西吃透往后迁移到新架构也不慌。2. 安装与启动 EI 6.6.0JDK 检查、启动脚本与热部署目录2.1 装之前先检查三件事JDK、端口、内存EI 6.6.0 是 Java 8 时代的产物。第一步是确认 JDK 版本常见做法是装 JDK 8不挑发行版关键是 JAVA_HOME 指向它以后 java -version 输出 1.8 开头。拿 JDK 11 或更新的版本直接跑启动早期就会出现类加载异常日志里翻半天才发现是版本问题属于典型的“白装半小时”的坑。第二步是端口。默认占用 9443管理控制台、8280HTTP 服务端口、8243HTTPS 服务端口。启动前先确认这三个端口没被占用Linux/macOS 用 netstat -tlnp | grep -E 9443|8280|8243有输出就说明被占了Windows 用 netstat -ano 对应查找。这是新手最容易卡住的第一关。第三步是内存。给 EI 进程本身预留至少 2GB如果同一台机器还要跑数据库和开发工具建议 4GB 起步。解压后目录名可以保持 wso2ei-6.6.0路径里尽量不要有中文和空格否则后面看日志、写外部脚本时会出现一些莫名其妙的定位问题。2.2 启动与停止wso2server 脚本、Profile 和端口偏移安装步骤其实只有解压和启动两步整个过程常见做法如下# 解压发布包到目标目录 unzip wso2ei-6.6.0.zip -d /opt/integration cd /opt/integration/wso2ei-6.6.0 # 显式指定 JDK8 路径避免系统默认 JDK 干扰 export JAVA_HOME/your/path/to/jdk8 export PATH$JAVA_HOME/bin:$PATH # 前台启动集成运行时 profile ./bin/wso2server.sh -Dprofileintegrator说明-Dprofileintegrator 是集成运行时也就是原来的 ESB 加数据服务能力的组合不加这个参数启动的也是同一套运行时我习惯显式写出来部署脚本里可读性更好。Broker、Analytics、Business Process 这些 profile 通常对应独立发布包普通接口集成用不到装的时候不用管。如果 9443 或 8280 被占又暂时动不了那个进程可以用端口偏移整体挪走./bin/wso2server.sh -Dprofileintegrator -DportOffset1这样控制台变成 9444HTTP 端口变成 8281。偏移量也可以写进 conf/carbon.xml 的 节点效果一样二选一即可。停止进程按 CtrlC后台启动的话用 kill 配合 PID 处理。启动成功的标志是日志里出现类似 “WSO2 Carbon started” 的信息然后浏览器访问 https://localhost:9443/carbon默认账密 admin/admin。提示第一次登录管理控制台后建议立刻在右上角账户菜单里修改默认密码。2.3 目录结构conf 改配置、repository 热部署、logs 排错6.6.0 解压后的目录结构需要先记下来排错时全靠它定位wso2ei-6.6.0/ ├── bin/ # 启动脚本 wso2server.sh / wso2server.bat ├── conf/ → repository/conf # 全局配置多数发行版是软链 ├── repository/ │ ├── conf/ │ │ ├── carbon.xml # 端口偏移、节点 ID │ │ ├── axis2/axis2.xml # 传输端口、线程池、连接池 │ │ ├── datasources/ # 数据源定义 │ │ ├── user-mgt.xml # 用户存储配置 │ │ └── log4j.properties # 日志级别 │ ├── database/ # 内置数据库文件用户、注册表 │ └── deployment/server/ │ ├── synapse-configs/default/ # 代理/序列/端点/API 热部署目录 │ └── carbonapps/ # CAR 应用目录 ├── lib/ # 扩展 jar └── logs/ # wso2carbon.log、http_access.log、gc.log我一直把 conf 和 repository 的边界当成“静态配置”和“动态部署”的分界线改服务器级参数去 conf发布业务去 repository/deployment/server。代理服务丢进 synapse-configs/default/proxy-services调解序列丢 sequences端点丢 endpointsREST 接口丢 api服务器会热加载不用重启。用开发工具打出来的 CAR 包则放到 carbonapps 目录。遇到任何部署问题第一件事就是看 logs/wso2carbon.log里面会写清楚是哪个 XML 解析失败、哪个端口绑定失败。3. 第一个能跑的代理服务代理 XML、调解序列与端点选型3.1 回显代理与带端点的代理理解 in/out 序列分离代理服务是 6.6.0 里最基本的对外入口。一个最小可运行的代理只需要 inSequence别人请求它它把消息原样回给调用方proxy xmlnshttp://ws.apache.org/ns/synapse nameEchoProxy startOnLoadtrue transportshttp https target inSequence log levelfull/ respond/ /inSequence /target /proxy保存成 repository/deployment/server/synapse-configs/default/proxy-services/EchoProxy.xml然后访问 http://localhost:8280/services/EchoProxy 就能看到请求日志和回显内容。这里有两个关键点文件名必须和 里的名字完全一致否则部署报错 表示不需要后端直接把当前消息返回适合做连通性测试。真实场景里代理一般要转给后端。带端点的代理长这样proxy nameOrderProxy startOnLoadtrue transportshttp https target inSequence log levelcustomproperty nameaction valueOrderProxy-in//log header nameAction scopetransport valueurn:getOrder/ sendendpoint keyOrderEndpoint//send /inSequence outSequence log levelcustomproperty nameaction valueOrderProxy-out//log send/ /outSequence /target /proxyinSequence 负责请求方向的处理outSequence 负责处理后端返回。这个分离模型是 WSO2 产品的核心习惯请求和响应是两条独立的执行链各自加日志、改头、做转换互不干扰。参数上重点看 startOnLoad随服务器启动部署和 transports对外暴露的传输协议一般写 http https 两个。endpoint key 引用的是一个独立端点文件放在 endpoints 目录里方便多处复用。3.2 先学会 log、property、payloadFactory 三个调解器调解序列里最先要掌握的是 log、property、payloadFactory它们覆盖了调试、改头和组装消息三类最频繁的操作。下面这个序列演示了把请求体改造成 JSON 再发给后端sequence nameOrderSeq xmlnshttp://ws.apache.org/ns/synapse property namemessageType valueapplication/json scopedefault/ log levelcustom property namestep valuebefore-payload/ /log payloadFactory media-typejson template-typedefault format {code:200,orderId:$1,msg:ok} /format args arg value1001/ /args /payloadFactory log levelfull categoryINFO/ send endpoint address urihttp://backend-host:8080/order/ /endpoint /send /sequence逻辑说明property 先把消息类型强制成 application/json避免后面的 payloadFactory 按 XML 模式生成log levelcustom 配合 property 子节点做轻量埋点只记自己想看的字段payloadFactory 的 format 里的 $1 对应 args 里的第一个参数顺序一一对应media-type 决定输出格式是 JSON 还是 XML。最后的 log levelfull 会把整个消息体打出来调试时非常直观但生产环境务必拆掉否则高并发下日志量会吓人。参数上记得几个习惯scope 不写就是 default作用域覆盖当前调解流程category 可以填 INFO/DEBUG 区分日志归属payloadFactory 的 template-type 保持 default 就好除非你有明确的模板需求。3.3 端点三选一address、failover 与 loadbalance端点决定消息最终往哪发。三种常见选型单点直连用 address主备切换用 failover后端有多台、需要轮流分摊用 loadbalance。下面是一个带超时和失败切换的 failover 配置endpoint nameOrderFailover xmlnshttp://ws.apache.org/ns/synapse failover endpoint address urihttp://node1:8080/order timeout responseActionfault/responseAction duration30000/duration /timeout /address /endpoint endpoint address urihttp://node2:8080/order/ /endpoint /failover /endpoint这段配置含义是优先发 node130 秒内没收到响应就按 fault 处理自动切到 node2。关键参数是 duration超时毫秒数和 responseAction超时后的动作fault 表示走错误分支并尝试下一个端点。要注意 failover 不是负载均衡——它平时只打第一个节点只有失败才切换。想做轮询分摊得用 loadbalance节点配置结构一样只是外层标签换掉内部可以配 algorithm 指定轮询或加权策略。选型上我的经验是后端是集群且服务无状态直接 loadbalance后端有明确主备角色用 failover后端只有一个地址且稳定address 最省事别为了架构好看硬套 failover排查时会多一层跳转。4. 贴近业务的三种用法REST API、JSON 转换与数据库对接4.1 用 API 工件暴露 RESTcontext、uri-template 与 method代理服务默认暴露成 /services/ 路径风格偏 SOAP。想要干净的 REST 路径用 API 工件。下面是一个读取路径参数的 REST 接口api nameOrderAPI context/order xmlnshttp://ws.apache.org/ns/synapse resource methodsGET uri-template/{id} inSequence property nameorderId expressionuri.var.id scopedefault/ log levelcustom property nameorderId value{orderId}/ /log property nameREST_URL_POSTFIX expressionfn:concat(/,get-property(orderId)) scopeaxis2/ send endpoint address urihttp://backend-host:8080/api/orders/ /endpoint /send /inSequence faultSequence log levelcustomproperty nameaction valueOrderAPI-fault//log respond/ /faultSequence /resource /api保存到 api 目录后访问 http://localhost:8280/order/1001 就会命中这个 APIuri.var.id 取到路径里的 1001。REST_URL_POSTFIX 是一个 axis2 作用域的传输属性它的值会被拼到后端地址后面这样后端收到的实际 URL 是 /api/orders/1001这是一种常见的“重写路径”做法。容易踩的是 context 冲突整个服务器所有 API 的 context 必须唯一写重了后部署的那个会把先部署的顶掉控制台和日志里都会出现部署错误。uri-template 和 uri-mapping 二选一新配置一律用 uri-template表达式能力更强。methods 不写就等于允许所有方法安全要求高的话显式列出来。4.2 JSON 取值与格式转换messageType 与 json-eval 配合6.6.0 里 JSON 消息有一套自己的表达式体系。取 JSON 字段必须用 json-eval 前缀不能用 XPath。下面这个序列按请求体里的 type 字段做分流sequence nameRouteByType xmlnshttp://ws.apache.org/ns/synapse property namemsgType expressionjson-eval($.type) scopedefault/ switch sourceget-property(msgType) case regexA log levelcustomproperty namematch valuetype-A//log sendendpoint keyEndpointA//send /case default sendendpoint keyEndpointB//send /default /switch /sequencejson-eval($.type) 取的是请求体 JSON 里 type 字段的值放进 msgType 属性switch 根据它走不同分支。这里最常见的翻车点是拿 XPath 去取 JSON 字段比如写 //type结果永远是空切成 json-eval 立竿见影。| 取数目标 | 表达式写法 | | JSON 字段 | json-eval($.字段名) | | XML/SOAP 节点 | //命名空间前缀:节点名 | | 流程属性 | get-property(属性名) | | REST 路径参数 | uri.var.参数名 |格式转换的核心是 messageType 属性。想在发后端前把 XML 转成 JSON在上游加 property namemessageType valueapplication/json想把 JSON 转 XML就设成 application/xml。转换发生在消息构建阶段所以这个属性必须加在真正使用消息内容之前否则改了也没效果。复杂的嵌套映射不要硬靠 messageType 自动转换结果不可控用 XSLT 或类调解器更稳。4.3 查数据库数据服务配置与回源路由的取舍EI 6.6.0 自带数据服务能力可以在控制台里用 SQL 查询直接生成对外接口适合快速把只读查询暴露成 REST 或 SOAP。常见做法是三步先在数据源配置里定义连接再创建数据服务并编写查询最后发布后访问对应 URL。需要重点确认的参数有三个数据源引用名、查询 SQL、输出映射字段名与返回结构。这套路径适合报表查询、简单主数据读取不适合复杂事务写入。我一般不建议在中间件里堆积大量 SQL。更可控的做法是让 ESB 只做路由和协议适配把数据库访问封装成后端服务。这样数据库连接数、事务边界、慢查询治理都在业务服务侧解决中间件保持无状态扩容时直接加节点就行。选数据服务还是回源路由判断标准就一条这个查询是不是只有中间件才碰得到。如果后端业务服务本来就存在永远优先复用后端接口从数据库直接拉到中间件会让排查链路多出一层。5. 6.6.0 高频坑排查启动、热部署、超时与格式5.1 启动报错的两大类端口被占与 JDK 版本不对现象wso2server.sh 启动到一半退出控制台页面打不开日志里出现 BindException或者启动早期抛出一串类加载异常。原因BindException 是 9443、8280、8243 中被占用类加载异常多半是 JAVA_HOME 指向了 JDK 9 以上版本老 Carbon 的类库对高版本 JDK 不兼容。解决先 netstat 查端口归属能挪走就挪走挪不走就用 -DportOffset1 整体偏移JDK 问题直接装回 JDK 8确认 java -version 输出是 1.8 开头再启动。两个问题都会在 wso2carbon.log 里留下明确报错养成启动失败先看日志的习惯能省大量时间。5.2 热部署不生效文件名、name 与 XML 合法性现象XML 文件丢进 proxy-services 或 api 目录等了几分钟控制台里还是没有服务日志里有 deployment 相关 error。原因三个常见原因——文件名和工件 不一致XML 里有非法转义或手滑多写了标签文件保存成了带 BOM 或编码不对的格式。解决把文件名改成和 name 完全一致用任意 XML 校验工具先过一遍再丢进部署目录日志里会指到具体行号按行号修。我习惯在本地编辑好并校验完再传到服务器不在服务器上直接改 XML。5.3 接口超时或 504endpoint 超时与连接池联动调整现象压测或联调时部分请求报超时日志里端点状态变成 SUSPENDED后端实际处理只要两三秒但客户端已经等不及。原因endpoint 默认超时配置对慢接口偏短超时后反复重试把端点挂起另一头高并发时 transport sender 的连接池不够用请求排队等连接。解决在 endpoint 里显式配置 30000 fault 把超时拉长同时到 conf/axis2/axis2.xml 里调 transportSender 的连接池参数。两个要一起调只加超时会让排队请求越积越多只调连接池又挡不住慢接口的超时切换。5.4 JSON 进去 XML 出来messageType 与 Content-Type 没设置对现象客户端发的是 JSON后端收到的 content-type 是 text/xml字段解析全错或者 payloadFactory 生成的内容格式和预期不一致。原因调解过程中没有设置 messageType中间件按默认格式处理消息payloadFactory 缺 media-type 属性时也会按 XML 生成。解决在进入转换逻辑之前加 property namemessageType valueapplication/jsonpayloadFactory 上写明 media-typejson如果后端对 Content-Type 头有严格校验再补一个 ContentType 属性。记住这条链路先设 messageType再构建消息最后发送。5.5 控制台密码遗忘用户库文件恢复的常见做法现象登录 9443 控制台提示密码错误admin 密码不记得了或者环境迁移后用户数据对不上。原因用户数据存在内置数据库文件里被改过、被环境覆盖过、或者迁移时只搬了配置没搬数据库都会导致对不上。解决上线前把 repository/database 目录纳入备份范围出问题直接恢复备份。没有备份的常见做法是从一台同版本干净环境复制用户数据库文件过来覆盖或改 conf/user-mgt.xml 里 admin 的密码哈希后重启。改完必须重启才生效。这个教训是内置库很省事但一定要备份否则找回成本比任何配置都高。6. 让 6.6.0 更耐压三个调优动作与一个查日志习惯先说明6.6.0 默认配置是“能用”水平不是“耐压”水平。三个动作按顺序做别跳。第一个动作是内存。在 bin/wso2server.sh 里找到启动参数里的 -Xmx改成匹配场景的值# 典型配置堆上限 3GB按并发与消息体大小调整 -Xms1g -Xmx3g经验估法预期并发数乘以单条消息平均体积再乘 2留出转换过程的临时对象空间。调解里大量用 payloadFactory 和 XSLT 时堆消耗比纯转发高不少这个系数可以再放大。第二个动作是 NIO 线程池。conf/axis2/axis2.xml 里 HTTP NIO transportReceiver 的线程池参数按 CPU 核数调。后端响应慢、IO 密集的场景线程数可以高于核数两倍纯转发、后端快的场景线程数太高反而增加上下文切换压测时吞吐会掉头。第三个动作是日志分级。开发期把 log4j.properties 里 org.apache.synapse 调到 DEBUG能看到调解序列的完整执行轨迹上线前调回 INFO保留业务自定义的 log mediator 埋点。定位慢接口时在代理入口、后端调用前、outSequence 三处各放一个 log levelcustom 埋点比对时间戳就知道耗时在哪一环。压测验证时盯 logs/http_access.log 的响应码分布和 wso2carbon.log 里有没有 SUSPENDED 端点比盯控制台直观。我最早在 6.6.0 上调优只加内存不改线程池压到两百并发就线程饥饿日志里全是等待连接后来线程池和超时一起调才稳住。从那以后我养成了习惯每个代理上线前先压一遍再根据日志决定改哪里而不是凭感觉堆参数。希望帮到你。本文还有配套的精品资源点击获取