# 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에서 사용할 때는 아래 순서를 우선 적용한다.

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

```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
```

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

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

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

```bash
ADB_SERVER_SOCKET=tcp:<WINDOWS_HOST_IP>:5037
```

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

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

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

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

```bash
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 우선 전환 기준을 보강한다.