Apache Synapse 3.0.2 配置参数详解

一、环境信息

项目	值
操作系统	Ubuntu 22.04.5 LTS / CentOS 8（x86_64，实测均验证）
组件版本	Apache Synapse 3.0.2
JDK	OpenJDK 8（1.8.0_504 / 1.8.0_312）
安装目录	/opt/synapse-3.0.2
默认端口	8280（HTTP）、8243（HTTPS）、1099（JMX）

本文参数均在实际运行环境验证，标注了每个参数的所在文件、默认值与修改后验证方式。

二、前置条件

已完成 Synapse 3.0.2 安装并能正常启动（synapse-daemon.sh status 显示 running）。文中相对路径均基于 /opt/synapse-3.0.2。修改任何配置后需重启进程：

cd /opt/synapse-3.0.2
./bin/synapse-daemon.sh restart

实测回显：

Stopped Apache Synapse (Synapse).
Starting Apache Synapse (Synapse)...

三、参数查看与修改方式

3.1 运行态查看 JVM 参数

/usr/lib/jvm/java-8-openjdk-amd64/bin/jps -v

实测回显（摘要）：

5407 SynapseServer -Xms512M -Xmx512M -Dorg.apache.xerces.xni.parser.XMLParserConfiguration=org.apache.xerces.parsers.XMLGrammarCachingConfiguration -Djava.endorsed.dirs=/opt/synapse-3.0.2/lib/endorsed -Djava.io.tmpdir=/opt/synapse-3.0.2/work/temp/synapse

daemon 模式下主类显示为 WrapperSimpleApp，参数同样可用 jps -v 或 ps -ef | grep [j]ava 查看：

java -Dorg.apache.xerces.xni.parser.XMLParserConfiguration=org.apache.xerces.parsers.XMLGrammarCachingConfiguration -Xms256m -Xmx512m -Djava.library.path=lib

3.2 配置生效方式说明

配置文件	生效方式
bin/synapse.sh（JVM 参数）	重启进程
repository/conf/wrapper.conf（daemon JVM 参数）	重启进程
repository/conf/axis2.xml（传输层）	重启进程
repository/conf/synapse-config/（中介配置）	重启进程（独立版无热加载）
repository/conf/passthru-http.properties	重启进程
lib/log4j.properties（日志）	重启进程

独立发行版不支持任何配置文件热加载，这是与商业 ESB 产品的关键差异。

四、参数总览

参数	所在文件	默认值	说明
-Xms / -Xmx	bin/synapse.sh	-Xms512M -Xmx512M	前台模式 JVM 堆
wrapper.java.initmemory	repository/conf/wrapper.conf	128	daemon 模式初始堆（MB）
wrapper.java.maxmemory	repository/conf/wrapper.conf	128	daemon 模式最大堆（MB）
wrapper.java.command	repository/conf/wrapper.conf	java	daemon 模式 java 路径
transportReceiver http port	repository/conf/axis2.xml	8280	HTTP 监听端口
transportReceiver https port	repository/conf/axis2.xml	8243	HTTPS 监听端口
synapse.jmx.jndiPort	repository/conf/synapse.properties	0	JMX 注册端口（1099 由内部分配）
http.socket.timeout	repository/conf/passthru-http.properties	180000	HTTP 套接字超时（毫秒）
worker_pool_size_core	repository/conf/passthru-http.properties	400	传输线程池核心数
worker_pool_size_max	repository/conf/passthru-http.properties	500	传输线程池最大数
io_buffer_size	repository/conf/passthru-http.properties	16384	IO 缓冲区字节数
http.socket.reuseaddr	repository/conf/passthru-http.properties	true	端口快速重用
log4j.rootCategory	lib/log4j.properties	ERROR	全局日志级别

五、核心参数分类详解

5.1 JVM 堆参数（前台模式）

前台模式堆参数硬编码在 /opt/synapse-3.0.2/bin/synapse.sh 启动命令行中：

grep -n 'Xms' /opt/synapse-3.0.2/bin/synapse.sh

实测回显：

$JAVA_HOME/bin/java -server -Xms512M -Xmx512M \

生产建议 256-512MB（小规格实例 256MB 起）。修改示例（改为 -Xms256M -Xmx512M）：

sed -i 's/-Xms512M -Xmx512M/-Xms256M -Xmx512M/' /opt/synapse-3.0.2/bin/synapse.sh

该脚本不读取任何 JAVA_OPTS 环境变量，修改必须直接编辑脚本。重启后用 jps -v 验证。

