개발자를 위한 v2rayN TUN 모드 설정과 Git·Docker 프록시

개발 환경에서 브라우저만 연결되는 이유

브라우저에서 웹사이트가 정상적으로 열리는데 터미널의 패키지 설치나 Git 작업은 실패하는 상황은 매우 흔합니다. 브라우저는 운영체제의 시스템 프록시 설정을 따르는 경우가 많지만, 개발 도구는 각자 다른 네트워크 방식을 사용합니다. git은 별도의 프록시 옵션을 가질 수 있고, Python이나 Node.js 패키지 관리자는 환경 변수 또는 자체 설정을 읽습니다. Docker CLI는 호스트의 프록시와 Docker 데몬의 프록시를 서로 다르게 처리하며, IDE 안에서 실행되는 확장 기능도 IDE의 네트워크 설정을 따로 사용할 수 있습니다.

따라서 “v2rayN이 연결되어 있다”는 사실만으로 모든 개발 도구가 같은 경로를 사용한다고 볼 수 없습니다. 먼저 어떤 프로그램이 실패하는지, 그 프로그램이 호스트에서 직접 실행되는지 아니면 컨테이너나 백그라운드 서비스 안에서 실행되는지를 나눠야 합니다. 이 구분을 하지 않으면 노드를 계속 바꾸거나 클라이언트를 재설치하면서 실제 원인인 프록시 적용 범위를 놓치게 됩니다.

개발용 프록시를 구성할 때는 세 가지 목표를 분리하는 것이 좋습니다. 첫째, v2rayN 자체와 노드가 정상인지 확인합니다. 둘째, 호스트에서 실행되는 Git과 패키지 관리자가 프록시를 사용하는지 확인합니다. 셋째, Docker CLI와 이미지 빌드가 사용하는 네트워크 경로를 별도로 점검합니다. 단계마다 간단한 테스트를 통과시킨 뒤 다음 설정으로 넘어가야 문제가 생겼을 때 되돌아갈 기준이 남습니다.

TUN 모드를 켜기 전에 확인할 항목

TUN 모드는 가상 네트워크 인터페이스를 사용해 시스템 네트워크 계층에 가까운 위치에서 트래픽을 처리합니다. 시스템 프록시를 무시하는 프로그램을 커버하는 데 유용하지만, 일반적인 웹 프록시보다 권한과 라우팅에 영향을 더 크게 줍니다. 처음부터 TUN을 만능 스위치처럼 켜기보다는 시스템 프록시에서 해결되지 않는 개발 도구가 분명할 때 사용하는 편이 안전합니다.

먼저 v2rayN에서 현재 선택한 노드가 브라우저 연결 테스트를 통과하는지 확인하세요. 구독 갱신이 실패했거나 노드가 만료된 상태라면 TUN을 켜도 해결되지 않습니다. 다른 VPN, 네트워크 가속기, 보안 제품의 웹 보호 기능, 또 다른 프록시 클라이언트가 실행 중이면 일단 종료하세요. 여러 가상 어댑터와 필터 드라이버가 동시에 네트워크를 제어하면 DNS 오류, 연결 지연, 특정 사이트만 열리지 않는 현상이 나타날 수 있습니다.

Windows에서는 TUN 활성화 과정에서 관리자 권한이나 드라이버 설치 허용이 필요할 수 있습니다. 권한 요청이 나타나면 출처를 확인한 뒤 허용하고, 허용하지 못한 경우에는 TUN이 켜진 것처럼 보여도 실제 트래픽이 가상 인터페이스를 통과하지 않을 수 있습니다. macOS와 Linux에서도 시스템 권한, 네트워크 확장, 방화벽 정책이 영향을 줄 수 있으므로 운영체제의 보안 알림을 무조건 무시하지 마세요.

개발 작업 중에는 로컬 주소를 프록시로 보내지 않는 것이 보통 더 편리합니다. localhost, 127.0.0.1, 사내 저장소 주소, Docker 브리지 네트워크와 같은 내부 대상은 외부 프록시를 거치면 오히려 연결이 실패할 수 있습니다. TUN의 라우팅 규칙에서 로컬 및 사설 네트워크를 제외할 수 있다면, 외부 패키지 저장소와 내부 개발 서버를 분리하는 방향으로 설정하세요.

