Git clone이 오래 걸리거나 Docker pull이 중간에 멈추고 npm install이 끝나지 않는 문제는 단순히 인터넷 회선이 느려서만 발생하지 않습니다. 저장소 호스트, 컨테이너 레지스트리, 패키지 저장소, DNS 조회, 프록시 적용 범위와 인증서 검증이 서로 다른 경로를 사용하기 때문입니다. 따라서 모든 문제를 하나의 클라이언트 설정으로 해결하려고 하기보다 작업별로 요청이 어디에서 출발하고 어느 프로세스가 프록시를 읽는지 확인해야 합니다.

이 글에서는 Windows, macOS, Linux 개발 환경을 기준으로 GitHub, Docker, npm, pip, API와 CI 작업에 프록시를 적용하는 순서를 설명합니다. 핵심은 전역 프록시를 무작정 켜는 것이 아니라 필요한 도메인과 프로그램에만 규칙을 적용하고, 인증 정보는 환경 변수나 CI 시크릿으로 분리하는 것입니다. 사용 중인 클라이언트가 구독 링크 가져오기를 지원한다면 먼저 클라이언트와 노드를 준비한 뒤, 실제 개발 도구에는 별도의 프록시 설정을 연결해야 합니다.

느린 작업을 먼저 분류하는 방법

GitHub 작업은 크게 HTTPS 기반 Git 요청, SSH 연결, 웹 API 호출로 나뉩니다. git clone이 HTTPS 주소를 사용하면 Git의 HTTP 프록시 설정이 영향을 주지만, [email protected]:... 형식의 SSH 주소는 일반적인 HTTP 프록시 설정만으로 해결되지 않습니다. SSH는 별도의 프록시 명령, 터널 또는 HTTPS 전환이 필요합니다. 저장소를 내려받은 뒤 릴리스 파일이나 API를 호출하는 과정은 다시 다른 프로그램의 설정을 사용합니다.

Docker도 두 영역을 나누어야 합니다. 터미널에서 실행하는 Docker CLI와 실제 이미지 레이어를 다운로드하는 Docker 데몬은 같은 프로세스가 아닐 수 있습니다. 데스크톱용 Docker는 내부 엔진을 별도로 실행하며, Linux에서는 systemd 서비스가 데몬을 관리하는 경우가 많습니다. CLI에 환경 변수를 넣었는데도 docker pull이 실패한다면 데몬이 프록시 설정을 읽지 못하고 있을 가능성이 있습니다.

npm과 pip는 현재 셸의 환경 변수, 사용자 설정 파일, 프로젝트 설정, 인증서 저장소의 영향을 받을 수 있습니다. 특히 셸에서 curl은 성공하지만 npm만 멈춘다면 네트워크 전체의 문제가 아니라 npm의 프록시 URL, 레지스트리 주소, 인증서 또는 캐시 문제일 수 있습니다. CI에서는 로컬 터미널의 설정이 자동으로 복사되지 않으므로 러너 이미지와 작업 단계별 환경 변수도 함께 살펴봐야 합니다.

100+

지원 국가

220+

지원 회선

不限

동시 접속 기기

5

지원 플랫폼

VPNRZ는 Windows, macOS, iOS, Android, Linux 환경을 지원합니다. 다만 지원 플랫폼은 클라이언트를 설치할 수 있다는 의미이며, Git, Docker 데몬과 CI 서비스의 프록시 설정까지 자동으로 끝난다는 의미는 아닙니다. 개발 도구에서는 연결 상태, 라우팅 모드, DNS, 프로세스별 프록시를 따로 확인해야 합니다.

핵심 결론: 브라우저의 성공 여부를 개발 도구의 성공으로 간주하지 말고, Git HTTP, SSH, Docker 데몬, 패키지 매니저와 CI 러너를 각각 독립적인 네트워크 대상으로 점검하세요.

GitHub clone과 API에 프록시 적용하기

먼저 저장소 주소가 HTTPS인지 SSH인지 확인합니다. 다음 명령으로 현재 원격 주소를 볼 수 있습니다.

git remote -v

HTTPS 저장소라면 Git 전용 프록시를 설정할 수 있습니다. 아래 예시의 주소와 포트는 실제로 사용 중인 로컬 프록시 포트로 바꾸어야 합니다.

git config --global http.proxy http://127.0.0.1:PORT
git config --global https.proxy http://127.0.0.1:PORT

이 설정은 Git의 HTTP와 HTTPS 요청에 적용됩니다. SOCKS5 프록시를 사용하는 경우에는 클라이언트와 Git 버전이 해당 형식을 올바르게 지원하는지 확인해야 합니다. 형식이 맞지 않으면 연결이 즉시 실패하거나, 인증 단계에서 멈출 수 있습니다. 설정을 확인할 때는 다음 명령을 사용합니다.

