[Infra Ops] WAR 배포부터 server.xml 튜닝, 장애 대응까지

Tomcat을 제대로 운영하려면 어떤 파일이 어디에 있는지를 알아야 합니다. 로그를 찾지 못해 장애 대응이 늦어지거나, 라이브러리를 잘못된 경로에 두어 클래스를 못 찾는 문제가 현장에서 반복됩니다. 디렉터리 구조는 한 번 제대로 익혀두면 어떤 버전의 Tomcat이든 동일하게 적용됩니다.

확대

$CATALINA_HOME/의 주요 디렉터리입니다.

• bin/ — Tomcat 실행·종료 스크립트
  • startup.sh (→ catalina.sh start), shutdown.sh (→ catalina.sh stop), catalina.sh (실제 JVM 기동 파라미터, JAVA_OPTS 등)
• conf/ — 핵심 설정 파일
  • server.xml (Connector·Host·Engine 등 서버 구조), context.xml (전역 컨텍스트, JNDI DataSource), web.xml (서블릿 기본 동작), tomcat-users.xml (Manager App 계정 — 운영 주의)
• logs/ — 장애 대응 시 가장 먼저 열 곳
  • catalina.out (표준 출력+에러, 주 진단 대상), localhost.YYYY-MM-DD.log (앱별), localhost_access_log.YYYY-MM-DD.txt (HTTP 접근)
• webapps/ — WAR 배포 위치 (Tomcat이 감시): ROOT/ (/ 경로 기본 앱), myapp/ (myapp.war 압축 해제)
• work/ — JSP 컴파일 캐시 (Catalina/localhost/myapp/)
• lib/ — Tomcat + 모든 앱이 공유하는 JAR (mysql-connector-j-8.x.jar 등 JDBC 드라이버)

CATALINA_HOME vs CATALINA_BASE — 멀티 인스턴스 운영:

서버에 Tomcat 인스턴스를 2개 이상 운영할 때(8080, 8090 포트 등) CATALINA_HOME은 하나로 두고, CATALINA_BASE를 인스턴스마다 다르게 지정합니다. /opt/tomcat-8080/, /opt/tomcat-8090/ 식으로 분리하면 로그와 설정이 섞이지 않습니다.

# 실행 중인 Tomcat 프로세스와 CATALINA_HOME 확인
ps aux | grep catalina | grep -v grep
# 출력 예시:
# tomcat   1234  2.1 12.3 3456789 234567 ?  Sl  09:00  0:45
#   /usr/lib/jvm/java-17/bin/java ... -Dcatalina.home=/opt/tomcat ...

server.xml은 Tomcat 전체 구조를 정의합니다. 그 중 Connector는 외부 HTTP 요청을 받는 입구입니다. 여기서 스레드 수, 대기 큐, 타임아웃을 잘못 설정하면 트래픽 급증 시 서비스가 멈추거나, 반대로 리소스를 낭비합니다.

<!-- /opt/tomcat/conf/server.xml — Connector 핵심 설정 -->
<Connector port="8080" protocol="HTTP/1.1"
           connectionTimeout="20000"
           maxThreads="200"
           minSpareThreads="10"
           acceptCount="100"
           redirectPort="8443"
           URIEncoding="UTF-8" />

파라미터별 역할과 튜닝 기준:

요청 처리 흐름 — 스레드가 소진되면 어떻게 되나:

1. 요청이 들어오면 가용 스레드가 할당되어 처리
2. 가용 스레드가 maxThreads에 도달하면 → acceptCount 크기의 OS 큐에 대기
3. OS 큐도 가득 차면 → 새 연결은 즉시 거부(Connection refused)

따라서 maxThreads를 무작정 높이는 것이 해결책이 아닙니다. 스레드가 오래 점유되는 근본 원인(느린 DB 쿼리, 외부 API 지연)을 먼저 찾아야 합니다.

# server.xml 설정 확인 (grep으로 빠르게)
grep -A 5 'Connector port="8080"' /opt/tomcat/conf/server.xml

확대

