Apache Axis2 配置参数详解

详解 Axis2 2.0.1 配置体系：conf/axis2.xml 全局参数、传输层 HTTP/TCP 参数、log4j2 日志、services.xml 服务级参数与作用域，附生产配置模板与修改生效规则，全部实测。

Apache Axis2Axis22026/10/13

Apache Axis2 配置参数详解

目标：系统梳理 Apache Axis2 2.0.1 的三层配置体系——全局 axis2.xml、传输层参数、服务级 services.xml 与日志配置，逐项给出真实默认值、作用与修改方法，已在 Ubuntu 22.04.5（OpenJDK 17.0.20.1、Axis2 2.0.1 standalone）实测通过。

一、环境信息

本篇所有参数取值与验证命令均在以下环境中实测采集：

  • 操作系统：Ubuntu 22.04.5 LTS，x86_64
  • JDK：OpenJDK 17.0.20.1
  • 组件版本：Apache Axis2 2.0.1（官方 bin 发行包，standalone 形态）
  • 安装目录：/opt/axis2
  • 配置文件：/opt/axis2/conf/axis2.xml（374 行）、/opt/axis2/conf/log4j2.xml、/opt/axis2/conf/commons-logging.properties
  • 服务端口：HTTP 8080
  • 执行用户：root

配置文件位置随发行包解压根目录而定（本篇统一为 /opt/axis2，war 部署时全局配置在 WEB-INF/conf/axis2.xml，服务仓库由 axis2.repository.path 指定）。

二、前置条件

本篇为配置专题，不需要重新安装，但要求具备可运行的 Axis2 2.0.1 环境以做修改验证。安装方法见《CentOS 8 安装 Apache Axis2 指南》或《Ubuntu 22.04 安装 Apache Axis2 指南》。开始前确认基线状态：

curl -s "http://localhost:8080/axis2/services/Version/getVersion"

回显（实测）：

<ns:getVersionResponse xmlns:ns="http://axisversion.sample"><ns:return>Hi - the Axis2 version is 2.0.1</ns:return></ns:getVersionResponse>

服务可调用即环境基线正常，后续修改都以该状态为对照。

三、参数查看与修改方式

Axis2 的配置分三层，修改方式与生效规则各不相同：

层级文件作用范围生效方式
全局/opt/axis2/conf/axis2.xml全部服务与传输重启（部分部署参数受热更新影响）
服务级服务包内 META-INF/services.xml单个服务新增 .aar 可热部署；更新已有 .aar 需重启（hotupdate=false）
日志/opt/axis2/conf/log4j2.xml日志输出重启

查看全局参数原文（本篇核心文件，共 374 行）：

wc -l /opt/axis2/conf/axis2.xml

回显（实测）：

374 /opt/axis2/conf/axis2.xml

⚠️ 注意：修改 axis2.xml 后必须重启 standalone 进程（systemd 环境执行 systemctl restart axis2）才生效；验证修改生效用 curl 复调 Version 服务加 jps -v 复核进程参数，不要只凭"改过了"。

四、参数总览

axis2.xml 顶层 <parameter> 实测清单（含默认值）：

参数名默认值作用
hotdeploymenttrue监控 services 目录，新 .aar 自动部署
hotupdatefalse是否允许热更新已部署服务
enableMTOMfalse启用 MTOM 二进制附件优化
enableSwAfalse启用 SOAP with Attachments
enableJSONOnlyfalse仅 JSON 消息模式
EnableChildFirstClassLoadingfalse服务类加载优先于父加载器
exposeServiceMetadatatrue对外暴露 ?wsdl/?xsd/?policy 元数据
ConfigContextTimeoutInterval30000配置上下文超时（毫秒）
sendStacktraceDetailsWithFaultsfalse故障响应中是否带 Java 堆栈
DrillDownToRootCauseForFaultReasonfalse故障原因是否追到根异常
disableRESTfalse禁用 REST 形态调用
disableSOAP12false禁用 SOAP 1.2
useGeneratedWSDLinJAXWSfalseJAX-WS 用生成 WSDL 而非实时构建
ServicesDirectory（注释态）service服务仓库目录名
ModulesDirectory（注释态）modules模块仓库目录名
contextRoot（注释态）axis2URL 上下文根
servicePath（注释态）services服务 URL 路径段
restPath（注释态）restREST URL 路径段
hostname（注释态）无回复 EPR 使用的主机名
userName / password空服务端基础鉴权（配合 security 模块）

关键解读：exposeServiceMetadata 与 sendStacktraceDetailsWithFaults 是生产安全最先要审的两项；hotdeployment/hotupdate 决定上线流程；其余传输参数见第五章分类详解。

