DOCS/journey/troubleshooting/250914_happybell80_git_pull_tls_error.md

트러블슈팅: Git Pull TLS 패킷 디코딩 오류

발생 시간

• 2025년 9월 14일

문제 상황

DOCS 저장소에서 git pull 실행 시 TLS 패킷 오류 발생

오류 메시지

error: RPC failed; curl 56 GnuTLS recv error (-9): Error decoding the received TLS packet.
error: 1481 bytes of body are still expected
fetch-pack: unexpected disconnect while reading sideband packet
fatal: early EOF
fatal: unpack-objects failed

시도한 해결 방법들

1. git config 버퍼 크기 증가 (실패)

git config http.postBuffer 524288000
git pull

• 결과: 동일한 오류 반복

2. shallow pull 시도 (부분 성공)

git pull --depth=1

• 결과: fetch는 성공했지만 "refusing to merge unrelated histories" 오류

3. hard reset으로 강제 동기화 (임시 해결)

git reset --hard origin/main

• 결과: 일시적 해결, 하지만 근본 원인 미해결

최종 해결 방법

nginx 프록시 버퍼 설정 수정

/home/happybell80/ivada_project/nginx-infra/server-nginx-default 파일의 git.ro-being.com 서버 블록 수정:

server {
    listen 443 ssl http2;
    server_name git.ro-being.com;

    location / {
        proxy_pass http://localhost:3000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 버퍼 설정 추가
        proxy_buffering off;
        proxy_request_buffering off;
        proxy_buffer_size 128k;
        proxy_buffers 8 256k;
        proxy_busy_buffers_size 512k;
        proxy_temp_file_write_size 512k;
        client_body_buffer_size 512m;
    }
}

적용 명령어

# 서버에서 실행
sudo nginx -t
sudo systemctl reload nginx

원인 분석

1. nginx 리버스 프록시 버퍼링: nginx가 Gitea의 응답을 버퍼링하면서 대용량 git 객체 전송 시 타임아웃/버퍼 오버플로우 발생
2. TLS 패킷 손상: 버퍼 크기 제한으로 인해 TLS 암호화된 데이터가 중간에 잘려서 디코딩 실패
3. git pack 파일 전송 중단: git은 pack 파일을 스트리밍으로 받는데, nginx 버퍼링으로 인해 연결이 끊김

해결 원리

• proxy_buffering off: 응답을 버퍼링하지 않고 즉시 클라이언트에 전달
• proxy_request_buffering off: 요청도 버퍼링 없이 즉시 업스트림 서버로 전달
• proxy_buffer_size 128k: 헤더용 버퍼 크기 증가
• client_body_buffer_size 512m: 클라이언트 요청 본문 버퍼 크기 대폭 증가

교훈

1. git 서버 프록시 설정 중요성: git은 대용량 바이너리 데이터를 스트리밍으로 전송하므로, 프록시 서버는 버퍼링을 비활성화해야 함
2. nginx 기본 버퍼 크기 한계: 기본 설정은 일반 웹 트래픽용이므로 git 같은 특수 프로토콜에는 부적합
3. 문제 해결 우선순위:
   • 클라이언트 설정(git config) 변경보다 서버 설정 확인이 우선
   • 특히 프록시 서버가 있는 경우 프록시 설정이 핵심

참고 사항

• 이 설정은 Gitea 뿐만 아니라 다른 git 서버(GitLab, GitHub Enterprise 등)를 nginx로 프록시할 때도 적용 가능
• 메모리 사용량이 증가할 수 있으므로 서버 리소스 모니터링 필요