docs: Gitea HTTPS 클론 실패 트러블슈팅 문서 추가

- TLS 패킷 디코딩 오류 분석
- HTTP/2 및 HTTP/1.1 모두 실패 케이스 문서화
- SSH 우회 방법 제시
- 근본 해결 방안 정리

troubleshooting/250907_gitea_https_clone_failure.md

@@ -0,0 +1,82 @@
+# Gitea HTTPS 클론 실패 - TLS 패킷 디코딩 오류
+
+## 작성일: 2025-09-07
+## 작성자: 51123 서버 관리자
+## 환경: Ubuntu 22.04, Gitea 1.x, nginx HTTP/2
+
+## 문제 증상
+HTTPS를 통한 Git 클론 시 TLS 패킷 디코딩 오류로 실패
+
+### 에러 메시지
+```bash
+# HTTP/2 사용 시
+error: RPC 실패; curl 92 HTTP/2 stream 0 was not closed cleanly: INTERNAL_ERROR (err 2)
+error: 4608 bytes of body are still expected
+fetch-pack: unexpected disconnect while reading sideband packet
+
+# HTTP/1.1 강제 사용 시
+error: RPC 실패; curl 56 GnuTLS recv error (-9): Error decoding the received TLS packet.
+error: 716 bytes of body are still expected
+```
+
+## 검증 과정
+
+### 1. 서비스 상태 확인
+```bash
+systemctl status gitea  # Active (running) - 1개월 이상 정상 운영
+ss -tlnp | grep 3000    # 포트 정상 리스닝
+curl -I https://git.ro-being.com  # HTTP/2 200 정상 응답
+```
+
+### 2. 클론 테스트
+```bash
+# 서버 내부에서도 동일 오류 발생
+git clone https://git.ro-being.com/happybell80/company-x_hompage.git
+# HTTP/1.1 강제해도 실패
+git -c http.version=HTTP/1.1 clone https://git.ro-being.com/...
+```
+
+## 원인 분석
+
+1. **GnuTLS 라이브러리 문제**: Ubuntu Git이 GnuTLS 사용, TLS 패킷 처리 중 오류
+2. **Gitea Git 프로토콜 처리**: 대용량 데이터 스트리밍 중 버퍼 문제 추정
+3. **HTTP/2 멀티플렉싱**: 스트림이 정상 종료되지 않음 (INTERNAL_ERROR)
+4. **작은 저장소도 실패**: 4.5MB 크기에도 발생 → 프로토콜 레벨 이슈
+
+## 해결 방법
+
+### 즉시 해결 (권장)
+SSH 프로토콜 사용으로 우회
+```bash
+# SSH 키 설정 후
+git clone git@git.ro-being.com:happybell80/company-x_hompage.git
+```
+
+### 임시 해결
+1. Gitea 서비스 재시작
+```bash
+sudo systemctl restart gitea
+```
+
+2. nginx HTTP/2 비활성화 (성능 저하)
+```nginx
+# /etc/nginx/sites-enabled/default
+listen 443 ssl;  # http2 제거
+```
+
+### 근본 해결
+1. Gitea 버전 업그레이드
+2. Git을 OpenSSL 버전으로 재컴파일
+3. Gitea 설정에서 버퍼 크기 증가
+```ini
+# /etc/gitea/app.ini
+[server]
+LFS_MAX_FILE_SIZE = 10485760
+```
+
+## 관련 이슈
+- Gitea GitHub Issue #xxxxx (TLS handshake 관련)
+- Git GnuTLS vs OpenSSL 호환성 문제
+
+## 결론
+SSH 프로토콜 사용이 가장 안정적이며, HTTPS 클론은 Gitea 업그레이드 후 재검토 필요