Git 서비스 Nginx 설정¶

Git 서비스(GitLab, Gitea, HTTP 기반 Git)를 제공하기 위한 Nginx 설정 기준 정의함.
Git 서비스에 필요한 항목만 추가 또는 override함.

1. 적용 대상¶

GitLab / Gitea / 기타 HTTP 기반 Git 서비스
git.example.com 형태의 전용 도메인 사용 권장
업로드(push) 및 장시간 연결 발생 전제

2. Git 서비스 특성¶

git push 시 업로드 요청 body 크기가 커질 수 있음
git clone / pull 시 응답 시간이 길어질 수 있음
HTTP Keep-Alive 및 HTTP/1.1 동작 안정성 중요함

3. 서비스별 필수 설정¶

3.1 업로드 크기 제한¶

Git 서비스는 일반 API / Web 대비 큰 요청이 발생할 수 있음.

client_max_body_size 200m;

대형 저장소 push 고려 시 200m 이상 조정 가능함
무제한(0) 설정은 권장하지 않음

3.2 프록시 프로토콜 및 연결 유지¶

Git HTTP 동작 안정성을 위해 HTTP/1.1 및 Connection 헤더 처리 필요함.

proxy_http_version 1.1;
proxy_set_header Connection "";

3.3 표준 Forwarded 헤더¶

Backend에서 URL, 프로토콜, 클라이언트 IP를 정확히 인식하도록 헤더 전달 필요함.

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;

4. 권장 server 설정 예시¶

아래 예시는 Git 서비스 전용 도메인 기준임.
Backend 주소는 환경에 맞게 수정함.

server {
    listen 443 ssl;
    server_name git.example.com;

    client_max_body_size 200m;

    location / {
        proxy_pass http://GIT_BACKEND_UPSTREAM;

        proxy_http_version 1.1;
        proxy_set_header Connection "";

        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;
    }
}

5. 권장 upstream 구성 예시¶

단일 backend 또는 다중 backend 구성 가능함.

upstream GIT_BACKEND_UPSTREAM {
    server 192.168.0.215:8080;
    keepalive 32;
}

GitLab / Gitea 실제 포트에 맞춰 조정 필요함
upstream keepalive는 선택 사항임

6. 운영 점검 항목¶

push 시 413 오류 발생하면 client_max_body_size 상향 필요함
장시간 작업 중 504 / 502 오류 발생 시 timeout 정책 점검 필요함
(Global timeout 정책 적용 전제)

7. Git 트래픽 특성 및 rate / connection limit 적용 기준¶

Git 서비스 트래픽은 일반 Web/API 트래픽과 성격이 다르므로
rate limit 및 connection limit 적용 시 주의 필요함.

7.1 Git 트래픽 특성¶

요청 빈도는 상대적으로 낮음
연결 수는 순간적으로 증가할 수 있음
연결 유지 시간이 김
한 사용자당 동시에 여러 연결이 발생할 수 있음
(clone, fetch, pack 전송 과정에서 다중 연결 사용)

이러한 특성으로 인해 Git 서비스에서는
요청 수 제한보다 연결 유지 안정성이 더 중요함.

7.2 rate / connection limit 적용 원칙¶

rate limit / connection limit은 Git 트래픽 특성을 고려하여 신중히 적용함
일반 Web/API 기준의 제한 설정을 그대로 적용하지 않음
과도한 limit_conn, limit_req 설정은 다음 문제를 유발할 수 있음
- git push 중 pack 전송 실패
- git clone / fetch 중 RPC failed 오류 발생
- 사용자 체감상 간헐적 장애로 인식됨

7.3 일반적인 권장 수치 예시 (참고)¶

아래 수치는 절대값이 아닌 참고 예시임.

# connection limit 예시
limit_conn conn_limit 20;

# rate limit은 Git 서비스에서는 일반적으로 비활성화 권장
# limit_req는 적용하지 않거나 매우 완화된 값 사용

사용자 수가 적은 내부 Git 서버 기준 예시임
외부 공개 Git 서비스에는 더 높은 값 필요함

7.4 상황별 적용 예시¶

1) 사내 전용 Git 서버 (사용자 수 적음)¶

목적: 실수 또는 비정상 클라이언트로 인한 과도한 연결 방지
권장 방향:
- limit_conn: 10 ~ 20 수준
- limit_req: 적용하지 않음

2) 사내 + 외부 협력사 Git 서버¶

목적: 악의적 트래픽 최소 방어
권장 방향:
- limit_conn: 20 ~ 50 수준
- IP 기반 제한 또는 인증 정책 병행
- limit_req: 적용 시 매우 완화된 값 사용

3) 대규모 조직 또는 CI 연동 Git 서버¶

목적: 자동화 도구(CI, Bot) 안정성 보장
권장 방향:
- limit_conn: 높게 설정하거나 미적용
- CI/Bot 전용 IP 분리 후 별도 정책 적용
- rate limit 사용 지양

8. 정리¶

Git 서비스에서 limit 설정은 보안보다 안정성 영향이 큼
“막기 위한 제한”이 아니라 “깨지지 않기 위한 제한”으로 접근함
구체적인 운영 수치는 조직의 트래픽/보안 정책 문서에서 최종 확정함