一、起源

1.1 两种使用形态

形态 做法 配置方式 特点
内嵌容器 容器作为依赖打进应用,随应用进程启动 应用配置文件与代码 打包一体、环境一致、无需运维容器本身
独立安装 容器单独安装,应用以 war 部署进去 容器配置文件与部署描述符 容器与应用的发布解耦,一个容器承载多个应用

内嵌形态下"容器的部署"这一命题基本消失:容器随应用走,参数由应用配置表达,日志与进程管理也由应用统一处理。

独立安装形态下,容器本身成为一个需要部署、配置、升级与加固的独立软件,工作内容与 nginx、MySQL 等中间件类似,只是它承载的是 Java 应用而非静态资源或数据。

1.2 仍需独立安装的四种场景

  • 一个容器需要同时部署多个应用,且这些应用需要共享容器级配置与连接池资源。
  • 组织已有既定的运维体系、监控项与发布流程围绕独立容器建立,改造为内嵌形态的成本高于收益。
  • 应用不是 Spring Boot 工程,或使用依赖容器提供的共享类库与容器级资源(如容器管理的数据源、领域模型)。
  • 需要容器级的热部署能力,在不重启容器的情况下更新单个应用(内嵌形态不提供该能力)。

1.3 取舍

选择 获得 付出
内嵌 部署简单、环境一致、容器与应用版本绑定 无法共享容器资源、无法热部署单个应用
独立安装 多应用共享、容器与应用解耦、可热部署 需要维护容器配置、类库放置与版本升级,类冲突风险更高

二、原理

2.1 目录结构与职责

目录 内容 需要关注的点
bin 启动与停止脚本、引导 jar 脚本本身不应修改,环境相关配置放 setenv.sh
conf 全部配置文件 升级时会被覆盖,自定义项需单独留存
lib 容器级公共类库 对所有应用可见,放置第三方依赖会引发类冲突
logs 全部日志文件 需要纳入日志轮转与容量治理
temp 运行时临时文件 需要可写且有足够空间
webapps 默认部署目录 自动部署的扫描目录
work 编译产物与运行时工作目录 JSP 编译结果与序列化数据存放于此,清理后可自动重建

conf 与 lib 是独立安装形态的核心:conf 决定容器行为,lib 决定所有应用可见的类范围。两者在容器升级时都需要重新核对,特别是 lib 下的第三方依赖,它们是类冲突的高发位置。

2.2 配置文件体系与作用域

文件 作用域 主要内容
catalina.properties 容器级系统属性 类加载器配置、jar 扫描过滤、包访问限制
server.xml 容器结构 监听端口、连接器、引擎、虚拟主机、应用上下文
context.xml Context 默认值(conf 下为全局,应用 META-INF 下为单应用) 会话管理器、Cookie 属性、资源定义、安全阀
web.xml 全局默认部署描述符(conf 下为全局,应用 WEB-INF 下为单应用) 默认 Servlet 与 Filter、欢迎页、会话超时、错误页、MIME 映射
tomcat-users.xml 管理入口身份 管理界面的用户与角色
logging.properties 容器日志 日志级别、处理器与输出文件

作用域规则是理解配置来源的关键:

  • conf 下的同名文件是"全局默认值",应用内的 WEB-INF/web.xml 与 META-INF/context.xml 是"应用级覆盖"。
  • 应用级配置只能收紧或覆盖部分行为,不能修改容器结构;容器结构只能在 server.xml 中调整。
  • 因此同一个参数在多处出现时,需要按"应用级优先于全局默认"的顺序确认最终生效值。

catalina.properties 中与部署关系最直接的是 jar 扫描过滤:容器启动时默认会扫描类路径中的 jar 以查找注解与描述符,依赖较多时这一过程会显著拖长启动时间,通过过滤配置可以跳过确定不需要扫描的 jar。

2.3 类加载层次与依赖放置

独立安装形态下存在四层类加载器:

