개발자를 위한 v2rayN 터미널 프록시 설정과 Git·Docker 활용법

터미널 프록시는 v2rayN의 어떤 포트를 사용하나요?

v2rayN은 원격 노드와 직접 통신하는 프로그램이 아니라, 컴퓨터 안에 로컬 프록시 진입점을 열고 애플리케이션의 요청을 코어로 전달하는 관리자입니다. 일반적인 구성에서는 HTTP 프록시가 127.0.0.1:10809, SOCKS5 프록시가 127.0.0.1:10808에 열립니다. 하지만 이 값은 설치 버전, 기존 설정, 다른 프록시 프로그램과의 충돌 여부에 따라 달라질 수 있으므로 숫자를 무조건 복사하지 말고 v2rayN의 실제 설정과 로그를 먼저 확인해야 합니다.

브라우저처럼 운영체제의 시스템 프록시를 읽는 프로그램은 v2rayN에서 시스템 프록시를 켜는 것만으로 동작할 수 있습니다. 반면 Git, npm, Docker CLI, Python 패키지 도구와 같은 개발 도구는 자체 설정 또는 환경 변수를 우선할 수 있습니다. 따라서 화면에 “시스템 프록시 사용 중”이라고 표시되어도 터미널 명령이 반드시 같은 경로를 이용한다고 단정할 수 없습니다.

v2rayN에서 개발용 로컬 진입점을 준비하는 순서

이 글의 작업 기준은 Windows 데스크톱의 v2rayN 7.x와 Xray 코어입니다. 메뉴 이름은 세부 버전에 따라 “설정”, “매개변수 설정”, “환경 설정”처럼 조금 다를 수 있지만, 핵심은 HTTP와 SOCKS 진입점의 주소를 확인하는 것입니다. 개발 도구를 여러 개 사용할 때는 우선 HTTP 포트 하나를 공통으로 사용하고, SOCKS가 필요한 프로그램만 별도로 지정하면 상태를 추적하기 쉽습니다.

1. 노드 연결 확인

   v2rayN에서 사용할 노드를 선택하고 코어를 시작합니다. 브라우저로 HTTPS 사이트를 열어 원격 연결과 DNS가 정상인지 먼저 확인하세요.

2. 로컬 포트 확인

   메인 화면 또는 「설정」→「매개변수 설정」에서 HTTP 포트와 SOCKS 포트를 확인합니다. 예시는 HTTP 127.0.0.1:10809, SOCKS5 127.0.0.1:10808입니다.

3. 시스템 프록시 활성화

   v2rayN의 시스템 프록시 메뉴에서 활성화를 선택한 뒤 Windows의 「설정」→「네트워크 및 인터넷」→「프록시」에 같은 로컬 주소가 표시되는지 확인합니다.

4. 새 터미널 열기

   기존 PowerShell 또는 명령 프롬프트를 닫고 새 창을 엽니다. 이후 환경 변수와 Git 설정을 한 단계씩 적용하여 어떤 설정이 실제 요청을 처리하는지 기록합니다.

5. 도구별 테스트

   curl, Git, npm, Docker 순서로 테스트합니다. 한 도구가 실패했다고 모든 프록시 설정을 동시에 바꾸지 말고 실패한 계층만 수정하세요.

로컬 포트가 열려 있는지는 PowerShell에서 확인할 수 있습니다. 아래 명령에서 TcpTestSucceeded : True가 나오면 해당 주소에 연결을 받을 프로세스가 있다는 뜻입니다. 이것은 원격 노드 접속 성공을 의미하지는 않지만, 적어도 애플리케이션이 빈 포트로 요청하는 상황은 배제할 수 있습니다.

Test-NetConnection 127.0.0.1 -Port 10809
Test-NetConnection 127.0.0.1 -Port 10808

HTTP 프록시를 사용하는 간단한 테스트도 가능합니다. 응답이 나오면 터미널에서 v2rayN의 HTTP 진입점까지 요청이 도달한 것입니다. 인증서 오류나 원격 시간 초과가 발생하면 로컬 포트 자체보다 노드, TLS, DNS 또는 라우팅을 확인해야 합니다.

