도커(Docker)에서 curl (56) Recv failure 에러: 원인과 해결 가이드

로

도커 컨테이너 환경에서 자주 마주치는 문제 중 하나가 바로 curl (56) Recv failure 에러입니다. 이 에러는 개발자들이 네트워크 통신 과정에서 빈번히 경험하지만, 그 원인이 매우 다양하고 복합적이어서 문제를 정확하게 진단하고 해결하는 데 상당한 시간이 소요되곤 하는데요.

기본적으로 이 에러 메시지는 “TCP 연결 자체는 성공적으로 이루어졌으나, 서버로부터 데이터를 수신하는 과정에서 연결이 예기치 않게 종료되었다”는 의미를 담고 있습니다. 즉, 클라이언트가 서버와 통신을 시작하는 데는 문제가 없었지만, 데이터가 완전히 도착하기 전에 통신이 끊겼음을 알리는 신호입니다.

도커 컨테이너는 호스트 OS와 격리된 독립적인 환경에서 실행되기 때문에, 네트워크 통신은 여러 복잡한 계층과 구성 요소를 거치게 됩니다. 컨테이너 내부 네트워크 설정, 호스트 네트워크 인터페이스, 도커 네트워크 드라이버, 그리고 그 위에 존재하는 방화벽 규칙이나 중간 프록시 서버 등 다양한 요소가 영향을 미칠 수 있습니다. 또한, 서버 측의 설정 문제나 응답 지연, 리소스 제한 등도 이러한 에러를 유발할 수 있어 원인 파악이 쉽지 않습니다.

따라서 이 문제를 효과적으로 해결하려면 단편적인 접근 대신, 단계별로 체계적인 점검 절차를 수행하는 것이 중요합니다. 우선, 컨테이너 네트워크 구성과 연결 상태를 확인하고, 내부 DNS 해석이나 라우팅 이슈가 없는지 검토해야 합니다. 이어서, 서버의 응답 상태와 로그를 분석해 서버 측에서 연결을 중단하는 원인이 있는지 살펴봅니다. 중간에 위치한 프록시나 로드밸런서가 있다면 해당 설정이나 타임아웃 값도 점검 대상입니다. 또한, 컨테이너 리소스 제한(CPU, 메모리)으로 인한 성능 저하가 발생하지 않는지도 확인해야 합니다.

이처럼 curl (56) Recv failure 에러는 단순한 네트워크 오류 이상으로, 도커 컨테이너 환경 특유의 복잡성을 고려한 전반적인 점검과 조치가 요구됩니다. 아래에서 제시하는 체계적인 점검 순서를 따라가면 문제의 원인을 신속히 진단하고, 안정적인 네트워크 통신 환경을 구축하는 데 아마 큰 도움이 되지 않을까 싶습니다.

 

1. 초기 진단: 증상 스냅샷 만들기

 

문제를 해결하기 위해선 정확한 증상을 파악하는 것이 가장 중요합니다.

  • 에러 정보 기록: 에러가 발생하는 curl 명령어, 대상 URL, HTTP 메서드, 헤더 정보를 정확하게 기록하세요.
  • 호스트와 비교: 동일한 curl 명령을 컨테이너 내부와 호스트(컨테이너 바깥)에서 각각 실행하고 결과를 비교하세요. 호스트에서는 정상 작동하는데 컨테이너에서만 실패한다면, 컨테이너의 네트워크 환경에 문제가 있을 가능성이 높습니다.
  • 특정 조건 확인: 대용량 파일 업로드/다운로드, HTTP/2 사용, 서버 스트리밍 등 특정 조건에서만 문제가 발생하는지 확인하세요.

팁: curl 명령어에 -v 또는 --trace-ascii 옵션을 추가하면 상세한 로그를 볼 수 있어, 어느 단계에서 연결이 끊겼는지 바로 파악하는 데 큰 도움이 됩니다.

 

2. 컨테이너 내부 환경 1차 체크

 

가장 간단하면서도 효과적인 방법은 컨테이너 내부 환경을 점검하는 것입니다.

  • DNS 및 라우팅 확인:
    Bash

    curl -vI http://example.com
dig/nslookup example.com

    dig나 nslookup 명령어로 DNS가 URL을 올바른 IP 주소로 해석하는지 확인하세요. DNS 설정 문제로 잘못된 주소에 연결되면 에러가 발생할 수 있습니다.

  • 프록시 환경 변수 점검:
    Bash

    env | grep -i proxy

    의도치 않게 http_proxy나 https_proxy와 같은 프록시 환경 변수가 설정되어 있는지 확인하세요. 만약 설정되어 있다면 unset 명령어로 해제한 후 다시 시도해 보세요.

  • 방화벽/보안 그룹 확인:

    nc -vz <대상 IP> <포트> 명령어로 컨테이너 내부에서 목적지 서버의 포트가 열려 있는지 확인하세요. 방화벽이나 보안 그룹이 트래픽을 차단하면 연결이 끊길 수 있습니다.

 

3. curl 옵션으로 원인 좁히기

 

