Máy Chủ Tomcat Nhúng Hoạt Động Như Thế Nào Trong Spring Boot? (Series Java Spring Roadmap)

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.

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-webmvc là 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 synchronized cũ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-count hiệ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=graceful và đặt timeout thấp hơn terminationGracePeriodSeconds.
  • Đư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.