五、核心参数分类详解

5.1 部署控制：hotdeployment 与 hotupdate

这两个参数决定"放一个 .aar 进去算不算发布"。当前默认配置（实测原文）：

<parameter name="hotdeployment">true</parameter>
<parameter name="hotupdate">false</parameter>
  • hotdeployment=true：向 repository/services/ 复制新的 .aar 文件即自动部署。实测将 HelloService.aar 复制进 services 目录后，日志立即打印 Deploying Web service: HelloService.aar，服务列表页随即出现该服务，无需重启。
  • hotupdate=false：对已部署服务的 .aar 内容更新不生效，必须重启进程。生产建议保持 false——热更新会引入类加载器残留与半更新状态。

验证部署开关的实际效果（新增服务热部署）：

cp /opt/software/HelloService.aar /opt/axis2/repository/services/
sleep 3
curl -s "http://localhost:8080/axis2/services/" | grep -oE "<h3><a href=\"[^\"]+\">[^<]+"

回显（实测）：

<h3><a href="HelloService?wsdl">HelloService
<h3><a href="Version?wsdl">Version

新服务免重启上线，hotdeployment=true 生效。

5.2 附件与二进制优化：enableMTOM / enableSwA

默认配置（实测原文）：

<parameter name="enableMTOM">false</parameter>
<parameter name="enableSwA">false</parameter>

enableMTOM=true 后，二进制参数自动以 MIME 附件分片传输而不是 Base64 内联；enableSwA=true 支持 SOAP with Attachments 风格。附件相关注释态参数：cacheAttachments=true（大附件落盘缓存）、attachmentDIR（缓存目录）、sizeThreshold=4000（超过 4KB 切换缓存）。

💡 技术拓展：二进制附件传输方案对比——

方案原理适用场景
Base64 内联二进制编码进 XML 文本小文件、实现最简单
MTOMXOP 引用 + MIME 分片，按需传输大附件、跨平台互操作首选
SwA整体 MIME multipart 包装遗留 .NET/Java 互操作

本文环境默认均关闭（false），纯 XML 业务无需开启；传输图片/文档类大参数时按互操作方能力选择 MTOM 优先。

5.3 服务元数据与 REST：exposeServiceMetadata / disableREST

默认配置（实测原文）：

<parameter name="exposeServiceMetadata">true</parameter>
<parameter name="disableREST" locked="false">false</parameter>
<parameter name="disableSOAP12" locked="true">false</parameter>
  • exposeServiceMetadata=true：?wsdl、?wsdl2、?xsd、?policy 请求返回元数据。实测 curl http://localhost:8080/axis2/services/Version?wsdl 返回完整 WSDL 文档；生产若不希望接口结构外泄，改为 false 后该类请求被拒绝。
  • disableREST=false：允许 HTTP GET/POST 的 REST 形态调用（如 Version/getVersion）；改 true 后仅接受标准 SOAP 信封。
  • disableSOAP12：locked="true" 表示子服务不得覆盖，默认不禁用 SOAP 1.2。

验证元数据开关：

curl -s "http://localhost:8080/axis2/services/Version?wsdl" | head -c 120; echo

回显（实测）：

<?xml version="1.0" encoding="UTF-8"?><wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:ns="http://axisversion.sample"

WSDL 可读即 exposeServiceMetadata=true 在生效。

5.4 HTTP 传输参数（transportReceiver http）

HTTP 接收器默认配置（实测原文，参数详解注释同步摘自配置文件）：

<transportReceiver name="http"
                   class="org.apache.axis2.transport.http.SimpleHTTPServer">
    <parameter name="port">8080</parameter>
    <!-- <parameter name="hostname">http://www.myApp.com/ws</parameter> -->
    <!-- <parameter name="originServer">My-Server/1.1</parameter> -->
    <!-- <parameter name="requestTimeout">10000</parameter> -->
    <!-- <parameter name="requestTcpNoDelay">false</parameter> -->
    <!-- <parameter name="requestCoreThreadPoolSize">50</parameter> -->
    <!-- <parameter name="requestMaxThreadPoolSize">100</parameter> -->
    <!-- <parameter name="threadKeepAliveTime">240000</parameter> -->
    <!-- <parameter name="threadKeepAliveTimeUnit">MILLISECONDS</parameter> -->
</transportReceiver>

逐项说明（含真实默认值）：port 默认 8080，standalone 的监听端口改这里；hostname 默认 null，设置后回复的 EPR 地址用它做前缀；originServer 默认 Simple-Server/1.1，是响应头的 Server 值；requestTimeout 默认 20000 毫秒请求等待；requestTcpNoDelay 默认 true（低延迟优先）；requestCoreThreadPoolSize 默认 25，requestMaxThreadPoolSize 默认 150（默认队列无界，最大线程数平时不生效）；threadKeepAliveTime 默认 180（SECONDS）。