브라우저가 http://shop.example.com/shop/cart를 요청하면 화면에 장바구니가 뜹니다. 그 사이 Tomcat 안에서는 Connector 수신 → 스레드 배정 → Engine·Host·Context 매핑 → 필터 체인 → 서블릿 service() → 응답이 순서대로 일어납니다. 이 단계를 나눠 두면 "왜 404지", "왜 요청이 catalina.out에 로그도 안 남고 사라지지", "왜 로그인이 풀리지"를 특정 단계로 좁힐 수 있습니다. Tomcat은 WAR를 올리는 상자가 아니라 아래 7단계를 밟는 컨테이너입니다.

[클라이언트]  GET /shop/cart HTTP/1.1  → :8080
   │
   ① Connector 수신                         (HTTP/1.1 or AJP, NIO poller가 소켓 감시)
   │
   ② 스레드풀에서 워커 스레드 배정           (maxThreads 한도, 없으면 acceptCount 큐 대기)
   │
   ③ Engine → Host → Context 매핑            (도메인→Host, 컨텍스트경로 /shop→앱)
   │
   ④ 필터 체인 통과                          (인코딩·인증 Filter, web.xml 순서대로)
   │
   ⑤ 서블릿 매핑 → service() 실행            (url-pattern 매칭 → doGet/doPost)
   │    → 이 안에서 세션(JSESSIONID) 조회·JNDI DB 연결 사용
   │
   ⑥ 응답 작성 → 필터 역순 통과 → Connector
   │
   ⑦ 워커 스레드 반납                        (keep-alive면 연결 유지하며 대기)
   ▼
[클라이언트]  200 OK   (스레드는 풀로 복귀)

각 단계에서 무슨 일이 일어나고, 막히면 어떤 증상인가:

즉 요청이 어느 단계까지 갔는지에 따라 로그가 남는 위치가 갈립니다. ①②(커넥터·스레드 층)에서 막히면 요청이 애플리케이션에 닿지 못해 catalina.out에 앱 로그가 한 줄도 없고, 서버는 멀쩡한데 클라이언트만 타임아웃·Connection refused를 겪습니다 — 이때는 Manager status의 currentThreadsBusy와 ss -tlnp의 Recv-Q 적체를 봅니다. ⑤ 이후에서 막히면 스택트레이스·슬로우 요청이 앱 로그와 access_log(%D)에 남습니다. 그래서 "로그가 있느냐 없느냐"가 커넥터 문제(②)와 애플리케이션 문제(⑤)를 가르는 첫 분기점입니다.

운영 중인 서비스가 갑자기 "DB 연결 실패" 에러를 쏟아내기 시작했습니다. 로그를 보니 Cannot get a connection, pool error Timeout waiting for connection from pool입니다. DB 자체는 살아있는데 연결을 못 받는 상황 — 연결 풀이 고갈된 것입니다. 처음 배포할 때 기본값 그대로 뒀다가 트래픽이 늘면서 터지는 전형적인 패턴입니다. context.xml 설정 한 줄 차이가 서비스 가용성을 결정합니다.

애플리케이션이 DB에 접근하는 방법은 두 가지입니다. 코드 내에서 직접 JDBC 연결을 생성하거나, Tomcat이 관리하는 JNDI DataSource를 통해 연결 풀을 빌려 쓰는 방식입니다. 실무에서는 거의 항상 JNDI DataSource를 씁니다 — DB 연결 생성 비용을 줄이고, 연결 수를 제어하며, 코드와 DB 설정을 분리할 수 있기 때문입니다.

<!-- /opt/tomcat/conf/context.xml — 전역 DataSource 설정 -->
<Context>
  <Resource name="jdbc/myapp"
            auth="Container"
            type="javax.sql.DataSource"
            driverClassName="com.mysql.cj.jdbc.Driver"
            url="jdbc:mysql://db-server:3306/mydb?useSSL=false&amp;serverTimezone=Asia/Seoul"
            username="appuser"
            password="secret"
            maxTotal="30"
            maxIdle="10"
            minIdle="5"
            maxWaitMillis="10000"
            validationQuery="SELECT 1"
            testOnBorrow="true"
            timeBetweenEvictionRunsMillis="60000"
            minEvictableIdleTimeMillis="300000" />
</Context>

연결 풀 파라미터 튜닝 기준:

JDBC 드라이버 배치 위치:

드라이버 JAR(mysql-connector-j-8.x.jar 등)는 반드시 $CATALINA_HOME/lib/에 둬야 합니다. webapps/앱명/WEB-INF/lib/에 드라이버를 두면 Tomcat 레벨의 JNDI DataSource가 드라이버를 찾지 못해 ClassNotFoundException이 발생합니다.

