Apache Synapse 3.0.2 Docker Compose 部署指南

使用 Docker Compose 部署 Apache Synapse 3.0.2 的实测指南，提供自建镜像 Dockerfile 与编排文件样例，覆盖构建启动、端口映射、配置与日志持久化、JVM 堆固化、等价运行命令及运维排障。

Apache SynapseApache Synapse2026/10/12

Apache Synapse 3.0.2 Docker Compose 部署指南

一、环境信息

项目值
Docker Engine29.8.0（实测版本）
Docker Composev5.5.1（实测版本）
组件版本Apache Synapse 3.0.2
基座镜像eclipse-temurin:8-jdk（OpenJDK 8，Synapse 3.0.x 仅完整支持 Java 1.8）
端口8280（HTTP）、8243（HTTPS）、1099（JMX）
项目目录/opt/synapse-compose

本文全部构建与运行步骤均在 Docker 29.8.0 环境实测通过。

二、镜像选型说明

  • Docker Hub 上没有 Apache 官方发布的 Synapse 镜像，可靠方案是基于官方发行包自建镜像。
  • 基座选用 eclipse-temurin:8-jdk：Synapse 3.0.2 的启动脚本携带 -Djava.endorsed.dirs 参数，JDK 9 及以上版本会直接导致 JVM 创建失败，必须使用 JDK 8。
  • 构建时内置官方 MD5 校验（652b62cede3439cbde9fd71fea66ad4e），并完成三件标准化处理：禁用无法在纯 64 位运行库环境执行的 32 位 wrapper 二进制、将 JVM 堆从脚本默认的 512M 固化为 -Xms256M -Xmx512M、预创建 logs 与 work 目录。
  • 镜像内 Synapse 安装路径为 /opt/synapse-3.0.2，与物理机部署保持一致，便于配置复用。

三、前置条件

  • Docker Engine 20.10+ 与 Docker Compose v2+ 已安装且可用：docker version 与 docker compose version 均正常返回。
  • 主机可访问外网下载官方发行包（或已准备离线包与内部源）。
  • 磁盘剩余空间不低于 3GB（基座镜像约 460MB，构建后总占用约 1GB）。
  • 主机端口 8280、8243 未被占用：ss -tlnp | grep -E '8280|8243' 应无输出。

四、部署步骤

4.1 创建项目目录

mkdir -p /opt/synapse-compose/synapse-config
mkdir -p /opt/synapse-compose/synapse-logs
cd /opt/synapse-compose

4.2 编写 Dockerfile

cat > /opt/synapse-compose/Dockerfile <<'EOF'
FROM eclipse-temurin:8-jdk

RUN curl -SL --retry 3 -o /tmp/synapse.tar.gz https://downloads.apache.org/synapse/3.0.2/synapse-distribution-3.0.2-bin.tar.gz \
    && echo '652b62cede3439cbde9fd71fea66ad4e  /tmp/synapse.tar.gz' | md5sum -c - \
    && tar -xzf /tmp/synapse.tar.gz -C /opt/ \
    && rm -f /tmp/synapse.tar.gz \
    && mv /opt/synapse-3.0.2/bin/native/wrapper-linux-x86-32 /opt/synapse-3.0.2/bin/native/wrapper-linux-x86-32.disabled \
    && sed -i 's/-Xms512M -Xmx512M/-Xms256M -Xmx512M/' /opt/synapse-3.0.2/bin/synapse.sh \
    && mkdir -p /opt/synapse-3.0.2/logs /opt/synapse-3.0.2/work/temp/synapse

ENV SYNAPSE_HOME=/opt/synapse-3.0.2 \
    JAVA_HOME=/opt/java/openjdk

EXPOSE 8280 8243 1099

WORKDIR /opt/synapse-3.0.2

CMD ["/opt/synapse-3.0.2/bin/synapse.sh"]
EOF

构建层说明：MD5 校验保证发行包完整性；mv 禁用 32 位 wrapper（否则容器内同样报 wrapper-linux-x86-32 not found）；sed 将 synapse.sh 硬编码的堆参数固化为 256-512MB（该脚本不读取 JAVA_OPTS 环境变量，只能在构建期修改）。

