Apache TomEE 10.2.0 常用 CLI 命令与工具详解

一、环境信息

项目	内容
组件版本	Apache TomEE 10.2.0（Web Profile，内置 Tomcat 10.1.57）
JDK	OpenJDK 17
安装目录	/opt/tomee
脚本目录	/opt/tomee/bin
HTTP 端口	8080
停止端口	8005
管理账号	admin / q1w2e3r4（需在 conf/tomcat-users.xml 配置 manager-script 角色）

二、工具概览

命令	作用	典型场景
bin/startup.sh	后台启动 TomEE	日常启动
bin/shutdown.sh	优雅停止 TomEE	日常停止
bin/catalina.sh	核心控制脚本（start/stop/run/configtest/version 等）	前台运行、语法检查、版本查看
bin/version.sh	输出版本信息	排障确认版本
bin/configtest.sh	校验 server.xml 语法	改配置后重启前检查
bin/digest.sh	生成密码摘要	tomcat-users.xml 密码加密存储
manager 文本接口	通过 HTTP 管理应用（部署/启停/卸载/状态）	自动化运维、CI 发布
jps / ps	核验进程与 JVM 参数	内存配置验证

bin 目录下与上述同名但以 .bat 结尾的文件是 Windows 版本，Linux 服务器不使用。

三、前置条件

已按安装指南完成部署，TomEE 进程可正常启停。
使用 manager 文本接口需在 /opt/tomee/conf/tomcat-users.xml 中配置具备 manager-script 角色的账号：

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

可选：将 bin 目录加入 PATH（重新登录生效），下文命令以绝对路径书写，两种方式等价：

echo 'export CATALINA_HOME=/opt/tomee' > /etc/profile.d/tomee.sh

echo 'export PATH=$CATALINA_HOME/bin:$PATH' >> /etc/profile.d/tomee.sh

四、工具详解

4.1 startup.sh：启动服务

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

说明：

startup.sh 实质是调用 catalina.sh start，以 fork 方式在后台运行。
非 TTY 环境（如自动化脚本）只输出 Tomcat started.，Using 开头的信息块仅在检测到终端时打印，属脚本内部设计，不影响功能。
启动结果以日志为准：tail -5 /opt/tomee/logs/catalina.out 出现 Server startup in 起始的行即成功。

4.2 shutdown.sh：停止服务

/opt/tomee/bin/shutdown.sh

实测向 8005 端口发送 SHUTDOWN 指令，进程优雅退出（会话与连接等待关闭）。对未运行的实例执行会报连接拒绝：

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

该输出表示 8005 端口无进程监听，属正常现象。

4.3 catalina.sh：核心控制脚本

不带参数执行可查看全部子命令用法：

/opt/tomee/bin/catalina.sh

实测回显：

Usage: catalina.sh ( commands ... )
commands:
  debug             Start Catalina in a debugger
  debug -security   Debug Catalina with a security manager
  jpda start        Start Catalina under JPDA debugger
  run               Start Catalina in the current window
  run -security     Start in the current window with security manager
  start             Start Catalina in a separate window
  start -security   Start in a separate window with security manager
  stop              Stop Catalina, waiting up to 5 seconds for the process to end
  stop n            Stop Catalina, waiting up to n seconds for the process to end
  stop -force       Stop Catalina, wait up to 5 seconds and then use kill -KILL if still running
  stop n -force     Stop Catalina, wait up to n seconds and then use kill -KILL if still running
  configtest        Run a basic syntax check on server.xml - check exit code for result
  version           What version of tomcat are you running?
Note: Waiting for the process to end and use of the -force option require that $CATALINA_PID is defined

常用组合说明：

子命令	说明
run	前台运行（systemd 单元推荐方式，日志直连标准输出）
start / stop	后台启动 / 优雅停止，等价 startup.sh、shutdown.sh
stop n	最多等待 n 秒
stop -force	超时后强制 kill -KILL，需先设置 CATALINA_PID
jpda start	开启远程调试（默认端口 8000，可通过 setenv.sh 的 JPDA_ADDRESS 修改）
configtest / version	语法检查 / 版本查看

version 子命令实测：

/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

4.4 version.sh 与 configtest.sh

version.sh 是 catalina.sh version 的快捷方式，输出与上节一致：

/opt/tomee/bin/version.sh

configtest.sh 用于重启前校验 server.xml 语法：

/opt/tomee/bin/configtest.sh

实测回显末行：

INFO: Server initialization in [1110] milliseconds

校验通过时退出码为 0；语法错误时输出对应的行号与原因，可直接定位问题。等价写法：

/opt/tomee/bin/catalina.sh configtest

4.5 digest.sh：密码摘要生成

为 tomcat-users.xml 生成 SHA-512 摘要（示例密码 q1w2e3r4）：

/opt/tomee/bin/digest.sh -a sha-512 q1w2e3r4

实测回显（摘要含随机盐，每次执行结果不同）：

q1w2e3r4:d7d801e6a688a302585840dedd9f7180344db77c8e0ab3014611ed831def838c$1$2216c9cf5811a256cbd70ee13ce3d8c47e879114f7c21c5130f46c64de6ee993bc3b4fd3e4966601298802839920fb9106ea6374616633adb6da11eb9c944d09

冒号前为输入的明文，冒号后为摘要值。将冒号后的整段内容按 {SHA512}摘要值 格式写入 tomcat-users.xml 的 password 属性即可启用摘要认证。

