개발 도구마다 프록시를 따로 넣는 방식의 한계

브라우저에서는 웹사이트가 잘 열리는데 Git clone, npm install, Docker pull만 실패한다면 먼저 애플리케이션별 프록시 설정을 의심하게 됩니다. 실제로 HTTP_PROXY와 HTTPS_PROXY 환경 변수를 넣고, Git에는 git config --global http.proxy를 지정하고, Docker 데몬에는 별도의 프록시 파일을 만드는 식으로 문제를 해결할 수 있습니다. 하지만 도구가 늘어날수록 설정 위치와 문법도 함께 늘어나며, 어느 프로세스가 어떤 프록시를 사용하는지 추적하기가 어려워집니다.

개발 환경에서는 하나의 명령이 단일 서버만 호출하지 않습니다. GitHub 저장소를 복제할 때는 저장소 도메인, 릴리스 파일을 제공하는 CDN, 서브모듈 주소가 차례로 등장할 수 있습니다. npm이나 pnpm은 레지스트리에서 메타데이터를 받은 뒤 다른 tarball 호스트로 이동하고, Docker는 레지스트리 인증 서버와 이미지 레이어 저장소를 별도로 요청합니다. 브라우저에만 시스템 프록시가 적용된 상태라면 이 통신들은 DIRECT로 빠지거나, 서로 다른 출구를 사용해 인증과 다운로드가 엇갈릴 수 있습니다.

전제: 이 글은 회사·학교 네트워크 정책과 서비스 이용 약관을 준수하는 환경에서, 개발 도구의 연결 경로를 일관되게 관리하는 방법을 설명합니다. 구독 URL과 인증 토큰은 로그나 설정 파일에 노출하지 말고, 허용된 네트워크에서만 사용하세요.

TUN 모드가 터미널 프록시에 적합한 이유

일반적인 시스템 프록시는 운영체제와 브라우저가 이해하는 프록시 설정을 전달하는 방식입니다. 반면 TUN 모드는 가상 네트워크 인터페이스를 만들고, 운영체제가 발생시키는 IP 트래픽을 Clash 또는 Mihomo의 네트워크 스택으로 넘깁니다. 따라서 애플리케이션이 프록시 환경 변수를 읽지 않거나 자체 네트워크 라이브러리를 사용하더라도, 해당 연결을 규칙 엔진에서 확인할 가능성이 높아집니다. 터미널, IDE 확장, Docker CLI, WSL2 프로세스처럼 시스템 프록시를 자주 무시하는 프로그램에서 특히 유용합니다.

다만 TUN은 모든 문제를 자동으로 해결하는 만능 스위치는 아닙니다. DNS가 로컬에서 먼저 해석되면 Clash가 도메인을 기준으로 규칙을 적용하기 전에 잘못된 주소가 선택될 수 있고, 가상 인터페이스와 기존 VPN이 동시에 동작하면 라우팅 루프가 발생할 수 있습니다. 또한 Docker 데몬이 별도 가상 머신 안에서 실행되는 환경에서는 호스트의 TUN 경로와 데몬 내부의 네트워크 경로가 다를 수 있습니다. 그러므로 TUN을 켠 뒤에는 연결 로그, DNS 모드, 라우팅 테이블을 함께 확인해야 합니다.

개발 트래픽을 세 가지 층으로 나누기

  • 소스 코드 계층: github.com, GitLab, Bitbucket, 서브모듈 저장소처럼 코드와 릴리스를 가져오는 요청입니다.
  • 패키지 계층: registry.npmjs.org, PyPI, RubyGems, crates.io 및 각 생태계의 CDN 요청입니다.
  • 컨테이너 계층: Docker Hub나 사설 레지스트리의 인증 엔드포인트, 매니페스트, 이미지 레이어 다운로드입니다.