出方向发送器（实测原文）：

<transportSender name="tcp"
                 class="org.apache.axis2.transport.tcp.TCPTransportSender"/>
<transportSender name="local"
                 class="org.apache.axis2.transport.local.LocalTransportSender"/>
<transportSender name="http"
                 class="org.apache.axis2.transport.http.impl.httpclient5.HTTPClient5TransportSender">
    <parameter name="PROTOCOL">HTTP/1.1</parameter>
    <parameter name="Transfer-Encoding">chunked</parameter>
</transportSender>
<transportSender name="https"
                 class="org.apache.axis2.transport.http.impl.httpclient5.HTTPClient5TransportSender">
    <parameter name="PROTOCOL">HTTP/1.1</parameter>
    <parameter name="Transfer-Encoding">chunked</parameter>
</transportSender>

HTTP 出站基于 Apache HttpClient 5，默认 chunked 传输编码。修改端口示例（改成 8090）并重启验证：

sed -i 's|<parameter name="port">8080</parameter>|<parameter name="port">8090</parameter>|' /opt/axis2/conf/axis2.xml
systemctl restart axis2
sleep 16
curl -s -o /dev/null -w "%{http_code}\n" "http://localhost:8090/axis2/services/Version/getVersion"

回显（实测）：

200

5.5 TCP 传输参数（实测启用过程）

默认 axis2.xml 没有 TCP 接收器，需要时手动加入。实测生效配置：

<transportReceiver name="tcp"
                   class="org.apache.axis2.transport.tcp.TCPTransportListener">
    <parameter name="transport.tcp.port">6060</parameter>
</transportReceiver>

⚠️ 注意：端口参数名是 transport.tcp.port 而不是 port。实测写成 port 时监听线程启动但从未绑定端口（/dev/tcp/localhost/6060 探测 CLOSED）；改正后日志出现 TCP server started on port : 6060，探测 OPEN。

TCP 相关参数（实测自运行日志与类定义）：transport.tcp.port 指定监听端口（实测设 6060）；transport.tcp.contentType 默认 text/xml（按 SOAP 1.1 解析，SOAP 1.2 客户端需配 application/soap+xml）；transport.tcp.hostname 与 transport.tcp.backlog 可选。同时该传输启用后日志出现 TCP Sender started。

TCP 模式下服务必须在 services.xml 声明暴露的传输，否则启动日志报 Service doesn't have configuration information for transport tcp 且服务对 TCP 不可用（实测复现）：

<transports>
    <transport>http</transport>
    <transport>tcp</transport>
</transports>

5.6 超时与故障调试参数

默认配置（实测原文）：

<parameter name="ConfigContextTimeoutInterval">30000</parameter>
<parameter name="sendStacktraceDetailsWithFaults">false</parameter>
<parameter name="DrillDownToRootCauseForFaultReason">false</parameter>
  • ConfigContextTimeoutInterval：配置上下文失效间隔，30000 毫秒。
  • sendStacktraceDetailsWithFaults：false 时 SOAP Fault 不携带服务端 Java 堆栈（生产保持 false，避免泄露内部路径）。
  • DrillDownToRootCauseForFaultReason：false 时故障原因不追溯根异常。

实测故障形态（调用不存在的方法时）：

curl -s -H "Content-Type: text/xml" -d '<?xml version="1.0"?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body/></soapenv:Envelope>' "http://localhost:8080/axis2/services/Version" | grep -oE "<faultstring>[^<]*" | head -1

回显（实测）：

<faultstring>The endpoint reference (EPR) for the Operation not found is /axis2/services/Version

默认配置下 Fault 文本不含堆栈，安全基线成立。

5.7 日志配置（log4j2.xml）

日志文件 conf/log4j2.xml（16 行），核心输出配置（实测原文）：

<Appenders>
    <Console name="Console">
        <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
    </Console>
</Appenders>
<Loggers>
    <!-- <Logger name="org.apache.axis2" level="debug" additivity="false"/> -->
    <Root level="info">
        <AppenderRef ref="Console"/>
    </Root>
</Loggers>

说明：Root level 默认 info，日志走 Console（standalone 被 nohup 重定向到文件时即全量落文件）；把 org.apache.axis2 的 Logger 行注释解开可单独开 Axis2 的 debug 而不动全局。修改后重启生效。

5.8 服务级参数（services.xml）

每个服务包（.aar）内 META-INF/services.xml 定义服务级配置。内置 Version 服务的完整原文（实测解包）：

