Android Studio / WSL ADB 연동 트러블슈팅 타임테이블

작성일: 2026-07-03 대상 작업: Windows Android Studio emulator 준비, Windows ADB 확인, WSL/Docker Flutter CLI 연동 관련 시나리오: docs/scenario_android_emulator_device_integration_test_2026-07-03.md

1. 요약

2026-07-03 오전에는 tdc114plus Flutter integration test 실행을 위해 Windows Android Studio에서 Android emulator를 만들고, WSL 및 Docker 기반 Flutter CLI에서 해당 emulator를 인식하도록 연결했다.

최종적으로 아래 상태까지 확인했다.

Windows PowerShell adb devices: emulator-5554 device 확인
Windows netsh interface portproxy: 0.0.0.0:5037 -> 127.0.0.1:5037 설정
WSL에서 Windows host 172.21.128.1:5037 연결 성공
Flutter Docker 컨테이너 내부 adb devices: emulator-5554 device 확인
ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 ./scripts/flutter-docker.sh devices: Android emulator 표시 확인

통합테스트 실행은 아직 최종 성공/실패 판정 전이다. 기존 scripts/integration_tests.sh가 출력을 임시 파일에 모았다가 종료 후 출력하는 구조라, Android 첫 빌드 중 진행 상태 확인이 어려웠다. 다음 단계에서는 실시간 출력이 가능하도록 스크립트를 보강한 뒤 재실행한다.

2. 기대 시간과 실제 소요 시간

구간	설치/연동 전 기대 시간	실제 소요 시간	판정
Android Studio 설치 및 Setup Wizard	15-25분	약 25-35분 추정	대체로 정상 범위
AVD 생성 및 system image 다운로드	10-20분	약 15-25분 추정	정상 범위
Windows `adb devices` 확인	5분	약 5-10분	정상 범위
WSL/Docker에서 Windows ADB 접근 구성	10-15분	최소 49분 이상	지연 발생
Flutter Docker에서 emulator 인식 확인	5-10분	약 10분	정상 범위
전체 Android Studio 설치부터 Docker device 인식까지	30-45분	약 50-70분 추정	지연 발생

실제 소요 시간 중 명령 로그로 확인 가능한 핵심 구간은 아래와 같다.

08:45 KST: adb -a -P 5037 nodaemon server 첫 실패 확인
08:54 KST: adb -a -P 5037 nodaemon server 재시도 실패 확인
09:00 ~ 09:30 KST: 업무회의참여
09:34 KST: emulator용 local env 파일 생성
09:34 KST 이후: flutter-docker.sh devices에서 Android emulator 인식 확인

따라서 Windows ADB를 WSL/Docker에서 접근 가능하게 만드는 구간만 최소 49분 이상 소요되었다.

3. 타임테이블

시간(KST)	단계	수행 내용	결과
오전 초반	Android Studio 설치 시작	Android Studio 공식 다운로드 페이지에서 Windows용 Android Studio 설치	설치 진행
오전 초반	Setup Wizard	usage statistics는 전송하지 않는 방향으로 선택, Standard 설치, SDK license 수락	Android Studio 초기 설정 완료
오전 중반	Device Manager 진입	Android Studio Welcome 화면에서 Device Manager 열기	가상 기기 목록 화면 진입
오전 중반	AVD 생성	Medium Phone 선택, Android 15 API 35, Google Play Intel x86_64 system image 선택	`Medium Phone` AVD 생성
오전 중반	Emulator 실행	Device Manager에서 `Medium Phone` 실행	Windows ADB에서 emulator 확인 가능 상태
오전 중반	Windows ADB 경로 확인	PowerShell에서 기본 `adb devices` 실행	`adb`가 PATH에 없어 실패
오전 중반	Windows ADB 직접 실행	`& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" devices`	`emulator-5554 device` 확인
08:45	ADB 외부 바인딩 1차 시도	`adb -a -P 5037 nodaemon server`	`10048`, `0.0.0.0:5037` bind 실패
08:45-08:54	포트 점유 원인 확인	`Get-Process adb`, `netstat -ano`, `taskkill`, `Get-CimInstance` 반복	Android Studio/ADB client가 일반 ADB server를 계속 재기동하는 패턴 확인
08:54	ADB 외부 바인딩 재시도	기존 ADB 종료 후 `adb -a -P 5037 nodaemon server` 재실행	동일하게 `10048` 실패
08:54 이후	2순위 방식 전환	`adb -a` 대신 Windows `portproxy` 방식으로 전환 결정	우회 경로 확정
오전 후반	관리자 PowerShell 실행	관리자 권한 PowerShell에서 `netsh interface portproxy` 설정	`0.0.0.0:5037 -> 127.0.0.1:5037` 등록
오전 후반	방화벽 허용	`netsh advfirewall firewall add rule name="ADB 5037 for WSL"`	방화벽 rule 추가 완료
오전 후반	WSL 연결 확인	WSL에서 Windows host `172.21.128.1:5037` TCP 연결 확인	연결 성공
오전 후반	Docker 내부 ADB 확인	`ghcr.io/cirruslabs/flutter:stable` 컨테이너에서 `ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 adb devices`	`emulator-5554 device` 확인
오전 후반	스크립트 보강	`scripts/flutter-docker.sh`가 `ADB_SERVER_SOCKET`을 Docker 컨테이너에 전달하도록 수정	프로젝트 스크립트에서도 emulator 인식 가능
오전 후반	Flutter device 확인	`ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 ./scripts/flutter-docker.sh devices`	Android emulator와 Linux desktop 표시
09:34	Emulator env 준비	`scripts/.env.android-emulator.local` 생성, API base를 `http://10.0.2.2:5000`으로 설정	민감정보 없는 방식으로 local env 준비
09:34 이후	Integration test 1차 실행	`TDC114_SMOKE_ENV_FILE=scripts/.env.android-emulator.local ADB_SERVER_SOCKET=... ./scripts/integration_tests.sh`	출력이 종료 후 표시되는 구조라 진행 상태 판단 곤란
09:50 전후	실행 방식 재검토	프로세스 확인 및 실시간 출력 재실행 준비	다음 단계에서 스크립트 출력 개선 필요

