Ubuntu 22.04 安装 Apache TomEE 10.2.0 指南

一、环境信息

项目	内容
操作系统	Ubuntu 22.04.5 LTS（x86_64）
组件	Apache TomEE 10.2.0（Web Profile 发行包）
内置 Tomcat 版本	10.1.57
JDK	OpenJDK 17（实测 17.0.20.1）
安装目录	/opt/tomee
HTTP 端口	8080
停止端口	8005（仅监听本机回环地址）
运行方式	systemd 托管（tomee.service）

二、前置条件

一台 Ubuntu 22.04 服务器，具备 root 或 sudo 权限。
服务器可访问公网（下载 JDK 与 TomEE 发行包）。
8080 端口未被占用，可用以下命令确认：

ss -ltn | grep :8080

无任何输出表示端口空闲；若已占用，请先释放端口或修改后文连接器端口。

安装基础工具 curl（用于下载与校验）：

apt-get update

apt-get install -y curl ca-certificates

三、版本选型说明

Apache TomEE 是构建在 Tomcat 之上的 Java EE / Jakarta EE 应用服务器，同一版本号提供 4 种发行包，均可在官方下载目录 https://downloads.apache.org/tomee/tomee-10.2.0/ 获取：

发行包	定位	典型场景
webprofile	Jakarta EE 10 Web Profile 认证子集	常规 Web 应用（Servlet、JSP、CDI、JPA、JSF、EJB Lite）
microprofile	Web Profile + MicroProfile	微服务、可观测性场景
plus	Web Profile + JMS 等更多企业特性	需要消息中间件集成的应用
plume	plus + JPA 完整实现（EclipseLink）等	遗留企业应用

本文选择当前最新稳定版 TomEE 10.2.0 的 Web Profile 发行包，对应文件 apache-tomee-10.2.0-webprofile.tar.gz（约 61MB）。TomEE 10.x 基于 Jakarta EE 10，要求 JDK 17 及以上版本，本文统一安装 OpenJDK 17。

四、部署步骤

4.1 安装 JDK 17

apt-get install -y openjdk-17-jdk-headless

安装完成后验证版本与安装路径：

java -version

实测回显：

openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)

readlink -f $(which java)

实测回显：

/usr/lib/jvm/java-17-openjdk-amd64/bin/java

4.2 下载官方发行包并校验

进入临时目录下载发行包与 SHA512 校验文件：

cd /tmp

curl -fLO https://downloads.apache.org/tomee/tomee-10.2.0/apache-tomee-10.2.0-webprofile.tar.gz

实测下载进度末行：

100 60.9M  100 60.9M    0     0  12.1M      0  0:00:05  0:00:05 --:--:-- 15.2M

下载校验文件并比对：

curl -sL -O https://downloads.apache.org/tomee/tomee-10.2.0/apache-tomee-10.2.0-webprofile.tar.gz.sha512

sha512sum -c apache-tomee-10.2.0-webprofile.tar.gz.sha512

实测回显：

apache-tomee-10.2.0-webprofile.tar.gz: OK

若当前稳定版升级导致该 URL 404，可到 https://archive.apache.org/dist/tomee/ 历史归档目录获取同名文件。

4.3 解压安装到 /opt/tomee

tar -xzf apache-tomee-10.2.0-webprofile.tar.gz -C /opt/

解压后目录名为 apache-tomee-webprofile-10.2.0，统一重命名为 /opt/tomee 便于后续维护：

mv /opt/apache-tomee-webprofile-10.2.0 /opt/tomee

确认目录结构：

ls /opt/tomee

实测回显：

BUILDING.txt  CONTRIBUTING.md  LICENSE  NOTICE  README.md  RELEASE-NOTES  RUNNING.txt
bin  conf  lib  logs  temp  webapps  work

4.4 配置 JVM 内存与运行参数（setenv.sh）

TomEE 启动脚本会自动加载 bin/setenv.sh（该文件默认不存在，需手工创建），这是调整 JVM 内存的标准位置。新建该文件：

cat > /opt/tomee/bin/setenv.sh << 'EOF'
#!/bin/sh
JAVA_OPTS="-Xms256m -Xmx512m -Djava.awt.headless=true"
EOF

赋予执行权限：

chmod +x /opt/tomee/bin/setenv.sh

堆内存说明：-Xms256m 初始堆 256MB，-Xmx512m 最大堆 512MB，适合中小规模 Web 应用；应用负载增大后可按需上调 -Xmx 值（如 1024m），并保证服务器物理内存充足。