4.3 编写 docker-compose.yml

cat > /opt/synapse-compose/docker-compose.yml <<'EOF'
services:
  synapse:
    build: .
    image: apache-synapse:3.0.2
    container_name: synapse-esb
    ports:
      - '8280:8280'
      - '8243:8243'
    volumes:
      - ./synapse-config:/opt/synapse-3.0.2/repository/conf/synapse-config
      - ./synapse-logs:/opt/synapse-3.0.2/logs
    restart: unless-stopped
EOF

4.4 准备中介配置

挂载目录会覆盖镜像内的默认配置，必须放入有效配置。最小可用回显代理（实测返回 HTTP 200）：

cat > /opt/synapse-compose/synapse-config/synapse.xml <<'EOF'
<?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>
EOF

同时从镜像补齐默认的序列文件（避免 main/fault 序列缺失影响代理部署）：

cd /opt/synapse-compose
docker build -t apache-synapse:3.0.2 .
docker create --name synapse-tmp apache-synapse:3.0.2
docker cp synapse-tmp:/opt/synapse-3.0.2/repository/conf/synapse-config/sequences synapse-config/
docker rm synapse-tmp

注意 synapse.xml 与 sequences/main.xml、sequences/fault.xml 不能重复定义同名序列，否则启动报 Duplicate sequence definition 后退出。

4.5 构建并启动

cd /opt/synapse-compose
docker compose up -d --build

实测回显：

Container synapse-esb Creating
Container synapse-esb Created
Container synapse-esb Starting
Container synapse-esb Started

4.6 验证部署

确认运行状态与端口映射：

docker compose ps

实测回显：

NAME          IMAGE                  STATUS         PORTS
synapse-esb   apache-synapse:3.0.2   Up 37 seconds  0.0.0.0:8280->8280/tcp, 0.0.0.0:8243->8243/tcp, 1099/tcp

业务验证（回显代理）：

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>hello</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>

JVM 堆验证：

docker exec synapse-esb ps -ef | grep [j]ava | grep -o '\-Xms\S* \-Xmx\S*'

实测回显：

-Xms256M -Xmx512M

启动日志验证：

docker logs synapse-esb 2>&1 | grep -E 'started successfully|listener started'

实测回显：

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

五、数据持久化说明

宿主目录容器内路径内容
/opt/synapse-compose/synapse-config/opt/synapse-3.0.2/repository/conf/synapse-config中介配置（代理、序列、端点）
/opt/synapse-compose/synapse-logs/opt/synapse-3.0.2/logssynapse.log、service.log、trace.log、http_access_日期.log

实测挂载后日志文件正常落盘宿主目录；重建容器（down 后 up）不丢失日志与配置。axis2.xml、wrapper.conf 等其余配置仍在镜像内，如需持久化可按同样方式增加挂载行。需要备份时归档两个宿主目录即可。

六、常用环境变量表

环境变量默认值说明
SYNAPSE_HOME/opt/synapse-3.0.2Synapse 安装目录（镜像 ENV 已固化）
JAVA_HOME/opt/java/openjdkJDK 路径（基座镜像自带）
JAVA_OPTS不生效synapse.sh 不读取该变量，JVM 参数需改脚本，勿在 compose 中设置

注意：Synapse 启动脚本将 JVM 参数硬编码在脚本内，不消费任何 JAVA_OPTS 环境变量，调整堆大小必须修改 synapse.sh（本文通过 Dockerfile 构建期 sed 固化为 -Xms256M -Xmx512M）。

七、常用配置参数说明

参数所在位置默认值说明
HTTP 监听端口repository/conf/axis2.xml8280transportReceiver http port
HTTPS 监听端口repository/conf/axis2.xml8243transportReceiver https port
服务路径前缀repository/conf/axis2.xml/services代理访问 URL 必须带此前缀
堆参数（前台模式）bin/synapse.sh-Xms512M -Xmx512M（本文镜像固化为 256/512）JVM 堆
HTTP 超时repository/conf/passthru-http.propertieshttp.socket.timeout=180000毫秒
传输线程池repository/conf/passthru-http.propertiescore=400 / max=500高并发可上调
日志级别lib/log4j.propertiesorg.apache.synapse=INFO排障可临时 DEBUG

