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