Apache TomEE 10.2.0 配置参数详解

一、环境信息

二、前置条件

1. 已按安装指南完成 TomEE 10.2.0 的解压部署，/opt/tomee 目录可用。
2. 了解 XML 基本语法；修改配置前先备份原文件：

cp /opt/tomee/conf/server.xml /opt/tomee/conf/server.xml.bak

3. 修改任意配置文件后均需重启进程生效：

systemctl restart tomee

三、参数查看与修改方式

3.1 配置文件清单

ls /opt/tomee/conf

实测回显：

catalina.policy  catalina.properties  context.xml  logging.properties
server.xml  server.xml.original  system.properties  tomcat-users.xml
tomcat-users.xml.original  tomcat-users.xsd  tomee.xml  web.xml

带 .original 后缀的是发行包原始备份，可作为改动前的参照。

3.2 修改生效方式

3.3 验证配置正确性

改动 server.xml 后可先做语法检查再重启：

/opt/tomee/bin/configtest.sh

实测回显末行：

INFO: Server initialization in [1110] milliseconds

命令退出码为 0 表示 server.xml 语法正确。

四、参数总览

五、核心参数分类详解

5.1 server.xml：端口与连接器

server.xml 是 Catalina 的主配置文件。停止端口位于文件根部：

<Server port="8005" shutdown="SHUTDOWN">

• port="8005"：接收 SHUTDOWN 关闭指令的端口，实测仅监听本机回环地址；务必不对公网开放。
• shutdown="SHUTDOWN"：触发关闭的明文指令，可改为自定义字符串增强安全性。

默认启用的 HTTP 连接器（TomEE 发行包特有 server 与 xpoweredBy 属性，用于隐藏产品指纹）：

<Connector port="8080" protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="8443"
           maxParameterCount="1000"
           xpoweredBy="false" server="Apache TomEE" />

8443 的 SSL/TLS 连接器与 8009 的 AJP 连接器在 10.2.0 发行包中默认处于注释状态，未使用时不监听对应端口。

5.2 server.xml：Host 与应用部署

<Host name="localhost"  appBase="webapps"
      unpackWARs="true" autoDeploy="true">

war 包放入 /opt/tomee/webapps 后自动解压部署，目录名即访问路径。实测将 hello.war 放入后通过 http://localhost:8080/hello/ 访问返回 200。

5.3 tomee.xml：TomEE 专属配置

tomee.xml 是 TomEE 区别于原版 Tomcat 的核心配置文件，默认内容几乎为空：

<tomee>
  <!-- activate next line to be able to deploy applications in apps -->
  <!-- <Deployments dir="apps" /> -->
</tomee>

常用能力：

1. 声明部署目录：取消注释 <Deployments dir="apps" /> 后，/opt/tomee/apps 目录中的应用也会被部署。
2. 声明资源：在 tomee.xml 中以 <Resource>、<Container> 元素声明数据源、JMS 连接工厂等，供应用按 JNDI 名称引用。例如声明一个数据源：

<tomee>
  <Resource id="myDataSource" type="DataSource">
    JdbcDriver = org.hsqldb.jdbcDriver
    JdbcUrl = jdbc:hsqldb:mem:testdb
    UserName = sa
    Password =
    JtaManaged = true
  </Resource>
</tomee>

3. 调整服务器行为：<Container id="myCmp" ctype="ENTITY"/>、<Connector id="http+tomcat" port="8081"/> 等子元素按需声明。

5.4 system.properties：TomEE 系统属性

system.properties 中的键值对会在启动时注入为 JVM 系统属性。10.2.0 默认唯一启用项：

tomee.serialization.class.blacklist = *

含义：出于安全考虑默认拒绝全部远程反序列化类。常用可调参数还包括（默认均以注释形式给出）：

修改后重启生效；确认属性已注入可用 JDK 自带的 jcmd 查看：

jcmd $(jps | awk '/Bootstrap/{print $1}') VM.system_properties | grep tomee.serialization

实测回显：

tomee.serialization.class.blacklist=*

5.5 bin/setenv.sh：JVM 参数

setenv.sh 默认不存在，由维护者创建，startup.sh 与 catalina.sh 会自动加载。实测配置：

#!/bin/sh
JAVA_OPTS="-Xms256m -Xmx512m -Djava.awt.headless=true"

验证堆参数已生效：

jps -v | grep Bootstrap | grep -oE "Xms256m Xmx512m"

实测回显：

Xms256m Xmx512m

