全栈攻城狮

Appearance

Tomcat server.xml 配置全面解析 ​

概述 ​

conf/server.xml 是 Tomcat 的总装配文件，描述了整棵组件树：监听哪些端口、每个端口用什么协议、请求如何路由到具体应用。读懂它，就能理解 Tomcat 的运行时形态；改对它，是部署与性能优化的第一步。

一、文件结构总览 ​

一个典型的 server.xml（Tomcat 10.1 默认）结构如下：

xml
<Server port="8005" shutdown="SHUTDOWN">
  <Listener className="org.apache.catalina.startup.VersionLoggerListener" />
  <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
  <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener" />
  <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />
  <Listener className="org.apache.catalina.core.ThreadLocalLeakPreventionListener" />

  <GlobalNamingResources>
    <Resource name="UserDatabase" auth="Container"
              type="org.apache.catalina.UserDatabase"
              description="User database that can be updated and saved"
              factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
              pathname="conf/tomcat-users.xml" />
  </GlobalNamingResources>

  <Service name="Catalina">
    <Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000" redirectPort="8443"
               maxParameterCount="10000" />

    <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

    <Engine name="Catalina" defaultHost="localhost">
      <Realm className="org.apache.catalina.realm.LockOutRealm">
        <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
               resourceName="UserDatabase" />
      </Realm>

      <Host name="localhost" appBase="webapps"
            unpackWARs="true" autoDeploy="true">
        <Valve className="org.apache.catalina.valves.AccessLogValve"
               directory="logs"
               prefix="localhost_access_log" suffix=".txt"
               pattern="%h %l %u %t &quot;%r&quot; %s %b" />
      </Host>
    </Engine>
  </Service>
</Server>

在 VitePress 渲染中，&quot; 是 " 的 XML 实体写法，用于在 XML 属性值中嵌入双引号。自定义配置时如需在 pattern 等属性里写双引号，同样要转义。

XML 元素之间的嵌套关系即容器层次：Server → Service → Connector / Engine → Host → Context。

二、Server：顶层实例 ​

属性默认值说明
port8005关闭端口，收到匹配的 shutdown 命令字符串即退出
shutdownSHUTDOWN关闭命令字符串
address127.0.0.1监听地址，默认仅本机
xml
<Server port="8005" shutdown="SHUTDOWN">

两个注意点：

  1. 关闭端口的风险：任何能访问该端口的人发送 SHUTDOWN 字符串即可停止 Tomcat。生产环境建议绑定 address="127.0.0.1" 并修改默认命令串，或用防火墙封锁。
  2. 不可启动多个 Server：同一 JVM 内每个端口只允许一个 Server。

三、Service：Connector 与 Engine 的绑定 ​

Service 把一组 Connector 与一个 Engine 绑定成可对外提供服务的单元。默认只有一个名为 Catalina 的 Service：

xml
<Service name="Catalina">

一个 Service 内的 Connector 共享同一个 Engine——请求无论从哪个端口进来，最终都进入同一个 Engine 做路由。多 Service 场景（如一个实例同时服务 HTTP 与 AJP 且逻辑隔离）不常见，一般保持默认即可。

四、Connector：端口与协议 ​

Connector 是 Coyote 的配置入口，控制监听端口、协议、线程模型、超时与 TLS。

4.1 核心属性 ​

属性默认值说明
port8080监听端口
protocolHTTP/1.1协议实现类或别名
connectionTimeout20000连接超时（毫秒）
redirectPort8443SSL 重定向端口
acceptCount100积压连接队列长度
maxThreads200工作线程池最大线程数
minSpareThreads10最小空闲线程数
maxConnections8192最大并发连接数（NIO 下为队列上限）
URIEncodingUTF-8URL 编码
maxParameterCount10000参数数量上限，防 DoS

典型 HTTP 连接器配置：

xml
<Connector port="8080" protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="8443"
           acceptCount="200"
           maxThreads="400"
           minSpareThreads="20"
           URIEncoding="UTF-8" />

4.2 protocol 属性取值 ​

取值解析结果
HTTP/1.1自动选择最优实现（默认 NIO）
org.apache.coyote.http11.Http11NioProtocol显式指定 NIO
org.apache.coyote.http11.Http11Nio2ProtocolNIO2
AJP/1.3AJP 协议，与 Apache/Nginx 对接

4.3 AJP 连接器 ​

xml
<Connector port="8009" protocol="AJP/1.3" redirectPort="8443"
           secretRequired="true" secret="your-secret" />