5.2 JVM 堆与 java 路径（daemon 模式）

daemon 模式由 /opt/synapse-3.0.2/repository/conf/wrapper.conf 控制，关键项实测：

wrapper.java.command=java
wrapper.java.initmemory=128
wrapper.java.maxmemory=128

生产修改：

wrapper.java.command=/usr/lib/jvm/java-8-openjdk-amd64/bin/java
wrapper.java.initmemory=256
wrapper.java.maxmemory=512

两个必改原因：其一，默认 128M 偏小；其二，wrapper.java.command=java 取系统 PATH 中的 java，若默认 java 为 JDK 9+ 将导致 wrapper 反复拉起失败（logs/wrapper.log 出现 5 次失败后放弃，报 -Djava.endorsed.dirs ... is not supported），必须写 JDK 8 全路径。验证：ps -ef | grep [j]ava 输出中应包含 -Xms256m -Xmx512m。

5.3 传输层端口（axis2.xml）

/opt/synapse-3.0.2/repository/conf/axis2.xml 中 HTTP/HTTPS 监听器定义（实测节选）：

<transportReceiver name="http" class="org.apache.synapse.transport.passthru.PassThroughHttpListener">
    <parameter name="port">8280</parameter>
    <!-- 其余子参数保持默认 -->
<transportReceiver name="https" class="org.apache.synapse.transport.passthru.PassThroughHttpSSLListener">
    <parameter name="port" locked="false">8243</parameter>
    <!-- 其余子参数保持默认 -->

可调参数：

port：监听端口，修改后重启生效，验证 ss -tlnp | grep 8280。
bind-address：默认注释，需要绑定内网网卡时取消注释并填入 IP。
WSDLEPRPrefix：WSDL 发布地址前缀，反代场景需要调整。

发送器（transportSender）默认启用 http、https、jms、vfs，mailto/fix/tcp/udp/amqp 处于注释状态，启用对应协议需取消注释并补充连接工厂参数。

服务路径前缀 /services/ 由 axis2.xml 的 servicePath 参数控制，代理服务访问 URL 固定为 http://<host>:8280/services/<代理名>；不带前缀的请求不会路由到代理，落入默认 main 序列并返回 202 空响应（实测确认）。

5.4 synapse.properties

/opt/synapse-3.0.2/repository/conf/synapse.properties 有效内容仅一行：

synapse.jmx.jndiPort=0

该参数控制 JMX 远程连接注册端口，默认 0 表示由系统分配（实测 JMX 绑定 1099）。需要固定管理端口时改为具体值。

5.5 HTTP 传输参数（passthru-http.properties）

/opt/synapse-3.0.2/repository/conf/passthru-http.properties 默认有效参数（实测）：

http.socket.timeout=180000
worker_pool_size_core=400
worker_pool_size_max=500
io_buffer_size=16384
http.socket.reuseaddr=true

http.socket.timeout：180000 毫秒即 3 分钟，长连接后端建议保持默认；后端普遍响应快时可降低到 60000 释放连接。
worker_pool_size_core / max：passthru 传输线程池，高并发场景将 max 提升到 800-1000，同时确认 JVM 堆外内存充足。
io_buffer_size：16KB 默认值适合大多数报文；大报文场景可提升到 65536。
该文件为 properties 键值格式，直接追加新键即可生效（如 http.connection.stalecheck=true）。

注意：同目录 nhttp.properties 属于旧 nhttp 传输，默认全部注释，passthru 为当前默认传输，无需配置 nhttp。

5.6 中介配置（synapse-config 目录）

/opt/synapse-3.0.2/repository/conf/synapse-config/ 结构（实测）：

synapse.xml            # 主配置：代理、端点、本地序列定义
sequences/main.xml     # 默认 main 序列（log + send）
sequences/fault.xml    # 默认 fault 序列
registry.xml           # 本地注册表配置

两条实测确认的硬性约束：

synapse.xml 内不能重复定义 main/fault 序列，否则启动报错且进程退出：

ERROR SynapseConfiguration Duplicate sequence definition for key : fault
org.apache.synapse.SynapseException: Duplicate sequence definition for key : fault

自定义序列应使用独立命名（如 name="myFaultSeq"）或在代理内以 faultSequence 子元素定义。

独立版无热加载，synapse.xml 修改后必须重启进程。