v2rayN에서 TUN 모드 설정하기

다음 순서는 설정을 한 번에 많이 바꾸지 않고, 각 단계의 결과를 확인하는 방식입니다. 메뉴 이름은 v2rayN 버전에 따라 조금 다를 수 있지만, 핵심은 TUN 활성화, DNS 처리, 라우팅 모드, 예외 대상의 순서입니다.

  1. v2rayN을 최신 버전으로 실행하고 사용할 노드를 먼저 선택합니다. 노드 목록에 나타난다고 연결이 보장되는 것은 아니므로 브라우저나 기본 연결 테스트로 통신 가능 여부를 확인합니다.
  2. 설정에서 TUN 관련 옵션을 찾아 가상 네트워크 인터페이스 사용을 활성화합니다. 관리자 권한 또는 네트워크 권한 요청이 나타나면 내용을 확인하고 승인합니다.
  3. 처음에는 복잡한 사용자 규칙보다 기본 라우팅을 사용합니다. 모든 트래픽을 무조건 프록시로 보내기보다, 로컬 주소와 사설 네트워크를 직접 연결하는 예외가 있는지 확인합니다.
  4. TUN을 켠 뒤 브라우저, 터미널, Git 순서로 테스트합니다. 브라우저만 확인하고 성공으로 판단하지 말고, 실제 개발에 사용할 외부 저장소와 패키지 도메인을 각각 확인하세요.
  5. 문제가 생기면 TUN을 끄고 시스템 프록시 상태로 돌아가 원인을 비교합니다. 두 모드에서 모두 실패하면 노드나 구독 문제일 가능성이 높고, TUN에서만 실패하면 권한·DNS·라우팅 충돌을 우선 의심합니다.

TUN을 켠 뒤에는 DNS 응답 방식도 살펴보세요. 도메인은 해석되지만 연결이 실패한다면 프록시 경로와 DNS 경로가 서로 어긋났을 수 있습니다. 반대로 모든 도메인이 느려졌다면 TUN 자체보다 과도한 규칙, 중복 DNS 필터, 다른 VPN의 잔여 설정을 확인하는 편이 좋습니다. 설정을 바꿀 때마다 한 가지 항목만 수정하고 같은 주소로 재시험하면 원인을 훨씬 빠르게 좁힐 수 있습니다.

Git·터미널·IDE에 프록시 적용하기

TUN 모드는 많은 프로그램을 자동으로 커버하지만, Git처럼 자체 프록시 설정을 가지고 있는 도구는 명시 설정이 더 안정적인 경우가 있습니다. Git 작업이 TUN을 거치지 않거나 사내 저장소처럼 직접 연결해야 하는 주소가 있다면 전역 설정보다 저장소별 설정을 먼저 고려하세요. 특정 프로젝트만 외부 저장소를 사용한다면 프로젝트 범위 설정이 다른 작업에 미치는 영향을 줄여 줍니다.

Git에서 프록시를 설정할 때는 프록시 주소와 포트를 v2rayN의 로컬 수신 설정과 정확히 맞춰야 합니다. HTTP 프록시와 SOCKS 프록시는 입력 위치가 다를 수 있으므로 형식을 혼동하지 마세요. 이미 잘못된 전역 프록시가 남아 있으면 TUN을 켜도 Git이 오래된 포트로 접속을 시도합니다. Git 설정에서 현재 적용된 값을 확인하고, 사용하지 않는 전역 프록시는 제거한 뒤 한 가지 방식만 유지하는 것이 좋습니다.

터미널에서 실행하는 패키지 관리자도 같은 원칙으로 점검합니다. npm, pip, cargo, go 같은 도구는 운영체제 환경 변수나 각 도구의 설정 파일을 읽을 수 있습니다. 환경 변수에 예전 프록시 포트가 남아 있으면 v2rayN의 현재 포트와 맞지 않아 연결이 거부됩니다. 새 터미널을 열어 변경된 환경 변수를 적용하고, 회사 내부 저장소처럼 프록시를 거치면 안 되는 도메인은 예외 목록으로 분리하세요.