git config --global --get http.proxy
git config --global --get https.proxy

회사 내부 저장소나 로컬 Git 서버처럼 프록시를 거치면 안 되는 대상이 있다면 예외를 지정할 수 있습니다. 예외 규칙은 환경에 따라 다르므로 내부 도메인과 주소 범위를 확인한 뒤 적용해야 합니다.

git config --global http.noProxy localhost,127.0.0.1,.internal.example

SSH 저장소는 별도로 처리해야 합니다. SSH 키 인증은 HTTPS 프록시 설정을 읽지 않습니다. 가장 단순한 방법은 GitHub 저장소 주소를 HTTPS 방식으로 바꾸고 Git의 HTTPS 프록시를 사용하는 것입니다. SSH를 유지해야 한다면 OpenSSH의 ProxyCommand 또는 별도 터널 도구를 사용해야 하며, 조직의 보안 정책과 클라이언트 지원 여부를 먼저 확인하세요. 무작정 SSH 포트를 HTTP 프록시 포트에 입력하는 것은 올바른 설정이 아닙니다.

GitHub API를 호출하는 스크립트는 Git 설정을 자동으로 사용하지 않을 수 있습니다. Python, Node.js, Go 또는 직접 사용하는 HTTP 라이브러리마다 프록시 환경 변수 지원 방식이 다릅니다. 테스트할 때는 API 토큰을 명령줄에 직접 적지 말고 환경 변수나 비밀 저장소에서 주입하세요. 응답이 느린 경우에는 DNS 조회, TLS 핸드셰이크, API 인증, 응답 본문 다운로드를 나누어 어느 단계에서 지연되는지 확인하면 원인을 좁히기 쉽습니다.

  • ✅ git remote -v로 HTTPS와 SSH 중 어떤 방식을 쓰는지 먼저 확인하세요.
  • ✅ HTTPS 저장소에는 Git 전용 HTTP 및 HTTPS 프록시를 적용하세요.
  • ✅ SSH 저장소는 HTTPS 설정으로 해결된다고 가정하지 말고 별도 경로를 점검하세요.
  • ✅ API 토큰은 셸 기록, 저장소 파일과 로그에 남지 않도록 시크릿으로 관리하세요.
  • ❌ 연결이 느리다는 이유만으로 TLS 검증을 끄거나 인증서 오류를 무시하지 마세요.

Docker pull 실패를 CLI와 데몬으로 나누어 해결하기

docker pull은 명령을 입력하는 CLI보다 Docker 데몬의 네트워크 경로가 더 중요할 수 있습니다. CLI가 정상적으로 실행되어도 데몬이 레지스트리에 접근하지 못하면 이미지 매니페스트나 레이어 다운로드에서 오류가 발생합니다. 먼저 Docker의 현재 상태와 사용 중인 컨텍스트를 확인하세요.

docker context show
docker info

Docker Desktop을 사용한다면 애플리케이션의 프록시 설정에서 HTTP 또는 HTTPS 프록시를 지정하는 방식이 일반적입니다. 설정을 바꾼 뒤에는 내부 엔진이 새 설정을 읽도록 Docker Desktop을 재시작해야 할 수 있습니다. Linux에서 systemd가 Docker 데몬을 관리한다면 서비스 설정의 프록시 환경 변수를 별도로 구성하고 데몬을 다시 로드해야 합니다. 배포 환경마다 설정 파일 위치와 권한이 다르므로 운영체제 문서와 조직의 관리 정책을 함께 확인하세요.

레지스트리 주소가 특정 프록시를 거쳐야 하는지, 사설 레지스트리는 직접 연결해야 하는지도 구분해야 합니다. 모든 주소를 프록시로 보내면 사내 레지스트리나 로컬 미러에 불필요한 우회가 생길 수 있습니다. 반대로 레지스트리만 직접 연결하도록 예외를 두었는데 DNS가 외부 주소를 반환하면 예상과 다른 경로가 선택될 수 있습니다.

Docker 오류 메시지는 원인을 구분하는 단서가 됩니다. 이름을 해석하지 못한다면 DNS 또는 네트워크 예외를, 인증 실패라면 레지스트리 자격 증명을, TLS 오류라면 인증서 체인과 시스템 시간을, 타임아웃이라면 데몬의 프록시와 방화벽을 먼저 확인하세요. 이미지 레이어 일부만 반복해서 실패한다면 전체 연결을 계속 바꾸기보다 레지스트리 응답, 디스크 공간, 데몬 로그를 함께 살펴보는 편이 효율적입니다.

docker login REGISTRY_HOST
docker pull IMAGE_NAME:TAG