最小可用回显代理配置（实测返回 HTTP 200）：

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://ws.apache.org/ns/synapse">
    <proxy name="HelloProxy" transports="http https" startOnLoad="true">
        <target>
            <inSequence>
                <log level="custom">
                    <property name="msg" value="HelloProxy received request"/>
                </log>
                <payloadFactory media-type="xml">
                    <format>
                        <ns:response xmlns:ns="http://example.org">ok-from-synapse</ns:response>
                    </format>
                    <args/>
                </payloadFactory>
                <property name="RESPONSE" value="true"/>
                <header name="To" action="remove"/>
                <send/>
            </inSequence>
        </target>
    </proxy>
</definitions>

转发型代理使用 endpoint + outSequence(send) 结构，注意 passthru 发送器以 Transfer-Encoding: chunked 方式发送请求体，后端服务必须支持 chunked 请求（Tomcat 等标准服务器均支持）。

5.7 日志配置（lib/log4j.properties）

日志配置位于 lib/log4j.properties（注意不在 repository/conf 下），关键项（实测）：

log4j.rootCategory=ERROR, LOG_APPENDER, CONSOLE_APPENDER
log4j.category.org.apache.synapse=INFO
log4j.category.org.apache.synapse.transport=INFO
log4j.appender.SERVICE_APPENDER.File=logs/service.log
log4j.appender.SERVICE_APPENDER.MaxFileSize=1000KB
log4j.appender.SERVICE_APPENDER.MaxBackupIndex=10

运行期日志文件（logs/ 目录，实测生成）：synapse.log（主日志）、service.log（服务级）、trace.log（追踪）、wrapper.log（daemon 守护）、http_access_日期.log（访问记录）。排障时优先看 synapse.log 与 wrapper.log。

六、生产配置模板

适用场景：中小流量 ESB/网关节点，单机 2 核 4GB，JVM 堆控制在 256-512MB。

wrapper.conf（daemon 模式）：

wrapper.java.command=/usr/lib/jvm/java-8-openjdk-amd64/bin/java
wrapper.java.initmemory=256
wrapper.java.maxmemory=512
wrapper.java.additional.1=-Dorg.apache.xerces.xni.parser.XMLParserConfiguration=org.apache.xerces.parsers.XMLGrammarCachingConfiguration
wrapper.java.additional.3=-Djava.io.tmpdir=work/temp/synapse

passthru-http.properties（磁盘与内存均衡型）：

http.socket.timeout=60000
worker_pool_size_core=400
worker_pool_size_max=800
io_buffer_size=16384
http.socket.reuseaddr=true

log4j.properties（日志收敛）：

log4j.rootCategory=ERROR, LOG_APPENDER
log4j.category.org.apache.synapse=INFO
log4j.appender.SERVICE_APPENDER.MaxFileSize=1000KB
log4j.appender.SERVICE_APPENDER.MaxBackupIndex=10

模板说明：生产环境去掉 CONSOLE_APPENDER 减少 IO；后端平均响应低于 1 秒时 http.socket.timeout 可降至 60000；worker_pool_size_max 提升后建议配合 ss -s 观察连接数。

七、常见问题

Q1：改了 synapse.xml 后请求报 202 空响应？

请求路径缺少 /services/ 前缀，或修改后未重启。正确路径 http://<host>:8280/services/<代理名>，修改后执行 ./bin/synapse-daemon.sh restart。

Q2：启动报 Duplicate sequence definition？

synapse.xml 与 sequences/ 目录下文件重复定义了同名序列（main/fault 是默认保留名）。删除重复定义或将自定义序列改名。

Q3：wrapper 反复拉起失败后停止？

查看 logs/wrapper.log，若出现 endorsed not supported 报错，说明 wrapper.java.command 指向 JDK 9+，改为 JDK 8 的 java 全路径后重启。

Q4：JVM 参数修改后如何确认生效？

执行 /usr/lib/jvm/java-8-openjdk-amd64/bin/jps -v 或 ps -ef | grep [j]ava，输出中应包含修改后的 -Xms/-Xmx 值。

Q5：堆外内存或连接数不足如何调？

同步提升 passthru-http.properties 的 worker_pool_size_max 与系统文件句柄限制（LimitNOFILE=65535），并观察 ss -s 的 TCP 连接统计。

八、参考链接

官方主页：https://synapse.apache.org/
中介器与配置文档：https://synapse.apache.org/userguide/mediators.html
Axis2 传输配置参考：https://axis.apache.org/axis2/java/core/docs/http-transport.html
历史版本归档：https://archive.apache.org/dist/synapse/