이 글의 목적은 Windows에서 Docker Desktop을 사용할 때 Hyper-V 가상 스위치와 WSL2 네트워크가 충돌하여 발생하는 IP 대역 겹침, 라우팅 꼬임, 연결 끊김 문제를 “원인 진단 → 안전한 초기화/재구성 → 재발 방지 설계” 순서로 정리하여 현장에서 즉시 복구할 수 있도록 돕는 것이다.
1. 증상으로 보는 문제 유형 분류
Docker, Hyper-V, WSL2는 모두 Windows 네트워킹 스택 위에서 가상 NIC(vEthernet)과 NAT, 라우팅 규칙을 생성/수정하는 구조이다. 이때 주소 대역이 겹치거나(Overlap) Host Network Service(HNS) 구성이 꼬이면 아래와 같은 형태로 문제가 나타나다.
| 대표 증상 | 현상 예시 | 가능성이 높은 원인 | 우선 조치 |
|---|---|---|---|
| Docker 네트워크 겹침 경고 | 진단에서 “docker networks overlap with host IPs” 형태 오류가 발생하다 | Docker/WSL/Hyper-V NAT 대역이 사내망/VPN 대역과 겹치다 | 대역 확인 후 NAT 재구성 또는 초기화하다 |
| 컨테이너에서 사내망/게이트웨이 접근 불가 | 컨테이너에서 내부 IP로 ping/접속이 실패하다 | 라우팅 우선순위가 vEthernet 경로로 잘못 잡히다 | 라우팅/메트릭 점검 후 네트워크 재생성하다 |
| Windows 네트워크가 주기적으로 끊김 | vEthernet(Default Switch) 또는 WSL 어댑터가 계속 재연결되다 | HNS/ICS 구성 충돌, 손상된 가상 네트워크 개체가 남다 | HNS 네트워크 정리 후 재부팅하다 |
| WSL2는 되고 Docker만 안 됨 | WSL에서는 인터넷이 되나 docker pull이 실패하다 | Docker Desktop 내부 NAT/프록시 설정 또는 HNS 엔드포인트 꼬임이다 | Docker 네트워크/엔진 초기화 후 재기동하다 |
주의 : 네트워크 재구성은 기존 가상 스위치, 가상 머신, 컨테이너 네트워크가 끊길 수 있는 작업이다. 운영 서버나 원격 접속(RDP) 환경에서는 로컬 콘솔 접근 수단을 확보한 뒤 진행하는 것이 안전하다.
2. 구조 이해: Hyper-V, WSL2, Docker Desktop이 네트워크를 만드는 방식
2.1 Hyper-V 가상 스위치와 Default Switch
Hyper-V는 가상 스위치(External/Internal/Private)를 생성하며, Windows는 vEthernet 어댑터를 통해 호스트와 VM 간 트래픽을 처리하다. 특히 Default Switch는 내부적으로 NAT/ICS 성격을 띠며 자동으로 대역을 구성하는 경우가 많다.
2.2 WSL2 NAT 또는 미러링 네트워킹
WSL2는 기본적으로 NAT 기반 가상 네트워크를 사용하다. Windows 11에서는 미러링 네트워킹을 설정하여 Windows의 실제 인터페이스 구성을 WSL에 “미러” 형태로 반영하는 방식도 사용 가능하다. NAT 구조에서 대역 충돌이 빈번할수록 미러링 네트워킹이 유리한 경우가 많다.
2.3 Docker Desktop과 HNS
Docker Desktop은 Windows에서 HNS를 통해 가상 네트워크, 엔드포인트, NAT 규칙을 생성하다. WSL2 백엔드를 사용하는 경우에도 Windows 측 HNS 개체와 WSL 배포판 내부 네트워크가 함께 얽히다. 충돌이 발생하면 “남아있는 HNS 네트워크/엔드포인트”가 재부팅 후에도 꼬임을 유지하는 경우가 많다.
3. 원인 진단: ‘대역 겹침’과 ‘개체 꼬임’을 분리해서 본다
3.1 먼저 대역 겹침(Overlap) 여부를 확인하다
가장 흔한 1순위 원인은 사내망(예: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) 또는 VPN이 사용하는 대역과 Docker/WSL/Hyper-V NAT가 겹치는 상황이다. 겹치면 라우팅이 정상이어도 특정 구간 트래픽이 가상 어댑터로 빨려 들어가며 접속 실패가 발생하다.
ipconfig /all route print -4 powershell -NoProfile -Command "Get-NetIPAddress -AddressFamily IPv4 | Sort-Object InterfaceAlias | Format-Table InterfaceAlias,IPAddress,PrefixLength -Auto" powershell -NoProfile -Command "Get-NetIPInterface -AddressFamily IPv4 | Sort-Object InterfaceMetric | Format-Table InterfaceAlias,InterfaceMetric,Dhcp -Auto"위 결과에서 아래 항목을 표시해두면 원인 특정이 빨라지다.
| 확인 포인트 | 무엇을 찾는가 | 의미 |
|---|---|---|
| vEthernet(WSL), vEthernet(Default Switch), Docker 관련 vEthernet | 각 어댑터의 IPv4/Prefix | NAT 대역이 사내망/VPN 대역과 겹치는지 판단하다 |
| route print -4 | 동일한 목적지 대역에 대한 여러 경로 | 우선순위(메트릭)로 인해 잘못된 경로가 선택되다 |
| InterfaceMetric | 가상 어댑터 메트릭이 비정상적으로 낮음 | 가상 경로가 실제 NIC보다 우선되어 문제를 유발하다 |
3.2 다음으로 HNS 개체 꼬임 여부를 확인하다
대역이 겹치지 않는데도 문제가 반복된다면 HNS 네트워크/엔드포인트가 업데이트, 재부팅, 강제 종료 등으로 정상 삭제되지 않고 남아 “유령 구성”처럼 충돌을 일으키는 경우가 많다.
powershell -NoProfile -Command "Get-Service hns,lxssmanager | Format-Table Name,Status,StartType -Auto" powershell -NoProfile -Command "Get-Command Get-HnsNetwork,Get-HnsEndpoint -ErrorAction SilentlyContinue" powershell -NoProfile -Command "Get-HnsNetwork | Format-Table Name,Type,Subnets -Auto" powershell -NoProfile -Command "Get-HnsEndpoint | Select-Object -First 20 | Format-List"주의 : HNS 개체를 정리하면 Docker 네트워크, Windows 컨테이너 네트워크, 일부 Hyper-V/ICS 구성에 영향이 발생할 수 있다. 반드시 Docker Desktop을 완전히 종료하고 진행해야 하다.
4. 해결 전략: “주소 설계” 후 “재구성”하는 순서가 재발을 줄이다
4.1 권장 주소 설계 원칙
사내망/VPN이 10.0.0.0/8 또는 172.16.0.0/12를 넓게 사용하는 환경에서는 Docker/WSL/Hyper-V NAT를 192.168.x.0/24처럼 좁고 명확한 대역으로 고정하는 편이 충돌 가능성이 낮다. 반대로 사내망이 192.168.0.0/16을 넓게 쓰면 172.20.x.0/24처럼 다른 사설 대역을 선택하는 방식이 유리하다.
| 환경 | 피해야 할 대역 예시 | 권장 대역 예시 | 설명 |
|---|---|---|---|
| 사내망/VPN이 10.x 위주 | 10.0.0.0/8 | 172.30.0.0/16 또는 192.168.200.0/24 | 사내 라우팅과 겹침을 피하다 |
| 사내망이 192.168.0.0/16 위주 | 192.168.0.0/16 | 172.20.0.0/16 또는 10.250.0.0/16 | 현장 장비/라우터 기본 대역과 충돌을 줄이다 |
| 여러 VPN을 자주 바꾸는 개발 PC | 광범위 사설대역 전부 | WSL 미러링 네트워킹 사용 | NAT 대역 자체를 없애 충돌을 줄이다 |
5. 표준 복구 절차: 안전 종료 → 네트워크 개체 정리 → 재생성
5.1 0단계: Docker/WSL/VM을 모두 안전 종료하다
wsl --shutdown
taskkill /F /IM "Docker Desktop.exe" 2>nul
taskkill /F /IM "com.docker.backend.exe" 2>nul
taskkill /F /IM "com.docker.proxy.exe" 2>nulHyper-V 가상 머신을 사용 중이면 VM도 종료하는 것이 안전하다.
5.2 1단계: 현재 네트워크 상태를 백업해두다
ipconfig /all > "%USERPROFILE%\Desktop\net_ipconfig_all.txt" route print -4 > "%USERPROFILE%\Desktop\net_route_v4.txt"
powershell -NoProfile -Command "Get-NetIPAddress -AddressFamily IPv4 | Sort-Object InterfaceAlias | Format-Table InterfaceAlias,IPAddress,PrefixLength -Auto" ^
> "%USERPROFILE%\Desktop\net_ipv4_table.txt"5.3 2단계: HNS 기반 네트워크를 정리하다
아래는 “HNS 서비스 정지 → HNS 네트워크/엔드포인트 정리 → 서비스 재기동”의 보편 절차이다. 환경에 따라 일부 명령만으로도 복구되지만, 반복 재발이면 정리 범위를 넓히는 것이 유리하다.
powershell -NoProfile -Command ^ "Stop-Service hns -Force; Stop-Service LxssManager -Force" powershell -NoProfile -Command ^ "Get-HnsEndpoint | Remove-HnsEndpoint -ErrorAction SilentlyContinue" powershell -NoProfile -Command ^ "Get-HnsNetwork | Remove-HnsNetwork -ErrorAction SilentlyContinue" powershell -NoProfile -Command ^ "Start-Service hns; Start-Service LxssManager"주의 : Remove-HnsNetwork는 Docker/컨테이너 네트워크를 모두 삭제하다. 작업 후 Docker Desktop이 네트워크를 재생성하도록 재기동이 필요하다.
5.4 3단계: (필요 시) HNS 데이터 파일 초기화로 “완전 재구성”하다
위 정리로도 즉시 재발하거나, vEthernet이 계속 생성/삭제를 반복하는 등 손상 징후가 명확하면 HNS 데이터 파일을 초기화하는 방식이 강력하다. 이 방식은 “완전 초기화”에 가까우므로 운영 환경에서는 특히 주의가 필요하다.
powershell -NoProfile -Command ^ "Stop-Service hns -Force" powershell -NoProfile -Command ^ "Remove-Item -Force 'C:\ProgramData\Microsoft\Windows\HNS\HNS.data' -ErrorAction SilentlyContinue" powershell -NoProfile -Command ^ "Start-Service hns"이후 재부팅을 수행하는 편이 안정적이다.
5.5 4단계: Docker Desktop을 재기동하여 네트워크를 재생성하다
Docker Desktop을 실행한 뒤, 엔진이 정상 기동되었는지 확인하다.
docker version docker network ls docker run --rm hello-world6. 재발 방지 1: WSL2 미러링 네트워킹으로 NAT 충돌을 줄이다
VPN, 보안 에이전트, 사내 라우팅 정책이 복잡한 환경에서는 WSL2 NAT 자체가 불안정 요인이 되다. Windows 11에서는 .wslconfig에서 미러링 네트워킹을 사용하여 충돌을 줄이는 선택지가 존재하다.
6.1 .wslconfig 예시
사용자 프로필 경로에 .wslconfig를 생성/수정하다. 파일 경로는 다음과 같다.
%UserProfile%\.wslconfig예시는 아래와 같다.
[wsl2] networkingMode=mirrored dnsTunneling=true autoProxy=true적용은 WSL 종료 후 재시작으로 진행하다.
wsl --shutdown주의 : 일부 환경에서는 미러링 네트워킹이 모든 도구와 100% 동일한 동작을 보장하지 않다. 다만 “대역 충돌” 유형의 문제를 구조적으로 줄이는 데 효과적이다.
7. 재발 방지 2: Hyper-V 스위치와 Docker 네트워크 역할을 분리하다
7.1 Hyper-V는 External 스위치 중심으로 설계하다
가능하면 Hyper-V VM이 실제 LAN에 붙는 External 스위치를 사용하여, Default Switch 의존도를 낮추는 방식이 충돌을 줄이다. Default Switch는 자동 NAT 성격으로 인해 다른 가상 NAT와 충돌 소지가 커지다.
7.2 Docker 네트워크는 사용자 정의 대역으로 통일하다
프로젝트별 브리지 네트워크를 만들 때도 사내망과 겹치지 않는 대역으로 통일하는 편이 운영이 단순하다.
docker network create --driver bridge --subnet 172.30.10.0/24 --gateway 172.30.10.1 devnet docker run --rm -it --network devnet alpine sh8. 최종 검증 체크리스트
재구성 후에는 “호스트 → WSL → 컨테이너” 3단계로 네트워크가 연속적으로 동작하는지 확인해야 하다.
| 구간 | 검증 명령 | 정상 기준 | 실패 시 의심 |
|---|---|---|---|
| 호스트 DNS/라우팅 | nslookup, route print | 사내망/VPN 라우팅이 정상이다 | VPN 클라이언트 라우팅 정책이다 |
| WSL2 인터넷 | wsl 내 ping, curl | 외부 접속이 안정적이다 | WSL NAT/미러링 설정 문제이다 |
| 컨테이너 인터넷 | docker run alpine ping/curl | 이미지 pull 및 외부 접속이 된다 | Docker Desktop 프록시/HNS 개체 꼬임이다 |
| 컨테이너→사내망 | 사내 게이트웨이/서버 접속 | 사내 IP 접근이 된다 | 대역 겹침 또는 라우팅 메트릭 문제이다 |
9. 운영 팁: 충돌을 줄이는 실무 설정
9.1 VPN을 자주 쓰는 PC는 “대역 넓은 VPN”을 특히 경계하다
VPN이 10.0.0.0/8처럼 넓은 대역을 터널링하는 경우 Docker/WSL NAT가 충돌하기 쉽다. 이때는 WSL 미러링 네트워킹 적용 또는 Docker 사용자 정의 대역 고정이 효과적이다.
9.2 인터페이스 메트릭이 비정상적으로 낮으면 조정하다
가상 어댑터 메트릭이 실제 NIC보다 낮으면 의도치 않게 가상 경로가 우선되다. 정책 환경에서는 임의 변경이 어려울 수 있으나, 원인 분리에는 큰 도움이 되다.
9.3 “재부팅하면 잠깐 고쳐짐”은 대체로 대역 충돌 또는 유령 개체이다
재부팅 직후에는 우연히 다른 NAT 대역이 잡혀 정상처럼 보이다가, VPN 연결 또는 Docker 네트워크 재생성 시 다시 충돌하는 패턴이 반복되다. 이런 경우는 “대역 설계” 없이는 재발 확률이 높다.
FAQ
Docker Desktop 진단에서 네트워크 겹침 오류가 나오면 무엇부터 봐야 하나?
우선 ipconfig와 route print로 vEthernet(WSL), vEthernet(Default Switch), Docker 관련 어댑터의 IPv4 대역을 모두 적어 비교해야 하다. 그 다음 사내망/VPN에서 사용하는 대역과 겹치는지를 확인하고, 겹친다면 Docker 네트워크를 사용자 정의 서브넷으로 통일하거나 WSL 미러링 네트워킹을 적용하는 것이 우선이다.
Remove-HnsNetwork를 했더니 Docker 네트워크가 다 사라졌는데 정상인가?
정상이다. HNS 네트워크 정리는 컨테이너 네트워크 개체를 강제로 삭제하는 방식이다. 이후 Docker Desktop을 재기동하면 기본 네트워크가 재생성되다. 다만 프로젝트별 커스텀 네트워크는 다시 생성해야 하다.
Default Switch를 지우거나 비활성화해도 되나?
Default Switch는 자동으로 재생성되는 성격이 강해 “삭제” 자체로 해결되지 않는 경우가 많다. 핵심은 Default Switch가 생성하는 대역/라우팅이 다른 NAT와 충돌하지 않도록 구조를 단순화하는 것이다. VM은 External 스위치로 옮기고, Docker/WSL은 고정 대역 또는 미러링 네트워킹으로 안정화하는 접근이 재발을 줄이다.
회사 보안 정책 때문에 네트워크가 자주 꼬이면 어떤 구성이 가장 무난한가?
VPN이 복잡하고 자주 바뀌는 환경에서는 WSL 미러링 네트워킹을 우선 검토하는 편이 무난하다. 동시에 Docker는 프로젝트별 네트워크 서브넷을 명시적으로 지정하여 사내망 대역과 겹치지 않게 관리하는 방식이 운영 측면에서 안정적이다.