Bootstrap(JVM 自身类库)
  └── System(应用类路径)
        └── Common($CATALINA_HOME/lib)
              ├── Server(容器自身使用,默认与 Common 相同)
              └── Shared(所有 Web 应用共享,默认与 Common 相同)
                    └── Webapp(单应用的 WEB-INF/classes 与 WEB-INF/lib)

两个关键性质:

  • Web 应用类加载器默认先在自身路径中查找,找不到才委派父加载器,即打破了双亲委派的"先父后子"顺序。这一设计保证容器自带的类库不会覆盖应用依赖的版本,使同一容器上的应用可以使用不同版本的同一类库。
  • delegate 属性可以改为先委派父加载器。开启后,容器 lib 下的类会优先于应用内的同名类,适用于需要强制统一某个类库版本的场景。

依赖放置的选择依据:

放置位置 可见范围 适用 风险
应用 WEB-INF/lib 仅该应用 绝大多数第三方依赖 依赖重复打包,但相互隔离
容器 lib 所有应用 容器扩展组件、数据库驱动等确实需要共享的类库 版本被固定,应用无法升级;容易与其他应用期望的版本冲突

实践结论:第三方业务依赖一律放在应用内,容器 lib 只放容器级扩展与确实需要全局共享的驱动;把业务依赖放到容器 lib 是升级困难与类冲突的主要来源。

2.4 部署方式与路径映射

方式 做法 访问路径 特点
war 复制部署 把 war 放入 webapps 由 war 文件名决定,根路径由 ROOT.war 决定 简单,适合自动化发布
解压目录部署 把解压后的目录放入 webapps 由目录名决定 可预解压,启动略快
外部 docBase 通过应用级 context.xml 或 server.xml 指定 docBase 与 path 由 path 决定 应用不放在 webapps 下,便于权限与磁盘分离
虚拟主机 在 Host 下配置多个 Context 由主机名加路径决定 一个容器承载多域名的多应用

需要控制三个开关:

  • autoDeploy:运行期扫描 webapps 与 xmlBase 目录,发现新增或更新时自动部署与重新加载。生产环境建议关闭,避免误放文件导致未评审的应用上线。
  • deployOnStartup:启动时部署已存在的应用,通常保持开启。
  • unpackWARs:是否解压 war。保持解压便于查看与调试,不解压则减少一次磁盘操作。
  • reloadable:检测类文件变化后重新加载应用。它通过后台线程持续扫描类文件实现,代价是额外 CPU 与内存,并且重新加载不彻底、容易残留类引用,生产环境应关闭。

2.5 连接器与 HTTPS

连接器声明监听端口与协议,与内嵌形态的参数一一对应,只是表达方式从应用配置变为 XML 属性:

属性 含义 与内嵌配置的对应
port 监听端口 server.port
protocol 协议实现(HTTP/1.1 的 NIO 实现) 由依赖决定
connectionTimeout 连接建立后等待请求的超时 server.tomcat.connection-timeout
maxThreads、minSpareThreads 请求线程池上下限 server.tomcat.threads.max 与 min-spare
maxConnections、acceptCount 已接受连接上限与内核队列长度 server.tomcat.max-connections 与 accept-count
URIEncoding URI 解码字符集 新版默认 UTF-8
maxPostSize、maxHttpHeaderSize 请求体与请求头大小上限 对应框架层同类限制
address 绑定地址 server.address
server Server 响应头内容 与隐藏版本相关

HTTPS 需要新增一个连接器并指定证书信息:可以指向密钥库,也可以直接指向证书与私钥文件。明文 HTTP 连接器需要配置 redirectPort 指向 HTTPS 端口,使需要安全通道的请求被重定向。

AJP 连接器用于与前置 Web 服务器通过二进制协议通信,在现代部署中已被反向代理的 HTTP 代理方式取代,且新版本容器中该连接器已被移除,新部署不应启用。