공용 이미지와 내부 이미지를 같은 방식으로 취급하지 않는 것도 중요합니다. 내부 레지스트리의 인증서가 조직의 사설 인증 기관에서 발급되었다면 해당 CA를 Docker가 신뢰하도록 정식으로 설치해야 합니다. 검증을 끄는 옵션은 문제를 숨길 뿐이며, 이미지 공급망을 확인해야 하는 개발 및 배포 환경에는 적합하지 않습니다.

Docker 점검 순서 먼저 Docker 데몬이 실행 중인지 확인하고, 다음으로 데몬이 사용하는 DNS와 프록시를 점검하세요. 그 후 레지스트리 로그인, 이미지 이름과 태그, 인증서 체인을 확인합니다. CLI에만 프록시 변수를 설정하고 데몬 설정을 생략하는 것이 가장 흔한 실수입니다.

npm과 pip의 레지스트리, 프록시와 인증서 확인하기

npm은 레지스트리 주소와 프록시 설정을 따로 가집니다. 현재 설정을 확인할 때는 민감한 인증 토큰이 출력되지 않도록 주의하세요.

npm config get registry
npm config get proxy
npm config get https-proxy

일반적인 공개 패키지 설치가 느리다면 레지스트리 주소가 올바른지, 프록시 URL에 불필요한 공백이나 잘못된 인증 정보가 들어 있지 않은지 확인합니다. 프로젝트에 .npmrc가 포함되어 있으면 사용자 전역 설정을 덮어쓸 수 있습니다. 저장소에 커밋된 설정 파일 안에 토큰이 들어 있는지도 반드시 확인해야 합니다. 조직 내부 패키지와 공개 패키지를 함께 사용한다면 스코프별 레지스트리 규칙을 명시해 의도하지 않은 서버로 인증 정보가 전송되지 않도록 하세요.

npm 설치가 멈춘 것처럼 보일 때는 네트워크 외에도 lockfile 충돌, 설치 스크립트, 네이티브 모듈 빌드, 캐시 손상과 권한 문제가 원인일 수 있습니다. 먼저 상세 로그를 확인하고, 같은 명령을 다른 프로젝트에서 반복하여 프로젝트 자체의 문제인지 분리합니다. 캐시를 무조건 삭제하기보다 오류 메시지와 캐시 상태를 확인한 뒤 필요한 범위에서만 정리하는 것이 좋습니다.

pip도 인덱스 주소, 프록시, 인증서와 신뢰할 수 있는 호스트 설정이 서로 영향을 줍니다. 다음과 같이 현재 Python 환경에서 사용하는 실행 파일과 pip를 확인하면 다른 가상 환경을 잘못 수정하는 일을 줄일 수 있습니다.

python -m pip --version
python -m pip config list

pip에 프록시를 적용할 때는 일회성 명령줄 옵션보다 운영체제의 안전한 환경 변수, 사용자 설정 파일 또는 CI 시크릿을 선택하는 편이 관리하기 쉽습니다. 사설 패키지 인덱스를 사용한다면 인증서 검증을 끄는 대신 올바른 CA 번들을 설치하세요. --trusted-host를 문제 해결의 만능 옵션처럼 사용하면 중간자 공격을 방어하는 검증 절차가 약해질 수 있습니다.

작업 먼저 확인할 설정 자주 놓치는 부분
Git HTTPS Git proxy와 원격 주소 SSH 주소에는 HTTP proxy가 자동 적용되지 않음
Docker pull Docker 데몬의 proxy CLI 환경 변수만 바꾸고 데몬을 재시작하지 않음
npm install registry와 https-proxy 프로젝트의 .npmrc가 전역 설정을 덮어씀
pip install index URL과 CA 설정 다른 가상 환경의 pip를 수정함

안전한 테스트 절차와 분할 라우팅 적용하기

설정을 한 번에 모두 바꾸지 말고, 작은 테스트를 순서대로 진행하세요. 아래 절차는 개발용 컴퓨터에서 프록시와 라우팅이 실제로 적용되는지 확인하는 기본 흐름입니다.

  1. VPN 클라이언트에서 구독을 업데이트하고, 현재 노드와 연결 상태를 확인합니다. 구독 가져오기 성공만으로 Git이나 Docker가 정상이라고 판단하지 않습니다.
  2. 터미널에서 DNS 조회와 HTTPS 요청을 각각 테스트합니다. 두 테스트 중 하나만 실패하면 DNS와 프록시를 같은 문제로 취급하지 말고 분리해서 확인합니다.
  3. Git 테스트용으로 작은 공개 저장소의 메타데이터를 조회하거나 현재 저장소의 원격 연결을 확인합니다. HTTPS와 SSH를 번갈아 사용하지 말고 한 가지 방식의 결과를 먼저 기록합니다.
  4. Docker에서는 데몬 상태를 확인한 뒤 필요한 레지스트리의 로그인과 작은 이미지의 매니페스트 요청을 테스트합니다. 실패하면 Docker Desktop 또는 systemd 데몬 로그를 확인합니다.
  5. npm과 pip는 새 가상 환경이나 별도 임시 디렉터리에서 패키지 인덱스와 프록시 설정을 확인한 뒤 설치를 시도합니다.
  6. 정상 동작을 확인한 다음에만 프로젝트 전체 설치, 대용량 이미지 다운로드와 CI 작업으로 범위를 넓힙니다.

