尧图网站建设 
大多数人对 Tomcat 的认知停在两个动作上下载解压把 war 包丢进 webapps然后双击 startup。直到某天日志里刷出一屏 BindException或者页面上飘着一堆问号乱码才开始翻 server.xml 找配置。更尴尬的场面是面试或者做内部分享时被问一句一个请求进来Tomcat 内部到底做了什么脑子里只剩一个模糊的 Connector、Engine说不出细节。这篇内容就干两件事。一是把 Tomcat 常见报错按日志现象、根因、定位手段三个层次拆开给出能直接照着敲命令的排查路径二是从零手写一个 Mini Tomcat用几百行代码把 Socket 接入、HTTP 报文解析、Servlet 映射和生命周期串起来。手写过一遍之后再回头看那些报错你会发现它们指向的往往是同一个东西容器的真实状态和你以为的状态不一致。适合谁看写过 Java Web、平时用 Tomcat 部署项目但没深究过的同学以及想把这块内容讲明白的人。前提不高知道 Servlet 是什么、能写最基础的 Java 就行不需要提前读 Tomcat 源码。1. 报错排查的通用套路先分清是 JVM 层、容器层还是应用层Tomcat 的日志之所以让人头大是因为它把三个不同层次的错误混在同一个 catalina.out 里输出。JVM 层的错误JDK 版本不匹配、内存参数、字符集在 Tomcat 启动横幅出现之前就可能崩掉容器层的错误端口、Connector、部署目录通常发生在 Starting ProtocolHandler 前后应用层的错误数据源、Servlet 初始化、依赖冲突则出现在 Deployment of web application archive 之后。分清这三层的最大好处是排查顺序明确了。看到报错先问自己一句这个错误是 Tomcat 自己抛的还是我部署的应用抛的如果是 Tomcat 自己抛的改 server.xml 和启动脚本就够了如果是应用抛的改 server.xml 改到天亮也没用。1.1 三个层次的日志锚点下面这张表是我自己排查时最常用的对照先找到日志里那行关键锚点再去对应层次里找原因能省掉大量瞎翻的时间。层次日志锚点关键字典型错误优先检查项JVM 层无横幅输出 / Unrecognized VM optionUnsupportedClassVersionError、Could not reserve enough spaceJDK 版本、JAVA_HOME、-Xmx 参数容器层Starting ProtocolHandler / Server startupBindException、LifecycleException端口占用、server.xml 语法、部署目录权限应用层Deployment of web application / Context startupClassNotFoundException、SQLException、Error listenerStartWEB-INF/lib、数据源配置、web.xml 监听器有一个经验值得单独说第一次启动失败一定要看 catalina.out不要只看 localhost.2024-xx-xx.log。后者只记录应用层的请求和错误容器还没起来的时候它根本不会写内容。而 catalina.out 里混着 System.out 和 System.err虽然乱但信息最全。1.2 排查顺序反过来会浪费多少时间我见过太多人踩这个坑页面报 404第一反应是去改 server.xml 里的 Context 配置改完重启还是 404。其实真正的原因是 war 包解压失败Deployment of web application archive那一行日志里明确写着 deployment failed应用压根就没部署成功容器自然只能返回 404。正确的顺序是这样走的先用ps -ef | grep tomcat确认进程在不在在的话用netstat -ano | findstr 8080Linux 用lsof -i:8080或ss -lntp确认端口是不是这个进程占的然后到日志里搜Deployment看应用是否成功部署最后才去应用日志里找业务异常。这四步走完基本能定位到 90% 的问题。顺带提一句关停。Tomcat 的 shutdown.sh 是靠连接 8005 端口发送 SHUTDOWN 命令来触发的如果你在 server.xml 里把 8005 那行注释掉了shutdown.sh 就会静默失效只能kill。这时很多人直接kill -9进程是没了但如果应用里有非守护线程还在跑、或者正在写文件就很容易留下脏数据。我自己的习惯是kill普通信号等三秒实在不退再kill -9。2. 端口、乱码、元数据连接三类高频报错的逐层排查2.1 端口占用从 BindException 到 8005 关停端口启动日志里出现这句java.net.BindException: Address already in use: JVM_Bind意思非常直白某个端口已经被别的进程占了。Tomcat 默认会占用三个端口8080HTTP 连接器、8005关停端口、8009AJP 连接器。这三个里任意一个被占用都会导致启动失败而最容易被忽略的是 8005因为它不对外提供服务平时根本没人注意。定位命令按系统分# Linux lsof -i:8080 ss -lntp | grep 8080 ps -ef | grep tomcat # Windows netstat -ano | findstr :8080 tasklist | findstr 上一步拿到的 PID如果确认是残留的 Tomcat 进程kill pid走正常关停流程。如果确认是别的程序比如另一个 JDK 自带的 HTTP 服务、某些开发工具的内置服务那就改 Tomcat 端口。改的时候注意三处一起改别只改 8080Server port8005 shutdownSHUTDOWN Service nameCatalina Connector port8080 protocolHTTP/1.1 connectionTimeout20000 redirectPort8443 / Connector port8009 protocolAJP/1.3 redirectPort8443 / /Service /Server还有一个隐蔽场景从 IDE 里点启动、同时又从命令行启动了一份两份用的是同一个 CATALINA_BASE 或者同一个端口。这种情况进程列表里会有两个 java 进程日志里却只有一个在报错因为另一个可能已经绑成功了。排查的时候把ps -ef | grep tomcat的全量输出看完不要只看第一行。2.2 乱码的四个位置改动的地方完全不同乱码是提问频率最高的问题但没有一个统一的改这里就好的答案因为乱码可能出现在四个完全不同的位置每个位置的解法都不一样。先把位置分清再动手。位置现象根因处理方式控制台/日志启动日志里一片问号平台默认字符集与控制台代码页不一致启动参数加-Dfile.encodingUTF-8Windows 控制台chcp 65001URL 参数GET 请求中文参数变乱码Connector 的 URI 解码字符集不对Connector 上加URIEncodingUTF-8请求体POST 表单中文变乱码请求体解码字符集未指定request.setCharacterEncoding(UTF-8)或统一 Filter响应体页面中文显示为乱码响应头没带 charsetresponse.setContentType(text/html;charsetUTF-8)先说控制台乱码。这是启动阶段就能看到的日志文件里的中文变成???。原因是 JVM 默认字符集跟终端代码页对不上。最稳的做法是在启动参数里显式指定set JAVA_OPTS%JAVA_OPTS% -Dfile.encodingUTF-8或者在 logging.properties 里把控制台 handler 的编码固定下来java.util.logging.ConsoleHandler.encoding UTF-8再说请求体乱码。这里有个特别容易踩的坑request.setCharacterEncoding(UTF-8)必须在第一次调用 getParameter 之前执行因为一旦参数被解析过后续再设编码就无效了。实际项目里的做法是写一个 Filter放在过滤器链最前面public class EncodingFilter implements Filter { Override public void doFilter(ServletRequest req, ServletResponse resp, FilterChain chain) throws IOException, ServletException { req.setCharacterEncoding(UTF-8); resp.setCharacterEncoding(UTF-8); chain.doFilter(req, resp); } }最后是响应体。response.setCharacterEncoding和setContentType只设一个是不够的浏览器判断编码主要看响应头的 Content-Type。直接写response.setContentType(text/html;charsetUTF-8)最省事。2.3 Could not obtain connection to query metadata 到底在报什么这个报错完整版本大概长这样Could not obtain connection to query metadata : Cannot create PoolableConnectionFactory它出现在应用启动阶段是连接池在初始化时尝试从数据库拿一条连接来做元数据探测结果失败了。注意这个报错跟 Tomcat 本身没关系是数据源配置或者网络的问题。但因为它出现在 Tomcat 的启动日志里很多人第一反应是去改 server.xml方向一开始就错了。我整理过一份排查清单按命中率从高到低排JDBC URL 本身就写错了。库名拼错、端口写错、高版本驱动没带时区参数导致连接被拒都会走到这一步。驱动 jar 没放进WEB-INF/lib或者版本跟 JDK 不匹配。经典表现是ClassNotFoundException: com.mysql.cj.jdbc.Driver现在驱动类名多了cj这一段老配置里写的是com.mysql.jdbc.Driver。数据库服务没起来或者容器所在机器到数据库的网络不通。用telnet host port或者nc -vz host port先测一下最直接。账号密码错、账号没有目标库的权限或者连接数已经打满。连接池的初始连接数、最大连接数配得比数据库允许的上限还大。最快的验证方式是把容器这个变量剥离掉写一个带 main 方法的类用完全相同的 URL、账号、密码、驱动去连一次数据库。能连上问题就在容器的配置加载或者 jar 打包上连不上问题就在数据库或网络跟 Tomcat 无关。这一招我在排查线上问题时用过很多次比反复重启容器快得多。3. 动手之前先搞清楚一个 HTTP 请求在字节层面长什么样要手写 Tomcat第一步不是写代码而是把浏览器发过来的到底是一串什么东西看明白。Tomcat 做的事情本质上就是从 Socket 里读字节按 HTTP 协议解析成结构化对象交给业务代码处理再把结果拼成字节写回去。协议这一层理解透了代码只是翻译。3.1 请求行、请求头、请求体的边界在哪一个典型的 POST 请求在 Socket 里读出来是这样POST /user/login HTTP/1.1 Host: localhost:8080 Content-Type: application/x-www-form-urlencoded Content-Length: 27 User-Agent: curl/8.0 usernamerootpassword123结构非常规整第一行是请求行包含方法、URI、协议版本三段用空格分开接下来若干行是请求头每行key: value的形式以冒号分隔然后是一个空行标志着头结束空行之后是请求体长度由 Content-Length 决定。响应也是同样的结构HTTP/1.1 200 OK Content-Type: text/html;charsetUTF-8 Content-Length: 12 Hello World!关键点在于每一行结尾都是\r\n头和体之间用一个单独的空行分隔。手写解析器的时候这个\r\n处理不好就会出现各种诡异问题。还有两个规范细节值得记一下。请求头和响应头里的字节默认按 ISO-8859-1 解码这是 HTTP 规范历史遗留的结果中文出现在头里很少见但确实存在。请求体的编码则由 Content-Type 里的 charset 决定没写的话就靠应用自己指定了——这也是上一节 POST 乱码的根源。3.2 用 ServerSocket 直接 readLine 会踩的两个坑我第一版实现是这么写的包一层BufferedReader然后循环readLine()读请求行和请求头。看起来没问题跑起来单测也全过但接上带请求体的 POST 就出问题了——请求体读不到或者只读到一半。原因在于 BufferedReader 内部有自己的字符缓冲区。它在调用 readLine 读请求头的时候会一次性从底层 InputStream 预读一大块数据默认 8192 字符这里面很可能已经把请求体的内容也读进来了。等你再用原始的 InputStream 去读 body数据早就被 BufferedReader 吞掉放进自己的缓冲区了读出来自然是空。第二个坑是readLine()按\r、\n、\r\n任意一种换行符切分而 HTTP 规范里头部行分隔符要求是 CRLF。对于头部解析来说这个差异通常无害但如果请求头里出现了裸露的\r或者某些老客户端用了单独的\n解析结果就会飘。解决办法是自己写一个按字节读行的工具方法不预读、不缓冲边界完全可控private static String readLine(InputStream in) throws IOException { ByteArrayOutputStream buf new ByteArrayOutputStream(128); int b; while ((b in.read()) ! -1) { if (b \n) { break; } if (b \r) { continue; } buf.write(b); if (buf.size() 8192) { throw new IOException(header line too long); } } if (b -1 buf.size() 0) { return null; } return buf.toString(ISO-8859-1); }注意这个方法读满一行就停绝不预读后面的字节所以请求体一定还在流里等着。用 ISO-8859-1 拼接是 HTTP 头的标准做法它能把任意字节无损地映射成字符后面要做 URL 解码也不会丢信息。4. 接入层落地从 ServerSocket 到可用的 HTTP 响应4.1 线程模型为什么不能一连接一线程最朴素的写法是 accept 到一个连接就new Thread(() - handle(socket)).start()。这在本地测试没问题但放到稍微有点并发的场景就不行了线程的创建和销毁有实打实的开销而且没有任何上限几百个并发请求就能把线程数拉到几千栈内存直接吃满最后 OutOfMemoryError。Tomcat 的做法是用线程池对应两个关键参数maxThreads 控制最大工作线程数acceptCount 控制等待队列长度。手写版本我用 ThreadPoolExecutor 把这两个语义都还原出来this.workers new ThreadPoolExecutor( 20, 20, 60L, TimeUnit.SECONDS, new ArrayBlockingQueue(100), new NamedThreadFactory(mini-worker), new ThreadPoolExecutor.AbortPolicy());这里 20 大致对应 maxThreads队列容量 100 大致对应 acceptCount。拒绝策略用 AbortPolicy 是有意的——当队列也满了说明系统已经过载这时候直接把连接关掉比无限堆积、最后把内存吃干净要安全。另外 socket 一定要设超时socket.setSoTimeout(5000)。不设的话一个只建立连接却不发数据的客户端就能把一个工作线程永久占住攒够 20 个这样的连接整个服务就假死了。这个坑在真实环境里被扫描器触发过很隐蔽。4.2 请求解析的完整实现解析的目标是把一串字节变成好用的对象。我的做法是先做最小可用的 HttpRequest只保留方法、URI、头、参数、请求体五样东西。public class HttpRequest { private String method; private String uri; private String path; private String queryString; private final MapString, String headers new LinkedHashMap(); private final MapString, String parameters new HashMap(); private byte[] body new byte[0]; public void setUri(String uri) { this.uri uri; int q uri.indexOf(?); if (q 0) { this.path uri.substring(0, q); this.queryString uri.substring(q 1); parseQuery(this.queryString); } else { this.path uri; } } private void parseQuery(String query) { for (String pair : query.split()) { if (pair.isEmpty()) { continue; } int eq pair.indexOf(); String k eq 0 ? pair.substring(0, eq) : pair; String v eq 0 ? pair.substring(eq 1) : ; try { parameters.put(URLDecoder.decode(k, UTF-8), URLDecoder.decode(v, UTF-8)); } catch (UnsupportedEncodingException ignored) { } } } public int getContentLength() { String v headers.get(content-length); return v null ? -1 : Integer.parseInt(v.trim()); } }有几个细节是踩过坑才加上的。头名字统一转小写存因为 HTTP 头名不区分大小写客户端可能发Content-Length也可能发content-length不统一的话取值时就要写一堆兼容逻辑。参数值一定要 URL 解码中文和特殊字符都是百分号编码过的不解码拿到手就是%E4%B8%AD这种字符串。请求体的读取必须严格按 Content-Length 来不能读到流结束为止因为 HTTP 长连接下流是不会结束的int contentLength request.getContentLength(); if (contentLength 0) { byte[] body new byte[contentLength]; int read 0; while (read contentLength) { int n in.read(body, read, contentLength - read); if (n -1) { break; } read n; } request.setBody(body); }4.3 响应写出与 Content-Length 的坑响应这边最容易错的就是 Content-Length。它是字节数不是字符数。写Hello的时候字符串长度和字节长度一样看不出问题一旦响应里有中文你好两个字符是 6 个字节按字符串长度写 2浏览器就会只显示前两个字节也就是一个乱码字符。我的做法是内部统一持有 byte[]写成字节之后长度自然就是对的public void flush() throws IOException { StringBuilder head new StringBuilder(); head.append(HTTP/1.1 ).append(status).append( ) .append(reason(status)).append(\r\n); headers.put(Content-Length, String.valueOf(body.length)); for (Map.EntryString, String e : headers.entrySet()) { head.append(e.getKey()).append(: ).append(e.getValue()).append(\r\n); } head.append(\r\n); out.write(head.toString().getBytes(StandardCharsets.ISO_8859_1)); out.write(body); out.flush(); }还有两点必须记住头部结束的空行不能省少了它浏览器会一直等直到超时写完一定要 flushOutputStream 有没有缓冲取决于具体实现不 flush 的话小响应可能一直卡在缓冲区里。至于长连接只有在 Content-Length 或者 Transfer-Encoding 明确给出边界的情况下才能保持两个都没有就只能写完就关这也是 HTTP/1.0 时代必须带 Content-Length 的原因。5. 把 Servlet 塞进去映射、装载与生命周期到这里 Mini Tomcat 还只能返回写死的字符串要让它认识 Servlet得补上三件事接口定义、路由映射、生命周期管理。5.1 注解扫描与 URL 到实例的映射先定义一个极简的 Servlet 接口把 init、service、destroy 三个方法留住因为这三个方法正是 Servlet 规范的核心约定public interface MiniServlet { void init(); void service(HttpRequest req, HttpResponse resp) throws IOException; void destroy(); }再定义一个注解用来标注 URLRetention(RetentionPolicy.RUNTIME) Target(ElementType.TYPE) public interface WebServlet { String value(); }扫描的逻辑就是遍历包下面的 class 文件反射加载看到带注解的就实例化注册进 Map。这里我特意用了clazz.getDeclaredConstructor().newInstance()而不是已经废弃的newInstance()后者会把构造器抛出的受检异常包装成InstantiationException排查起来特别费劲拿不到真实的异常栈。public void scan(String packageName) throws Exception { String path packageName.replace(., /); URL url Thread.currentThread().getContextClassLoader().getResource(path); if (url null) { return; } File dir new File(url.toURI()); for (File file : dir.listFiles()) { if (file.isDirectory()) { scan(packageName . file.getName()); } else if (file.getName().endsWith(.class)) { String className packageName . file.getName() .replace(.class, ); Class? clazz Class.forName(className); WebServlet ann clazz.getAnnotation(WebServlet.class); if (ann ! null MiniServlet.class.isAssignableFrom(clazz)) { register(ann.value(), (MiniServlet) clazz.getDeclaredConstructor().newInstance()); } } } }提示这段扫描只适用于 IDE 里跑、class 文件散落在目录中的情况。打成 jar 之后getResource返回的不是 file 协议new File(url.toURI())会直接抛异常。真实容器要处理 file 和 jar 两种协议这也是很多人自己写扫描时最容易翻车的地方。5.2 静态资源处理与 404 兜底路由的匹配顺序很关键先查 Servlet 映射没命中再当作静态资源找都找不到才返回 404。顺序反过来的话静态资源目录下如果恰好有个跟 Servlet 路径同名的目录就会互相干扰。public void service(HttpRequest req, HttpResponse resp) throws IOException { MiniServlet servlet servletMap.get(req.getPath()); if (servlet ! null) { servlet.service(req, resp); return; } StaticResourceHandler.handle(webRoot, req, resp); }静态资源处理里有个必须做的安全校验——路径穿越防护。请求/../../etc/passwd这种路径如果直接拼到 webRoot 后面就能读到服务器上的任意文件。用getCanonicalPath()规范化之后判断是否还在 webRoot 之内是最简单可靠的做法File file new File(webRoot, path); if (!file.getCanonicalPath().startsWith(new File(webRoot).getCanonicalPath())) { resp.setStatus(403); resp.write(h1403 Forbidden/h1, UTF-8); return; }MIME 类型也要给对不然 css 和 js 会被浏览器拒绝执行。用一张小的映射表就够覆盖日常开发扩展名Content-Typehtmltext/html;charsetUTF-8csstext/css;charsetUTF-8jsapplication/javascript;charsetUTF-8jsonapplication/json;charsetUTF-8png / jpgimage/png / image/jpeg5.3 init/service/destroy 的调用时机Servlet 的生命周期这三个方法是容器调用的不是我们自己调的。init 在注册时调用一次service 每次请求调用destroy 在容器关闭时调用一次。这个一次和每次的差别是很多 bug 的来源把有状态的变量写在 Servlet 实例字段上在并发请求下就会出现数据串台因为容器默认只创建一个 Servlet 实例多个线程共享它。destroy 的触发在 Mini Tomcat 里靠 JVM 的关停钩子Runtime.getRuntime().addShutdownHook(new Thread(() - { container.destroyAll(); workers.shutdown(); }));顺带说一个之前很困惑我、后来才想明白的点Tomcat 里load-on-startup配置为负数或者不配的时候Servlet 是第一次被访问时才 init而不是启动时就初始化。所以启动日志里看不到某个 Servlet 的初始化信息不代表它有问题可能只是还没被访问过。要让它随容器启动就把 load-on-startup 设成 0 或者正整数数字越小越先加载。6. 手写完之后再看 Tomcat几个设计选择的答案代码写完跑通之后回头再看 Tomcat 的架构图那些原本抽象的概念会突然变得具体。6.1 Connector 与 Container 拆开的意义我一开始是把手写版本的收字节和跑 Servlet放在一个类里的后来发现换协议的时候要改的地方太多才理解 Tomcat 为什么要把 Connector 和 Container 彻底拆开。Connector 只负责一件事把网络字节流翻译成标准的 Request/Response 对象再把 Response 写回字节流。它不关心 Servlet 是什么、URL 怎么映射。ContainerEngine、Host、Context、Wrapper 层层嵌套只负责 Servlet 语义路由、生命周期、会话、安全约束它不关心字节是从 HTTP 还是别的协议来的。这样拆开之后换一个协议只需要换 Connector容器部分一行不动。协议版本演进和容器逻辑解耦这是这个设计的核心收益。6.2 类加载器隔离解决的真实问题每个 web 应用都会被分配一个独立的 WebappClassLoader这个设计解决的是依赖冲突A 应用用某个库的 1.0 版本B 应用用 2.0 版本如果共用一个类加载器同名的类只能加载一次必然有一方拿到错误版本。每个应用一个加载器同名类就被隔离开互不影响。另一个作用是热部署。重新部署应用时容器把旧的 ClassLoader 整个丢掉新建一个重新加载类就被卸载了。但这也是为什么反复热部署容易出现 Metaspace 溢出——只要有任何一个地方还持有旧 ClassLoader 的强引用比如一个没关掉的线程、一个静态注册的回调整个加载器就回收不掉它加载的所有类元数据都留在 Metaspace 里。生产环境我一般会在启动参数里显式加上-XX:MaxMetaspaceSize让它早点报错而不是慢慢把机器拖死。6.3 BIO 到 NIO 的线程模型演进我手写的那版是典型的 BIO一个线程处理一个连接线程读不到数据就一直阻塞。并发上来之后线程数直接爆炸。Tomcat 早期也是这个模型后来换成了 NIO。NIO 的核心改动在于把等待这件事从线程身上拿走了。少量 Acceptor 线程负责接收连接Poller 线程用多路复用监听大量连接上的可读可写事件真正的读写和业务处理才交给 Worker 线程池。带来的直接效果是几万个空闲连接可能只占用几十个线程而这些线程大部分时间在做实际工作而不是傻等。需要提醒的是NIO 只解决连接空闲时不占线程的问题。如果业务代码本身很慢比如一个查询要几百毫秒Worker 线程还是会被占满此时瓶颈在业务处理而不是 IO 模型。所以调优的时候先分清是连接数问题还是处理速度问题再决定是调线程池参数还是优化业务代码方向搞反了怎么调都没用。7. 部署与配置里那些容易忽略的细节7.1 context path 与 docBase 的对应关系访问路径和文件目录的对应关系本质上是 Context 的 path 属性和 docBase 属性决定的。把 war 包丢进 webappsTomcat 会自动解压并注册一个路径等于 war 文件名的 Context比如app.war对应访问路径/app。如果你想让它变成根路径就把 war 重命名为ROOT.war。有个点现在很多人不知道直接在 server.xml 里写Context标签Tomcat 官方已经不推荐了因为改这个文件不会触发热部署而且每次改都容易把整个文件写坏。推荐做法是在conf/Catalina/localhost/下建一个以路径命名的 xml 文件比如app.xmlContext docBase/data/apps/myapp reloadablefalse /这样配置的 Context 独立成文件改完自动生效出问题也只影响这一个应用。7.2 指定主页welcome-file-list 的查找顺序访问一个目录路径时返回哪个文件由 welcome-file-list 决定welcome-file-list welcome-fileindex.html/welcome-file welcome-fileindex.htm/welcome-file welcome-fileindex.jsp/welcome-file /welcome-file-list这里的匹配顺序是按列表逐个去目标目录下找文件第一个存在的就返回。所以如果你同时放了 index.html 和 index.jsp而想优先走 jsp就必须把 jsp 往前排。一个小细节是如果这个列表里所有文件都不存在容器返回的是 404 而不是目录列表——目录列表默认是关闭的这本身也是个安全上的好处。7.3 SSL 双向认证的配置要点普通 HTTPS 只验证服务端双向认证mutual TLS要求客户端也出示证书。配置全在 Connector 上Connector port8443 protocolHTTP/1.1 SSLEnabledtrue schemehttps securetrue clientAuthtrue keystoreFile/data/certs/server.keystore keystorePasschangeit truststoreFile/data/certs/trust.keystore truststorePasschangeit sslProtocolTLS /几个容易配错的地方keystore 放服务端自己的私钥和证书truststore 放用来验证对方的 CA 证书两者职责不能混clientAuth有三个取值false 表示不要求want 表示请求客户端证书但拿不到也放行true 表示必须且校验失败就断开生产上双向认证要用 true证书用 keytool 生成时注意有效期内部系统里见过太多过期证书导致的握手失败日志只会写一句 handshake failed不主动去看证书有效期很容易绕远路。排查握手问题时浏览器只给一句模糊的提示这时候用命令行工具带详细输出去测会清楚很多curl -v --cert client.crt --key client.key --cacert ca.crt https://localhost:8443/输出里会明确指出是证书链不完整、还是客户端证书没被信任、还是协议版本不匹配比在浏览器里猜快得多。从把这些东西一件件踩过去到现在能对着报错大致判断是哪一层的问题中间最大的转变其实不是记住了多少配置项而是养成了一个习惯遇到报错先问这是哪个层次的问题然后按顺序把 JVM、容器、应用三层逐个排除。手写一遍 Mini Tomcat 的价值也在这里它让你知道那些看起来神秘的机制——连接接入、报文解析、路由匹配、生命周期回调——拆开之后都只是些普通的代码逻辑出错的地方也就那么几个。真要动手的话建议别一上来就追求功能完整先把一个 GET 请求跑通、能正确返回中文再往上叠 Servlet 和静态资源这样每一步出问题都容易定位。 Tomcat报错排查与手写Mini Tomcat：从HTTP到Servlet
大多数人对 Tomcat 的认知停在两个动作上下载解压把 war 包丢进 webapps然后双击 startup。直到某天日志里刷出一屏 BindException或者页面上飘着一堆问号乱码才开始翻 server.xml 找配置。更尴尬的场面是面试或者做内部分享时被问一句一个请求进来Tomcat 内部到底做了什么脑子里只剩一个模糊的 Connector、Engine说不出细节。这篇内容就干两件事。一是把 Tomcat 常见报错按日志现象、根因、定位手段三个层次拆开给出能直接照着敲命令的排查路径二是从零手写一个 Mini Tomcat用几百行代码把 Socket 接入、HTTP 报文解析、Servlet 映射和生命周期串起来。手写过一遍之后再回头看那些报错你会发现它们指向的往往是同一个东西容器的真实状态和你以为的状态不一致。适合谁看写过 Java Web、平时用 Tomcat 部署项目但没深究过的同学以及想把这块内容讲明白的人。前提不高知道 Servlet 是什么、能写最基础的 Java 就行不需要提前读 Tomcat 源码。1. 报错排查的通用套路先分清是 JVM 层、容器层还是应用层Tomcat 的日志之所以让人头大是因为它把三个不同层次的错误混在同一个 catalina.out 里输出。JVM 层的错误JDK 版本不匹配、内存参数、字符集在 Tomcat 启动横幅出现之前就可能崩掉容器层的错误端口、Connector、部署目录通常发生在 Starting ProtocolHandler 前后应用层的错误数据源、Servlet 初始化、依赖冲突则出现在 Deployment of web application archive 之后。分清这三层的最大好处是排查顺序明确了。看到报错先问自己一句这个错误是 Tomcat 自己抛的还是我部署的应用抛的如果是 Tomcat 自己抛的改 server.xml 和启动脚本就够了如果是应用抛的改 server.xml 改到天亮也没用。1.1 三个层次的日志锚点下面这张表是我自己排查时最常用的对照先找到日志里那行关键锚点再去对应层次里找原因能省掉大量瞎翻的时间。层次日志锚点关键字典型错误优先检查项JVM 层无横幅输出 / Unrecognized VM optionUnsupportedClassVersionError、Could not reserve enough spaceJDK 版本、JAVA_HOME、-Xmx 参数容器层Starting ProtocolHandler / Server startupBindException、LifecycleException端口占用、server.xml 语法、部署目录权限应用层Deployment of web application / Context startupClassNotFoundException、SQLException、Error listenerStartWEB-INF/lib、数据源配置、web.xml 监听器有一个经验值得单独说第一次启动失败一定要看 catalina.out不要只看 localhost.2024-xx-xx.log。后者只记录应用层的请求和错误容器还没起来的时候它根本不会写内容。而 catalina.out 里混着 System.out 和 System.err虽然乱但信息最全。1.2 排查顺序反过来会浪费多少时间我见过太多人踩这个坑页面报 404第一反应是去改 server.xml 里的 Context 配置改完重启还是 404。其实真正的原因是 war 包解压失败Deployment of web application archive那一行日志里明确写着 deployment failed应用压根就没部署成功容器自然只能返回 404。正确的顺序是这样走的先用ps -ef | grep tomcat确认进程在不在在的话用netstat -ano | findstr 8080Linux 用lsof -i:8080或ss -lntp确认端口是不是这个进程占的然后到日志里搜Deployment看应用是否成功部署最后才去应用日志里找业务异常。这四步走完基本能定位到 90% 的问题。顺带提一句关停。Tomcat 的 shutdown.sh 是靠连接 8005 端口发送 SHUTDOWN 命令来触发的如果你在 server.xml 里把 8005 那行注释掉了shutdown.sh 就会静默失效只能kill。这时很多人直接kill -9进程是没了但如果应用里有非守护线程还在跑、或者正在写文件就很容易留下脏数据。我自己的习惯是kill普通信号等三秒实在不退再kill -9。2. 端口、乱码、元数据连接三类高频报错的逐层排查2.1 端口占用从 BindException 到 8005 关停端口启动日志里出现这句java.net.BindException: Address already in use: JVM_Bind意思非常直白某个端口已经被别的进程占了。Tomcat 默认会占用三个端口8080HTTP 连接器、8005关停端口、8009AJP 连接器。这三个里任意一个被占用都会导致启动失败而最容易被忽略的是 8005因为它不对外提供服务平时根本没人注意。定位命令按系统分# Linux lsof -i:8080 ss -lntp | grep 8080 ps -ef | grep tomcat # Windows netstat -ano | findstr :8080 tasklist | findstr 上一步拿到的 PID如果确认是残留的 Tomcat 进程kill pid走正常关停流程。如果确认是别的程序比如另一个 JDK 自带的 HTTP 服务、某些开发工具的内置服务那就改 Tomcat 端口。改的时候注意三处一起改别只改 8080Server port8005 shutdownSHUTDOWN Service nameCatalina Connector port8080 protocolHTTP/1.1 connectionTimeout20000 redirectPort8443 / Connector port8009 protocolAJP/1.3 redirectPort8443 / /Service /Server还有一个隐蔽场景从 IDE 里点启动、同时又从命令行启动了一份两份用的是同一个 CATALINA_BASE 或者同一个端口。这种情况进程列表里会有两个 java 进程日志里却只有一个在报错因为另一个可能已经绑成功了。排查的时候把ps -ef | grep tomcat的全量输出看完不要只看第一行。2.2 乱码的四个位置改动的地方完全不同乱码是提问频率最高的问题但没有一个统一的改这里就好的答案因为乱码可能出现在四个完全不同的位置每个位置的解法都不一样。先把位置分清再动手。位置现象根因处理方式控制台/日志启动日志里一片问号平台默认字符集与控制台代码页不一致启动参数加-Dfile.encodingUTF-8Windows 控制台chcp 65001URL 参数GET 请求中文参数变乱码Connector 的 URI 解码字符集不对Connector 上加URIEncodingUTF-8请求体POST 表单中文变乱码请求体解码字符集未指定request.setCharacterEncoding(UTF-8)或统一 Filter响应体页面中文显示为乱码响应头没带 charsetresponse.setContentType(text/html;charsetUTF-8)先说控制台乱码。这是启动阶段就能看到的日志文件里的中文变成???。原因是 JVM 默认字符集跟终端代码页对不上。最稳的做法是在启动参数里显式指定set JAVA_OPTS%JAVA_OPTS% -Dfile.encodingUTF-8或者在 logging.properties 里把控制台 handler 的编码固定下来java.util.logging.ConsoleHandler.encoding UTF-8再说请求体乱码。这里有个特别容易踩的坑request.setCharacterEncoding(UTF-8)必须在第一次调用 getParameter 之前执行因为一旦参数被解析过后续再设编码就无效了。实际项目里的做法是写一个 Filter放在过滤器链最前面public class EncodingFilter implements Filter { Override public void doFilter(ServletRequest req, ServletResponse resp, FilterChain chain) throws IOException, ServletException { req.setCharacterEncoding(UTF-8); resp.setCharacterEncoding(UTF-8); chain.doFilter(req, resp); } }最后是响应体。response.setCharacterEncoding和setContentType只设一个是不够的浏览器判断编码主要看响应头的 Content-Type。直接写response.setContentType(text/html;charsetUTF-8)最省事。2.3 Could not obtain connection to query metadata 到底在报什么这个报错完整版本大概长这样Could not obtain connection to query metadata : Cannot create PoolableConnectionFactory它出现在应用启动阶段是连接池在初始化时尝试从数据库拿一条连接来做元数据探测结果失败了。注意这个报错跟 Tomcat 本身没关系是数据源配置或者网络的问题。但因为它出现在 Tomcat 的启动日志里很多人第一反应是去改 server.xml方向一开始就错了。我整理过一份排查清单按命中率从高到低排JDBC URL 本身就写错了。库名拼错、端口写错、高版本驱动没带时区参数导致连接被拒都会走到这一步。驱动 jar 没放进WEB-INF/lib或者版本跟 JDK 不匹配。经典表现是ClassNotFoundException: com.mysql.cj.jdbc.Driver现在驱动类名多了cj这一段老配置里写的是com.mysql.jdbc.Driver。数据库服务没起来或者容器所在机器到数据库的网络不通。用telnet host port或者nc -vz host port先测一下最直接。账号密码错、账号没有目标库的权限或者连接数已经打满。连接池的初始连接数、最大连接数配得比数据库允许的上限还大。最快的验证方式是把容器这个变量剥离掉写一个带 main 方法的类用完全相同的 URL、账号、密码、驱动去连一次数据库。能连上问题就在容器的配置加载或者 jar 打包上连不上问题就在数据库或网络跟 Tomcat 无关。这一招我在排查线上问题时用过很多次比反复重启容器快得多。3. 动手之前先搞清楚一个 HTTP 请求在字节层面长什么样要手写 Tomcat第一步不是写代码而是把浏览器发过来的到底是一串什么东西看明白。Tomcat 做的事情本质上就是从 Socket 里读字节按 HTTP 协议解析成结构化对象交给业务代码处理再把结果拼成字节写回去。协议这一层理解透了代码只是翻译。3.1 请求行、请求头、请求体的边界在哪一个典型的 POST 请求在 Socket 里读出来是这样POST /user/login HTTP/1.1 Host: localhost:8080 Content-Type: application/x-www-form-urlencoded Content-Length: 27 User-Agent: curl/8.0 usernamerootpassword123结构非常规整第一行是请求行包含方法、URI、协议版本三段用空格分开接下来若干行是请求头每行key: value的形式以冒号分隔然后是一个空行标志着头结束空行之后是请求体长度由 Content-Length 决定。响应也是同样的结构HTTP/1.1 200 OK Content-Type: text/html;charsetUTF-8 Content-Length: 12 Hello World!关键点在于每一行结尾都是\r\n头和体之间用一个单独的空行分隔。手写解析器的时候这个\r\n处理不好就会出现各种诡异问题。还有两个规范细节值得记一下。请求头和响应头里的字节默认按 ISO-8859-1 解码这是 HTTP 规范历史遗留的结果中文出现在头里很少见但确实存在。请求体的编码则由 Content-Type 里的 charset 决定没写的话就靠应用自己指定了——这也是上一节 POST 乱码的根源。3.2 用 ServerSocket 直接 readLine 会踩的两个坑我第一版实现是这么写的包一层BufferedReader然后循环readLine()读请求行和请求头。看起来没问题跑起来单测也全过但接上带请求体的 POST 就出问题了——请求体读不到或者只读到一半。原因在于 BufferedReader 内部有自己的字符缓冲区。它在调用 readLine 读请求头的时候会一次性从底层 InputStream 预读一大块数据默认 8192 字符这里面很可能已经把请求体的内容也读进来了。等你再用原始的 InputStream 去读 body数据早就被 BufferedReader 吞掉放进自己的缓冲区了读出来自然是空。第二个坑是readLine()按\r、\n、\r\n任意一种换行符切分而 HTTP 规范里头部行分隔符要求是 CRLF。对于头部解析来说这个差异通常无害但如果请求头里出现了裸露的\r或者某些老客户端用了单独的\n解析结果就会飘。解决办法是自己写一个按字节读行的工具方法不预读、不缓冲边界完全可控private static String readLine(InputStream in) throws IOException { ByteArrayOutputStream buf new ByteArrayOutputStream(128); int b; while ((b in.read()) ! -1) { if (b \n) { break; } if (b \r) { continue; } buf.write(b); if (buf.size() 8192) { throw new IOException(header line too long); } } if (b -1 buf.size() 0) { return null; } return buf.toString(ISO-8859-1); }注意这个方法读满一行就停绝不预读后面的字节所以请求体一定还在流里等着。用 ISO-8859-1 拼接是 HTTP 头的标准做法它能把任意字节无损地映射成字符后面要做 URL 解码也不会丢信息。4. 接入层落地从 ServerSocket 到可用的 HTTP 响应4.1 线程模型为什么不能一连接一线程最朴素的写法是 accept 到一个连接就new Thread(() - handle(socket)).start()。这在本地测试没问题但放到稍微有点并发的场景就不行了线程的创建和销毁有实打实的开销而且没有任何上限几百个并发请求就能把线程数拉到几千栈内存直接吃满最后 OutOfMemoryError。Tomcat 的做法是用线程池对应两个关键参数maxThreads 控制最大工作线程数acceptCount 控制等待队列长度。手写版本我用 ThreadPoolExecutor 把这两个语义都还原出来this.workers new ThreadPoolExecutor( 20, 20, 60L, TimeUnit.SECONDS, new ArrayBlockingQueue(100), new NamedThreadFactory(mini-worker), new ThreadPoolExecutor.AbortPolicy());这里 20 大致对应 maxThreads队列容量 100 大致对应 acceptCount。拒绝策略用 AbortPolicy 是有意的——当队列也满了说明系统已经过载这时候直接把连接关掉比无限堆积、最后把内存吃干净要安全。另外 socket 一定要设超时socket.setSoTimeout(5000)。不设的话一个只建立连接却不发数据的客户端就能把一个工作线程永久占住攒够 20 个这样的连接整个服务就假死了。这个坑在真实环境里被扫描器触发过很隐蔽。4.2 请求解析的完整实现解析的目标是把一串字节变成好用的对象。我的做法是先做最小可用的 HttpRequest只保留方法、URI、头、参数、请求体五样东西。public class HttpRequest { private String method; private String uri; private String path; private String queryString; private final MapString, String headers new LinkedHashMap(); private final MapString, String parameters new HashMap(); private byte[] body new byte[0]; public void setUri(String uri) { this.uri uri; int q uri.indexOf(?); if (q 0) { this.path uri.substring(0, q); this.queryString uri.substring(q 1); parseQuery(this.queryString); } else { this.path uri; } } private void parseQuery(String query) { for (String pair : query.split()) { if (pair.isEmpty()) { continue; } int eq pair.indexOf(); String k eq 0 ? pair.substring(0, eq) : pair; String v eq 0 ? pair.substring(eq 1) : ; try { parameters.put(URLDecoder.decode(k, UTF-8), URLDecoder.decode(v, UTF-8)); } catch (UnsupportedEncodingException ignored) { } } } public int getContentLength() { String v headers.get(content-length); return v null ? -1 : Integer.parseInt(v.trim()); } }有几个细节是踩过坑才加上的。头名字统一转小写存因为 HTTP 头名不区分大小写客户端可能发Content-Length也可能发content-length不统一的话取值时就要写一堆兼容逻辑。参数值一定要 URL 解码中文和特殊字符都是百分号编码过的不解码拿到手就是%E4%B8%AD这种字符串。请求体的读取必须严格按 Content-Length 来不能读到流结束为止因为 HTTP 长连接下流是不会结束的int contentLength request.getContentLength(); if (contentLength 0) { byte[] body new byte[contentLength]; int read 0; while (read contentLength) { int n in.read(body, read, contentLength - read); if (n -1) { break; } read n; } request.setBody(body); }4.3 响应写出与 Content-Length 的坑响应这边最容易错的就是 Content-Length。它是字节数不是字符数。写Hello的时候字符串长度和字节长度一样看不出问题一旦响应里有中文你好两个字符是 6 个字节按字符串长度写 2浏览器就会只显示前两个字节也就是一个乱码字符。我的做法是内部统一持有 byte[]写成字节之后长度自然就是对的public void flush() throws IOException { StringBuilder head new StringBuilder(); head.append(HTTP/1.1 ).append(status).append( ) .append(reason(status)).append(\r\n); headers.put(Content-Length, String.valueOf(body.length)); for (Map.EntryString, String e : headers.entrySet()) { head.append(e.getKey()).append(: ).append(e.getValue()).append(\r\n); } head.append(\r\n); out.write(head.toString().getBytes(StandardCharsets.ISO_8859_1)); out.write(body); out.flush(); }还有两点必须记住头部结束的空行不能省少了它浏览器会一直等直到超时写完一定要 flushOutputStream 有没有缓冲取决于具体实现不 flush 的话小响应可能一直卡在缓冲区里。至于长连接只有在 Content-Length 或者 Transfer-Encoding 明确给出边界的情况下才能保持两个都没有就只能写完就关这也是 HTTP/1.0 时代必须带 Content-Length 的原因。5. 把 Servlet 塞进去映射、装载与生命周期到这里 Mini Tomcat 还只能返回写死的字符串要让它认识 Servlet得补上三件事接口定义、路由映射、生命周期管理。5.1 注解扫描与 URL 到实例的映射先定义一个极简的 Servlet 接口把 init、service、destroy 三个方法留住因为这三个方法正是 Servlet 规范的核心约定public interface MiniServlet { void init(); void service(HttpRequest req, HttpResponse resp) throws IOException; void destroy(); }再定义一个注解用来标注 URLRetention(RetentionPolicy.RUNTIME) Target(ElementType.TYPE) public interface WebServlet { String value(); }扫描的逻辑就是遍历包下面的 class 文件反射加载看到带注解的就实例化注册进 Map。这里我特意用了clazz.getDeclaredConstructor().newInstance()而不是已经废弃的newInstance()后者会把构造器抛出的受检异常包装成InstantiationException排查起来特别费劲拿不到真实的异常栈。public void scan(String packageName) throws Exception { String path packageName.replace(., /); URL url Thread.currentThread().getContextClassLoader().getResource(path); if (url null) { return; } File dir new File(url.toURI()); for (File file : dir.listFiles()) { if (file.isDirectory()) { scan(packageName . file.getName()); } else if (file.getName().endsWith(.class)) { String className packageName . file.getName() .replace(.class, ); Class? clazz Class.forName(className); WebServlet ann clazz.getAnnotation(WebServlet.class); if (ann ! null MiniServlet.class.isAssignableFrom(clazz)) { register(ann.value(), (MiniServlet) clazz.getDeclaredConstructor().newInstance()); } } } }提示这段扫描只适用于 IDE 里跑、class 文件散落在目录中的情况。打成 jar 之后getResource返回的不是 file 协议new File(url.toURI())会直接抛异常。真实容器要处理 file 和 jar 两种协议这也是很多人自己写扫描时最容易翻车的地方。5.2 静态资源处理与 404 兜底路由的匹配顺序很关键先查 Servlet 映射没命中再当作静态资源找都找不到才返回 404。顺序反过来的话静态资源目录下如果恰好有个跟 Servlet 路径同名的目录就会互相干扰。public void service(HttpRequest req, HttpResponse resp) throws IOException { MiniServlet servlet servletMap.get(req.getPath()); if (servlet ! null) { servlet.service(req, resp); return; } StaticResourceHandler.handle(webRoot, req, resp); }静态资源处理里有个必须做的安全校验——路径穿越防护。请求/../../etc/passwd这种路径如果直接拼到 webRoot 后面就能读到服务器上的任意文件。用getCanonicalPath()规范化之后判断是否还在 webRoot 之内是最简单可靠的做法File file new File(webRoot, path); if (!file.getCanonicalPath().startsWith(new File(webRoot).getCanonicalPath())) { resp.setStatus(403); resp.write(h1403 Forbidden/h1, UTF-8); return; }MIME 类型也要给对不然 css 和 js 会被浏览器拒绝执行。用一张小的映射表就够覆盖日常开发扩展名Content-Typehtmltext/html;charsetUTF-8csstext/css;charsetUTF-8jsapplication/javascript;charsetUTF-8jsonapplication/json;charsetUTF-8png / jpgimage/png / image/jpeg5.3 init/service/destroy 的调用时机Servlet 的生命周期这三个方法是容器调用的不是我们自己调的。init 在注册时调用一次service 每次请求调用destroy 在容器关闭时调用一次。这个一次和每次的差别是很多 bug 的来源把有状态的变量写在 Servlet 实例字段上在并发请求下就会出现数据串台因为容器默认只创建一个 Servlet 实例多个线程共享它。destroy 的触发在 Mini Tomcat 里靠 JVM 的关停钩子Runtime.getRuntime().addShutdownHook(new Thread(() - { container.destroyAll(); workers.shutdown(); }));顺带说一个之前很困惑我、后来才想明白的点Tomcat 里load-on-startup配置为负数或者不配的时候Servlet 是第一次被访问时才 init而不是启动时就初始化。所以启动日志里看不到某个 Servlet 的初始化信息不代表它有问题可能只是还没被访问过。要让它随容器启动就把 load-on-startup 设成 0 或者正整数数字越小越先加载。6. 手写完之后再看 Tomcat几个设计选择的答案代码写完跑通之后回头再看 Tomcat 的架构图那些原本抽象的概念会突然变得具体。6.1 Connector 与 Container 拆开的意义我一开始是把手写版本的收字节和跑 Servlet放在一个类里的后来发现换协议的时候要改的地方太多才理解 Tomcat 为什么要把 Connector 和 Container 彻底拆开。Connector 只负责一件事把网络字节流翻译成标准的 Request/Response 对象再把 Response 写回字节流。它不关心 Servlet 是什么、URL 怎么映射。ContainerEngine、Host、Context、Wrapper 层层嵌套只负责 Servlet 语义路由、生命周期、会话、安全约束它不关心字节是从 HTTP 还是别的协议来的。这样拆开之后换一个协议只需要换 Connector容器部分一行不动。协议版本演进和容器逻辑解耦这是这个设计的核心收益。6.2 类加载器隔离解决的真实问题每个 web 应用都会被分配一个独立的 WebappClassLoader这个设计解决的是依赖冲突A 应用用某个库的 1.0 版本B 应用用 2.0 版本如果共用一个类加载器同名的类只能加载一次必然有一方拿到错误版本。每个应用一个加载器同名类就被隔离开互不影响。另一个作用是热部署。重新部署应用时容器把旧的 ClassLoader 整个丢掉新建一个重新加载类就被卸载了。但这也是为什么反复热部署容易出现 Metaspace 溢出——只要有任何一个地方还持有旧 ClassLoader 的强引用比如一个没关掉的线程、一个静态注册的回调整个加载器就回收不掉它加载的所有类元数据都留在 Metaspace 里。生产环境我一般会在启动参数里显式加上-XX:MaxMetaspaceSize让它早点报错而不是慢慢把机器拖死。6.3 BIO 到 NIO 的线程模型演进我手写的那版是典型的 BIO一个线程处理一个连接线程读不到数据就一直阻塞。并发上来之后线程数直接爆炸。Tomcat 早期也是这个模型后来换成了 NIO。NIO 的核心改动在于把等待这件事从线程身上拿走了。少量 Acceptor 线程负责接收连接Poller 线程用多路复用监听大量连接上的可读可写事件真正的读写和业务处理才交给 Worker 线程池。带来的直接效果是几万个空闲连接可能只占用几十个线程而这些线程大部分时间在做实际工作而不是傻等。需要提醒的是NIO 只解决连接空闲时不占线程的问题。如果业务代码本身很慢比如一个查询要几百毫秒Worker 线程还是会被占满此时瓶颈在业务处理而不是 IO 模型。所以调优的时候先分清是连接数问题还是处理速度问题再决定是调线程池参数还是优化业务代码方向搞反了怎么调都没用。7. 部署与配置里那些容易忽略的细节7.1 context path 与 docBase 的对应关系访问路径和文件目录的对应关系本质上是 Context 的 path 属性和 docBase 属性决定的。把 war 包丢进 webappsTomcat 会自动解压并注册一个路径等于 war 文件名的 Context比如app.war对应访问路径/app。如果你想让它变成根路径就把 war 重命名为ROOT.war。有个点现在很多人不知道直接在 server.xml 里写Context标签Tomcat 官方已经不推荐了因为改这个文件不会触发热部署而且每次改都容易把整个文件写坏。推荐做法是在conf/Catalina/localhost/下建一个以路径命名的 xml 文件比如app.xmlContext docBase/data/apps/myapp reloadablefalse /这样配置的 Context 独立成文件改完自动生效出问题也只影响这一个应用。7.2 指定主页welcome-file-list 的查找顺序访问一个目录路径时返回哪个文件由 welcome-file-list 决定welcome-file-list welcome-fileindex.html/welcome-file welcome-fileindex.htm/welcome-file welcome-fileindex.jsp/welcome-file /welcome-file-list这里的匹配顺序是按列表逐个去目标目录下找文件第一个存在的就返回。所以如果你同时放了 index.html 和 index.jsp而想优先走 jsp就必须把 jsp 往前排。一个小细节是如果这个列表里所有文件都不存在容器返回的是 404 而不是目录列表——目录列表默认是关闭的这本身也是个安全上的好处。7.3 SSL 双向认证的配置要点普通 HTTPS 只验证服务端双向认证mutual TLS要求客户端也出示证书。配置全在 Connector 上Connector port8443 protocolHTTP/1.1 SSLEnabledtrue schemehttps securetrue clientAuthtrue keystoreFile/data/certs/server.keystore keystorePasschangeit truststoreFile/data/certs/trust.keystore truststorePasschangeit sslProtocolTLS /几个容易配错的地方keystore 放服务端自己的私钥和证书truststore 放用来验证对方的 CA 证书两者职责不能混clientAuth有三个取值false 表示不要求want 表示请求客户端证书但拿不到也放行true 表示必须且校验失败就断开生产上双向认证要用 true证书用 keytool 生成时注意有效期内部系统里见过太多过期证书导致的握手失败日志只会写一句 handshake failed不主动去看证书有效期很容易绕远路。排查握手问题时浏览器只给一句模糊的提示这时候用命令行工具带详细输出去测会清楚很多curl -v --cert client.crt --key client.key --cacert ca.crt https://localhost:8443/输出里会明确指出是证书链不完整、还是客户端证书没被信任、还是协议版本不匹配比在浏览器里猜快得多。从把这些东西一件件踩过去到现在能对着报错大致判断是哪一层的问题中间最大的转变其实不是记住了多少配置项而是养成了一个习惯遇到报错先问这是哪个层次的问题然后按顺序把 JVM、容器、应用三层逐个排除。手写一遍 Mini Tomcat 的价值也在这里它让你知道那些看起来神秘的机制——连接接入、报文解析、路由匹配、生命周期回调——拆开之后都只是些普通的代码逻辑出错的地方也就那么几个。真要动手的话建议别一上来就追求功能完整先把一个 GET 请求跑通、能正确返回中文再往上叠 Servlet 和静态资源这样每一步出问题都容易定位。