Ubuntu 22.04 安装 Apache Synapse 3.0.2 指南

一、环境信息

项目	值
操作系统	Ubuntu 22.04.5 LTS（x86_64）
组件版本	Apache Synapse 3.0.2（当前官方最新稳定版）
JDK	OpenJDK 8（1.8.0_504，官方声明仅完整支持 Java 1.8 及更早版本）
安装目录	/opt/synapse-3.0.2
默认端口	8280（HTTP）、8243（HTTPS）、1099（JMX）
运行账号	root（生产环境建议创建专用账号）

本文所有命令与回显均来自真实服务器实测，可直接照抄执行。

二、前置条件

2.1 系统要求

2 核 CPU、2GB 内存以上（JVM 堆按本文配置为 256-512MB，其余内存供堆外与系统使用）
磁盘剩余空间不低于 2GB（发行包 43MB，解压后约 350MB，另需日志空间）
服务器可访问外网（下载 JDK 与官方发行包），或已配置内部软件源

2.2 安装基础工具与 OpenJDK 8

Synapse 3.0.2 的启动脚本会向 JVM 传递 -Djava.endorsed.dirs 参数，该参数在 JDK 9 及以上版本会直接导致 JVM 创建失败，实测在 OpenJDK 11 上启动报错 Error: Could not create the Java Virtual Machine.，因此必须使用 OpenJDK 8：

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-8-jdk curl iproute2

安装完成后确认版本与 JAVA_HOME 路径：

/usr/lib/jvm/java-8-openjdk-amd64/bin/java -version

实测回显：

openjdk version "1.8.0_504"
OpenJDK Runtime Environment (build 1.8.0_504-8u504-ga-1ubuntu1~22.04.3-b01)
OpenJDK 64-Bit Server VM (build 25.504-b01, mixed mode, sharing)

注意：Ubuntu 22.04 默认 java 命令可能指向 OpenJDK 11，建议后续配置环境变量显式指向 JDK 8，避免 daemon 模式使用系统默认 java 导致启动失败。

三、版本选型说明

官方下载目录 https://downloads.apache.org/synapse/ 当前提供 3.0.1 与 3.0.2 两个版本，3.0.2 为最新稳定版（2023 年 5 月发布）。
发行包为 synapse-distribution-3.0.2-bin.tar.gz（约 43MB），另有 zip 与源码包。
已知提示：发行包内 README.txt 头部仍显示 "Apache Synapse 3.0.1 build (December 2017)"，为官方未更新所致，实际版本以解压目录名 synapse-3.0.2 与 release_notes.txt 为准。
若下载目录已轮转（官方仅保留最新两个版本），可从 https://archive.apache.org/dist/synapse/3.0.2/ 获取历史版本。

四、部署步骤

以下按 0 到 1 的完整顺序执行，每条命令单独执行并核对回显。

4.1 下载官方发行包并校验

cd /tmp
curl -sO https://downloads.apache.org/synapse/3.0.2/synapse-distribution-3.0.2-bin.tar.gz

校验 MD5（与官方同名 .md5 文件比对）：

md5sum synapse-distribution-3.0.2-bin.tar.gz
curl -s https://downloads.apache.org/synapse/3.0.2/synapse-distribution-3.0.2-bin.tar.gz.md5

实测两行输出均为：

652b62cede3439cbde9fd71fea66ad4e  synapse-distribution-3.0.2-bin.tar.gz
652b62cede3439cbde9fd71fea66ad4e

4.2 解压到 /opt

tar -xzf /tmp/synapse-distribution-3.0.2-bin.tar.gz -C /opt/
ls /opt/

实测回显：

synapse-3.0.2

解压后目录结构（实测）：

/opt/synapse-3.0.2/
├── bin/            # synapse.sh、synapse-daemon.sh、ciphertool.sh、native/（wrapper 二进制）
├── docs/           # 本地文档
├── lib/            # 依赖 jar、log4j.properties、trust.jks、identity.jks
├── repository/conf/ # axis2.xml、synapse.properties、wrapper.conf、synapse-config/
├── samples/        # 官方示例配置与客户端
├── work/           # 运行期工作目录
└── release_notes.txt

4.3 创建运行期目录

发行包不带 logs 目录，首次启动前必须创建，否则日志重定向报 No such file or directory：