분할 라우팅은 개발 환경에서 특히 유용합니다. GitHub, 패키지 인덱스, 컨테이너 레지스트리와 관련 API만 프록시로 보내고, 로컬호스트, 사내 도메인, 사설 Git 서버와 내부 데이터베이스는 직접 연결하도록 규칙을 나눌 수 있습니다. 다만 도메인 목록이 바뀌거나 CDN이 여러 주소를 사용하면 규칙이 완전하지 않을 수 있으므로 실제 로그와 DNS 결과를 함께 확인해야 합니다.

  • ✅ 개발 도구별로 성공한 명령, 사용한 주소와 설정 위치를 기록하세요.
  • ✅ 공개 저장소와 사내 저장소의 라우팅 정책을 분리하세요.
  • ✅ Docker 데몬, CI 러너처럼 백그라운드에서 실행되는 프로세스를 따로 점검하세요.
  • ✅ 프록시 인증 정보는 셸 기록과 저장소 파일에 남기지 마세요.
  • ❌ 모든 트래픽을 무조건 프록시로 보내고 내부 서비스 예외를 생략하지 마세요.
  • ❌ 인증서 오류를 없애기 위해 TLS 검증을 끄지 마세요.

CI 환경에서 속도와 보안을 함께 지키는 방법

CI에서 로컬과 같은 결과를 얻으려면 러너가 어떤 네트워크에 있고, 어떤 사용자가 Docker 데몬과 패키지 매니저를 실행하는지 확인해야 합니다. 셸 단계에 HTTP_PROXY와 HTTPS_PROXY를 넣는 것만으로는 Docker 서비스 컨테이너나 별도의 데몬에 전달되지 않을 수 있습니다. 러너 이미지, 서비스 컨테이너, Docker-in-Docker 구성은 각각 환경 변수를 상속하는 방식이 다릅니다.

프록시 URL에 사용자 이름이나 비밀번호를 직접 넣으면 CI 로그, 프로세스 목록, 오류 메시지에 노출될 수 있습니다. 비밀 값은 CI 플랫폼의 시크릿 기능으로 저장하고, 로그 마스킹을 활성화하며, 작업이 끝난 뒤 환경 파일이나 임시 설정을 남기지 않도록 하세요. 토큰과 구독 링크는 일반 변수나 공개 빌드 출력에 넣지 않는 것이 안전합니다.

캐시는 속도 개선에 도움이 될 수 있지만 오래된 패키지나 이미지 레이어를 무조건 신뢰해서는 안 됩니다. lockfile, 이미지 다이제스트, 패키지 무결성 검사와 서명 정책을 함께 유지하세요. 캐시를 사용해 설치 시간이 짧아져도 외부 저장소에 대한 인증과 TLS 검증을 생략해서는 안 됩니다. 실패한 작업을 자동으로 여러 번 재시도하는 설정도 원인을 숨길 수 있으므로 재시도 횟수와 타임아웃을 합리적으로 관리해야 합니다.

개발 도구의 프록시를 구성할 때는 Shadowsocks, VMess, Trojan, Hysteria2, WireGuard 같은 연결 방식의 이름과 Git이나 npm이 직접 읽는 HTTP 프록시 설정을 혼동하지 않아야 합니다. VPN 클라이언트가 시스템 전체 터널을 제공할 수는 있지만, 애플리케이션이 자체 DNS나 자체 프록시를 사용하면 결과가 달라질 수 있습니다. 따라서 연결 방식은 클라이언트에서 확인하고, 애플리케이션 프록시는 해당 프로그램의 문서에 맞게 별도로 설정하세요.

최종 판단: 가장 안정적인 구성은 필요한 개발 트래픽만 명확한 규칙으로 전달하고, Git·Docker·npm·pip·CI가 각자의 프록시와 인증서 설정을 올바르게 읽도록 만드는 것입니다. 속도만 보고 검증을 끄기보다 경로, DNS, 인증과 로그를 함께 관리해야 장기적으로 안전한 개발 환경을 유지할 수 있습니다.