이 세 층을 하나의 광범위한 규칙으로 묶으면 처음에는 편해 보이지만, 필요하지 않은 업무 트래픽까지 같은 노드로 보내게 됩니다. 반대로 지나치게 잘게 쪼개면 누락된 호스트 하나 때문에 명령 전체가 멈춥니다. 실전에서는 업무별 프록시 그룹을 만들고, 로그를 통해 실제로 관찰된 도메인만 조금씩 보강하는 접근이 안정적입니다.

Clash 설정 전에 점검할 항목

먼저 사용 중인 클라이언트가 Mihomo 또는 TUN을 지원하는지 확인합니다. Clash Verge Rev, Mihomo Party, Clash for Android의 일부 최신 빌드는 메뉴 이름이 다르지만 대체로 프로필, DNS, TUN, 로그를 각각 관리할 수 있습니다. 기존 Clash for Windows 프로필을 그대로 가져올 때는 구형 문법이나 폐기된 옵션이 남아 있지 않은지 살펴보세요. 설정 파일이 정상적으로 로드되더라도 커널 버전에 따라 일부 필드가 무시될 수 있습니다.

다음으로 혼합 포트와 컨트롤러 포트를 확인합니다. 터미널에서 직접 프록시를 사용해야 하는 경우에는 보통 로컬 HTTP 혼합 포트가 필요하지만, TUN을 중심으로 운용한다면 애플리케이션별 프록시 환경 변수는 보조 수단이 됩니다. 이미 다른 VPN이나 프록시 프로그램이 실행 중이면 같은 포트를 선점하거나 기본 경로를 덮어쓸 수 있으므로 한 번에 하나의 네트워크 가상화 도구만 활성화하는 것이 좋습니다.

작업 전 기록: 현재 성공하는 브라우저 요청과 실패하는 터미널 명령을 각각 한 번씩 실행하고, Clash 연결 로그에서 도메인·매칭 규칙·사용 노드를 기록해 두세요. 설정을 한꺼번에 바꾸기보다 변경 전후를 비교하기 쉬워집니다.

Clash TUN과 개발용 규칙 설정하기

이제 실제로 TUN을 켜고 개발 트래픽을 확인합니다. 메뉴의 정확한 이름은 클라이언트에 따라 다를 수 있지만, 핵심은 TUN 활성화, DNS 처리 방식, 자동 라우팅, 로그 확인의 순서입니다.

  1. 프로필을 먼저 활성화합니다. 구독 URL 또는 로컬 YAML을 가져온 뒤, 노드와 규칙이 표시되는 프로필을 선택합니다. 빈 프로필이나 파싱 오류가 있는 상태에서 TUN부터 켜면 원인을 분리하기 어렵습니다.
  2. DNS 모드를 확인합니다. 지원되는 경우 fake-ip 또는 redir-host 중 현재 네트워크와 애플리케이션에 맞는 방식을 선택합니다. 사내 도메인과 로컬 개발 도메인이 있다면 예외 목록에 넣어 내부 해석을 보존합니다.
  3. TUN 모드를 활성화합니다. 설정 화면에서 TUN 또는 서비스 모드를 켜고, 운영체제가 요청하는 네트워크 확장·관리자 권한을 승인합니다. Windows에서는 방화벽 허용 여부를, macOS에서는 네트워크 확장 권한을 확인합니다.
  4. 자동 라우팅과 스택을 점검합니다. 기본값을 먼저 사용하고, 연결이 불안정할 때만 system, gVisor, Mixed 같은 스택 옵션을 비교합니다. 동시에 여러 옵션을 변경하면 어떤 항목이 개선했는지 알 수 없습니다.
  5. 개발 명령을 순서대로 재현합니다. git ls-remote, 패키지 매니저의 메타데이터 조회, docker pull을 각각 실행하면서 연결 로그를 캡처합니다. 실패한 명령만 반복하지 말고 성공한 요청과 비교해야 누락 도메인을 찾을 수 있습니다.
# HTTP 혼합 포트를 사용하는 보조 확인 예시
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7891

# 현재 셸에서 프록시 변수 확인
env | grep -i proxy