2.6 会话管理的两种实现

Context 下的会话管理器决定会话在内存与持久化介质之间的组织方式:

实现 行为 适用与代价
标准管理器 会话保存在内存,正常关闭时序列化到工作目录 默认实现;重启会丢失未过期会话的可靠性,且不适用于多节点
持久化管理器 会话写入外部存储(文件或数据库),并按策略换入换出内存 支持重启保留与会话数量控制;引入存储依赖与序列化开销

会话持久化只能解决"单节点重启不丢会话",不能解决多节点共享,多节点场景仍应使用外部集中存储。此外需要注意两点:存放在会话中的对象需要可序列化,否则持久化会失败;会话 Cookie 的安全属性(仅 HTTP、仅安全通道、路径与域)需要在 Context 中显式声明。

2.7 启动脚本与 JVM 参数

catalina.sh 是核心脚本,startup.sh 与 shutdown.sh 都是它的封装。脚本执行时会按顺序读取环境变量,其中:

变量 生效范围 放置内容
JAVA_OPTS 所有 Tomcat 命令,包括停止与版本查询 所有命令都需要的通用参数
CATALINA_OPTS 仅启动与运行命令 仅服务进程需要的内存量、GC、OOM 转储等参数

区分依据是:内存与 GC 参数只服务于运行进程,放在 CATALINA_OPTS 中,避免执行"停止"或"查询版本"这类命令时也按大堆参数启动 JVM。

环境相关配置应放在 bin/setenv.sh 中:该文件由 catalina.sh 自动引用,且不在容器的分发包内,容器升级时不会被覆盖,因此适合放置 JDK 路径、JVM 参数与凭据相关的环境变量。

2.8 服务化改造

以脚本方式启动的进程在会话结束时会被终止,且没有开机自启与统一的重启策略。改造为 systemd 服务需要处理三点:

  • 以前台方式运行(catalina.sh run),配合 Type=simple,使 systemd 能直接跟踪主进程,避免 forking 模式下进程跟踪失败。
  • 声明运行用户与工作目录,并设置 SuccessExitStatus 使停止时返回的退出码不被判定为异常。
  • 设置停机超时与重启策略,使异常退出能够自动拉起,同时避免无限重启。

三、实现

3.1 server.xml 关键片段

<?xml version="1.0" encoding="UTF-8"?>
<Server port="-1" shutdown="SHUTDOWN">
  <!-- port="-1" 关闭关闭指令端口,避免远程发送指令停止容器 -->

  <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
  <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener" />
  <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />

  <Service name="Catalina">
    <!-- 明文连接器:保留 80 用于重定向到 HTTPS -->
    <Connector port="8080" protocol="org.apache.coyote.http11.Http11NioProtocol"
               address="127.0.0.1"
               connectionTimeout="5000"
               maxThreads="200"
               minSpareThreads="20"
               maxConnections="8192"
               acceptCount="200"
               maxHttpHeaderSize="16384"
               maxPostSize="20971520"
               URIEncoding="UTF-8"
               enableLookups="false"
               server="web"
               redirectPort="8443" />

    <!-- HTTPS 连接器:使用 PEM 证书与私钥 -->
    <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
               address="127.0.0.1"
               maxThreads="200"
               SSLEnabled="true"
               scheme="https"
               secure="true"
               certificateFile="/etc/tomcat/ssl/fullchain.pem"
               certificateKeyFile="/etc/tomcat/ssl/privkey.pem"
               certificateChainFile="/etc/tomcat/ssl/chain.pem"
               sslProtocol="TLS"
               connectionTimeout="5000" />

    <Engine name="Catalina" defaultHost="localhost">
      <Host name="localhost" appBase="webapps"
            unpackWARs="true" autoDeploy="false" deployOnStartup="true">
        <!-- 显式声明应用位置,避免把应用放进 webapps 目录 -->
        <Context path="/app" docBase="/data/apps/app" reloadable="false">
          <CookieProcessor className="org.apache.tomcat.util.http.Rfc6265CookieProcessor" />
        </Context>
      </Host>
    </Engine>
  </Service>
