From e5a0e942c30845edd7ecf465016eea83b9d9bf73 Mon Sep 17 00:00:00 2001
From: happybell80 <happybell80@naver.com>
Date: Sun, 7 Sep 2025 21:44:25 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20Gitea=20HTTPS=20=ED=81=B4=EB=A1=A0=20?=
 =?UTF-8?q?=EC=8B=A4=ED=8C=A8=20=ED=8A=B8=EB=9F=AC=EB=B8=94=EC=8A=88?=
 =?UTF-8?q?=ED=8C=85=20=EB=AC=B8=EC=84=9C=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- TLS 패킷 디코딩 오류 분석
- HTTP/2 및 HTTP/1.1 모두 실패 케이스 문서화
- SSH 우회 방법 제시
- 근본 해결 방안 정리
---
 .../250907_gitea_https_clone_failure.md       | 82 +++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 troubleshooting/250907_gitea_https_clone_failure.md

diff --git a/troubleshooting/250907_gitea_https_clone_failure.md b/troubleshooting/250907_gitea_https_clone_failure.md
new file mode 100644
index 0000000..2ec5ae9
--- /dev/null
+++ b/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 업그레이드 후 재검토 필요
\ No newline at end of file