4.5 配置管理账号

TomEE 默认不启用任何管理账号，manager 与 host-manager 管理页均无法登录。编辑 conf/tomcat-users.xml，在 <tomcat-users> 根元素内写入实际账号（本文示例账号 admin，密码 q1w2e3r4）：

cat > /opt/tomee/conf/tomcat-users.xml << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<tomcat-users xmlns="http://tomcat.apache.org/xml"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://tomcat.apache.org/xml tomcat-users.xsd"
              version="1.0">
  <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"/>
</tomcat-users>
EOF

角色说明：manager-gui 访问 /manager/html 管理页；manager-script 使用文本接口部署应用；admin-gui 访问 /host-manager 虚拟主机管理页。

生产环境请务必更换为强密码，并限制可访问管理页的来源 IP。

4.6 启动服务

/opt/tomee/bin/startup.sh

在交互终端下实测回显：

Using CATALINA_BASE:   /opt/tomee
Using CATALINA_HOME:   /opt/tomee
Using CATALINA_TMPDIR: /opt/tomee/temp
Using JRE_HOME:        /usr
Using CLASSPATH:       /opt/tomee/bin/bootstrap.jar:/opt/tomee/bin/tomcat-juli.jar
Using CATALINA_OPTS:
Tomcat started.

查看启动日志确认无异常：

tail -5 /opt/tomee/logs/catalina.out

实测回显末行：

12-Oct-2026 05:33:41.143 INFO [main] jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke Server startup in [825] milliseconds

4.7 验证安装

验证 HTTP 端口与首页：

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/

实测回显：

查看首页标题确认版本：

curl -s http://localhost:8080/ | grep -oE "<title>[^<]+</title>"

实测回显：

<title>Apache Tomcat (TomEE)/10.1.57 (10.2.0)</title>

查看服务版本信息：

/opt/tomee/bin/catalina.sh version

实测回显：

Server version: Apache Tomcat (TomEE)/10.1.57 (10.2.0)
Server built:   Jul 3 2026 13:06:05 UTC
Server number:  10.1.57.0
OS Name:        Linux
OS Version:     6.8.0-138-generic
Architecture:   amd64
JVM Version:    17.0.20.1+1-1-22.04-Ubuntu
JVM Vendor:     Ubuntu

验证 JVM 堆参数已按 setenv.sh 生效：

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

实测回显：

Xms256m Xmx512m

4.8 部署示例应用验证

构建一个最小的 JSP 测试应用并打成 war 包：

mkdir -p /tmp/hello/WEB-INF

cat > /tmp/hello/WEB-INF/web.xml << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
                             https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd"
         version="6.0">
  <display-name>hello-tomee</display-name>
</web-app>
EOF

cat > /tmp/hello/index.jsp << 'EOF'
<%@ page contentType="text/html; charset=UTF-8" %>
<html><body><h1>Hello from Apache TomEE 10.2.0</h1></body></html>
EOF

cd /tmp/hello && jar -cf /tmp/hello.war .

通过 manager 文本接口部署（首次热部署需等待约 30 秒完成扫描）：

curl -s -u admin:q1w2e3r4 "http://localhost:8080/manager/text/deploy?path=/hello&update=true" --upload-file /tmp/hello.war

实测回显：

OK - Deployed application at context path [/hello]

访问验证：

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/hello/

curl -s http://localhost:8080/hello/ | grep -oE "<h1>[^<]+</h1>"

实测回显：

200
<h1>Hello from Apache TomEE 10.2.0</h1>

4.9 配置 systemd 托管

先停止手工启动的实例：

/opt/tomee/bin/shutdown.sh

创建 systemd 服务单元（每行一个 Environment 项，前台运行方式便于 systemd 直接管控进程）：

cat > /etc/systemd/system/tomee.service << 'EOF'
[Unit]
Description=Apache TomEE 10.2.0 Web Profile
After=network.target

[Service]
Type=simple
Environment=JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
Environment=CATALINA_BASE=/opt/tomee
Environment=CATALINA_HOME=/opt/tomee
Environment=JAVA_OPTS=-Xms256m -Xmx512m
ExecStart=/opt/tomee/bin/catalina.sh run
ExecStop=/bin/kill -s TERM $MAINPID
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

重载 systemd 配置并设置开机自启：

systemctl daemon-reload

systemctl enable tomee

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/tomee.service → /etc/systemd/system/tomee.service.

systemctl start tomee

验证服务状态与页面：