<service name="Version">
    <description>
        This service is to get the running Axis version
    </description>
    <parameter name="ServiceClass">sample.axisversion.Version</parameter>
    <operation name="getVersion">
    <messageReceiver  class="org.apache.axis2.rpc.receivers.RPCMessageReceiver" />
    </operation>
</service>

逐项说明：name 服务名即 URL 末段；ServiceClass 全限定实现类；operation/messageReceiver 指定每个操作的消息接收器（RPCMessageReceiver 适配 POJO 方法调用）。服务级还可配置 scope（实例作用域）与 <transports>（暴露的传输，见 5.5）。

💡 技术拓展：service scope 实例作用域对比——

scope实例生命周期适用场景
request每个请求新建实例无状态业务，默认推荐
application整个服务生命周期单例缓存/连接池类状态
soapsession绑定 SOAP 会话标识会话型交互

本文示例服务无状态，使用默认 request；带共享状态的 POJO 用 application 并注意线程安全。

六、生产配置模板

适用场景：2C4G 虚拟机、中小流量 SOA 网关类部署（约 50 万次日调用、报文 1-10KB）。基于默认配置的推荐改动（可直接替换对应行）：

<axisconfig name="AxisJava2.0">
    <parameter name="hotdeployment">true</parameter>
    <parameter name="hotupdate">false</parameter>
    <parameter name="enableMTOM">false</parameter>
    <parameter name="enableSwA">false</parameter>
    <parameter name="exposeServiceMetadata">false</parameter>
    <parameter name="sendStacktraceDetailsWithFaults">false</parameter>
    <parameter name="DrillDownToRootCauseForFaultReason">false</parameter>
    <parameter name="disableREST" locked="false">false</parameter>
</axisconfig>

逐项解读：关闭 exposeServiceMetadata 避免接口结构外泄；sendStacktraceDetailsWithFaults 维持 false；保留 hotdeployment=true 方便新服务上线、hotupdate=false 保证更新走重启流程；MTOM/SwA 按业务开启（有二进制附件才开）。配套 JVM 限制（/opt/axis2/bin/axis2server.sh 第 35 行）：

JAVA_OPTS="-Xms256m -Xmx512m"

生效验证：

jps -v | grep SimpleAxis2Server

回显（实测）：

8922 SimpleAxis2Server -Xms256m -Xmx512m

七、常见问题（FAQ）

Q1：改了 axis2.xml 却不生效？ axis2.xml 只在启动时加载，热部署机制只覆盖 services 目录的 .aar 新增。解决：重启进程（systemctl restart axis2）后用业务请求复验。传输端口类修改用 curl 探新端口确认。

Q2：TCP 监听器日志显示 started 但端口连不上？ 实测根因：端口参数名写成了 port。TCP 接收器读取的参数名是 transport.tcp.port（实测改正后日志 TCP server started on port : 6060，端口探测 OPEN）。此外若服务 services.xml 未声明 <transports> 含 tcp，启动日志会报 Service doesn't have configuration information for transport tcp 并禁用该服务的 TCP 暴露。

Q3：SOAP 1.2 客户端走 TCP 报 "Transport level information does not match with SOAP Message namespace URI"？ TCP 传输默认 contentType 为 text/xml（按 SOAP 1.1 解析），与 SOAP 1.2 报文不匹配（实测服务端 SOAPBuilder 抛出该 Fault）。实测结论：客户端改用 SOAP 1.1（options.setSoapVersionURI("http://schemas.xmlsoap.org/soap/envelope/")）后端到端调用通过；SOAP 1.2 需同时调整请求与响应两端的 contentType 匹配——实测仅给接收器配 transport.tcp.contentType=application/soap+xml 时请求能送达、响应处理仍报同一错误，因此 TCP 场景推荐统一用 SOAP 1.1。

Q4：更新已有服务的 .aar 后行为没变？ hotupdate=false（默认）下更新已部署服务必须重启。实测过程：修改服务返回文本后重新打包同名 .aar 覆盖，调用仍返回旧文本（Hello, HotUpdate!）；systemctl restart axis2 后再调返回新文本（Hi there, HotUpdate!）。解决：重启进程；或临时调 hotupdate=true（不推荐长期开启，存在类加载残留风险）。

Q5：standalone 的服务列表页打不开？ 注意三种地址行为差异（均实测）：/axis2/services/（带斜杠）返回 HTML 服务列表；/axis2/services/ListServices 返回 501 Not Implemented；不带斜杠 /axis2/services 返回 200 空响应。standalone 下应使用带斜杠地址；war 部署才用 /axis2/services/listServices。

八、参考链接