Apache TomEE 10.2.0 Docker Compose 部署指南

使用官方 tomee 镜像通过 Docker Compose 部署 Apache TomEE 10.2.0 的指南，覆盖镜像选型、compose 编写、持久化挂载、JAVA_OPTS 内存参数与运维命令。

Apache TomEEApache TomEE2026/10/12

Apache TomEE 10.2.0 Docker Compose 部署指南

一、环境信息

项目内容
宿主操作系统Linux x86_64（Docker 26+）
Docker Composev2.x 及以上（docker compose 子命令）
组件版本Apache TomEE 10.2.0（Web Profile）
官方镜像tomee:10-jre17-webprofile
镜像内 JDKOpenJDK 17.0.20.1
容器内安装目录/usr/local/tomee
HTTP 端口8080

二、镜像选型说明

Docker Hub 官方 tomee 镜像按 tomee:<JDK 版本>-<发行包> 组合打标，10.2.0 版本可选标签包括：

标签说明
tomee:10-jre17-webprofileJDK 17 + Web Profile，常规 Web 应用首选（本文实测使用）
tomee:10-jre17-microprofileMicroProfile，微服务场景
tomee:10-jre17-plusWeb Profile + JMS 等企业特性
tomee:10-jre17-plumeplus + EclipseLink 完整 JPA

镜像要点（实测自 docker image inspect）：默认工作目录 /usr/local/tomee，启动命令 catalina.sh run（前台运行），环境变量 TOMEE_VER=10.2.0、TOMEE_BUILD=webprofile、JAVA_HOME=/opt/java/openjdk。

三、前置条件

  1. 宿主机已安装 Docker 与 Compose 插件，验证方式：
docker info --format "{{.ServerVersion}}"

docker compose version
  1. 8080 端口未被占用。
  2. 准备部署目录：
mkdir -p /opt/tomee-compose/webapps /opt/tomee-compose/logs
  1. 拉取官方镜像（若内网无法直连 Docker Hub，请配置镜像加速或代理）：
docker pull tomee:10-jre17-webprofile

四、部署步骤

4.1 编写 docker-compose.yml

在 /opt/tomee-compose 目录创建 docker-compose.yml：

services:
  tomee:
    image: tomee:10-jre17-webprofile
    container_name: tomee-webprofile
    ports:
      - "8080:8080"
    environment:
      JAVA_OPTS: "-Xms256m -Xmx512m -Djava.awt.headless=true"
    volumes:
      - ./webapps:/usr/local/tomee/webapps
      - ./logs:/usr/local/tomee/logs
    restart: unless-stopped

参数说明：ports 将宿主机 8080 映射到容器内 TomEE 的 8080；environment 注入 JVM 堆参数；volumes 挂载应用目录与日志目录实现持久化。

4.2 预置默认应用目录（关键步骤）

官方镜像内置了 ROOT、docs、host-manager、manager 四个默认应用，位于镜像内 /usr/local/tomee/webapps。若按 4.1 直接挂载空目录，这些默认应用会被全部遮蔽，访问根路径返回 404。正确做法是先把镜像内的默认应用拷贝到宿主机挂载目录：

docker create --name tomee-tmp tomee:10-jre17-webprofile

docker cp tomee-tmp:/usr/local/tomee/webapps/. /opt/tomee-compose/webapps/

docker rm tomee-tmp

确认拷贝结果：

ls /opt/tomee-compose/webapps/

实测回显：

ROOT  docs  host-manager  manager

4.3 启动服务

cd /opt/tomee-compose

docker compose up -d

实测回显：

 Container tomee-webprofile Starting
 Container tomee-webprofile Started

4.4 验证部署

查看运行状态：

docker compose ps

实测回显：

NAME               STATUS          PORTS
tomee-webprofile   Up 10 seconds   0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp

验证页面（从宿主机或任意可访问主机执行）：

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

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

实测回显：

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

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

docker logs tomee-webprofile 2>&1 | grep "Server startup"

实测回显：

12-Oct-2026 05:39:26.447 INFO [main] jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke Server startup in [85] milliseconds

验证 JVM 堆参数已注入：

docker exec tomee-webprofile bash -c "cat /proc/1/cmdline | tr '\0' ' ' | grep -c Xms256m"

实测回显：

1

4.5 部署业务应用

将 war 包放入挂载目录 /opt/tomee-compose/webapps，容器内对应路径随即出现，TomEE 检测到新 war 包后自动解压部署（首次部署约需 30-60 秒扫描）：

cp /path/to/hello.war /opt/tomee-compose/webapps/

等待部署完成后验证：

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

实测回显：

200

也可以重启容器让部署在启动阶段完成：

docker compose restart

五、数据持久化说明

宿主机目录容器内路径内容
./webapps/usr/local/tomee/webapps部署的应用（war 包与解压目录）
./logs/usr/local/tomee/logscatalina.out 等日志文件
  1. webapps 目录持久化后，应用随宿主机目录保存，docker compose down 不会丢失应用；日志同理。
  2. 如需持久化配置，见第八节配置文件持久化。
  3. 容器自身存储仅承载 JDK 与 TomEE 程序本体，可随时销毁重建。

六、常用环境变量表