</Server>

改造时需要注意三点:autoDeploy 关闭后新应用需重启容器才能部署;将应用放在容器外的 docBase 便于按应用分配磁盘与权限;address 绑定到本机回环,使外部流量必须经过反向代理。

3.2 应用级 context.xml

<?xml version="1.0" encoding="UTF-8"?>
<Context>
  <!-- 会话 Cookie 安全属性:仅 HTTP 访问、仅安全通道、限制路径 -->
  <CookieProcessor sameSiteCookies="lax" />

  <Valve className="org.apache.catalina.valves.RemoteIpValve"
         remoteIpHeader="X-Forwarded-For"
         protocolHeader="X-Forwarded-Proto"
         trustedProxies="10\.0\.0\.\d+" />

  <Manager className="org.apache.catalina.session.PersistentManager"
           maxIdleSwap="60"
           minIdleSwap="30">
    <Store className="org.apache.catalina.session.FileStore"
           directory="/data/tomcat/sessions" />
  </Manager>

  <Resources cachingAllowed="true" cacheMaxSize="102400" />
</Context>

要点:RemoteIpValve 的作用与反向代理层是一致的,即把真实客户端地址还原到请求对象中,使应用侧的限制与日志不再记录代理地址;但只有在请求必须经过可信代理时启用才安全,否则客户端可以伪造请求头。

3.3 setenv.sh 与 JVM 参数

# /opt/tomcat/bin/setenv.sh  由 catalina.sh 自动引用,容器升级不会被覆盖
export JAVA_HOME=/usr/lib/jvm/java-21
export CATALINA_HOME=/opt/tomcat
export CATALINA_BASE=/opt/tomcat

# 仅服务进程需要的参数:堆、元空间、GC、OOM 转储
export CATALINA_OPTS="$CATALINA_OPTS \
  -Xms2g -Xmx2g \
  -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=512m \
  -XX:+UseG1GC -XX:MaxGCPauseMillis=200 \
  -XX:+HeapDumpOnOutOfMemoryError \
  -XX:HeapDumpPath=/data/dumps \
  -Xlog:gc*:file=/data/logs/gc.log:time,uptime:filecount=10,filesize=50M \
  -Dfile.encoding=UTF-8 \
  -Duser.timezone=UTC"

# 所有命令都需要的参数放这里
export JAVA_OPTS="$JAVA_OPTS -Djava.security.egd=file:/dev/urandom"
# 使脚本可执行,并且不要提交含凭据的内容到版本库
chmod +x /opt/tomcat/bin/setenv.sh

3.4 systemd 单元

# /etc/systemd/system/tomcat.service
[Unit]
Description=Apache Tomcat
After=network.target

[Service]
Type=simple
User=tomcat
Group=tomcat
EnvironmentFile=-/etc/sysconfig/tomcat
ExecStart=/opt/tomcat/bin/catalina.sh run
ExecStop=/opt/tomcat/bin/catalina.sh stop 30 -force
SuccessExitStatus=143
TimeoutStopSec=60
Restart=on-failure
RestartSec=10
LimitNOFILE=65535
WorkingDirectory=/opt/tomcat

[Install]
WantedBy=multi-user.target
# 启用并启动
systemctl daemon-reload
systemctl enable --now tomcat
systemctl status tomcat

# 查看服务日志(catalina.out 中的标准输出)
journalctl -u tomcat -f

3.5 部署验证

# 配置语法检查(不启动容器)
/opt/tomcat/bin/catalina.sh configtest

# 查看容器版本与 JVM 信息
/opt/tomcat/bin/version.sh

# 确认端口监听与绑定地址
ss -tlnp | grep -E ':8080|:8443'