curl.exe -I -x http://127.0.0.1:10809 https://example.com

Git과 npm에 프록시를 적용하는 방법

터미널 도구 전체에 적용하려면 PowerShell 세션에서 환경 변수를 설정할 수 있습니다. HTTPS 요청도 보통 HTTP 프록시 주소를 통해 전달하므로 HTTP_PROXY와 HTTPS_PROXY를 모두 설정합니다. 일부 프로그램은 소문자 변수만 읽기도 하므로 호환성을 높이려면 대문자와 소문자를 함께 지정할 수 있습니다. 다만 회사 네트워크나 보안 도구가 별도 인증을 요구하는 환경에서는 주소와 포트만으로 충분하지 않을 수 있습니다.

$env:HTTP_PROXY="http://127.0.0.1:10809"
$env:HTTPS_PROXY="http://127.0.0.1:10809"
$env:http_proxy=$env:HTTP_PROXY
$env:https_proxy=$env:HTTPS_PROXY
$env:NO_PROXY="localhost,127.0.0.1,.local"

이 방식은 현재 PowerShell 창과 그 창에서 실행한 자식 프로세스에 적용됩니다. 터미널을 닫으면 사라지므로 임시 작업에 적합합니다. 영구 적용이 필요하다면 운영체제 환경 변수에 등록할 수 있지만, 프록시를 끈 뒤에도 값이 남아 네트워크 오류를 만들기 쉽습니다. 여러 장소에서 개발하거나 회사와 개인 네트워크를 오가는 경우에는 영구 등록보다 프로젝트별 스크립트 또는 세션 단위 설정이 안전합니다.

Git clone 및 fetch 점검

Git은 환경 변수 외에 자체 전역 설정을 가지고 있습니다. 먼저 현재 적용된 값을 확인하세요. 저장소별 설정이 전역 설정보다 우선할 수 있으므로 프로젝트 디렉터리 안에서 명령을 실행하는 것이 좋습니다.

git config --show-origin --get-regexp "http\..*proxy|https\..*proxy"
git config --global http.proxy http://127.0.0.1:10809
git config --global https.proxy http://127.0.0.1:10809
git ls-remote https://example.com/sample/project.git

실제 저장소 주소 대신 위 예시는 구조를 보여 주기 위한 형식입니다. 이미 오래된 프록시가 등록되어 있다면 새 값을 덮어쓰거나 삭제해야 합니다. 특히 한 번만 사용한 SOCKS 포트, 중지된 로컬 프로그램 주소, 잘못된 인증 정보가 Git 설정에 남아 있으면 환경 변수를 바꿔도 계속 같은 오류가 나타납니다.

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

npm install 및 레지스트리 점검

npm은 프록시 설정과 패키지 레지스트리 설정을 분리해서 관리합니다. npm config get proxy, npm config get https-proxy, npm config get registry로 현재 값을 확인하세요. 레지스트리가 사설 주소라면 외부 프록시를 적용해도 해당 주소가 프록시를 통해 접근 가능한지 별도로 검증해야 합니다.

npm config get proxy
npm config get https-proxy
npm config get registry
npm config set proxy http://127.0.0.1:10809
npm config set https-proxy http://127.0.0.1:10809
npm ping

npm install이 멈춘 것처럼 보일 때는 프록시뿐 아니라 DNS 지연, 특정 패키지의 postinstall 스크립트, 캐시 손상, 레지스트리 응답 지연도 원인일 수 있습니다. 먼저 npm ping으로 레지스트리 접근을 확인하고, 그 다음 작은 패키지 하나를 새 작업 디렉터리에서 설치해 범위를 좁히세요. 프록시를 끈 뒤에도 npm이 계속 대기한다면 네트워크 계층의 문제로 단정하지 말고 npm 로그와 패키지 스크립트 실행 여부를 함께 확인해야 합니다.

Docker pull은 CLI와 데몬을 나누어 설정하세요

