개발 환경에서 GitHub clone이 느리거나 Docker 이미지가 오랫동안 대기하고, npm install이 특정 패키지에서 멈추는 현상은 단순히 인터넷 요금제의 속도 문제만으로 설명되지 않습니다. 개발 도구가 연결하는 목적지가 서로 다르고, DNS 조회·TLS 연결·리디렉션·인증·대용량 레이어 다운로드가 각각 다른 경로를 사용하기 때문입니다. 브라우저에서 웹 페이지가 잘 열린다고 해서 Git 클라이언트, Docker 데몬, npm이 같은 방식으로 동작하는 것도 아닙니다.
이 글에서는 VPN 또는 호환 프록시 클라이언트를 개발 작업에 적용할 때 확인해야 할 원리와 실전 설정 순서를 정리합니다. Windows, macOS, Linux 공식 클라이언트뿐 아니라 Clash Verge, sing-box 계열 클라이언트에서도 적용할 수 있도록 시스템 프록시와 앱별 환경 변수의 차이, DNS 처리, 분할 라우팅, 인증서 문제, CI/CD 환경의 주의점까지 함께 살펴보겠습니다.
개발 도구의 속도를 좌우하는 네트워크 요소
GitHub의 저장소를 복제할 때는 먼저 도메인 조회가 이루어지고, 이후 TLS 연결과 인증, 객체 전송이 이어집니다. 저장소의 파일이 많거나 커밋 기록이 크다면 작은 요청이 여러 번 발생할 수 있습니다. 이때 DNS는 로컬 통신사 경로로 처리되고 실제 데이터만 프록시를 통과하면, 도메인 해석 결과와 데이터 경로가 서로 어긋나 연결이 불안정해질 수 있습니다.
Docker Hub에서 이미지를 받을 때는 문제가 더 복합적입니다. 레지스트리 주소에서 매니페스트를 읽은 뒤 여러 레이어를 병렬 또는 순차적으로 내려받고, 인증 서비스와 저장소 주소를 추가로 호출합니다. 브라우저에서 Docker Hub 페이지가 열려도 Docker CLI가 사용하는 레지스트리 API와 인증 엔드포인트가 규칙에서 빠져 있으면 이미지 다운로드는 계속 대기할 수 있습니다.
npm install 역시 npm 레지스트리, 패키지의 tarball 주소, Git 저장소 의존성, 사설 레지스트리 등 여러 출처에 접속할 수 있습니다. 기본 레지스트리를 바꾸는 것만으로 모든 패키지가 해결되지 않는 이유입니다. lockfile에 기록된 실제 URL과 현재 npm 설정을 함께 확인해야 하며, 조직 내부 패키지는 공용 프록시로 보내지 않도록 분리하는 편이 안전합니다.
90+
국가 커버리지
200+
회선 수
5
지원 플랫폼
무제한
동시 연결 기기
| 작업 | 주요 연결 대상 | 확인할 경로 | 자주 놓치는 부분 |
|---|---|---|---|
| Git clone | 코드 호스팅 도메인, 인증 서비스 | Git 프록시 설정, SSH 또는 HTTPS | 브라우저 프록시만 설정하고 Git은 직접 연결하는 경우 |
| Docker pull | 이미지 레지스트리, 인증 엔드포인트 | Docker 데몬의 프록시 환경 | 터미널의 환경 변수와 데몬 설정이 서로 다름 |
| npm install | npm 레지스트리, 패키지 tarball | npm proxy, registry, 인증 설정 | lockfile의 다른 호스트를 규칙에서 제외함 |
| CI/CD | 빌드 러너, 저장소, 레지스트리 | 실행 환경의 비밀 변수와 네트워크 정책 | 개발 PC의 VPN 설정을 러너가 자동으로 상속한다고 생각함 |
클라이언트와 프로토콜을 개발 환경에 맞게 선택하기
개발용 접속에서는 가장 유명한 클라이언트보다 현재 사용하는 운영체제와 구독 형식이 더 중요합니다. Windows와 macOS에서는 공식 클라이언트로 로그인한 뒤 구독을 가져오는 방식이 가장 단순합니다. Linux에서는 공식 클라이언트가 제공되는지 먼저 확인하고, 필요하다면 sing-box 기반 구성이나 시스템 서비스 방식으로 전환합니다. Clash Verge는 규칙 기반 분할 라우팅을 시각적으로 관리하기 좋지만, 구독 설정이 사용하는 필드와 코어가 실제로 지원하는지 확인해야 합니다.
Shadowsocks는 비교적 단순한 암호화 프록시 방식으로 여러 클라이언트에서 널리 지원됩니다. VMess와 Trojan은 전송 계층과 인증 구성을 함께 확인해야 하며, 단순히 노드 이름만 보고 호환 여부를 판단해서는 안 됩니다. Hysteria2는 UDP 기반 전송 특성을 활용하지만 네트워크 환경과 클라이언트 지원 여부에 따라 결과가 달라질 수 있습니다. WireGuard는 운영체제의 네트워크 인터페이스에 가까운 방식이므로 일반적인 HTTP 프록시 환경과 설정 방법이 다릅니다.
개발 도구만 선택적으로 연결하려면 규칙 기반 프록시가 유용합니다. GitHub, Docker Hub, npm 관련 도메인은 프록시로 보내고 사내 Git 서버, 로컬 패키지 저장소, LAN 주소는 직접 연결하도록 구성할 수 있습니다. 반대로 규칙이 충분히 검증되지 않은 상태에서 복잡한 분할 설정을 적용하면 인증 서버만 다른 경로로 빠지는 문제가 생길 수 있으므로, 처음에는 전체 연결로 기본 동작을 확인한 뒤 필요한 예외를 추가하는 순서가 좋습니다.
- ✅ 먼저 공식 클라이언트 또는 호환 클라이언트가 구독 형식을 정상적으로 읽는지 확인합니다.
- ✅ 브라우저 프록시와 시스템 터널 모드의 적용 범위를 구분합니다.
- ✅ Git, Docker, npm이 서로 다른 프로세스와 환경 변수를 사용한다는 점을 기억합니다.
- ❌ 여러 프록시 클라이언트를 동시에 실행해 가상 어댑터와 DNS 설정을 충돌시키지 않습니다.
- ❌ 프로토콜 이름만 보고 모든 앱과 UDP 트래픽이 자동으로 처리된다고 가정하지 않습니다.
GitHub·Docker·npm을 직접 점검하는 설정 순서
실제 설정은 한 번에 모든 도구를 바꾸기보다 단계별로 진행해야 합니다. 먼저 VPN 클라이언트에서 하나의 노선을 선택하고 연결 상태를 확인합니다. 그 다음 DNS가 정상적으로 응답하는지, 브라우저가 아닌 터미널에서도 대상 도메인에 접근할 수 있는지 확인합니다. 명령어가 실패했을 때는 속도보다 오류 메시지와 어느 단계에서 멈추는지를 기록하는 것이 중요합니다.
- 기본 연결 확인: 클라이언트에서 선택한 노선의 지역과 프로토콜을 확인하고 시스템 터널 또는 규칙 모드를 활성화합니다. 사내 주소와 로컬 개발 서버가 있다면 직접 연결 규칙이 유지되는지도 확인합니다.
- Git 경로 확인: HTTPS 저장소를 사용하는 경우 Git이 시스템 프록시를 따르는지 확인합니다. 별도 프록시를 지정했다면 전역 설정과 저장소별 설정이 중복되지 않았는지 살펴봅니다. SSH를 사용하는 경우 브라우저 프록시 설정만으로는 충분하지 않을 수 있으므로 SSH의 연결 방식과 프록시 명령 지원 여부를 별도로 확인해야 합니다.
- Docker 경로 확인: 터미널에서 설정한
HTTP_PROXY,HTTPS_PROXY,NO_PROXY가 Docker 데몬에 자동 전달되는지 확인합니다. Docker Desktop은 앱 내부의 네트워크 설정이 별도로 존재할 수 있고, Linux의 systemd 서비스는 서비스 환경 파일을 별도로 읽을 수 있습니다. - npm 경로 확인: 현재 레지스트리와 프록시 설정을 확인하고, 사설 레지스트리 인증 정보가 공용 설정에 노출되지 않도록 분리합니다. 패키지 설치가 특정 모듈에서 멈추면 해당 모듈이 실제로 어느 호스트에서 내려오는지 lockfile과 설치 로그에서 확인합니다.
- 규칙 모드 전환: 전체 연결에서 세 작업이 모두 정상 동작한 뒤 도메인과 프로세스 단위의 분할 규칙을 적용합니다. 각 규칙을 추가할 때 Git clone, Docker pull, npm install을 다시 실행해 어느 항목이 영향을 받았는지 기록합니다.
# Git 프록시 설정 상태 확인
git config --global --get http.proxy
git config --global --get https.proxy
# npm의 현재 레지스트리와 프록시 확인
npm config get registry
npm config get proxy
npm config get https-proxy
# Docker 환경 변수 확인
printenv | grep -i proxyDocker와 npm에서 자주 발생하는 실패 원인
Docker pull이 멈출 때는 먼저 이미지 이름이 정확한지, 레지스트리 인증이 필요한지, 그리고 데몬이 프록시를 통해 외부로 나가는지 확인합니다. Docker CLI가 정상적으로 실행되어도 실제 다운로드를 담당하는 것은 데몬이므로, CLI 셸의 프록시만 수정해서는 문제가 해결되지 않을 수 있습니다. Docker Desktop을 사용하는 경우 앱의 프록시 설정과 운영체제의 시스템 프록시가 서로 다른 정책을 가질 수 있습니다.
또한 NO_PROXY에 로컬 주소와 사내 레지스트리를 넣지 않으면 내부 통신까지 외부 프록시로 전송될 수 있습니다. 반대로 외부 레지스트리 도메인을 예외 목록에 잘못 넣으면 다운로드가 직접 연결로 빠집니다. 예외 목록은 짧게 유지하고, 도메인 전체를 무조건 우회하기보다 실제로 직접 연결해야 하는 내부 주소만 지정하는 편이 관리하기 쉽습니다.
npm install이 중단되는 경우에는 레지스트리 주소, 인증 토큰, 프록시 인증, TLS 검사 장비를 차례로 확인합니다. 사내 네트워크가 자체 인증서를 사용한다면 인증서 체인을 무시하는 방식으로 해결하기보다 운영체제 또는 Node.js가 신뢰할 수 있는 인증서를 올바르게 등록해야 합니다. 보안 검증을 끄는 설정은 일시적인 진단 외에는 사용하지 않는 것이 좋습니다.
패키지 관리자의 캐시는 문제를 숨길 수도 있습니다. 동일한 패키지가 캐시에 남아 있으면 네트워크가 끊겨도 설치되는 것처럼 보이고, 새로운 의존성에서만 실패할 수 있습니다. 따라서 정상 설치와 실패 설치의 로그를 비교하고, 오류가 DNS 조회인지 TLS 협상인지 HTTP 인증인지 다운로드 중단인지 구분해야 합니다.
| 증상 | 우선 확인할 곳 | 설정 방향 |
|---|---|---|
| Git clone 인증 전 멈춤 | Git의 HTTPS 또는 SSH 경로 | Git 전용 프록시와 시스템 터널 적용 여부 확인 |
| Docker가 매니페스트를 읽지 못함 | 데몬의 프록시와 인증 서비스 | Docker Desktop 또는 서비스 환경을 별도로 설정 |
| npm이 특정 tarball에서 대기 | lockfile의 실제 다운로드 호스트 | 해당 호스트의 DNS·TLS·프록시 규칙 확인 |
| 사내 저장소만 접속 불가 | NO_PROXY와 직접 연결 규칙 | 내부 도메인과 LAN 주소를 예외 처리 |
CI/CD와 보안까지 고려한 운영 방법
개발 PC에서 VPN을 켜고 성공했다고 해서 CI/CD 러너에서도 같은 결과가 보장되지는 않습니다. 러너는 별도의 네트워크, DNS, 컨테이너 런타임, 비밀 변수 저장소를 사용합니다. 빌드가 외부 저장소를 필요로 한다면 러너가 사용할 수 있는 프록시 주소와 인증 방식을 운영 정책에 맞게 제공해야 하며, 개인 계정의 구독 링크나 비밀번호를 로그에 출력하지 않도록 주의해야 합니다.
컨테이너 빌드에서는 빌드 단계의 환경 변수와 실행 단계의 환경 변수를 구분해야 합니다. 패키지 설치에만 필요한 프록시 인증 정보가 최종 이미지 레이어에 남으면 보안 문제가 됩니다. 가능한 경우 빌드 시크릿 기능, 사내 미러, 아티팩트 저장소를 사용하고, 빌드 로그에는 토큰과 전체 구독 URL이 노출되지 않도록 마스킹합니다.
개발 장비에서는 무조건 전체 트래픽을 프록시로 보내기보다 업무 목적에 맞는 분할 정책을 사용하는 것이 편리할 수 있습니다. 그러나 DNS 누출, 잘못된 예외 규칙, 로컬 서비스 접근 실패를 함께 점검해야 합니다. 회사 정책이나 프로젝트의 보안 요구사항이 있다면 개인 VPN 설정을 임의로 적용하기 전에 관리자의 지침을 따라야 합니다.
VPN TX는 Windows, macOS, iOS, Android, Linux를 지원하며, 구독 링크를 호환 클라이언트에 가져와 사용할 수 있습니다. 공식 클라이언트가 적합하지 않은 환경에서는 Clash Verge 또는 sing-box 계열 클라이언트의 지원 범위와 설정 문법을 먼저 확인하세요. 자세한 기본 연결 순서는 사용 가이드에서 확인할 수 있습니다.
- ✅ 개발용 구독 링크와 인증 정보를 공개 저장소, Dockerfile, CI 로그에 직접 기록하지 않습니다.
- ✅ Git, Docker 데몬, npm, CI 러너를 각각 독립적으로 점검합니다.
- ✅ 사내 도메인과 로컬 주소는 직접 연결 정책을 별도로 검증합니다.
- ✅ 문제가 해결된 뒤에도 노선 변경과 네트워크 전환 후 재현 여부를 확인합니다.
- ❌ TLS 인증서 검증을 영구적으로 끄거나 모든 주소를 무조건 예외 처리하지 않습니다.
문제 재발을 막는 최종 점검표
설정을 마친 뒤에는 브라우저 접속 여부만 확인하지 말고 실제 개발 작업을 기준으로 검증해야 합니다. 새 저장소를 복제하고, 의존성을 새로 설치하고, 필요한 Docker 이미지를 내려받는 과정을 각각 실행합니다. 한 작업만 성공하고 다른 작업이 실패한다면 VPN 자체보다 해당 프로그램의 프록시 범위나 인증 구성이 원인일 가능성이 큽니다.
노선을 바꿀 때는 같은 명령을 반복하기보다 먼저 DNS 캐시, 기존 연결, Docker 데몬 상태, IDE의 내장 터미널 환경을 확인합니다. 특히 IDE가 별도 프록시 설정을 가지고 있으면 시스템 클라이언트와 다른 경로를 사용할 수 있습니다. Linux 서비스는 셸과 독립적으로 실행될 수 있고, macOS와 Windows의 GUI 앱도 로그인 시점의 환경 변수를 그대로 반영하지 않을 수 있습니다.
마지막으로 정상 상태의 설정을 안전한 장소에 기록하되 비밀번호, 토큰, 개인 구독 링크는 제외합니다. 기록할 항목은 사용한 클라이언트, 연결 모드, 직접 연결 예외, Git·Docker·npm의 프록시 적용 범위, 실패 시 확인할 로그 위치입니다. 이렇게 정리하면 다음 네트워크 변경이나 새 장비 설정에서 무작정 모든 값을 바꾸지 않고 원인을 빠르게 좁힐 수 있습니다.