curl의 다양한 옵션을 활용해 문제의 원인을 좁혀 나갈 수 있습니다.

  • HTTP/2 비활성화:
    Bash

    curl -v --http1.1 https://target.com

    HTTP/2 프로토콜의 구현 문제나 프록시 장비와의 충돌로 에러가 발생할 수 있습니다. 위 명령어처럼 HTTP/1.1을 강제로 사용했을 때 성공한다면, HTTP/2 프레이밍 관련 문제일 가능성이 높습니다.

  • TLS/SSL 문제 분리:
    Bash

    curl -vk https://target.com

    -k 옵션은 SSL 인증서 검증을 무시합니다. 이 옵션으로 성공한다면, 인증서 문제(만료, 체인 오류 등)가 원인입니다. curl --tls-max 1.2와 같이 TLS 버전을 강제로 지정해 구형 장비와의 호환성 문제를 테스트해볼 수도 있습니다.

  • 데이터 인코딩 및 연결 유지:
    Bash

    curl --header 'Connection: close' https://target.com
curl --header 'Accept-Encoding: identity' https://target.com

    첫 번째 명령어는 연결을 유지하지 않고 바로 끊도록 합니다. 두 번째 명령어는 압축(GZIP)이나 청크 인코딩을 비활성화해 데이터 전송 방식의 문제를 점검합니다. 이 옵션으로 성공한다면 서버/프록시의 압축 또는 인코딩 처리 문제일 수 있습니다.

  • 타임아웃 및 재시도 설정:

    –max-time 30 –retry 3 옵션으로 네트워크 지연에 의한 타임아웃 문제를 완화하고, 재시도를 통해 일시적인 오류를 극복할 수 있습니다.

 

4. 도커 네트워크 이슈 포인트

 

도커 컨테이너는 호스트와는 다른 가상 네트워크 환경을 사용하므로, 이로 인한 문제가 발생할 수 있습니다.

  • MTU (Maximum Transmission Unit) 불일치:
    • 원인: 컨테이너의 MTU 값(기본 1500)과 호스트 또는 외부 네트워크 인터페이스의 MTU 값이 다르면, 대용량 패킷이 조각화되거나 손실될 수 있습니다.
    • 해결: docker network create --mtu 1450 명령어로 MTU 값을 명시적으로 지정하거나, /etc/docker/daemon.json 파일에 MTU 값을 설정해 도커 데몬을 재시작하세요.
  • IPv6 문제: 특정 네트워크 환경에서는 IPv6를 통한 연결에서만 문제가 발생할 수 있습니다. curl -4 https://target.com 명령어로 IPv4를 강제로 사용해 보세요.
  • CA 루트 번들 누락: 경량 리눅스 이미지(예: alpine:scratch)를 사용하면 HTTPS 통신에 필요한 CA 루트 인증서 번들이 누락되어 있을 수 있습니다. ca-certificates 패키지를 설치하면 해결됩니다.

 

5. 서버 및 중간 프록시 문제

 

컨테이너 환경이 아닌, 목적지 서버나 중간 프록시의 설정 때문에 에러가 발생할 수도 있습니다.

  • 서버 로그 확인: 서버(Nginx, Envoy 등)의 로그에서 499, 502, 504 에러나 upstream prematurely closed connection, empty reply from server와 같은 메시지를 찾아보세요. 이는 서버가 클라이언트 요청을 처리하는 도중 연결을 끊었다는 의미입니다.
  • 타임아웃 설정: Nginx 같은 프록시 서버의 proxy_read_timeout이나 keepalive_timeout 설정이 너무 짧으면, 서버가 응답을 준비하는 동안 연결이 끊길 수 있습니다. 이 값을 충분히 길게 조정해 보세요.
  • 대용량 업로드/다운로드: client_max_body_size나 proxy_request_buffering 같은 서버 설정이 업로드 파일 크기 제한이나 버퍼링 문제로 인해 Recv failure를 유발할 수 있습니다.

 

6. 재현 스크립트 예시 (로그 풍부하게)

 

문제를 진단할 때 아래와 같은 명령어를 사용하면 원인 파악이 훨씬 쉬워집니다.

Bash

# HTTP/2 끄고 상세 로깅
curl --http1.1 -vL --trace-time --max-time 30 https://your.api/endpoint

# TLS/ALPN 디버그
curl -v --ciphers 'ECDHE+AESGCM:!SHA1' --tls-max 1.2 https://your.api

# 큰 바디/스트리밍 케이스
curl -v -T bigfile.bin https://your.api/upload
curl -vN https://your.api/stream

로그에서 server did not send any data before close, HTTP/2 stream was reset 등의 메시지가 나타나면 서버 측 문제일 가능성이 높습니다.

 

7. 체크리스트 (복사/붙여넣기용)

 

아래 체크리스트를 활용해 문제를 빠르게 진단해 보세요.

  • 호스트에서는 정상, 컨테이너만 실패? → MTU, 프록시, CA 번들, IPv6 우선순위 확인
  • HTTP/2를 끄면 정상? → ALPN/h2 설정, 중간 프록시/서버 파라미터 조정
  • TLS 옵션 바꾸면 정상? → 암호군/버전/SSL Inspection 영향, 서버/네트워크 정책 확인
  • 큰 바디/스트리밍에서만 실패? → 서버 타임아웃/버퍼/프록시 파라미터 조정
  • 무작위로 간헐적 실패? → 로드 밸런서/프록시 중 일부의 설정 문제일 가능성, 특정 백엔드로 핀포인트 테스트

Disclaimer: 본 블로그의 정보는 개인의 단순 참고 및 기록용으로 작성된 것이며, 개인적인 조사와 생각을 담은 내용이기에 오류가 있거나 편향된 내용이 있을 수 있습니다.

댓글 남기기