AJP 是二进制协议，用于 Apache httpd 与 Tomcat 之间通信。安全要点：Tomcat 9.0.31 后默认 secretRequired="true"，必须配置共享密钥，否则拒绝连接——这是针对 CVE-2020-1938（Ghostcat 文件包含漏洞）的修复。

五、Engine：顶层容器 ​

xml
<Engine name="Catalina" defaultHost="localhost">
属性说明
name引擎名称，与 Service 无强制关联
defaultHost默认虚拟主机：请求 Host 头未匹配任何 Host 时落入该 Host

Engine 是请求路由的入口：收到请求后，根据 HTTP Host 头选择对应的 Host 容器。defaultHost 必须指向下面已定义的某个 Host 名称。

六、Host：虚拟主机 ​

xml
<Host name="localhost" appBase="webapps"
      unpackWARs="true" autoDeploy="true">
属性默认值说明
name—虚拟主机名（域名），匹配请求的 Host 头
appBasewebapps应用部署基准目录
unpackWARstrueWAR 是否自动解压运行
autoDeploytrue是否自动部署新放入的应用
deployOnStartuptrue启动时是否部署 appBase 下的应用

一个 Engine 下可以有多个 Host，实现一台机器多域名：

xml
<Engine name="Catalina" defaultHost="localhost">
  <Host name="localhost" appBase="webapps" />
  <Host name="www.example.com" appBase="webapps2" />
</Engine>

请求 www.example.com:8080/ 会进入 webapps2 目录部署的应用。

七、Context：Web 应用 ​

Context 可以显式写在 server.xml 中，但更推荐放在 conf/Catalina/<host>/<app>.xml 或应用内 META-INF/context.xml——原因是 server.xml 的修改需要重启才生效，而 Context 文件支持热加载。

xml
<Context path="/myapp" docBase="/data/apps/myapp" reloadable="false" />
属性说明
pathURL 路径前缀，如 /myapp
docBase应用文件位置（目录或 WAR 路径）
reloadable是否监听 classes 变化自动重载（生产建议 false）
privileged是否使用容器级 Servlet
sessionCookiePath会话 Cookie 路径，多应用共用域名时需注意隔离

reloadable="true" 会在类文件变化时销毁并重建 Context，开发便利但生产有性能与内存泄漏风险（ThreadLocal、静态引用可能残留）。

八、Valve：容器级拦截器 ​

Valve 挂在容器（Host/Context）的 Pipeline 上，作用于该容器下的所有请求。默认配置中最常见的是访问日志阀：

xml
<Valve className="org.apache.catalina.valves.AccessLogValve"
       directory="logs"
       prefix="localhost_access_log" suffix=".txt"
       pattern="%h %l %u %t &quot;%r&quot; %s %b" />

常用内置 Valve：

Valve作用
AccessLogValve访问日志
RemoteAddrValve按客户端 IP 允许/拒绝
RemoteHostValve按主机名过滤
RewriteValve类似 Apache 的 URL 重写
ErrorReportValve错误页定制

九、Realm：认证与授权数据源 ​

Realm 定义了 Tomcat 容器级认证（BASIC/DIGEST/FORM）的用户数据来源：

xml
<Realm className="org.apache.catalina.realm.LockOutRealm">
  <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
         resourceName="UserDatabase" />
</Realm>
Realm 实现数据来源
UserDatabaseRealmtomcat-users.xml
MemoryRealm内存 XML 文件
JDBCRealm数据库表
DataSourceRealm通过 JNDI 数据源访问数据库
JAASRealmJAAS 认证框架

LockOutRealm 包在外层提供失败锁定，防止暴力破解。

十、配置排错：从 server.xml 定位问题 ​

症状可能原因检查点
端口冲突端口被占用netstat -ano | findstr 8080
Host 头不匹配 404defaultHost 未配置或应用未部署检查 Engine.defaultHost 与 Host.name
HTTPS 不生效redirectPort 配置错误检查 Connector.redirectPort 与 SSL 配置
请求参数超限 400maxParameterCount 过小调大 maxParameterCount
应用 403Context privileged/部署路径问题检查 Context 配置与目录权限

十一、修改 server.xml 的最佳实践 ​

  1. 改动前备份：cp server.xml server.xml.bak。
  2. 区分生效方式：Connector/Engine/Host 级修改需重启；Context 级修改尽量放外部文件支持热部署。
  3. 最小改动原则：默认配置经过官方调优，只改必要的属性。
  4. 端口规划表：多实例/多 Service 时提前规划端口，写入运维文档。
  5. 语法校验：改完后用 catalina.sh start 前台观察，XML 错误会立即打印在控制台并停止启动。

参考链接：