修改镜像内配置的推荐流程：改 Dockerfile（追加 RUN sed 或 COPY 覆盖文件）后 docker compose up -d --build 重建。

八、配置文件持久化

中介配置持久化（compose 已含）：

volumes:
  - ./synapse-config:/opt/synapse-3.0.2/repository/conf/synapse-config

如需持久化传输配置，在 volumes 中追加：

      - ./conf/axis2.xml:/opt/synapse-3.0.2/repository/conf/axis2.xml
      - ./conf/passthru-http.properties:/opt/synapse-3.0.2/repository/conf/passthru-http.properties

先将镜像内原始文件拷出再挂载，避免权限与格式问题：

docker cp synapse-esb:/opt/synapse-3.0.2/repository/conf/axis2.xml ./conf/

修改挂载的配置后执行 docker compose restart 生效（Synapse 无热加载）。

九、等价 docker run 运行方式

不使用 Compose 时等价命令：

docker run -d \
  --name synapse-esb \
  -p 8280:8280 \
  -p 8243:8243 \
  -v /opt/synapse-compose/synapse-config:/opt/synapse-3.0.2/repository/conf/synapse-config \
  -v /opt/synapse-compose/synapse-logs:/opt/synapse-3.0.2/logs \
  --restart unless-stopped \
  apache-synapse:3.0.2

构建镜像（与 compose build 等价）：

cd /opt/synapse-compose
docker build -t apache-synapse:3.0.2 .

十、常用运维命令

docker compose ps                 # 查看服务状态
docker compose logs -f synapse    # 跟踪容器日志（启动输出）
docker compose restart            # 重启（配置变更后生效）
docker compose down               # 停止并移除（数据卷保留）
docker compose up -d              # 再次启动
docker compose up -d --build      # 配置或 Dockerfile 变更后重建
docker exec synapse-esb ps -ef | grep [j]ava   # 查看进程与 JVM 参数

实测 down 再 up 循环后服务正常、回显代理仍返回 200。停止时优先用 docker compose stop（保留容器便于快速拉起），down 会删除容器与网络但保留宿主挂载数据。

十一、常见问题

Q1：构建时报 failed to resolve source metadata for docker.io/library/eclipse-temurin:8-jdk？

主机无法直连 Docker Hub。配置镜像加速地址或代理后重试；离线环境可在可达机器 docker pull eclipse-temurin:8-jdk && docker save -o temurin8.tar eclipse-temurin:8-jdk，目标机 docker load -i temurin8.tar 后再构建。

Q2：容器反复重启，日志报 Could not create the Java Virtual Machine？

基座镜像被换成了 JDK 9+。Synapse 3.0.2 脚本携带 -Djava.endorsed.dirs，必须使用 JDK 8 基座（eclipse-temurin:8-jdk），确认 Dockerfile FROM 行未被改动。

Q3：请求 8280 返回 202 空响应？

路径缺少 /services/ 前缀。正确地址 http://<host>:8280/services/<代理名>；同时确认挂载的 synapse-config 内有该代理定义且 compose 已 restart。

Q4：启动报 Duplicate sequence definition？

挂载目录中的 synapse.xml 与 sequences/main.xml、sequences/fault.xml 重复定义了同名序列。删除 synapse.xml 内的 main/fault 定义或将自定义序列改名。

Q5：修改了 compose 中的环境变量 JAVA_OPTS 但堆没变？

synapse.sh 不读取 JAVA_OPTS。堆参数在脚本内硬编码，需通过 Dockerfile 的 sed 修改（本文镜像已固化为 -Xms256M -Xmx512M），重建后用 docker exec synapse-esb ps -ef | grep [j]ava 验证。

Q6：日志目录为空？

启动前容器内需存在 logs 目录（本文 Dockerfile 已预创建）；确认 compose 的 synapse-logs 挂载行未被注释，且宿主目录属主与容器内运行用户一致。

十二、参考链接