GitHub 및 npm용 프록시: 차단된 국가에서의 접근

```html

GitHub이 차단되었거나 10~30초의 지연으로 작동하거나 npm install이 중단되는 경우 — 이는 러시아, 이란, 중국 및 기타 여러 국가의 개발자들에게 익숙한 상황입니다. 해결책이 있으며, 생각보다 간단합니다: 올바르게 설정된 프록시는 VPN 없이도 리포지토리, 패키지 및 GitHub API에 안정적으로 접근할 수 있게 해줍니다.

왜 GitHub과 npm이 차단되거나 느려지는가

프록시를 설정하기 전에, 당신이 직면한 문제를 이해하는 것이 중요합니다. GitHub과 npm에 대한 접근 문제는 세 가지 유형이 있으며, 각각은 다른 접근 방식을 요구합니다.

국가 차원의 완전한 차단

중국, 이란, 북한과 같은 여러 국가에서는 DNS 또는 IP 수준에서 GitHub을 차단합니다. 이는 github.com에 대한 요청이 전혀 통과하지 않거나 연결 오류를 반환함을 의미합니다. 이 경우 npm 레지스트리 (registry.npmjs.org)는 정상적으로 작동할 수 있지만, 차단될 수도 있습니다.

기업 방화벽 및 네트워크 제한

국가 차단이 없더라도 기업 네트워크는 종종 외부 리포지토리에 대한 접근을 제한합니다. 이는 은행, 정부 기관 및 대기업에서 일반적인 관행입니다: IT 부서는 443 포트에 대한 아웃바운드 연결을 차단하거나 특정 도메인을 차단합니다. 이러한 네트워크에서 개발자는 git clone 또는 npm install을 우회하지 않고 수행할 수 없습니다.

지리적 원인으로 인한 느린 속도

기술적으로 GitHub에 접근할 수 있지만, 500MB의 리포지토리를 클론하는 데 40분이 걸리고, npm을 통한 종속성 설치는 영원히 걸릴 수 있습니다. 이는 라우팅 문제로, 패키지가 과부하된 노드나 긴 경로를 통해 이동하기 때문입니다. 미국이나 유럽에 위치한 프록시 서버는 경로를 단축시켜 3~10배의 속도 향상을 제공합니다.

중요한 점:

프록시는 세 가지 문제를 모두 해결합니다: 차단을 우회하고, 허용된 포트를 통해 트래픽을 터널링하며, 지리적으로 가까운 출구 노드를 통해 속도를 향상시킵니다. 이때 프록시는 특정 애플리케이션 수준에서 작동합니다 — Git, npm, 브라우저 등 — 기계의 나머지 트래픽에는 영향을 미치지 않습니다.

프록시 vs VPN: 코드 작업에 어떤 것을 선택해야 하는가

많은 개발자들이 습관적으로 VPN을 선택합니다. 이는 이해할 수 있습니다 — VPN은 설정이 간단하고 시스템 전체에 즉시 작동합니다. 그러나 GitHub과 npm 작업에는 프록시가 더 편리한 경우가 많습니다. 차이점을 살펴보겠습니다.

기준	프록시	VPN
트래픽 범위	특정 애플리케이션만 (Git, npm)	시스템 전체의 모든 트래픽
CI/CD에서의 설정	환경 변수로, 간단함	클라이언트 설치 필요, 복잡함
Docker에서의 작동	ENV를 통해 전달, 문제 없음	특권 모드 필요
속도	높음 (모든 트래픽 암호화 없음)	암호화로 인해 낮음
기업 네트워크와의 충돌	최소화됨	빈번함 (IT 부서에 의해 차단됨)
서버에서의 사용	env 변수를 통해 네이티브하게	데몬 설치 필요

결론은 간단합니다: 팀에 GitHub 및 npm에 대한 접근을 제공하는 것이 목표라면, 프록시는 구성 파일에서 한 번 설정하면 시스템의 각 기계의 설정에 개입하지 않고 작동합니다. 이는 특히 VPN을 물리적으로 설정하기 어려운 CI/CD 파이프라인에서 중요합니다.

GitHub 및 npm에 적합한 프록시 유형

모든 프록시가 Git 및 npm과 잘 작동하는 것은 아닙니다. 선택은 차단을 우회할지, 다운로드 속도를 높일지, 기업 네트워크에서 작업할지를 기준으로 합니다.

HTTP/HTTPS 프록시

가장 간단한 옵션입니다. Git과 npm은 표준 환경 변수를 통해 HTTP 프록시를 기본적으로 지원합니다. 대부분의 작업에 적합합니다: 리포지토리 클론, 패키지 설치, GitHub API 작업. 프록시 제공자가 HTTP 주소를 제공한다면 — 그것부터 시작하세요.

SOCKS5 프록시

더 유연한 프로토콜로, TCP 레벨에서 작동합니다. SSH 연결을 포함한 모든 유형의 트래픽을 지원합니다 (포트 22). Git을 HTTPS가 아닌 SSH를 통해 사용하는 경우 — SOCKS5가 더 바람직합니다. Git은 구성에서 socks5:// 매개변수를 통해 SOCKS5를 지원합니다.

레지던트 프록시

레지던트 프록시는 실제 가정 사용자의 IP 주소를 사용합니다. GitHub에서 특히 유용합니다, 차단이 심한 국가에서 작업할 경우: 이러한 IP는 블랙리스트에 거의 올라가지 않으며 일반 사용자 트래픽처럼 보입니다. 데이터 센터 IP가 이미 제공업체 수준에서 차단된 상황에 적합합니다.

데이터 센터 프록시

데이터 센터 프록시는 대부분의 개발자에게 최적의 선택입니다. 레지던트 프록시보다 빠르고, 비용이 저렴하며, 안정적인 연결을 제공합니다. GitHub이 단순히 느리지만 차단되지 않았다면 — 미국이나 유럽의 데이터 센터 프록시는 클론 및 패키지 다운로드 시 최대 속도 향상을 제공합니다.

프록시 유형	속도	차단 우회	가장 적합한 경우
데이터 센터 HTTP	⭐⭐⭐⭐⭐	중간	다운로드 속도 향상, npm install
데이터 센터 SOCKS5	⭐⭐⭐⭐⭐	중간	SSH를 통한 Git, 유연한 설정
레지던트	⭐⭐⭐	높음	강력한 차단 (이란, 중국)
모바일	⭐⭐⭐	매우 높음	최대 우회, 드문 경우

Git을 위한 프록시 설정: 단계별 안내

Git은 내장된 구성 및 환경 변수를 통해 프록시를 지원합니다. 두 가지 방법을 모두 보여드리니, 작업 흐름에 더 편리한 방법을 선택하세요.

방법 1: git config를 통한 설정 (추천)

이는 기계의 모든 Git 작업에 적용되는 영구적인 설정입니다. 터미널을 열고 다음을 실행하세요:

# HTTP/HTTPS 프록시용
git config --global http.proxy http://username:password@proxy-host:port
git config --global https.proxy http://username:password@proxy-host:port

# SOCKS5 프록시용
git config --global http.proxy socks5://username:password@proxy-host:port
git config --global https.proxy socks5://username:password@proxy-host:port

# 설정이 적용되었는지 확인
git config --global --list | grep proxy

username:password@proxy-host:port를 프록시의 데이터로 교체하세요. 인증이 필요 없는 프록시라면 — username:password@를 제거하세요.

방법 2: 환경 변수를 통한 설정

임시 사용이나 스크립트에서 편리합니다. Git은 표준 변수 HTTP_PROXY 및 HTTPS_PROXY를 자동으로 인식합니다:

# Linux / macOS — ~/.bashrc 또는 ~/.zshrc에 추가
export HTTP_PROXY="http://username:password@proxy-host:port"
export HTTPS_PROXY="http://username:password@proxy-host:port"
export NO_PROXY="localhost,127.0.0.1,::1"

# Windows (PowerShell)
$env:HTTP_PROXY="http://username:password@proxy-host:port"
$env:HTTPS_PROXY="http://username:password@proxy-host:port"

# 터미널을 재시작하지 않고 적용하기 (Linux/macOS)
source ~/.bashrc

GitHub에 대해서만 프록시 설정하기

모든 리포지토리가 아닌 GitHub에 대한 요청만 프록시를 통해 전달하고 싶다면, 섹션 설정을 사용하세요:

# github.com에 대해서만 프록시
git config --global http.https://github.com.proxy http://username:password@proxy-host:port

# 프록시를 통한 클론 확인
git clone https://github.com/username/repo.git

SOCKS5를 통한 SSH로 Git 사용하기

GitHub를 SSH를 통해 사용하는 경우 (HTTPS가 아닌), 설정이 약간 다릅니다. ~/.ssh/config 파일을 수정해야 합니다:

# ~/.ssh/config

Host github.com
    HostName github.com
    User git
    # Linux/macOS에서는 nc (netcat) 사용
    ProxyCommand nc -X 5 -x proxy-host:port %h %p
    
    # 또는 connect-proxy를 통해 (설치 필요)
    # ProxyCommand connect -S proxy-host:port %h %p
    
    # Windows에서는 Git Bash를 통해
    # ProxyCommand connect -S proxy-host:port %h %p

이후 git clone [email protected]:user/repo.git 및 git push 명령은 자동으로 SOCKS5 프록시를 통해 진행됩니다.

프록시 설정 초기화하기

# 전역 구성에서 프록시 제거
git config --global --unset http.proxy
git config --global --unset https.proxy

npm, yarn 및 pnpm을 위한 프록시 설정

각 패키지 관리자는 프록시 설정 방법이 다릅니다. npm, yarn 및 pnpm의 세 가지를 구체적인 명령과 함께 살펴보겠습니다.

npm

npm은 내장된 구성 설정을 통해 프록시를 지원합니다:

# npm을 위한 프록시 설정
npm config set proxy http://username:password@proxy-host:port
npm config set https-proxy http://username:password@proxy-host:port

# 설정 확인
npm config get proxy
npm config get https-proxy

# 테스트: 프록시를 통한 패키지 설치
npm install lodash

# 프록시 초기화
npm config delete proxy
npm config delete https-proxy

설정은 ~/.npmrc 파일에 저장됩니다. 직접 수정할 수도 있습니다:

# ~/.npmrc
proxy=http://username:password@proxy-host:port
https-proxy=http://username:password@proxy-host:port
strict-ssl=false

strict-ssl=false 매개변수

프록시가 SSL 트래픽을 가로채는 경우 (예: 기업 프록시), npm이 인증서에 대해 경고할 수 있습니다. strict-ssl=false는 검증을 비활성화합니다. 기업 네트워크에서만 사용하세요 — 공공 네트워크에서는 안전하지 않습니다.

Yarn (v1 Classic)

# Yarn Classic (v1)
yarn config set proxy http://username:password@proxy-host:port
yarn config set https-proxy http://username:password@proxy-host:port

# 설정 확인
yarn config get proxy

# 초기화
yarn config delete proxy
yarn config delete https-proxy

Yarn Berry (v2+)

# Yarn Berry는 환경 변수를 사용합니다
# 프로젝트 루트의 .yarnrc.yml에 추가:
httpProxy: "http://username:password@proxy-host:port"
httpsProxy: "http://username:password@proxy-host:port"

# 또는 환경 변수를 통해
export HTTP_PROXY="http://username:password@proxy-host:port"
export HTTPS_PROXY="http://username:password@proxy-host:port"

pnpm

# pnpm은 npm과 동일한 .npmrc를 사용합니다
# npm이 이미 설정된 경우 자동으로 적용됩니다

# 또는 pnpm config를 통해 명시적으로 설정
pnpm config set proxy http://username:password@proxy-host:port
pnpm config set https-proxy http://username:password@proxy-host:port

대안: npm 레지스트리 미러

npm 레지스트리가 느리지만 GitHub에 접근할 수 있는 경우 — 미러로 전환할 수 있습니다. 인기 있는 옵션: Taobao (중국용), Verdaccio (자체 호스팅). 그러나 미러는 종종 패키지 버전이 뒤쳐질 수 있으므로 프록시가 더 신뢰할 수 있습니다:

# 레지스트리를 미러로 전환 (속도를 위한 것, 차단을 위한 것은 아님)
npm config set registry https://registry.npmmirror.com

# 공식 레지스트리로 복원
npm config set registry https://registry.npmjs.org

CI/CD에서의 프록시: GitHub Actions, Docker, Jenkins

로컬 머신에서 프록시를 설정하는 것은 일의 절반입니다. 진짜 문제는 CI/CD 파이프라인에서 GitHub과 npm에 대한 접근을 제공해야 할 때 시작됩니다. 세 가지 가장 일반적인 시나리오를 살펴보겠습니다.

GitHub Actions

GitHub Actions에서는 workflow 파일의 환경 변수를 통해 프록시를 설정합니다. 리포지토리 설정에서 비밀을 추가한 후 (Settings → Secrets), workflow에서 이를 사용하세요:

# .github/workflows/build.yml
name: Build

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    
    env:
      HTTP_PROXY: ${{ secrets.PROXY_URL }}
      HTTPS_PROXY: ${{ secrets.PROXY_URL }}
      NO_PROXY: "localhost,127.0.0.1"
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Node.js 설정
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: npm 프록시 구성
        run: |
          npm config set proxy ${{ secrets.PROXY_URL }}
          npm config set https-proxy ${{ secrets.PROXY_URL }}
      
      - name: 종속성 설치
        run: npm ci

Docker

Docker에서는 두 가지 수준에서 프록시가 필요합니다: 이미지 빌드 시 (docker build) 및 컨테이너 내부. 이는 서로 다른 설정입니다:

# --build-arg를 통해 빌드 시 프록시 전달
docker build \
  --build-arg HTTP_PROXY=http://user:pass@proxy-host:port \
  --build-arg HTTPS_PROXY=http://user:pass@proxy-host:port \
  -t myapp .

# Dockerfile에서 프록시를 위해 ARG 사용
# Dockerfile
ARG HTTP_PROXY
ARG HTTPS_PROXY
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

RUN npm ci

# 종속성 설치 후 — 프록시 초기화 (이미지에 저장하지 않기!)
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

Docker 데몬에 대한 전역 프록시 설정 (예: docker pull):

# /etc/docker/daemon.json
{
  "proxies": {
    "http-proxy": "http://user:pass@proxy-host:port",
    "https-proxy": "http://user:pass@proxy-host:port",
    "no-proxy": "localhost,127.0.0.1"
  }
}

# 변경 후 Docker 재시작
sudo systemctl restart docker

Jenkins

Jenkins에서는 Jenkinsfile의 환경 변수를 통해 에이전트 수준에서 프록시를 설정하거나 시스템 설정에서 전역적으로 설정합니다:

// Jenkinsfile
pipeline {
    agent any
    
    environment {
        HTTP_PROXY  = credentials('proxy-url')
        HTTPS_PROXY = credentials('proxy-url')
        NO_PROXY    = 'localhost,127.0.0.1'
    }
    
    stages {
        stage('설치') {
            steps {
                sh 'npm config set proxy $HTTP_PROXY'
                sh 'npm config set https-proxy $HTTPS_PROXY'
                sh 'npm ci'
            }
        }
        stage('빌드') {
            steps {
                sh 'npm run build'
            }
        }
    }
}

자주 발생하는 오류 및 해결 방법

프록시가 올바르게 설정되었더라도 무언가 잘못될 수 있습니다. 가장 일반적인 오류와 해결 방법을 모았습니다.

오류: ECONNREFUSED 또는 Connection refused

프록시가 응답하지 않습니다. 원인: 잘못된 주소 또는 포트, 프록시 서버가 사용할 수 없음, 자격 증명이 만료됨.

해결 방법: 다음 명령어로 프록시의 접근 가능성을 확인하세요:

curl -v --proxy http://user:pass@proxy-host:port https://github.com

오류: SSL certificate problem / UNABLE_TO_VERIFY_LEAF_SIGNATURE

프록시가 SSL 트래픽을 가로채고 자신의 인증서를 삽입하는데, Git이나 npm이 이를 신뢰하지 않습니다.

Git에 대한 해결 방법:

git config --global http.sslVerify false
# 또는 프록시의 루트 인증서를 추가:
git config --global http.sslCAInfo /path/to/proxy-ca.crt

오류: npm ERR! code ENOTFOUND

npm이 레지스트리의 DNS 이름을 확인할 수 없습니다. 프록시는 설정되었지만 DNS 요청이 이를 통해 이루어지지 않습니다.

해결 방법: HTTP 프록시 대신 SOCKS5를 사용하세요 — DNS 요청을 터널링합니다:

npm config set proxy socks5://user:pass@proxy-host:port
npm config set https-proxy socks5://user:pass@proxy-host:port

오류: 407 Proxy Authentication Required

프록시가 인증을 요구하지만 자격 증명이 전달되지 않았거나 잘못 전달되었습니다.

# URL의 로그인 및 비밀번호가 올바르게 인코딩되었는지 확인
# 비밀번호에 특수 문자 (@, :, #)가 있는 경우 — 이를 인코딩하세요:
# @ → %40, : → %3A, # → %23

# 예: 비밀번호 "p@ss:word" → "p%40ss%3Aword"
npm config set proxy http://user:p%40ss%3Aword@proxy-host:port

Git clone은 작동하지만 git push는 작동하지 않음

Clone (읽기)과 push (쓰기)는 서로 다른 프로토콜을 사용할 수 있습니다. 프록시가 HTTP와 HTTPS 모두에 대해 설정되었는지 확인하세요. push를 위해 SSH를 사용하는 경우 — 위에서 설명한 대로 ~/.ssh/config에 별도의 설정이 필요합니다.

체크리스트: 모든 것이 작동하는지 확인하기

프록시 설정 후, 모든 것이 올바르게 작동하는지 확인하기 위해 이 체크리스트를 따라가세요.

✅ GitHub 및 npm을 위한 프록시 설정 체크리스트

프록시 접근 가능: curl -v --proxy PROXY_URL https://github.com가 200을 반환합니다
Git config 설정됨: git config --global --list | grep proxy가 프록시를 보여줍니다
클론 테스트: git clone https://github.com/torvalds/linux.git --depth=1가 작동합니다
npm 프록시 설정됨: npm config get proxy가 프록시를 보여줍니다
npm install 테스트: npm install lodash가 성공적으로 완료됩니다
SSH를 사용하는 경우: ssh -T [email protected]가 환영 메시지를 반환합니다
CI/CD: 환경 변수가 비밀에 추가되었으며, 파이프라인이 통과합니다
Docker: docker build가 --build-arg와 함께 네트워크 오류 없이 완료됩니다
속도: 클론이 프록시 없이보다 눈에 띄게 빨라집니다
프록시 자격 증명이 코드에 노출되지 않음 (비밀에만 저장됨)

한 줄로 빠른 진단

무언가 작동하지 않고 문제가 어디에 있는지 불확실한 경우 — 이 진단 스크립트를 실행하세요:

#!/bin/bash
# GitHub/npm을 위한 프록시 진단

PROXY="http://user:pass@proxy-host:port"

echo "=== 1. GitHub에 직접 접근 ==="
curl -s -o /dev/null -w "%{http_code}" https://github.com && echo " OK" || echo " FAIL"

echo "=== 2. 프록시를 통한 접근 ==="
curl -s -o /dev/null -w "%{http_code}" --proxy "$PROXY" https://github.com && echo " OK" || echo " FAIL"

echo "=== 3. npm 레지스트리에 대한 프록시 접근 ==="
curl -s -o /dev/null -w "%{http_code}" --proxy "$PROXY" https://registry.npmjs.org && echo " OK" || echo " FAIL"

echo "=== 4. 현재 Git 프록시 설정 ==="
git config --global --list | grep proxy || echo "Git 프록시가 설정되지 않음"

echo "=== 5. 현재 npm 프록시 설정 ==="
npm config get proxy
npm config get https-proxy

결론

GitHub 및 npm을 위한 프록시 설정은 올바른 절차를 알고 있다면 복잡한 작업이 아닙니다. 요약하겠습니다:

느린 GitHub을 가속화하기 위해 — 미국이나 유럽의 데이터 센터 프록시가 적합합니다: 빠르고, 안정적이며, 저렴합니다.
차단을 우회하기 위해 — 실제 사용자의 IP를 사용하는 레지던트 프록시가 최대의 신뢰성을 제공합니다.
HTTPS를 통한 Git을 위해 — git config에서 http.proxy를 설정하세요.
SSH를 통한 Git을 위해 — ~/.ssh/config에서 ProxyCommand를 사용하세요.
npm/yarn/pnpm을 위해 — config 또는 환경 변수를 통해 프록시를 설정하세요.
CI/CD를 위해 — 비밀을 통해 프록시 데이터를 전달하고, 코드에 하드코딩하지 마세요.

10~15분의 설정 시간을 투자하면, 인터넷 연결 상태나 차단 정책에 관계없이 GitHub 및 npm에 안정적으로 접근할 수 있습니다. 팀은 느린 다운로드를 기다리는 시간을 잃지 않으며, CI/CD 파이프라인은 네트워크 오류 없이 진행되고, 다양한 국가의 개발자들이 동일한 조건에서 작업할 수 있습니다.

제한된 접근이 있는 국가에서 GitHub 및 npm을 위한 안정적인 프록시를 찾고 있다면, 데이터 센터 프록시를 고려해 보세요 — 이들은 리포지토리 클론 및 종속성 설치 시 높은 속도와 안정성을 제공합니다. 강력한 차단이 있는 지역에서는 레지던트 프록시가 더 적합합니다 — 이들의 IP는 거의 차단되지 않습니다.

```

GitHub 및 npm용 프록시: GitHub이 차단되거나 느리게 작동하는 국가에서 리포지토리 및 패키지에 액세스하는 방법