4.6 manager 文本接口：应用管理

文本接口基址为 http://localhost:8080/manager/text/，全部命令需携带账号密码。下述命令在 TomEE 10.2.0 上逐一实测。

查看已部署应用列表：

curl -s -u admin:q1w2e3r4 http://localhost:8080/manager/text/list

OK - Listed applications for virtual host [localhost]
/hello:running:1:hello
/:running:0:ROOT
/host-manager:running:0:host-manager
/manager:running:0:manager
/docs:running:0:docs

每行格式为 路径:运行状态:会话数:应用名。

部署 war 包（update=true 表示覆盖已有同路径应用）：

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 -u admin:q1w2e3r4 "http://localhost:8080/manager/text/stop?path=/hello"

OK - Stopped application at context path [/hello]

curl -s -u admin:q1w2e3r4 "http://localhost:8080/manager/text/start?path=/hello"

OK - Started application at context path [/hello]

重载应用（保留会话重建上下文）：

curl -s -u admin:q1w2e3r4 "http://localhost:8080/manager/text/reload?path=/hello"

OK - Reloaded application at context path [/hello]

卸载应用：

curl -s -u admin:q1w2e3r4 "http://localhost:8080/manager/text/undeploy?path=/hello"

OK - Undeployed application at context path [/hello]

查看服务器信息：

curl -s -u admin:q1w2e3r4 http://localhost:8080/manager/text/serverinfo

OK - Server info
Tomcat Version: [Apache Tomcat (TomEE)/10.1.57 (10.2.0)]
OS Name: [Linux]
OS Version: [6.8.0-138-generic]
OS Architecture: [amd64]
JVM Version: [17.0.20.1+1-1-22.04-Ubuntu]
JVM Vendor: [Ubuntu]

查看会话信息与线程转储：

curl -s -u admin:q1w2e3r4 "http://localhost:8080/manager/text/sessions?path=/hello"

OK - Session information for application at context path [/hello]
Default maximum session inactive interval is [30] minutes

curl -s -u admin:q1w2e3r4 http://localhost:8080/manager/text/threaddump | head -3

OK - JVM thread dump
2026-10-12 05:43:41.264
Full thread dump OpenJDK 64-Bit Server VM (17.0.20.1+1-1-22.04-Ubuntu mixed mode, sharing):

查看 JVM 运行信息：

curl -s -u admin:q1w2e3r4 http://localhost:8080/manager/text/vminfo | head -4

OK - VM info
2026-10-12 05:43:41.238
Runtime information:
  vmName: OpenJDK 64-Bit Server VM

查看全局 JNDI 资源：

curl -s -u admin:q1w2e3r4 http://localhost:8080/manager/text/resources | head -2

OK - Listed global resources of all types
UserDatabase:org.apache.catalina.users.MemoryUserDatabase

注意：文本接口没有 /status 命令，误用会返回 FAIL - Unknown command [/status]；状态监控请使用 threaddump、vminfo、serverinfo 组合。

4.7 jps 与 ps：进程与内存核验

确认 TomEE 进程存在及其 JVM 参数（jps 随 JDK 提供）：

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

实测回显：

Xms256m Xmx512m

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

实测回显：

Xms256m Xmx512m

以上回显说明 bin/setenv.sh 中配置的 JAVA_OPTS="-Xms256m -Xmx512m -Djava.awt.headless=true" 已生效。修改堆参数后需重启进程，再用上述命令复核。

五、注意事项

start/stop 类脚本只在 JVM 启动时读取 setenv.sh，修改 JVM 参数后必须重启才生效。
stop -force 依赖 CATALINA_PID 变量，使用前需在 setenv.sh 中设置 CATALINA_PID=/opt/tomee/temp/tomee.pid。
manager 文本接口账号拥有部署任意应用的权限，生产环境应限制来源地址或改用受限角色。
首次热部署 war 包时 TldScanner 扫描约需 30 秒，等待完成后再验证访问，避免误判失败。
catalina.sh run 前台方式是 systemd 托管的标准形态（Type=simple），避免同时使用 startup.sh 与 systemd 双重管理。

六、常见问题

Q1：startup.sh 提示 Tomcat started. 但端口没起来？

以日志为准排查：

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

常见原因包括端口占用（Address already in use）、setenv.sh 参数非法导致 JVM 启动失败等，按日志修正后重新启动。

Q2：manager 文本接口返回 401 或 403？

401 表示账号密码错误或 tomcat-users.xml 未配置；403 表示账号缺少对应角色：部署启停需要 manager-script。核对配置后重启进程生效。

Q3：deploy 命令返回 FAIL 提示 war 已存在？

追加 &update=true 参数覆盖部署，或先执行 undeploy 再 deploy。

Q4：如何确认当前运行的是哪个版本？

/opt/tomee/bin/version.sh | head -3

实测回显：

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

七、参考链接

Tomcat 10.1 Manager 应用文档：https://tomcat.apache.org/tomcat-10.1-doc/manager-howto.html
Tomcat 10.1 RUNNING.txt（脚本说明）：https://tomcat.apache.org/tomcat-10.1-doc/RUNNING.txt
TomEE 官网：https://tomee.apache.org/
Tomcat 10.1 安全管理文档：https://tomcat.apache.org/tomcat-10.1-doc/security-howto.html