환경 변수는 TUN의 대체재라기보다 진단용으로 생각하는 편이 좋습니다. TUN을 켠 상태에서 환경 변수까지 함께 사용하면 이중 프록시가 될 수 있으므로, 테스트가 끝난 뒤에는 필요 여부를 결정해야 합니다. 특히 일부 CLI는 ALL_PROXY만 읽고 다른 프로그램은 HTTPS_PROXY만 읽기 때문에, 환경 변수가 남아 있으면 프로세스마다 서로 다른 경로를 사용할 수 있습니다.

Git·패키지·Docker별 규칙과 검증법

Git과 저장소 호스트

Git 작업에서는 저장소 본체와 서브모듈, 릴리스 파일의 호스트가 다를 수 있습니다. 우선 연결 로그에서 실제로 사용된 도메인을 확인하고, 필요한 경우 저장소 호스트를 전용 그룹으로 보냅니다. DOMAIN-SUFFIX,github.com처럼 범위를 잡으면 대부분의 GitHub 웹·API 요청을 포괄할 수 있지만, 조직의 내부 Git 서버까지 무조건 같은 경로로 보내서는 안 됩니다. 사내 주소는 명시적인 DIRECT 예외를 앞쪽에 배치하는 편이 안전합니다.

Git에 오래전에 저장한 프록시 값도 확인해야 합니다. 다음 명령으로 현재 설정을 읽고, TUN 환경에서 중복 적용이 의심되면 해당 값을 임시로 해제한 뒤 다시 테스트합니다.

git config --global --get-regexp 'http.*proxy'
git config --local --get-regexp 'http.*proxy'
git ls-remote https://github.com/example/project.git

npm·pnpm·Python 패키지

패키지 설치 실패는 레지스트리 자체보다 tarball CDN에서 발생하는 경우가 많습니다. 처음에는 레지스트리 주소만 로그에 보여도, 실제 파일을 내려받는 순간 다른 호스트가 추가됩니다. npm install이나 pnpm install을 실행하면서 새로 나타난 도메인을 기록하고, 공식 레지스트리·패키지 CDN·소스 저장소를 필요에 따라 같은 개발 그룹에 넣습니다. 무조건 모든 CDN을 키워드 규칙으로 묶으면 광고·분석·무관한 서비스까지 프록시로 들어올 수 있으므로 구체적인 접미사 규칙을 우선하세요.

캐시를 삭제하기 전에 오류 유형도 읽어야 합니다. ETIMEDOUT과 ECONNRESET은 경로 또는 노드 문제일 가능성이 있고, 404나 무결성 해시 오류는 프록시보다 레지스트리·잠금 파일·캐시 문제일 수 있습니다. 같은 명령을 다른 노드로 반복해 보고, 연결 로그에서 DNS 응답과 실제 접속 주소가 일관적인지 확인합니다.

Docker와 컨테이너 런타임

Docker는 CLI만 프록시를 타면 충분하지 않은 경우가 많습니다. 실제 이미지 다운로드는 Docker 데몬이 담당하므로, Docker Desktop·Linux systemd 서비스·WSL2 배포판 중 어디에서 데몬이 실행되는지 먼저 확인해야 합니다. 호스트의 TUN이 Docker Desktop 내부 VM까지 전달되지 않는 구성이라면, 데몬에 허용된 프록시 설정을 별도로 넣어야 합니다. 반대로 이미 데몬이 호스트 프록시를 사용하고 있는데 CLI에도 다른 프록시를 지정하면 인증과 레이어 요청의 경로가 갈라질 수 있습니다.

docker login이 성공했는데 docker pull이 실패한다면 인증 서버와 레이어 저장소가 서로 다른 도메인일 가능성이 큽니다. 두 요청을 각각 실행하고 연결 로그를 비교하세요. 사설 레지스트리, 회사 내부 이미지, 로컬 Kubernetes 레지스트리는 외부 프록시로 보내지 않도록 명시적 예외를 두는 것이 일반적으로 안전합니다.

연결 로그로 문제를 좁히는 방법

