docs: git pull TLS 패킷 디코딩 오류 트러블슈팅 추가

- nginx 프록시 버퍼 설정으로 해결
- 원인 분석 및 해결 방법 상세 문서화

troubleshooting/250914_happybell80_git_pull_tls_error.md

@@ -0,0 +1,95 @@
+# 트러블슈팅: 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 버퍼 크기 증가 (실패)
+```bash
+git config http.postBuffer 524288000
+git pull
+```
+- 결과: 동일한 오류 반복
+
+### 2. shallow pull 시도 (부분 성공)
+```bash
+git pull --depth=1
+```
+- 결과: fetch는 성공했지만 "refusing to merge unrelated histories" 오류
+
+### 3. hard reset으로 강제 동기화 (임시 해결)
+```bash
+git reset --hard origin/main
+```
+- 결과: 일시적 해결, 하지만 근본 원인 미해결
+
+## 최종 해결 방법
+
+### nginx 프록시 버퍼 설정 수정
+`/home/happybell80/ivada_project/nginx-infra/server-nginx-default` 파일의 git.ro-being.com 서버 블록 수정:
+
+```nginx
+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;
+    }
+}
+```
+
+### 적용 명령어
+```bash
+# 서버에서 실행
+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로 프록시할 때도 적용 가능
+- 메모리 사용량이 증가할 수 있으므로 서버 리소스 모니터링 필요