IDE는 터미널과 별도의 네트워크 설정을 가질 수 있습니다. IDE 내장 터미널에서 성공해도 확장 기능의 다운로드가 실패하거나, 반대로 IDE는 되는데 외부 터미널이 실패할 수 있습니다. IDE 설정에서 HTTP 프록시 사용 여부를 확인하고, 자동 감지와 수동 입력을 동시에 활성화하지 마세요. 프록시를 수동으로 입력했다면 v2rayN을 변경할 때 포트가 함께 바뀌지 않았는지 확인해야 합니다.

Git 인증 실패와 프록시 연결 실패도 구분해야 합니다. 저장소 주소에 접근하지 못하는 경우에는 DNS, 시간 초과, 연결 거부 같은 네트워크 오류가 나타나지만, 저장소는 열리면서 로그인만 실패한다면 토큰, SSH 키, 계정 권한 문제일 수 있습니다. 네트워크 문제로 단정하기 전에 오류 메시지의 단계가 연결인지 인증인지 확인하세요.

Docker CLI와 이미지 빌드 프록시 설정

Docker는 개발자 프록시 설정에서 가장 많이 혼동되는 부분입니다. 호스트 터미널의 Docker CLI와 이미지를 빌드하는 Docker 데몬은 서로 다른 프로세스일 수 있습니다. 호스트에서 docker pull이 성공하더라도 데몬이 외부 레지스트리에 접근하지 못하면 이미지 빌드가 실패합니다. 반대로 데몬은 이미지를 가져오지만 Dockerfile 안의 패키지 설치가 실패할 수도 있습니다. 어느 단계에서 인터넷이 필요한지 먼저 분리해야 합니다.

공개 레지스트리에서 기본 이미지를 가져오는 단계가 실패한다면 Docker 데몬에 프록시를 지정해야 할 수 있습니다. Docker Desktop을 사용한다면 애플리케이션의 프록시 설정을 확인하고, 별도 Linux 데몬이나 원격 Docker 호스트를 사용한다면 그 호스트의 서비스 환경에 프록시를 설정해야 합니다. 로컬 Windows의 v2rayN만 설정하고 원격 서버의 Docker 데몬까지 자동으로 바뀐다고 생각하면 안 됩니다.

Dockerfile의 RUN 단계에서 패키지 다운로드가 실패하는 경우에는 빌드 프로세스가 프록시 환경 변수를 전달받는지 확인합니다. HTTP와 HTTPS 프록시, 프록시 제외 목록이 필요한 경우가 많으며, 이미지 안에 인증 토큰이나 비밀번호를 평문으로 남기지 않도록 주의해야 합니다. 테스트용 환경 변수는 빌드가 끝난 뒤 이미지 레이어에 남을 수 있으므로 민감한 값은 별도의 안전한 빌드 비밀 관리 방법을 사용하세요.

컨테이너 안에서 localhost는 호스트를 의미하지 않는다는 점도 중요합니다. 컨테이너의 localhost는 컨테이너 자신이므로, 호스트에서 실행 중인 v2rayN의 로컬 프록시 포트에 그대로 연결되지 않을 수 있습니다. Docker Desktop에서는 호스트 접근용 주소를 사용해야 할 수 있고, Linux에서는 네트워크 모드나 호스트 게이트웨이 설정을 검토해야 합니다. 플랫폼마다 지원 방식이 다르므로, 사용 중인 Docker 환경의 공식 네트워크 동작을 확인하고 주소를 추측하지 마세요.

이미지 빌드는 성공하지만 실행 중인 컨테이너의 API 호출이 실패한다면 빌드 프록시와 런타임 프록시를 별도로 봐야 합니다. 빌드 시 전달한 환경 변수는 컨테이너 실행 시 자동으로 유지되지 않을 수 있습니다. 애플리케이션이 실제로 외부 API를 호출하는 시점에 필요한 프록시 변수를 실행 설정에 넣고, 내부 서비스 주소는 NO_PROXY 예외에 추가하는 방식이 일반적입니다.

문제가 생겼을 때의 점검 순서