TUN 설정이 끝난 뒤에도 문제가 남는다면 규칙 파일을 무작정 크게 바꾸지 말고 한 요청의 생애를 따라가야 합니다. 먼저 명령을 재현하고, Clash 로그에서 FQDN이 보이는지 확인합니다. 도메인이 보이지 않고 IP 주소만 표시된다면 DNS 모드나 애플리케이션의 자체 해석을 살펴봅니다. 도메인은 보이지만 예상한 규칙이 아니라면 규칙 순서와 프로필의 실제 활성 상태를 확인합니다.

  • 로그에 요청이 전혀 없음: TUN 권한, 라우팅 테이블, 다른 VPN의 우선순위, Docker 또는 WSL2 내부 네트워크를 점검합니다.
  • 요청은 있으나 DIRECT로 표시됨: 도메인 규칙이 없거나 더 앞선 GEOIP, IP-CIDR 규칙에 먼저 매칭되었는지 확인합니다.
  • 프록시 그룹으로 갔지만 실패함: 노드 연결성, TLS 오류, MTU, 원격 서버 응답 코드를 비교합니다. 모든 실패를 규칙 누락으로 판단하지 마세요.
  • 인증만 실패함: 로그인 호스트와 API·다운로드 호스트가 동일한 그룹을 사용하는지, 시스템 시간이 정확한지, 셸에 오래된 인증 프록시 변수가 남아 있지 않은지 확인합니다.

검증은 한 번에 하나의 도구로 진행하는 것이 좋습니다. 먼저 curl로 대상 URL의 헤더를 확인하고, 그 다음 Git, 패키지 매니저, Docker 순으로 범위를 넓히면 네트워크 계층과 도구별 설정을 구분하기 쉽습니다. 성공 후에는 불필요하게 추가한 와일드카드 규칙을 줄이고, 내부 도메인과 외부 개발 서비스의 예외를 문서화하세요. 나중에 노드를 교체하거나 새 컴퓨터로 옮길 때도 이 기록이 재현 가능한 기준이 됩니다.

안정적인 개발 프록시를 유지하는 운영 체크리스트

개발용 TUN은 한 번 켜고 잊는 기능보다, 작업 흐름에 맞춰 관리해야 하는 네트워크 계층에 가깝습니다. 정기적으로 프로필 업데이트 후 규칙 문법 오류가 없는지 확인하고, 기존 노드가 사라졌을 때 대체 그룹이 선택되는지 테스트하세요. 노드가 바뀐 뒤 특정 패키지만 느려졌다면 패키지 매니저 캐시를 먼저 지우기보다 같은 도메인이 다른 출구로 매칭되는지 로그에서 비교하는 편이 빠릅니다.

회사 저장소와 공용 저장소를 함께 사용하는 개발자는 특히 DIRECT 예외를 명확히 유지해야 합니다. 내부 DNS 이름, RFC1918 대역, 로컬 Kubernetes 주소를 외부 프록시로 보내면 인증 오류나 보안 경고가 발생할 수 있습니다. 반대로 외부 서비스에 대한 광범위한 키워드 규칙은 예상하지 못한 트래픽을 같은 노드로 보낼 수 있으므로, 필요한 도메인 접미사와 포트만 단계적으로 추가하세요.

시중의 일부 프록시 도구는 브라우저 연결에는 간단하지만 TUN 권한, DNS 예외, Docker 데몬, WSL2 경로를 한 화면에서 설명하지 않거나 개발자용 문서가 부족합니다. 또 애플리케이션마다 프록시를 따로 넣는 방식은 도구가 추가될 때마다 설정이 분산되고, 실패한 요청이 어느 경로로 나갔는지 확인하기 어렵습니다. Clash 공식 사이트는 Clash·Mihomo 클라이언트의 프로필, TUN, 터미널 프록시, 연결 로그를 함께 점검할 수 있도록 단계별 자료를 제공하므로 이 글의 순서를 따라 환경을 정리하기 좋습니다. 개발 도구의 프록시 경로를 한곳에서 관리해 보고 싶다면 다운로드 시작으로 필요한 클라이언트를 확인해 보세요.