# JDBC 드라이버 배치 및 확인
sudo cp mysql-connector-j-8.x.jar /opt/tomcat/lib/
ls -la /opt/tomcat/lib/ | grep mysql
# Tomcat 재시작 후 반영됨 (lib 변경은 재시작 필요)

밤 11시에 긴급 배포를 해야 합니다. WAR 파일을 webapps/ 에 복사했는데 15분째 서비스가 뜨질 않습니다. 로그를 보러 갔더니 catalina.out이 수백 MB — 어디서부터 봐야 할지 모릅니다. 설상가상으로 롤백해야 하는데 이전 WAR 파일을 어디 뒀는지도 불확실합니다. 배포 방식을 이해하지 못한 채 운영에 들어가면 이런 상황이 반복됩니다.

Tomcat에 애플리케이션을 배포하는 방법은 상황에 따라 다릅니다. 개발 환경과 운영 환경에서 다른 방식을 써야 하고, 각 방식의 동작 원리를 이해해야 배포가 왜 실패했는지를 알 수 있습니다.

배포 방식 비교:

autoDeploy 설정 위치 (server.xml):

<!-- server.xml의 Host 엘리먼트 -->
<Host name="localhost" appBase="webapps"
      unpackWARs="true"
      autoDeploy="true">   <!-- 운영 환경에서는 false 권장 -->

배포 후 성공 확인 기준:

# catalina.out에서 정상 기동 확인
grep "Server startup in" /opt/tomcat/logs/catalina.out | tail -3
# 정상 출력 예시:
# INFO [main] org.apache.catalina.startup.Catalina.start
#   Server startup in [3456] milliseconds

기동 완료 메시지가 나오기 전까지는 서비스가 준비되지 않은 것입니다. 로드밸런서 헬스체크가 이 시간보다 짧으면 503이 발생할 수 있습니다.

maxThreads를 아는 것과, 그 스레드가 전부 찼을 때 '그다음 요청이 어디로 가는지'를 아는 것은 다릅니다. 부하 장애의 진짜 병목은 대개 스레드풀이 아니라 그 앞뒤에 있습니다.

• acceptCount는 애플리케이션이 아니라 커널 큐입니다: maxThreads가 전부 busy면 새로 맺어진 연결은 acceptCount 크기의 OS accept 큐(소켓 백로그)에서 대기합니다. 이 큐는 커널 소켓 백로그라 Tomcat이 처리하기 전이고, 그래서 대기·거부가 catalina.out에 한 줄도 안 남습니다. 큐마저 차면 커널이 연결을 거부해 클라이언트는 Connection refused나 타임아웃을 받습니다.
• NIO 커넥터는 연결과 스레드를 분리합니다: 옛 BIO 커넥터는 연결 하나가 스레드 하나를 물었지만, 현재 기본인 NIO 커넥터는 poller 스레드가 여러 연결의 소켓을 감시하다 실제 데이터가 올 때만 워커 스레드에 넘깁니다(Apache event MPM과 같은 발상). 그래서 keep-alive 유휴 연결이 워커를 붙잡지 않습니다. maxConnections(NIO 기본 8192)는 커넥터가 동시에 들고 있을 수 있는 연결 수로, 동시 처리 스레드인 maxThreads와는 별개 값입니다.
• 스레드풀과 DB 풀은 함께 사이징해야 합니다: maxThreads가 200인데 JNDI maxTotal이 30이면, 최대 200개의 요청 스레드가 30개의 DB 연결을 놓고 경쟁합니다. DB를 쓰는 동시 요청이 30을 넘는 순간 나머지는 maxWaitMillis만큼 풀에서 대기하므로, 슬로우 쿼리가 없어도 지연이 생깁니다. 두 값은 '요청 중 DB를 쓰는 비율'에 맞춰 정렬합니다.

핵심 한계: maxThreads·acceptCount를 키우는 것은 병목을 뒤로 미룰 뿐입니다. 스레드가 오래 붙잡히는 근본 원인(느린 다운스트림 — DB·외부 API)을 없애지 않으면 큐만 길어지고 클라이언트 체감 지연은 그대로입니다.