Bạn thêm spring-boot-starter-webmvc, chạy hàm main, và một Tomcat 11 nhúng bắt đầu nghe cổng 8080 dù bạn chưa cài Tomcat. Nhưng khi production chậm, câu hỏi thực tế không phải “Tomcat từ đâu ra” mà là request đang xếp ở đâu, thread nào đang giữ nó, và timeout nào sẽ cắt nó trước khi proxy bỏ cuộc.
Bài này mổ xẻ máy chủ Tomcat nhúng trên Spring Boot 4.1.2 (Tomcat 11.0.x, Servlet 6.1, Java 25 LTS): Boot dựng server qua ServletWebServerFactory thế nào, cổng bind ở bước nào, và bốn nhóm cấu hình quyết định hành vi thật: thread pool, timeout, virtual threads, shutdown.
Mục lục
Cập nhật 2026
- Boot 4.1.2 quản lý Tomcat 11.0.x — Servlet 6.1, Jakarta EE 11, namespace
jakarta.*. Java 25 LTS là baseline sản xuất; Boot chỉ yêu cầu tối thiểu Java 17. spring-boot-starter-webmvclà starter cho code mới.spring-boot-starter-webđã bị deprecate từ Boot 4.1 nhưng vẫn resolve và chạy.- Undertow không còn được hỗ trợ (Framework 7 đã bỏ); Tomcat và Jetty 12.1.x là hai lựa chọn nhúng của Boot 4.
- Virtual threads, graceful shutdown và access log đều là cấu hình, không cần customizer; cảnh báo pinning do
synchronizedcũng đã đổi từ Java 24.
Máy chủ Tomcat nhúng: Boot đóng gói gì vào jar?
Starter web kéo spring-boot-starter-tomcat, rồi starter này kéo thư viện Tomcat nhúng vào classpath. File jar thực thi vì thế chứa cả ứng dụng lẫn servlet container: java -jar shop.jar chạy một tiến trình duy nhất gồm JVM, Spring context và Tomcat.
Đây là thay đổi mô hình: với WAR, quản trị viên sở hữu Tomcat, connector và vòng đời deploy; với jar nhúng, ứng dụng sở hữu tất cả. Bạn đổi phiên bản Tomcat bằng dependency, nhưng cũng chịu trách nhiệm về thread pool, timeout và cổng.
// File: src/main/java/com/example/shop/ShopApplication.java
package com.example.shop;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class ShopApplication {
public static void main(String[] args) {
SpringApplication.run(ShopApplication.class, args);
}
}
Boot tạo web server như thế nào?
SpringApplication chọn WebApplicationType theo classpath: có DispatcherServlet và API servlet thì là SERVLET, và Boot tạo ServletWebServerApplicationContext thay vì context thường. Web server vì thế là một phần của context, không phải tiến trình riêng.
Auto-configuration tạo bean ServletWebServerFactory khi classpath có Tomcat và chưa có bean cùng kiểu; implementation mặc định là TomcatServletWebServerFactory, dựng Tomcat, Engine, Host, Context, Connector và áp các customizer bạn khai báo. Các WebServerFactoryCustomizer — kể cả customizer đọc ServerProperties — được áp trước khi factory dùng.
Context gọi factory.getWebServer(initializers). Tham số là ServletContextInitializer: DispatcherServletRegistrationBean, filter, servlet, listener, được đăng ký trước khi connector nhận request. Kết quả là TomcatWebServer do context quản lý vòng đời.
Chỉ được có một factory; khai báo thêm ServletWebServerFactory mà không loại trừ auto-config sẽ làm context dừng khởi động. Muốn đổi chi tiết, dùng customizer hoặc property.
Boot 4 đã tách module và đổi package nhiều lớp Tomcat. Đừng copy FQCN org.springframework.boot.web.embedded.tomcat.* từ Boot 3; để IDE import theo artifact thực dùng — lỗi compile phổ biến khi nâng từ Boot 3.5 lên 4.1.
Vòng đời: tạo ở onRefresh, bind cổng ở finishRefresh
ServletWebServerApplicationContext override onRefresh(). Đây là lúc createWebServer() chạy: Tomcat được dựng, engine/context/connector được cấu hình, initializer được đăng ký. Tomcat đi qua vòng đời khởi tạo nhưng connector chưa nhận traffic; việc bind bị hoãn đến finishRefresh để request không vào trước khi singleton bean sẵn sàng.
finishRefresh() gọi WebServer.start(). Lúc này connector được gắn lại, cổng được bind, servlet load-on-startup hoàn tất và ServletWebServerInitializedEvent được phát; sau đó là ApplicationRunner/CommandLineRunner, rồi ApplicationReadyEvent.
Hệ quả: lỗi “Port 8080 was already in use” xuất hiện ở finishRefresh, sau khi toàn bộ bean đã tạo nhưng trước khi ứng dụng báo ready. Nó không có nghĩa context chưa khởi tạo xong; nó có nghĩa tầng network chưa mở.
Khi test hoặc chạy song song, dùng server.port=0 và đọc cổng thật từ ServletWebServerInitializedEvent, đừng hard-code 8080.
Connector và thread pool: năm tham số quyết định throughput
| Tham số | Mặc định | Ý nghĩa |
|---|---|---|
server.tomcat.threads.max |
200 | Số thread xử lý request đồng thời |
server.tomcat.threads.min-spare |
10 | Số thread rảnh tối thiểu được giữ lại |
server.tomcat.max-connections |
8192 | Số connection được accept và xử lý, gồm cả keep-alive đang rảnh |
server.tomcat.accept-count |
100 | Độ dài backlog khi connection đã đầy |
server.tomcat.max-keep-alive-requests |
100 | Số request tối đa trên một connection; 1 là tắt keep-alive, -1 là không giới hạn |
threads.max là số request xử lý đồng thời, không phải số connection. Thread pool đầy thì request chờ; max-connections đầy thì connection mới vào backlog accept-count; backlog đầy thì OS từ chối. Tăng thread mà không tăng connection, hoặc ngược lại, thường không giải quyết nút thắt.
Chọn số theo Little’s law: concurrency xấp xỉ throughput × latency. 20 request/giây với một lời gọi chậm 3 giây tạo ra 60 request đồng thời; hạ threads.max xuống 20 chỉ làm phần còn lại ngồi chờ.
# File: src/main/resources/application.yml
server:
port: 8080
tomcat:
threads:
max: 200
min-spare: 10
max-connections: 8192
accept-count: 100
Đây là điểm khởi đầu cho dịch vụ I/O-bound, không phải công thức. Đo thread bận trước khi tăng số; tăng thread chỉ che bottleneck phía sau, thường là database hoặc API ngoài.
Timeout và keep-alive: đọc đúng ba tầng
server.tomcat.connection-timeout là thời gian chờ dòng request hoặc header sau khi connection được accept. Boot không đặt giá trị; connector HTTP/1.1 của Tomcat mặc định 60 giây. Giảm xuống vài giây giúp chống slowloris, nhưng có thể cắt client mạng yếu đang gửi header chậm.
server.tomcat.keep-alive-timeout là thời gian giữ connection rảnh chờ request kế tiếp. Nếu không đặt, Tomcat lấy theo connection-timeout. max-keep-alive-requests mặc định 100; đặt 1 để tắt keep-alive trên mỗi connection.
Nguyên tắc với proxy: timeout xử lý của ứng dụng phải ngắn hơn timeout đọc của proxy, và cả hai nên ngắn hơn timeout phía client. Nếu nginx hoặc load balancer cắt ở 60 giây còn app chờ 90 giây, client nhận 504 trong khi app vẫn ghi database; request có thể bị retry và chạy hai lần nếu endpoint không idempotent. Với tác vụ dài, trả 202 kèm job id thay vì giữ connection chờ.
server:
tomcat:
connection-timeout: 5s
keep-alive-timeout: 15s
max-keep-alive-requests: 100
Đừng đặt connection-timeout quá thấp cho endpoint upload lớn hoặc SSE. Timeout của connector là timeout đọc request, không phải timeout xử lý nghiệp vụ; hai thứ cần cấu hình riêng.
Virtual threads: đổi mô hình thread, không đổi giới hạn thật
spring.threads.virtual.enabled=true thay executor connector Tomcat bằng executor tạo virtual thread cho mỗi request. threads.max/min-spare không còn là trần xử lý; max-connections vẫn là trần connection. Boot cũng dùng virtual thread cho applicationTaskExecutor, nên @Async hưởng lợi.
spring:
threads:
virtual:
enabled: true
Điều nó sửa: request chờ I/O — JDBC, HTTP, đọc file — không còn chiếm platform thread đắt; service từng giới hạn 200 request đồng thời có thể chờ hàng nghìn request.
Điều nó không sửa: CPU (4 core vẫn là 4 core) và các pool phía sau — HikariCP mặc định 10 connection, HTTP client pool, Redis pool. Virtual thread xếp hàng ở đó y như platform thread, nên bật mà không hiểu downstream chỉ chuyển hàng chờ từ Tomcat sang database.
Pinning: trên Java 21, synchronized giữ carrier thread; từ Java 24, JEP 491 đã bỏ pinning cho synchronized, nên trên Java 25 LTS rủi ro còn lại chủ yếu ở native frame và thư viện cũ. Chạy JFR để xem pinning thật thay vì tắt virtual threads theo cảnh báo cũ. Vì virtual thread rẻ, hãy giới hạn concurrency theo tài nguyên thật bằng semaphore hoặc bulkhead, đừng dùng thread pool Tomcat làm van an toàn.
Graceful shutdown: đóng cổng trước, cắt request sau
server.shutdown=graceful đổi hành vi đóng context: Tomcat ngừng nhận connection mới, để request đang chạy hoàn tất, rồi mới đóng. Thời gian chờ do spring.lifecycle.timeout-per-shutdown-phase quyết định, mặc định 30 giây; hết thời gian, phần còn lại bị cắt.
server:
shutdown: graceful
spring:
lifecycle:
timeout-per-shutdown-phase: 20s
Mặc định là immediate: tiện khi dev, nhưng production sẽ làm rơi request đang ghi database. Đặt timeout shutdown thấp hơn terminationGracePeriodSeconds của Kubernetes ít nhất vài giây, nếu không SIGKILL sẽ đến trước khi Spring kịp đóng.
Readiness phải chuyển sang fail trước khi connection bị đóng để ingress rút traffic; một preStop ngắn giúp tránh 502 khi rolling. WebSocket, SSE và upload rất dài cần timeout riêng vì không tự drain theo timeout request thường.
Access log: bật khi cần điều tra, không phải để thay metric
Access log Tomcat ghi một dòng mỗi request và mặc định tắt. Bật bằng server.tomcat.accesslog.enabled=true; file ở logs, prefix access_log, xoay theo ngày. Pattern mặc định common; thêm %D để có thời gian xử lý millisecond.
server:
tomcat:
accesslog:
enabled: true
directory: /var/log/shop
prefix: access
suffix: .log
pattern: '%h %l %u %t "%r" %s %b %D'
rotate: true
max-days: 14
buffered: true
Trong container, file trong filesystem của pod mất khi pod chết: mount volume, hoặc để proxy/ingress giữ access log và dùng log ứng dụng cho lỗi nghiệp vụ. Đừng trỏ directory vào /dev/stdout vì rotation và buffer sẽ không hoạt động.
Access log trả lời “ai gọi, status nào, mất bao lâu”; nó không phải metric. p95/p99, thread bận, connection đang mở lấy từ Micrometer và Actuator.
JAR tự chạy hay WAR + Tomcat ngoài?
| Tiêu chí | JAR + Tomcat nhúng | WAR + Tomcat ngoài |
|---|---|---|
| Chạy | java -jar app.jar |
Deploy file .war vào container đã cài |
| Ai quản connector | Ứng dụng, qua server.* |
Tomcat ngoài, cấu hình trong server |
| Phiên bản Tomcat | Dependency do Boot quản lý | Do platform quyết định, dùng chung nhiều app |
| Phù hợp | Microservice, container, rollback theo image | Ràng buộc hạ tầng cũ, JSP legacy |
WAR vẫn hợp lệ khi tổ chức có platform Tomcat dùng chung, khi ứng dụng JSP legacy chưa chuyển được, hoặc khi vendor bắt buộc WAR. Cách đóng gói: packaging là war, spring-boot-starter-tomcat để scope provided, lớp main kế thừa SpringBootServletInitializer. Container ngoài phải là Tomcat 11.0.x/Servlet 6.1; Tomcat 10.1 chỉ có Servlet 6.0 và không đủ baseline của Boot 4.1.
Khi chạy WAR, server.port và phần lớn cấu hình connector trong application.yml không điều khiển Tomcat ngoài: container sở hữu connector, thread pool và cổng. Đó là lý do WAR + Tomcat ngoài là legacy deployment cho hầu hết service mới — bạn mất quyền kiểm soát đúng những thứ quyết định hành vi production.
Năm lỗi hay gặp
Hạ threads.max vì “máy chỉ có 4 core”
Số core quyết định throughput CPU-bound, không quyết định số request I/O-bound đang chờ. Workload gọi database 300 ms vẫn cần hàng chục thread để giữ throughput; hạ threads.max xuống 20 chỉ làm request xếp hàng lâu hơn. Tính theo Little’s law và đo thời gian bận, đừng dùng số core làm trần thread.
Gọi blocking không có timeout
Một lời gọi JDBC hoặc HTTP không timeout có thể giữ thread vô thời hạn; thread pool đầy, backlog đầy, health check không trả lời. Đặt connect timeout và read timeout cho mọi I/O ra ngoài, dùng circuit breaker hoặc bulkhead để cắt dependency chậm. Virtual threads làm thread rẻ hơn nhưng không cứu được một call treo mãi.
Timeout proxy ngắn hơn timeout ứng dụng
Proxy cắt ở 60 giây, app chờ 90 giây: client thấy 504, app vẫn ghi sau khi client retry, tạo duplicate request hoặc lock lâu hơn. Đồng bộ timeout theo thứ tự app → proxy → client; dùng idempotency key cho endpoint có retry.
server.port đụng nhau
Hai service cùng 8080, một sidecar trong cùng pod, hoặc một tiến trình dev còn chạy nền đều gây lỗi bind ở finishRefresh. Chạy với cổng khác qua CLI hoặc biến môi trường; trong test dùng cổng ngẫu nhiên.
# chạy với cổng khác khi 8080 đã bị chiếm
java -jar shop.jar --server.port=8081
# hoặc qua biến môi trường (relaxed binding)
SERVER_PORT=8081 java -jar shop.jar
Actuator health dùng chung cổng với traffic nghiệp vụ
Khi thread pool cạn, health check không có thread để trả lời; orchestrator tưởng ứng dụng chết và restart, tạo vòng lặp tệ hơn. Đặt management endpoint trên cổng riêng bằng management.server.port; liveness không gọi database, readiness có thể kiểm tra dependency.
management:
server:
port: 8081
endpoints:
web:
exposure:
include: health,info
endpoint:
health:
probes:
enabled: true
Nhìn trước 2027
Boot 4.2 đang ở RC2; hướng đi không đổi: module hóa sâu hơn, Tomcat 11.0.x là mặc định, và virtual threads ngày càng phổ biến nhưng không thay thế việc hiểu downstream. Java 29 LTS dự kiến trong 2027, tiếp tục chu kỳ hai năm. Điều đáng đầu tư không phải mẹo tăng thread, mà là timeout, backpressure và khả năng quan sát.
Checklist trước khi đưa service lên production
- Biết
threads.max,max-connections,accept-counthiện tại và lý do của từng con số. - Đặt timeout cho mọi JDBC, HTTP client và cache; không để mặc định vô hạn.
- Nếu bật virtual threads, kiểm tra HikariCP, HTTP pool và pinning bằng JFR.
- Bật
server.shutdown=gracefulvà đặt timeout thấp hơnterminationGracePeriodSeconds. - Đưa health ra cổng management riêng; liveness không phụ thuộc database.
- Giữ jar nhúng làm mặc định; chỉ dùng WAR khi có ràng buộc hạ tầng thật.
Đọc tiếp trong series
Nền tảng của bài này là Spring Boot Autoconfiguration — nơi giải thích vì sao TomcatServletWebServerFactory xuất hiện mà bạn không khai báo. Cách Spring tổ chức context và bean nằm ở Cách Spring hoạt động; cách đọc health, metric và endpoint vận hành nằm ở Actuator. Toàn bộ thứ tự bài học ở Spring Boot Roadmap.



