Apache Synapse 3.0.2 常用 CLI 命令与工具详解

一、环境信息

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

本文所有命令与回显均来自真实环境实测。

二、工具概览

命令	位置	用途
synapse.sh	bin/	前台启动 Synapse（支持样例与调试参数）
synapse-daemon.sh	bin/	daemon 模式启停与状态管理（wrapper 托管）
ciphertool.sh	bin/	安全加密库工具（配置敏感值加密）
synapse-config-migrator.sh	bin/	旧版本配置迁移工具
jps / ps / ss	JDK / 系统	运行态进程、参数与端口排查辅助

三、前置条件

3.1 JAVA_HOME 必须指向 JDK 8

所有 bin/ 下脚本均要求 JAVA_HOME，缺失时直接退出：

You must set the JAVA_HOME variable before running Synapse.

同时必须为 JDK 8。JDK 9+ 环境下启动会报 Error: Could not create the Java Virtual Machine.（endorse 机制不兼容）。确认方式：

export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
$JAVA_HOME/bin/java -version

实测回显：

openjdk version "1.8.0_504"
OpenJDK 64-Bit Server VM (build 25.504-b01, mixed mode, sharing)

3.2 运行目录

synapse.sh 启动时切换到 SYNAPSE_HOME，建议统一从安装目录调用脚本：

cd /opt/synapse-3.0.2

四、工具详解

4.1 synapse.sh：前台启动

查看帮助：

./bin/synapse.sh -h

实测回显：

Usage: synapse.sh ( commands ... )
commands:
  -xdebug            Start Synapse under JPDA debugger
  -sample (number)   Start with sample Synapse configuration of given number
  -serverName <name> Name of the Synapse server instance
  -synapseDebug      Start Synapse under debug mode

基础启动（前台运行，Ctrl+C 停止）：

./bin/synapse.sh

实测启动日志关键行：

Starting Synapse/Java ...
Using SYNAPSE_HOME:    /opt/synapse-3.0.2
Using JAVA_HOME:       /usr/lib/jvm/java-8-openjdk-amd64
Using SYNAPSE_XML:     /opt/synapse-3.0.2/repository/conf/synapse-config
INFO SynapseServer Starting Apache Synapse...
INFO PassThroughHttpListener Pass-through HTTP listener started on port: 8280
INFO PassThroughHttpSSLListener Pass-through HTTPS listener started on port: 8243
INFO SynapseServer Apache Synapse started successfully

参数实测：

-sample 0：加载官方样例配置并启动，日志显示 Using synapse.xml location : /opt/synapse-3.0.2/repository/conf/sample/synapse_sample_0.xml 与 Apache Synapse started successfully。样例编号对应 samples/ 目录下的 synapse_sample_N.xml。
-serverName <name>：实测传入后日志仍显示 Using server name : localhost，该参数在 3.0.2 实测未生效，服务器名以配置内部解析为准。
-xdebug：实测 JVM 附加 -Xrunjdwp:transport=dt_socket,server=y,address=8000，可用 ps -ef | grep [j]ava | grep -o 'Xrunjdwp[^ ]*' 确认，调试端口 8000。
-synapseDebug：正常启动，开启 Synapse 中介调试输出。
未知参数报错并退出（实测传入 -bad）：

Error: unknown command:-bad
For help: synapse.sh -h

注意：前台模式 JVM 堆参数硬编码于脚本（默认 -Xms512M -Xmx512M），修改需编辑 bin/synapse.sh。

4.2 synapse-daemon.sh：daemon 生命周期管理

支持的命令（脚本内实测）：

Usage: $0 { console | start | stop | restart | status | dump }

start 启动：

./bin/synapse-daemon.sh start

实测回显：

Starting Apache Synapse (Synapse)...

status 查询：

./bin/synapse-daemon.sh status

实测回显：

Apache Synapse (Synapse) is running (7847).

restart 重启：

./bin/synapse-daemon.sh restart

实测回显：

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

stop 停止：

./bin/synapse-daemon.sh stop

实测回显：

Stopped Apache Synapse (Synapse).

console 前台运行：以控制台模式输出日志（排障用）。dump 输出线程转储。

两个实测发现的运行约束：

首次启动前需创建日志目录：mkdir -p /opt/synapse-3.0.2/logs /opt/synapse-3.0.2/work/temp/synapse。
daemon 模式由 Tanuki wrapper 拉起，wrapper.conf 中 wrapper.java.command 必须指向 JDK 8 的 java 全路径，且 bin/native/ 下 32 位 wrapper 二进制在无 32 位运行库的系统上无法执行（表现为 wrapper-linux-x86-32 not found），需将其改名禁用，脚本自动回退 64 位。