# 确认应用已部署且路径正确
curl -sI http://127.0.0.1:8080/app/ | head -3

# 确认会话 Cookie 的安全属性
curl -sI http://127.0.0.1:8080/app/login | grep -i 'set-cookie'

# 确认真实客户端地址已被还原(应用侧打印或查看访问日志)
curl -s -H 'X-Forwarded-For: 1.2.3.4' http://127.0.0.1:8080/app/whoami
grep '1.2.3.4' /opt/tomcat/logs/localhost_access_log.*.txt

# 确认类加载器层次与依赖来源
jcmd $(pgrep -f 'Bootstrap start') VM.classloader_stats | head -20

# 确认 jar 扫描过滤是否生效(观察启动日志中的扫描耗时)
grep -i 'scanning\|skipping' /opt/tomcat/logs/catalina.out | head

3.6 常见问题对照

现象 常见原因 处理方式
启动报端口占用 已有实例在运行或端口被其他进程占用 用 ss -tlnp 确认占用进程
启动报找不到 JAVA_HOME 环境变量未在服务上下文中设置 在 setenv.sh 或 systemd 的环境文件中声明
应用部署成功但访问 404 path 与请求路径不匹配,或应用名与 ROOT 冲突 核对 Context 的 path 与 war 文件名
两个应用同时报类找不到 依赖被放在容器 lib 且版本冲突 把业务依赖移回 WEB-INF/lib
应用内依赖版本未生效 容器 lib 中存在同名类,或 delegate 配置导致父加载器优先 清理容器 lib,核对 delegate
启动时间过长 jar 扫描量过大 在 catalina.properties 中配置扫描过滤
修改类文件后应用未生效 关闭了自动部署与 reloadable 重新部署应用或重启容器
HTTPS 握手失败 证书链不完整或私钥格式不匹配 核对证书文件与链文件的配置
应用侧记录到的是代理地址 未启用 RemoteIpValve 配置该阀并限制可信代理范围
会话在重启后丢失 使用标准管理器且未完成正常关闭 改用持久化管理器,或将会话放到外部存储
关闭容器时被判定为启动失败 systemd 未声明 SuccessExitStatus 补充退出码声明

四、总结

  1. Tomcat 有内嵌与独立安装两种形态,内嵌形态下容器随应用走,独立安装形态下容器本身成为需要部署与维护的软件。
  2. 独立安装的四个目录职责中,conf 决定容器行为,lib 决定所有应用可见的类范围,两者是配置与类冲突的主要来源。
  3. 四个 conf 下的配置文件是全局默认值,应用内的同名文件是应用级覆盖,参数最终值按应用级优先于全局的顺序确认。
  4. 类加载层次为 Common 与 Server 与 Shared 与 Webapp,Web 应用类加载器默认先查自身再委派父加载器,因此业务依赖应放在应用内,容器 lib 只放共享的容器级扩展。
  5. 部署路径由 war 文件名或 Context 的 path 决定,autoDeploy 与 reloadable 在生产环境应关闭,前者避免误放文件上线,后者避免扫描开销与类残留。
  6. 连接器属性与内嵌形态的应用配置一一对应,独立安装下 HTTPS 需要单独声明连接器与证书信息;AJP 已被反向代理的 HTTP 方式取代。
  7. 会话管理器的选择决定重启后会话是否保留,持久化只解决单节点问题,多节点仍应使用外部集中存储,且会话对象必须可序列化。
  8. JAVA_OPTS 对全部命令生效,CATALINA_OPTS 只对运行进程生效;内存与 GC 参数应放在后者,环境相关配置放在 setenv.sh 以避免升级被覆盖。
  9. 服务化改造的关键是以前台方式运行并声明退出码,使进程跟踪与停止判定都正确。
  10. 部署完成后需要核对端口绑定、应用路径、Cookie 安全属性、真实地址还原与类加载来源五项,它们是独立安装形态下最容易出错的环节。