본문으로 건너뛰기

안동민 개발노트

본문 시작

트러블슈팅 방법론

물리 계층부터 애플리케이션까지 연결 실패를 단계적으로 분리하고 증상·오류별 체크리스트로 원인을 좁힙니다.

서버에 접속이 안 됩니다.

개발자가 가장 자주 듣는 말 중 하나입니다.

하지만 접속이 안 된다의 원인은 수십 가지입니다.

DNS가 안 풀리는 건지, TCP 연결이 안 되는 건지, 연결은 되지만 응답이 안 오는 건지, 응답은 오지만 에러인 건지.

계층별로 체계적으로 진단하는 방법을 알아야 원인을 빠르게 찾을 수 있습니다.


계층별 진단 접근법

네트워크 장애는 아래 계층부터 위로 좁힌다

케이블과 인터페이스부터 IP, 포트, HTTP 응답까지 한 단계씩 통과 여부를 확인하면 추측을 줄일 수 있다.

  1. L1/L2 link up, ARP/ND 케이블

    VLAN, NIC

  2. L3 IP, route, ping 라우팅

    보안 정책

  3. L4 port open, SYN/SYN-ACK

    방화벽, listen 상태

  4. L7 status code, header 앱

    인증, 프록시 설정

네트워크 문제는 아래 계층부터 위로 진단하는 것이 원칙입니다.

계층별 진단 흐름
[L1 물리] 케이블? Wi-Fi? NIC?
    │ ✓

[L2 링크] 인터페이스 활성? ARP?
    │ ✓

[L3 네트워크] IP 할당? 게이트웨이 ping? 라우팅?
    │ ✓          도구: ping, traceroute, ip route

[L4 전송] 포트 열림? 방화벽? TCP 연결?
    │ ✓      도구: telnet, nc, ss

[L7 애플리케이션] HTTP 응답? 상태 코드? 내용?
                  도구: curl, wget

1계층 — 물리적 연결: 케이블이 빠져 있거나, 무선 신호가 약하거나, NIC가 비활성화되어 있지 않은지 확인합니다.

2계층 — 링크: 네트워크 인터페이스가 활성화되어 있는지, ARP 테이블에 게이트웨이의 MAC 주소가 있는지 확인합니다.

arp -a로 확인할 수 있습니다.

3계층 — 네트워크: IP 주소가 올바르게 할당되었는지, 게이트웨이에 핑이 되는지, 목적지까지 라우팅이 가능한지 확인합니다.

4계층 — 전송: 목적지의 특정 포트에 TCP 연결이 되는지 확인합니다.

포트가 열려 있는지, 방화벽이 차단하고 있지 않은지 검사합니다.

7계층 — 애플리케이션: HTTP 요청을 보내고 응답을 확인합니다.

상태 코드, 헤더, 바디를 검사합니다.


통신이 안 될 때의 체크리스트

troubleshoot.sh
#!/bin/bash
# 네트워크 트러블슈팅 체크리스트 스크립트
TARGET=${1:-"example.com"}
PORT=${2:-443}

echo "=== 1. 인터넷 연결 확인 ==="
ping -c 2 8.8.8.8 && echo "[OK] 인터넷 연결" || echo "[FAIL] 인터넷 불가"

echo ""
echo "=== 2. DNS 확인 ==="
nslookup "$TARGET" && echo "[OK] DNS 정상" || echo "[FAIL] DNS 실패"

echo ""
echo "=== 3. 대상 서버 PING ==="
ping -c 2 "$TARGET" && echo "[OK] PING 응답" || echo "[WARN] PING 차단 가능"

echo ""
echo "=== 4. 포트 연결 확인 ==="
nc -z -w 3 "$TARGET" "$PORT" && echo "[OK] 포트 $PORT 연결 가능" || echo "[FAIL] 포트 $PORT 연결 실패(닫힘/차단/경로 문제 가능)"

echo ""
echo "=== 5. HTTP 응답 확인 ==="
STATUS=$(curl -s -o /dev/null -w "%{http_code}" "https://$TARGET" 2>/dev/null)
echo "HTTP 상태 코드: $STATUS"

echo ""
echo "=== 6. 경로 추적 ==="
traceroute -m 10 "$TARGET" 2>/dev/null || tracert "$TARGET" 2>/dev/null

에러별 원인 진단표

증상 문구는 실패한 계층을 좁히는 단서다

같은 접속 실패라도 DNS 실패, 포트 거부, 타임아웃, 502는 확인해야 할 위치가 다릅니다.

  1. DNS

    NXDOMAIN DNS 이름 해석 실패

  2. L3

    No route L3 게이트웨이/경로 실패

  3. L4

    Refused L4 포트 수신 없음

  4. L7

    502/5xx L7 프록시 또는 앱 오류

증상가능한 원인확인 명령해결 방향
ping 8.8.8.8 실패인터넷 연결 자체 문제ip addr, ifconfigNIC, 케이블, DHCP 확인
ping OK, DNS 실패DNS 서버 문제cat /etc/resolv.confDNS 서버 변경
ping OK, 포트 연결 실패방화벽 차단iptables -L, 보안그룹방화벽 규칙 추가
Connection refused프로세스 미실행ss -tlnp서비스 재시작
Connection timed out방화벽 DROP, 라우팅 문제, 서버 무응답tcpdump port 포트, mtr 대상IP경로와 방화벽 규칙 확인
502 Bad Gateway백엔드 연결 실패프록시 로그 확인백엔드 상태 확인
503 Service Unavailable서버 과부하/점검서버 리소스 확인스케일아웃, 재시작
간헐적 느림패킷 유실, 재전송mtr 대상IP네트워크 경로 점검

네트워크 문제 vs 애플리케이션 문제

장애 상황에서 가장 먼저 구분해야 할 것은 네트워크 문제인가, 애플리케이션 문제인가입니다.

네트워크 문제와 애플리케이션 문제는 관측 지점이 다르다

IP와 포트까지 성공했는지, HTTP 처리에서 실패했는지를 분리하면 담당 범위가 좁아진다.

  1. Client DNS, route, timeout

    CORS, status code

  2. Server listen port, SYN 도착

    handler error, DB timeout

  3. Proxy/LB target health

    reset routing rule, auth header

  4. Log 연결 packet trace

    LB log request id와 app log

다음 절에서는 이 진단 과정에서 사용하는 핵심 도구들의 실제 사용법을 다루겠습니다.

트러블슈팅 기록은 통과한 계층과 실패한 계층을 남긴다

한 번 확인한 사실을 다시 의심하지 않도록, 통과 조건과 실패 응답을 짧게 기록하며 위로 올라갑니다.

  1. L1/L2

    PASS L1/L2 링크와 VLAN 정상

  2. L3

    PASS L3 게이트웨이 응답

  3. L4

    FAIL L4 443 SYN 재전송

  4. 조치

    NEXT 조치 방화벽/리스너 확인

트러블슈팅 방법론에서는 프로토콜 상태, 실패 응답, 관측 도구, 복구 기준을 확인합니다.

보충 점검은 단정 대신 반례를 확인한다

ping 실패가 서버 다운을 뜻하지 않고, HTTP 200이 정상 처리를 뜻하지 않을 수 있습니다.

  1. DNS 문제

    설 DNS 문제 IP 직접 접속도 실패하는가?

  2. 다른 리전 성공

    반례 다른 리전 성공 경로 또는 정책 차이

  3. 특정 포트만 실패

    축소 특정 포트만 실패 L4 규칙 후보

  4. 캡처 증거

    확정 캡처 증거 SYN 응답 없음