systemctl status tomee --no-pager | head -5

实测回显：

● tomee.service - Apache TomEE 10.2.0 Web Profile
     Loaded: loaded (/etc/systemd/system/tomee.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-10-12 05:34:54 UTC; 8s ago
   Main PID: 4894 (java)
     Tasks: 47 (limit: 5753)

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/hello/

实测回显均为：

五、配置说明

配置项	位置	说明
HTTP 端口	/opt/tomee/conf/server.xml 中 `<Connector port="8080" protocol="HTTP/1.1"/>`	修改 port 后需重启
停止端口	server.xml 中 `<Server port="8005" shutdown="SHUTDOWN">`	关闭脚本的内部通道，仅监听本机
JVM 内存	/opt/tomee/bin/setenv.sh 的 JAVA_OPTS	修改后 systemctl restart tomee 生效
管理账号	/opt/tomee/conf/tomcat-users.xml	生产环境应改强密码
应用部署目录	/opt/tomee/webapps（server.xml 的 appBase）	war 包放入后自动解压部署
TomEE 专属配置	/opt/tomee/conf/tomee.xml	默认为空，可声明资源与部署目录
系统属性	/opt/tomee/conf/system.properties	反序列化白/黑名单等 TomEE 专属属性

可选：将 TomEE 命令加入环境变量，编辑 /etc/profile.d/tomee.sh：

cat > /etc/profile.d/tomee.sh << 'EOF'
export CATALINA_HOME=/opt/tomee
export PATH=$CATALINA_HOME/bin:$PATH
EOF

重新登录后可直接执行 catalina.sh version 等命令。

六、注意事项

生产环境建议创建专用的低权限系统用户运行 TomEE，并通过 chown -R 限制 /opt/tomee 目录归属，避免使用 root 运行。
setenv.sh 是 JVM 参数唯一推荐修改点，请勿直接改动 catalina.sh，否则升级时会被覆盖。
manager 文本接口与 HTML 管理页默认对所有来源开放，生产环境应通过防火墙或反向代理限制来源。
升级 TomEE 时建议保留 conf 目录与 webapps 的备份，新版本解压到独立目录后做软切换。
8005 端口的 SHUTDOWN 指令默认无认证，务必保证该端口不对公网开放（默认已仅绑定本机回环地址）。

七、常见问题

Q1：执行 startup.sh 后页面无法访问怎么办？

先看启动日志尾部是否出现 Server startup in 行：

tail -20 /opt/tomee/logs/catalina.out

常见原因：8080 端口被占用（日志出现 Address already in use），先释放端口或修改 server.xml 中的连接器端口后重启。

Q2：对已停止的实例执行 shutdown.sh 报错是否正常？

实测对未运行实例执行停止命令会输出：

SEVERE: Error stopping Catalina
java.net.ConnectException: Connection refused

该报错表示 8005 停止端口上没有进程在监听，属于正常现象，无需处理。

Q3：交互终端能看到 Using CATALINA_BASE 等回显，自动化脚本里为什么没有？

catalina.sh 内部仅在检测到终端（TTY）时才打印 Using CATALINA_BASE、Using CATALINA_HOME 等信息，非终端环境只输出 Tomcat started.，不影响实际启动结果。

Q4：修改 setenv.sh 后内存没有变化？

setenv.sh 仅在 JVM 启动时读取，必须重启进程生效。可用以下命令核对当前堆参数：

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

实测回显：

Xms256m Xmx512m

八、卸载方式

依次执行以下命令（先停止并移除开机自启）：

systemctl disable tomee

实测回显：

Removed /etc/systemd/system/multi-user.target.wants/tomee.service.

systemctl stop tomee

删除服务单元并重载：

rm /etc/systemd/system/tomee.service

systemctl daemon-reload

删除程序目录与可选的环境变量文件：

rm -rf /opt/tomee

rm -f /etc/profile.d/tomee.sh

如需一并卸载 JDK：

apt-get remove --purge -y openjdk-17-jdk-headless

apt-get autoremove -y

九、参考链接

Apache TomEE 官网：https://tomee.apache.org/
TomEE 10.2.0 官方下载目录：https://downloads.apache.org/tomee/tomee-10.2.0/
TomEE 历史版本归档：https://archive.apache.org/dist/tomee/
Tomcat 10.1 配置参考：https://tomcat.apache.org/tomcat-10.1-doc/config/
TomEE 属性清单：https://tomee.apache.org/latest/docs/admin/configuration/properties-listing.html