mkdir -p /opt/synapse-3.0.2/logs
mkdir -p /opt/synapse-3.0.2/work/temp/synapse

4.4 配置环境变量

cat > /etc/profile.d/synapse.sh <<'EOF'
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
export SYNAPSE_HOME=/opt/synapse-3.0.2
export PATH=$JAVA_HOME/bin:$SYNAPSE_HOME/bin:$PATH
EOF

使配置生效并验证：

source /etc/profile.d/synapse.sh
echo $JAVA_HOME

实测回显：

/usr/lib/jvm/java-8-openjdk-amd64

4.5 修改 daemon 模式 JVM 配置（关键）

daemon 启动脚本依赖 Tanuki wrapper，需修改 /opt/synapse-3.0.2/repository/conf/wrapper.conf 三处：

第一处，显式指定 JDK 8 的 java 可执行文件（避免系统默认 java 指向 JDK 11 导致启动失败）：

sed -i 's|wrapper.java.command=java|wrapper.java.command=/usr/lib/jvm/java-8-openjdk-amd64/bin/java|' /opt/synapse-3.0.2/repository/conf/wrapper.conf

第二处，将默认堆参数 128M 调整为符合生产要求的 256-512MB：

sed -i 's/wrapper.java.initmemory=128/wrapper.java.initmemory=256/' /opt/synapse-3.0.2/repository/conf/wrapper.conf
sed -i 's/wrapper.java.maxmemory=128/wrapper.java.maxmemory=512/' /opt/synapse-3.0.2/repository/conf/wrapper.conf

确认修改结果：

grep -E 'java.command|initmemory|maxmemory' /opt/synapse-3.0.2/repository/conf/wrapper.conf

实测回显：

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

第三处，禁用 32 位 wrapper 二进制。发行包自带 32 位与 64 位两份 wrapper，启动脚本优先使用 32 位；在无 32 位运行库的系统上虽然文件存在且有执行位，但实际执行会报 wrapper-linux-x86-32: not found。将其改名后脚本自动回退到 64 位：

mv /opt/synapse-3.0.2/bin/native/wrapper-linux-x86-32 /opt/synapse-3.0.2/bin/native/wrapper-linux-x86-32.disabled

4.6 启动服务

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

实测回显：

Starting Apache Synapse (Synapse)...

查询运行状态：

./bin/synapse-daemon.sh status

实测回显：

Apache Synapse (Synapse) is running (7847).

4.7 验证服务

端口验证：

ss -tlnp | grep -E '8280|8243|1099'

实测回显：

LISTEN 0      50   *:8280   *:*   users:(("java",pid=7849,fd=317))
LISTEN 0      50   *:8243   *:*   users:(("java",pid=7849,fd=277))
LISTEN 0      50   *:1099   *:*   users:(("java",pid=7849,fd=231))

JVM 堆参数验证：

/usr/lib/jvm/java-8-openjdk-amd64/bin/jps -v | grep -o '\-Xms\S* \-Xmx\S*'

实测回显：

-Xms256m -Xmx512m

启动日志验证：

tail -3 /opt/synapse-3.0.2/logs/wrapper.log

实测回显：

INFO ServerManager Server ready for processing...
INFO SynapseServer Apache Synapse started successfully

4.8 配置 systemd 开机自启

cat > /etc/systemd/system/synapse.service <<'EOF'
[Unit]
Description=Apache Synapse ESB
After=network.target

[Service]
Type=forking
User=root
ExecStart=/opt/synapse-3.0.2/bin/synapse-daemon.sh start
ExecStop=/opt/synapse-3.0.2/bin/synapse-daemon.sh stop
ExecReload=/opt/synapse-3.0.2/bin/synapse-daemon.sh restart
PIDFile=/opt/synapse-3.0.2/Synapse.pid
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF

注册并启动：

