GitHub 저장소를 복제할 때는 괜찮은데 Docker 이미지를 받거나 npm·pip 패키지를 설치할 때 유독 느리다면, 단순히 VPN 회선을 바꾸는 것만으로 해결되지 않을 수 있습니다. 터미널, Docker 데몬, 패키지 관리자, CI 실행 환경은 서로 다른 네트워크 설정을 사용할 수 있기 때문입니다. 어디에서 요청이 나가고 어떤 프록시 설정을 따르는지부터 확인해야 원인을 좁힐 수 있습니다.
이 글에서는 GitHub 연결, 컨테이너 이미지, 패키지 다운로드, CI 작업을 차례로 점검하는 방법을 설명합니다. 특정 미러나 DNS를 무조건 설정하기보다, 실제 환경에서 병목이 생기는 단계만 조정하고 변경 전 설정을 되돌릴 방법을 남겨 두는 것이 중요합니다. VPN 클라이언트의 분할 터널링을 사용할 때도 개발 도구만 우회하거나 포함하도록 규칙을 신중히 확인하세요.
4단계
요청 경로 점검
3개
주요 설정 영역
1개씩
변경 후 검증
먼저 느린 구간과 요청 경로를 구분하기
“개발 다운로드가 느리다”는 증상만으로는 원인을 특정할 수 없습니다. GitHub 웹페이지는 열리지만 저장소 복제만 느릴 수 있고, 패키지 메타데이터는 금방 받아도 실제 파일 전송이 오래 걸릴 수 있습니다. Docker에서는 레지스트리 인증, 이미지 매니페스트 조회, 레이어 다운로드가 각각 다른 단계입니다. 먼저 같은 작업을 VPN 연결 상태와 미연결 상태에서 각각 확인하고, 실패 여부와 어느 단계에서 멈추는지를 기록하세요. 네트워크 정책이나 서비스 이용 조건을 확인하지 않은 채 제한을 우회하는 방식으로 문제를 해결하려 해서는 안 됩니다.
다음 순서로 범위를 줄일 수 있습니다.
- 브라우저에서 해당 서비스의 웹페이지가 열리는지 확인합니다. 웹페이지가 열려도 Git, 레지스트리, 패키지 다운로드가 정상이라는 뜻은 아닙니다.
- 터미널에서 DNS 조회와 기본 연결을 살펴봅니다. 이름 해석은 되는데 TLS 연결이 실패한다면 DNS보다 프록시, 인증서 또는 경로 문제일 수 있습니다.
- 작은 저장소나 의존성 하나로 재현해 봅니다. 여러 도구를 한꺼번에 변경하면 어느 설정이 영향을 주었는지 알기 어렵습니다.
- VPN 클라이언트에서 현재 적용된 모드와 분할 터널링 규칙을 확인합니다. 규칙이 프로세스 이름 기준인지 도메인 기준인지도 살펴보세요.
개발 환경에서는 프록시 설정이 여러 겹으로 존재할 수 있습니다. 운영체제나 VPN 클라이언트의 시스템 프록시, 셸의 환경 변수, Git 설정, Docker 데몬 설정, npm·pip 설정을 구분해야 합니다. 한 프로그램에서 설정한 프록시가 다른 프로그램에도 자동 적용된다고 가정하지 마세요.
GitHub 복제와 Git 연결 점검하기
GitHub 저장소에 접근하는 방식은 주로 HTTPS와 SSH입니다. HTTPS 주소로 복제하는데 브라우저만 열리는 경우에는 터미널의 프록시 환경 변수나 Git 전역 설정이 영향을 주는지 확인하세요. 아래 예시는 로컬 프록시가 실제로 실행 중이고, 사용 중인 클라이언트가 해당 주소와 포트를 제공한 경우에만 적용할 수 있습니다. 포트 번호를 임의로 복사하지 말고 VPN 또는 프록시 클라이언트의 설정 화면에서 확인해야 합니다.
git config --global http.proxy http://127.0.0.1:PORT
git config --global https.proxy http://127.0.0.1:PORT
# 설정 확인
git config --global --get http.proxy
git config --global --get https.proxy
# 필요할 때 전역 설정 제거
git config --global --unset http.proxy
git config --global --unset https.proxy이 설정은 Git의 전역 구성에 저장되므로 다른 저장소에도 영향을 줄 수 있습니다. 업무용과 개인용 환경이 다르다면 저장소별 설정이나 일시적인 셸 환경 변수를 고려하고, 공유 컴퓨터에서는 인증 정보를 포함한 프록시 주소를 설정 파일에 남기지 마세요. 비밀번호나 토큰이 들어간 주소는 셸 기록, 설정 파일, 로그에 노출될 수 있습니다.
SSH 방식은 HTTPS 프록시 설정을 그대로 따르지 않을 수 있습니다. SSH 복제만 실패한다면 저장소 주소 형식, SSH 키와 에이전트, 네트워크에서 해당 연결이 허용되는지부터 점검하세요. HTTPS로 바꾸어 비교하는 것은 진단에 도움이 될 수 있지만, 조직의 저장소 정책과 인증 방식을 먼저 따라야 합니다. 프록시 설정을 바꾼 뒤에는 같은 저장소에서 복제 또는 fetch를 다시 실행하고, 실패 메시지가 DNS, 인증, 연결 시간 초과 중 무엇을 가리키는지 확인합니다.
Docker, npm, pip 설정을 각각 확인하기
Docker CLI가 명령을 보내는 경로와 이미지를 실제로 내려받는 Docker 데몬의 경로는 다를 수 있습니다. 따라서 셸에서 프록시 환경 변수를 설정했는데도 이미지 pull이 변하지 않는 경우가 있습니다. Docker Desktop을 사용한다면 앱의 프록시 설정을 확인하고, Linux에서 별도의 데몬을 운영한다면 데몬이 실행되는 환경에 적용된 프록시 구성을 점검하세요. 변경 후에는 데몬이나 앱을 재시작해야 설정이 반영되는 경우가 있습니다. 운영 중인 개발 환경에서는 재시작 영향을 먼저 확인해야 합니다.
컨테이너 빌드도 별도로 살펴봐야 합니다. 호스트에서 이미지를 받을 때와 빌드 중 컨테이너 안에서 패키지를 받을 때는 네트워크 경로와 프록시 전달 방식이 다를 수 있습니다. 빌드 단계에 프록시 변수를 전달해야 한다면 인증 정보가 이미지 레이어나 빌드 로그에 저장되지 않도록 안전한 비밀값 전달 기능을 사용하세요. 공개 가능한 예제 설정과 실제 자격 증명을 분리하고, 이미 생성된 이미지에 비밀값이 들어가지 않았는지 확인합니다.
npm과 pip은 각자 별도의 구성과 환경 변수를 참조할 수 있습니다. 먼저 현재 설정을 확인한 뒤 필요한 경우에만 프록시를 지정하세요. 프록시를 거치지 않도록 설정하거나 다른 주소로 변경할 때도 기존 설정을 기록해 두면 원상 복구가 쉽습니다.
# npm 설정 확인 및 필요할 때 설정
npm config get proxy
npm config get https-proxy
npm config set proxy http://127.0.0.1:PORT
npm config set https-proxy http://127.0.0.1:PORT
# pip에서 일회성으로 프록시 사용
python -m pip install --proxy http://127.0.0.1:PORT PACKAGE_NAME예시는 구성 형태를 보여 주기 위한 것이며, 실제 프록시 주소와 패키지 이름을 뜻하지 않습니다. HTTPS 대상에 HTTP 프록시를 지정하는 방식은 프록시 구현과 클라이언트 지원에 따라 달라질 수 있습니다. 연결 오류가 생기면 주소 체계와 인증 방식이 클라이언트 요구사항에 맞는지 확인하세요. 설치가 끝나면 임시 프록시 옵션을 제거하거나 명시적으로 관리되는 환경 설정으로 옮겨, 다른 네트워크에서 오래된 주소를 계속 사용하지 않도록 합니다.
- ✅ Docker 이미지 pull만 느리면 Docker 데몬 또는 Desktop의 프록시 설정을 확인합니다.
- ✅ 컨테이너 빌드 중에만 느리면 빌드 단계의 DNS와 프록시 전달 여부를 따로 점검합니다.
- ✅ npm과 pip은 현재 설정을 먼저 읽고 필요한 도구에만 변경을 적용합니다.
- ❌ 토큰이나 비밀번호가 포함된 프록시 문자열을 공개 저장소, Docker 이미지, 로그에 남기지 않습니다.
DNS와 분할 터널링을 안전하게 조정하기
DNS는 서비스 이름을 IP 주소로 찾는 단계입니다. DNS 조회가 실패하면 연결이 시작되기 전부터 문제가 발생할 수 있지만, 조회가 성공했다고 다운로드 경로까지 정상이라는 보장은 없습니다. 반대로 VPN을 켠 뒤 DNS를 임의의 공개 서버로 고정하면 내부 도메인 해석이 깨지거나, VPN이 의도한 DNS 보호와 충돌할 수 있습니다. 먼저 운영체제와 VPN 클라이언트가 현재 어떤 DNS를 사용하도록 설정했는지 확인하고, 조직에서 제공한 내부 도메인이 있다면 그 설정을 우선해야 합니다.
분할 터널링은 일부 앱이나 도메인의 트래픽만 VPN을 통과시키거나 VPN 밖으로 보내는 기능입니다. Git, Docker, 터미널 전체를 한 번에 제외하면 개발 도구가 사용하는 하위 프로세스나 다른 서비스 요청까지 예상과 다르게 처리될 수 있습니다. 반대로 브라우저만 VPN에 포함했는데 터미널은 포함되지 않았다면, 같은 서비스도 브라우저와 Git에서 서로 다른 결과를 보일 수 있습니다. 규칙을 추가한 다음 실제 요청이 어느 경로로 나가는지 클라이언트의 연결 정보와 테스트 결과로 확인하세요.
도메인 기반 규칙은 CDN이나 지역별 서버를 사용하는 서비스에서 복잡해질 수 있습니다. 한 도메인만 예외 처리해도 실제 파일을 전달하는 별도 도메인이 남아 있을 수 있고, IP 주소를 고정 등록하면 서비스 측 주소 변경 후 규칙이 낡을 수 있습니다. 필요한 도메인을 공식 문서나 관리자 안내에서 확인하고, 광범위한 와일드카드 규칙은 피하세요. DNS를 바꾼 뒤에는 캐시와 기존 연결이 결과에 영향을 줄 수 있으므로 새 터미널 세션이나 새 다운로드 작업으로 재검증하는 편이 좋습니다.
CI 환경과 예산에 맞는 운영 방식
로컬 컴퓨터에서 다운로드가 빠르더라도 CI 작업은 같은 결과를 내지 않을 수 있습니다. 호스팅 러너와 자체 관리 러너는 위치, DNS, 방화벽, 프록시 환경 변수, 캐시 설정이 서로 다릅니다. 먼저 실패한 작업의 로그에서 Git 복제, 이미지 pull, 의존성 설치 중 어느 단계가 오래 걸리는지 확인하세요. 로그에 접근 토큰, 프록시 인증 정보 또는 사설 저장소 주소가 노출되지 않도록 출력 내용을 점검해야 합니다.
반복되는 패키지 설치에는 프로젝트가 지원하는 잠금 파일과 캐시 기능을 우선 활용할 수 있습니다. 캐시는 다운로드 지연을 줄일 수 있지만 오래된 의존성이나 플랫폼이 다른 파일을 잘못 재사용하지 않도록 키와 무효화 조건을 관리해야 합니다. Docker 빌드에서는 레이어 캐시와 의존성 복사 순서를 검토하고, 변경이 잦은 파일 때문에 모든 단계가 매번 무효화되지 않도록 구성합니다. 캐시를 사용해도 보안 업데이트와 재현 가능한 빌드를 희생해서는 안 됩니다.
비용을 정할 때는 가장 높은 속도만 좇기보다 개발 작업이 실제로 막히는 빈도와 시간을 고려하세요. 가끔 저장소를 복제하는 개인 프로젝트라면 현재 네트워크와 클라이언트 설정을 먼저 바로잡는 편이 합리적일 수 있습니다. 매일 이미지와 의존성을 받는 팀이라면 자체 캐시나 미러를 운영할 가치가 있는지 검토하되, 접근 제어와 업데이트 책임도 함께 계산해야 합니다. VPN이나 프록시를 선택할 때는 필요한 플랫폼 지원, 개발 도구와의 호환성, 문제 발생 시 설정을 진단할 수 있는지 확인하고, 사용하지 않는 서비스를 중복 결제하지 않도록 현재 구성을 정리하세요.
- 느린 작업과 재현 조건을 기록하고, 로컬과 CI 중 어느 쪽에서만 발생하는지 구분합니다.
- DNS, VPN 경로, 프록시 설정, 캐시 순으로 확인하되 매 단계에서 한 항목씩 변경합니다.
- 변경 전 설정을 보관하고, 동일한 저장소·이미지·의존성 작업으로 개선 여부와 부작용을 함께 확인합니다.
- 인증 정보가 로그와 이미지에 남지 않는지 확인하고, 불필요한 임시 설정은 제거합니다.