Docker에서 가장 많이 발생하는 혼동은 터미널의 HTTP_PROXY가 Docker 이미지 다운로드 전체를 자동으로 해결한다고 생각하는 것입니다. Docker CLI는 명령을 Docker 데몬에 전달하고, 실제로 레지스트리에서 이미지를 가져오는 주체는 데몬입니다. 따라서 Docker Desktop을 사용하는 환경에서는 Desktop의 프록시 설정이 적용되는지 확인해야 하며, 별도 Docker Engine 서비스라면 데몬 서비스의 환경 설정에 프록시를 지정해야 합니다.

먼저 v2rayN의 HTTP 포트가 정상인지 확인한 다음 Docker가 사용하는 네트워크 경로를 분리해서 테스트하세요. Docker CLI에서 명령이 즉시 실패하는 경우에는 CLI와 데몬의 연결부터 확인하고, pull 중에 레지스트리 도메인 시간 초과가 발생하면 데몬 프록시 또는 DNS를 점검합니다. 컨테이너 안에서 실행되는 npm install은 호스트의 npm 설정을 자동으로 상속하지 않으므로, 빌드 인자나 컨테이너 환경 변수도 별도로 설계해야 합니다.

Docker Desktop의 설정 화면에 프록시 항목이 있다면 v2rayN의 HTTP 주소와 포트를 입력하고 저장한 뒤 Docker Desktop 또는 데몬을 재시작합니다. Linux에서 systemd로 Docker Engine을 실행한다면 서비스에 프록시 환경을 주입하는 방식이 사용되지만, 배포판과 설치 방식에 따라 파일 위치가 다를 수 있습니다. 변경 후에는 단순히 명령 프롬프트가 돌아오는지보다 실제 레지스트리에서 작은 이미지를 받아 로그가 정상적으로 끝나는지 확인해야 합니다.

docker info
docker pull hello-world

회사 내부 레지스트리나 로컬 개발 서버는 프록시를 거치지 않도록 NO_PROXY에 호스트명과 사설 대역을 넣는 것이 일반적입니다. 단, Docker 데몬과 컨테이너의 NO_PROXY는 서로 다른 환경일 수 있습니다. 내부 주소까지 원격 노드로 보내면 인증서 검증, 속도, 접근 제어가 모두 예상과 달라질 수 있으므로 사설 도메인과 127.0.0.1, localhost의 예외를 먼저 정리하세요.

IDE와 반복 오류를 단계별로 진단하기

IDE의 통합 터미널은 일반 PowerShell과 별도의 환경으로 시작될 수 있습니다. v2rayN을 켠 뒤 이미 열려 있던 IDE를 계속 사용하면 새 환경 변수가 전달되지 않을 수 있으므로, 환경 변수를 바꾼 뒤에는 IDE와 통합 터미널을 모두 다시 여는 편이 안전합니다. IDE 자체의 확장 기능이 별도 네트워크 라이브러리를 사용한다면 통합 터미널의 Git 설정과 IDE 확장의 프록시 설정이 서로 다를 수도 있습니다.

오류 원문은 추측보다 유용합니다. connection refused는 대개 로컬 포트에 수신 프로세스가 없거나 주소가 틀렸다는 의미이고, 407 Proxy Authentication Required는 프록시 인증을 요구하는 서버에 잘못된 방식으로 접근했다는 뜻입니다. Could not resolve host는 DNS 확인 경로를, i/o timeout은 원격 연결 지연이나 데몬 프록시 누락을 우선 의심할 수 있습니다. 같은 오류라도 명령이 호스트에서 실행됐는지 컨테이너 안에서 실행됐는지에 따라 수정 위치가 달라집니다.

업무를 마쳤다면 임시 프록시를 정리해야 합니다. 현재 PowerShell 세션에서만 설정했다면 다음처럼 환경 변수를 제거하고, Git과 npm에 저장한 전역 값도 필요에 따라 삭제합니다. Docker Desktop 또는 데몬에 프록시를 등록했다면 해당 설정을 원래 상태로 되돌리고 서비스를 재시작해야 합니다. 설정을 남겨 두면 v2rayN을 종료한 다음에도 Git clone이나 패키지 설치가 로컬의 닫힌 포트로 요청되어 실패할 수 있습니다.

Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:http_proxy, Env:https_proxy, Env:NO_PROXY
npm config delete proxy
npm config delete https-proxy
git config --global --unset http.proxy
git config --global --unset https.proxy