systemctl daemon-reload
systemctl enable synapse
systemctl start synapse
systemctl status synapse --no-pager | head -6

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/synapse.service → /etc/systemd/system/synapse.service.
● synapse.service - Apache Synapse ESB
     Loaded: loaded (/etc/systemd/system/synapse.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-10-12 01:08:54 UTC; 7ms ago
   Main PID: 8373 (wrapper-linux-x)

五、配置说明

5.1 目录与配置文件一览

路径	作用
/opt/synapse-3.0.2/bin/synapse.sh	前台启动脚本（JVM 参数在此定义）
/opt/synapse-3.0.2/bin/synapse-daemon.sh	daemon 启停脚本（基于 wrapper）
/opt/synapse-3.0.2/repository/conf/wrapper.conf	daemon 模式 JVM 参数与 java 命令
/opt/synapse-3.0.2/repository/conf/axis2.xml	传输层配置（端口、发送器/接收器）
/opt/synapse-3.0.2/repository/conf/synapse-config/synapse.xml	中介配置主文件（代理、序列、端点）
/opt/synapse-3.0.2/repository/conf/passthru-http.properties	HTTP 传输参数（超时、线程池）
/opt/synapse-3.0.2/lib/log4j.properties	日志级别与输出文件配置

5.2 验证代理服务

在 synapse.xml 中部署一个回显代理后重启，实测请求 http://127.0.0.1:8280/services/HelloProxy 返回 HTTP 200。注意：独立发行版的服务访问路径必须带 /services/ 前缀；不带前缀的请求会落入默认 main 序列并返回 202 空响应。修改 synapse.xml 后不会热加载，需重启进程生效。

六、注意事项

必须使用 OpenJDK 8，JDK 11 及以上版本因 -Djava.endorsed.dirs 不受支持而无法启动，这是 3.0.x 系列最常见的安装失败原因。
daemon 模式与前台模式的 JVM 参数分别由 wrapper.conf 和 bin/synapse.sh 控制，两处需同时保持一致（本文均为 256-512MB）。
synapse-daemon.sh 会优先执行 32 位 wrapper 二进制，若系统缺少 32 位运行库，必须按 4.5 节将其改名禁用。
生产环境建议创建专用系统账号运行 Synapse，并将 /opt/synapse-3.0.2 目录属主赋予该账号。
防火墙需放行 8280/8243（业务端口）与 1099（JMX，仅限内网管理网段访问）。

七、常见问题

Q1：启动时报 Error: Could not create the Java Virtual Machine. 和 -Djava.endorsed.dirs ... is not supported 怎么办？

当前 JAVA_HOME 或系统默认 java 指向了 JDK 9+。执行 java -version 确认版本，安装 openjdk-8-jdk 并按 4.4、4.5 节将 JAVA_HOME 与 wrapper.java.command 均指向 JDK 8 路径。

Q2：synapse-daemon.sh start 提示 wrapper-linux-x86-32: not found？

32 位 wrapper 二进制存在但无法执行（缺少 32 位运行库）。执行 mv /opt/synapse-3.0.2/bin/native/wrapper-linux-x86-32 /opt/synapse-3.0.2/bin/native/wrapper-linux-x86-32.disabled 后重新启动。

Q3：daemon 模式反复重启失败，logs/wrapper.log 提示 5 次失败后放弃？

打开 logs/wrapper.log 查看具体异常。最常见原因是 wrapper.java.command 指向 JDK 9+，导致 JVM 携带 endorsed 参数启动失败，按 4.5 节修改后重新启动。

Q4：请求 8280 端口返回 202 但响应体为空？

请求路径缺少 /services/ 前缀，未路由到任何代理服务，落入默认 main 序列。正确格式为 http://<host>:8280/services/<代理名>。

Q5：修改 synapse.xml 后不生效？

独立发行版不支持中介配置热加载，修改后需重启：systemctl restart synapse 或 ./bin/synapse-daemon.sh restart。

八、卸载方式

停止服务并取消自启：

systemctl stop synapse
systemctl disable synapse

删除 systemd 单元与环境变量：

rm /etc/systemd/system/synapse.service
systemctl daemon-reload
rm /etc/profile.d/synapse.sh

删除程序目录与发行包：

rm -rf /opt/synapse-3.0.2
rm -f /tmp/synapse-distribution-3.0.2-bin.tar.gz

如需同时卸载 JDK：

DEBIAN_FRONTEND=noninteractive apt-get purge -y openjdk-8-jdk
apt-get autoremove -y

九、参考链接

官方主页：https://synapse.apache.org/
官方下载页：https://synapse.apache.org/download.html
历史版本归档：https://archive.apache.org/dist/synapse/
配置与中介器文档：https://synapse.apache.org/userguide/mediators.html
安装指南（英文原版）：https://synapse.apache.org/docs/installation_guide.html