环境变量示例值说明
JAVA_OPTS-Xms256m -Xmx512m -Djava.awt.headless=trueJVM 参数，堆内存在此设置（实测注入 PID 1 进程）
CATALINA_OPTS-Dcom.example.prop=value仅传给 Catalina 的附加参数
JPDA_ADDRESS*:8000配合命令层启用远程调试时的监听地址

注意：官方镜像未提供服务器端口、管理账号等环境变量，这些需要通过配置文件挂载实现。

七、常用配置参数说明

  1. 端口映射：compose 中 ports: "8080:8080" 左侧为宿主机端口，可改为 "18080:8080" 等任意空闲端口。
  2. 堆内存：JAVA_OPTS 中 -Xms 初始堆、-Xmx 最大堆；修改后执行 docker compose up -d 重建容器生效。
  3. 重启策略：restart: unless-stopped 表示随 Docker 守护进程自动拉起，手工 stop 后不再自动启动。
  4. 默认应用处理：生产环境可删除 webapps 下的 docs、host-manager、manager 目录（仅保留 ROOT 与业务应用），减少暴露面。
  5. 时区：可在 environment 中追加 TZ: Asia/Shanghai，使日志时间戳与本时区一致。

八、配置文件持久化

将镜像内 /usr/local/tomee/conf 整体拷出后按需修改并挂载回容器：

docker create --name tomee-conf-tmp tomee:10-jre17-webprofile

docker cp tomee-conf-tmp:/usr/local/tomee/conf /opt/tomee-compose/conf

docker rm tomee-conf-tmp

修改 /opt/tomee-compose/conf 中的文件（例如在 tomcat-users.xml 中配置管理账号 admin，密码 q1w2e3r4，以及 manager-gui、manager-script、admin-gui 角色），然后在 compose 的 volumes 中追加：

    volumes:
      - ./webapps:/usr/local/tomee/webapps
      - ./logs:/usr/local/tomee/logs
      - ./conf:/usr/local/tomee/conf

执行 docker compose up -d 重建容器使配置生效。

九、等价 docker run 运行方式

不使用 Compose 时，以下单条命令与第四节配置等价：

docker run -d --name tomee-webprofile \
  -p 8080:8080 \
  -e JAVA_OPTS="-Xms256m -Xmx512m -Djava.awt.headless=true" \
  -v /opt/tomee-compose/webapps:/usr/local/tomee/webapps \
  -v /opt/tomee-compose/logs:/usr/local/tomee/logs \
  --restart unless-stopped \
  tomee:10-jre17-webprofile

挂载配置目录的等价写法追加：

docker run -d --name tomee-webprofile \
  -p 8080:8080 \
  -e JAVA_OPTS="-Xms256m -Xmx512m -Djava.awt.headless=true" \
  -v /opt/tomee-compose/webapps:/usr/local/tomee/webapps \
  -v /opt/tomee-compose/logs:/usr/local/tomee/logs \
  -v /opt/tomee-compose/conf:/usr/local/tomee/conf \
  --restart unless-stopped \
  tomee:10-jre17-webprofile

十、常用运维命令

docker compose ps

docker compose logs -f

docker compose restart

docker compose stop

docker compose start

docker compose down

docker compose up -d

实时查看容器内日志文件：

tail -f /opt/tomee-compose/logs/catalina.out

进入容器排查：

docker exec -it tomee-webprofile bash

重建容器（配置或镜像变更后）：

docker compose up -d --force-recreate

十一、常见问题

Q1：启动后访问 http://localhost:8080/ 返回 404？

原因是空的宿主机目录挂载到 /usr/local/tomee/webapps 后遮蔽了镜像内置的 ROOT 等默认应用。先按 4.2 节用 docker cp 将默认应用拷入挂载目录，再 docker compose up -d 重建容器。

Q2：war 包放入 webapps 后访问仍 404？

首次热部署需要 30-60 秒的扫描时间，可用 docker logs -f tomee-webprofile 观察，出现 Deployment of web application archive [/usr/local/tomee/webapps/hello.war] has finished in [142] ms 字样后再验证；也可直接 docker compose restart 在启动阶段完成部署。

Q3：JAVA_OPTS 内存参数没有生效？

确认写在 compose 的 environment 段，且执行了 docker compose up -d 重建（仅 restart 不刷新环境变量）。核验方式：

docker exec tomee-webprofile bash -c "cat /proc/1/cmdline | tr '\0' ' ' | grep -c Xms256m"

输出 1 表示参数已注入启动进程。

Q4：如何升级到新的 TomEE 小版本？

修改 compose 中 image 标签（如 tomee:10-jre17-webprofile 保持跟随官方更新，或固定到具体新版本标签），执行 docker compose up -d 重建容器；webapps 与 logs 已持久化，应用与日志不受影响。升级前建议备份挂载目录与自定义 conf。

十二、参考链接

  1. Docker Hub 官方 tomee 镜像页：https://hub.docker.com/_/tomee
  2. Apache TomEE 官网：https://tomee.apache.org/
  3. TomEE 10.2.0 下载目录：https://downloads.apache.org/tomee/tomee-10.2.0/
  4. Compose 文件参考：https://docs.docker.com/reference/compose-file/
  5. Tomcat 10.1 文档：https://tomcat.apache.org/tomcat-10.1-doc/