4. 지연 원인

가장 큰 지연 원인은 adb -a -P 5037 nodaemon server 방식이 Windows 환경에서 안정적으로 동작하지 않은 점이다.

세부 원인은 아래와 같다.

Windows ADB server가 기본적으로 127.0.0.1:5037에 먼저 바인딩되었다.
Android Studio, Device Manager, emulator 또는 다른 ADB client가 일반 ADB server를 자동으로 다시 띄웠다.
기존 ADB PID를 종료해도 즉시 새 PID가 127.0.0.1:5037을 다시 점유했다.
netstat에는 잠깐 포트가 비어 보였지만, adb -a 실행 시점에는 다시 점유되어 10048 오류가 반복되었다.
WSL 내부에는 adb, flutter, java, sdkmanager, emulator가 PATH에 없어서 WSL 단독 emulator 방식으로 바로 전환할 수 없었다.
scripts/integration_tests.sh는 출력을 임시 파일에 모았다가 종료 후 출력하므로, Android 첫 빌드가 오래 걸릴 때 진행 상태를 실시간으로 확인하기 어려웠다.

5. 다음 동일 상황에서 지연을 줄이는 방법

다음부터 Windows Android Studio emulator를 WSL/Docker Flutter에서 사용할 때는 아래 순서를 우선 적용한다.

Windows에서 emulator를 먼저 실행하고 adb.exe devices로 device 상태를 확인한다.
adb -a -P 5037 nodaemon server는 1차 시도만 한다.
10048이 1회라도 재현되면 즉시 portproxy 방식으로 전환한다.
관리자 PowerShell에서 아래를 적용한다.

netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=5037 connectaddress=127.0.0.1 connectport=5037
netsh advfirewall firewall add rule name="ADB 5037 for WSL" dir=in action=allow protocol=TCP localport=5037
netsh interface portproxy show v4tov4

WSL에서 Windows host IP를 확인한다.

awk '/nameserver/ {print $2; exit}' /etc/resolv.conf

Docker Flutter 실행 시 아래 환경변수를 넘긴다.

ADB_SERVER_SOCKET=tcp:<WINDOWS_HOST_IP>:5037

이번 환경에서는 <WINDOWS_HOST_IP>가 172.21.128.1이었다.

프로젝트 스크립트 기준으로 device 인식을 먼저 확인한다.

ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 ./scripts/flutter-docker.sh devices

emulator에서 host API는 127.0.0.1이 아니라 10.0.2.2를 사용한다.

TDC114_API_BASE=http://10.0.2.2:5000

6. 후속 작업

scripts/integration_tests.sh를 실시간 출력이 가능하도록 개선한다.
동일 환경에서 integration test를 재실행한다.
성공/실패 결과를 docs/test-logs/2026-07-test-execution-log.md에 누적 기록한다.
docs/scenario_android_emulator_device_integration_test_2026-07-03.md의 3-B 단계에 portproxy 우선 전환 기준을 보강한다.

8.4 KiB Raw Blame History