内存建议：初始堆与最大堆设置为相同值可避免运行期扩容抖动；256-512MB 适合中小应用，高负载场景按 可用物理内存 = 堆 + 元空间 + 线程栈 + 堆外缓存 估算上调。

5.6 tomcat-users.xml：管理账号

默认文件全部为注释，管理页不可用。实测启用的账号：

<role rolename="manager-gui"/>
<role rolename="manager-script"/>
<role rolename="manager-status"/>
<role rolename="admin-gui"/>
<user username="admin" password="q1w2e3r4" roles="manager-gui,manager-script,manager-status,admin-gui"/>

密码存储支持明文或摘要，摘要可用 digest.sh 生成后以 {SHA512}摘要值 形式写入 password 属性。

5.7 catalina.properties：类加载路径

common.loader="${catalina.base}/lib","${catalina.base}/lib/*.jar","${catalina.home}/lib","${catalina.home}/lib/*.jar"
server.loader=
shared.loader=

5.8 logging.properties：日志级别

日志框架为 JULI，常用参数：

1catalina.org.apache.juli.AsyncFileHandler.level = FINE
localhost.org.apache.juli.AsyncFileHandler.level = FINE

排障时可临时把 1catalina.org.apache.juli.AsyncFileHandler.level 调整为 ALL，完成后恢复 FINE，避免日志膨胀。

六、生产配置模板

以下为中小流量生产环境（2 核 4GB 内存的通用服务器、磁盘 40GB+）的推荐基线，均标注适用场景：

1. /opt/tomee/bin/setenv.sh（场景：中小 Web 应用，堆 512MB 上限防止单实例挤占整机内存）：

#!/bin/sh
JAVA_OPTS="-Xms512m -Xmx512m -Djava.awt.headless=true -XX:MaxMetaspaceSize=256m"
CATALINA_PID="/opt/tomee/temp/tomee.pid"

2. server.xml 连接器（场景：前面有 Nginx 反代，无长连接压力）：

<Connector port="8080" protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="8443"
           maxThreads="200"
           maxParameterCount="1000"
           xpoweredBy="false" server="Apache TomEE"
           acceptCount="100" />

3. system.properties（场景：需要远程 EJB 或 JNDI 客户端时才放开白名单，否则保持 blacklist=*）：

tomee.serialization.class.blacklist = *
# tomee.serialization.class.whitelist = com.example.dto

4. tomee.xml（场景：需要为应用提供共享数据源时添加 Resource 声明，否则保持为空）。

5. tomcat-users.xml（场景：仅保留必要角色，密码更换为强密码；磁盘方面常规部署小于 1GB，日志目录建议预留 5GB 并配置轮转）。

七、常见问题

Q1：修改了 server.xml 但重启后不生效？

先用 configtest.sh 确认语法正确且退出码为 0；再确认修改的是运行实例实际使用的 CATALINA_BASE 下的 conf 文件。systemd 单元中 Environment=CATALINA_BASE=/opt/tomee 指明了基准目录，若存在多实例，各实例的 conf 相互独立。

Q2：堆内存上限应该设多大？

以 256-512MB 为基线，观察 /opt/tomee/logs/catalina.out 中是否有 FullGC 频繁、java.lang.OutOfMemoryError 等信号再逐步上调。核对当前值：

ps -ef | grep "[j]ava" | grep -oE "Xms[0-9]+m Xmx[0-9]+m"

实测回显：

Xms256m Xmx512m

Q3：manager 页面提示 403 拒绝访问？

说明账号存在但角色不足或浏览器访问的路径与角色不匹配：/manager/html 需要 manager-gui，/manager/text 需要 manager-script。核对 tomcat-users.xml 中 user 元素的 roles 列表后重启进程。

Q4：如何确认某项 TomEE 系统属性已生效？

通过 JDK 自带的 jcmd 查看注入后的实际值：

jcmd $(jps | awk '/Bootstrap/{print $1}') VM.system_properties | grep "关键字"

八、参考链接

1. TomEE 官方文档（部署与资源说明）：https://tomee.apache.org/latest/docs/
2. TomEE 系统属性清单：https://tomee.apache.org/latest/docs/admin/configuration/properties-listing.html
3. Tomcat 10.1 server.xml 参考：https://tomcat.apache.org/tomcat-10.1-doc/config/server.html
4. Tomcat 10.1 HTTP Connector 参考：https://tomcat.apache.org/tomcat-10.1-doc/config/http.html
5. Tomcat 10.1 Manager 应用文档：https://tomcat.apache.org/tomcat-10.1-doc/manager-howto.html