개발 환경에서 실패 원인을 찾을 때는 가장 작은 단위부터 확인하세요. 먼저 v2rayN의 노드와 브라우저 연결을 확인하고, 다음으로 호스트 터미널에서 외부 도메인을 확인합니다. 그다음 Git 또는 패키지 관리자 하나를 선택해 테스트하고, 마지막으로 Docker 데몬과 컨테이너 내부를 점검합니다. 각 단계가 통과하지 않았는데 다음 단계의 복잡한 설정으로 넘어가면 문제가 겹쳐서 원인을 찾기 어려워집니다.

  • 브라우저와 터미널 모두 실패하면 노드, 구독, TUN 권한, DNS를 먼저 확인합니다.
  • 브라우저는 되지만 터미널만 실패하면 환경 변수와 도구별 프록시 설정을 확인합니다.
  • Git만 실패하면 오래된 전역 프록시, 인증 정보, 저장소 주소 형식을 구분합니다.
  • Docker pull만 실패하면 Docker 데몬 또는 Docker Desktop의 프록시를 확인합니다.
  • Dockerfile의 패키지 설치만 실패하면 빌드 단계에 프록시가 전달되는지 확인합니다.
  • 컨테이너 실행 후 외부 통신만 실패하면 런타임 변수, DNS, 컨테이너의 호스트 접근 경로를 점검합니다.

오류 로그에서 timeout, connection refused, DNS 이름 해석 실패, 인증 오류를 구별하면 점검 범위가 크게 줄어듭니다. 시간 초과는 경로 또는 방화벽, 연결 거부는 잘못된 포트나 프록시 미실행, DNS 오류는 이름 해석 경로, 인증 오류는 계정과 토큰 쪽을 먼저 확인하는 식입니다. 모든 오류를 “TUN이 불안정하다”로 묶지 않는 것이 핵심입니다.

자주 묻는 질문

TUN을 켜면 Git과 Docker를 따로 설정할 필요가 없나요? 많은 트래픽은 자동으로 처리되지만 항상 그렇지는 않습니다. Git의 전역 프록시, Docker 데몬의 네트워크, 컨테이너 내부의 실행 환경은 별도로 동작할 수 있습니다. TUN을 기본 경로로 사용하더라도 각 도구가 실제로 어떤 프로세스와 네트워크를 사용하는지 확인해야 합니다.

시스템 프록시와 TUN을 동시에 사용해도 되나요? v2rayN의 기능으로 함께 사용되는 경우가 있지만, 다른 프록시 클라이언트나 VPN까지 겹치면 충돌 가능성이 커집니다. 먼저 하나의 기준 모드로 연결을 확인한 뒤 필요한 범위에서만 추가하세요. 문제가 생기면 동시에 켜진 네트워크 도구를 줄이고 전후 상태를 비교하세요.

Docker 컨테이너에서 호스트의 v2rayN 포트에 연결할 수 없어요. 컨테이너의 localhost와 호스트의 localhost는 다릅니다. Docker Desktop과 Linux 환경의 호스트 접근 주소가 다를 수 있으므로, 사용 중인 플랫폼의 게이트웨이 주소와 네트워크 모드를 확인하세요. 또한 v2rayN의 로컬 수신기가 컨테이너가 접근할 수 있는 인터페이스에서 대기하는지도 점검해야 합니다.

프록시를 설정했는데 패키지 설치가 계속 실패합니다. 현재 터미널에 환경 변수가 적용됐는지, 프록시 포트가 v2rayN의 실제 수신 포트와 같은지, 패키지 저장소 도메인이 DNS에서 해석되는지 확인하세요. Docker 빌드라면 호스트 터미널의 설정이 아니라 빌드 프로세스와 Docker 데몬에 전달되는 설정을 따로 확인해야 합니다.

개발용 프록시는 TUN 하나로 모든 문제를 해결하는 기능이 아니라, 호스트·도구·데몬·컨테이너의 네트워크 경로를 일관되게 정리하는 작업입니다. v2rayN과 노드가 정상인지 먼저 확인하고, 시스템 프록시에서 시작한 뒤 필요한 프로그램에만 TUN과 개별 설정을 추가하세요. 이 순서를 지키면 Git clone, 패키지 설치, Docker 이미지 빌드가 실패했을 때 어디에서 경로가 끊겼는지 훨씬 빠르게 찾아낼 수 있습니다.