停止的替代方式：前台模式直接终止进程（按 Ctrl+C 或 kill），生产环境统一使用 synapse-daemon.sh stop 或 systemctl stop。

4.3 ciphertool.sh：安全加密库工具

ciphertool 用于 Synapse secure vault 场景（加密 cipher-text.properties 中的敏感明文，管理密钥库）。该工具无帮助选项，实测错误回显：

无参数执行：

SEVERE: The argument : source : cannot be null or empty.
Exception in thread "main" org.apache.synapse.securevault.SecureVaultException: The argument : source : cannot be null or empty.

-h 执行：

SEVERE: Error passing arguments
org.apache.commons.cli.UnrecognizedOptionException: Unrecognized option: -h

即 ciphertool 不支持 -h，必须携带具体子命令参数（加密/解密、密钥库路径与密码等）。日常独立部署通常用不到它，仅在需要加密配置敏感值时使用，操作前先备份 repository/conf 目录。

4.4 synapse-config-migrator.sh：配置迁移工具

用于将旧版本（2.x）Synapse 配置迁移到 3.x 格式。无 JAVA_HOME 时报错：

You must set the JAVA_HOME variable before running Synapse Configuration Migrator.

设置 JAVA_HOME 后无参运行（实测）：

Starting Synapse Configuration Migration ...
Using SYNAPSE_HOME :    /opt/synapse-3.0.2
Using JAVA_HOME :       /usr/lib/jvm/java-8-openjdk-amd64
Migrating configuration :

该工具按交互提示输入源配置路径，无 --help 选项；迁移前务必备份原配置目录，迁移完成后用 synapse.sh 启动验证。

4.5 辅助排查命令

进程与 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，参数中包含 -Xms256m -Xmx512m（wrapper.conf 定义的值）。

端口监听验证：

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))

服务可用性验证（回显代理实测）：

curl -s -X POST -H 'Content-Type: text/xml; charset=UTF-8' \
  -d '<?xml version="1.0"?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body><hi>hi</hi></soapenv:Body></soapenv:Envelope>' \
  http://127.0.0.1:8280/services/HelloProxy

实测回显：

<ns:response xmlns:ns="http://example.org">ok-from-synapse</ns:response>

日志定位：logs/synapse.log（主日志）、logs/wrapper.log（daemon 拉起失败排查首选）、logs/service.log、logs/http_access_日期.log。

五、注意事项

所有脚本对 JAVA_HOME 敏感，推荐在 /etc/profile.d/synapse.sh 统一定义，任何定时任务或 systemd 单元中也需显式传入。
synapse.sh 前台运行时终止终端会话会连带停止服务，长期运行必须使用 daemon 模式或 systemd。
synapse-daemon.sh stop 依赖 wrapper 正常握手；若 wrapper.log 显示 5 次拉起失败后放弃，需先修正 wrapper.conf 再操作。
ciphertool 与 migrator 均无帮助输出，操作前备份 repository/conf；migrator 迁移后逐项核对序列与端点定义。
中介配置修改后无热加载，任何 synapse.xml 变更都需 restart 后用 curl 复测。

六、常见问题

Q1：执行脚本提示必须先设置 JAVA_HOME？

执行 export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64，或写入 /etc/profile.d/synapse.sh 并 source。注意 JDK 必须是 8。

Q2：-serverName 参数为什么不生效？

实测 3.0.2 中该参数传入后日志仍显示 server name localhost，属于该版本未生效的参数，服务器命名以内部解析为准，依赖实例名区分的场景建议在日志或配置层面自行标注。

Q3：daemon start 后 status 显示 is not running？

查看 logs/wrapper.log 定位首次失败原因。最常见两点：wrapper.java.command 指向 JDK 9+ 导致 endorsed 报错；32 位 wrapper 二进制无法执行。分别改为 JDK 8 全路径、禁用 wrapper-linux-x86-32 后重启。

Q4：如何确认当前 JVM 堆参数？

jps -v 或 ps -ef | grep [j]ava，输出含 -Xms/-Xmx 实际值。前台模式与 daemon 模式参数来源不同（bin/synapse.sh 与 wrapper.conf），需分别确认。

Q5：curl 请求返回 202 空响应？

代理服务路径必须带 /services/ 前缀，检查 URL 是否为 http://<host>:8280/services/<代理名>。

七、参考链接

官方主页：https://synapse.apache.org/
安装与运行指南：https://synapse.apache.org/docs/installation_guide.html
官方样例列表：https://synapse.apache.org/docs/samples_setup.html
历史版本归档：https://archive.apache.org/dist/synapse/