kevin/tdc114plus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Stabilize auth flow and profile images

Browse Source
This commit is contained in:
Codex
2026-07-20 13:38:39 +09:00
parent 57caca8dc8
commit 5d3eee7a16
128 changed files with 28860 additions and 1468 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/troubleshooting/android-studio-wsl-adb-timetable-260703.md
+127
View File
@@ -0,0 +1,127 @@
# 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 우선 전환 기준을 보강한다.
docs/troubleshooting/flutter-docker-repeated-delay-countermeasures-2026-07-03.md
+142
View File
@@ -0,0 +1,142 @@
# Flutter Docker 반복 지연 대응 정리
작성일: 2026-07-03
대상: Windows Android Studio emulator + WSL/Docker Flutter CLI 조합에서 반복 실행 시 느려지는 항목
## 1. 목적
Android integration test와 Docker Flutter 실행에서 반복적으로 오래 걸리는 문제를 따로 모아, 다음 실행부터 시간을 줄일 수 있는 대응안을 정리한다.
## 2. 반복 지연 항목
| 항목 | 실제 증상 | 원인 | 우선 대응 |
| --- | --- | --- | --- |
| NDK 재설치 | 매 integration test에서 NDK license 확인 및 설치 반복 | Docker container가 매번 새로 뜨고 Android SDK 쓰기 경로가 유지되지 않음 | `.docker-cache/flutter/android-sdk/ndk` 유지 |
| CMake 재설치 | 매 integration test에서 CMake license 확인 및 설치 반복 | 위와 동일 | `.docker-cache/flutter/android-sdk/cmake` 유지 |
| Android SDK license 재확인 | license accept 로그 반복 | licenses 디렉터리 비지속 | `.docker-cache/flutter/android-sdk/licenses` 유지 |
| Gradle dependency 준비 시간 | `assembleDebug`가 매번 길어짐 | `/root/.gradle` 비지속 | `.docker-cache/flutter/gradle` 유지 |
| Flutter pub dependency 준비 | `flutter pub get` 반복 시간이 누적 | `/root/.pub-cache` 비지속 | `.docker-cache/flutter/pub` 유지 |
| ADB unauthorized | emulator 연결은 되지만 `unauthorized` | Docker ADB key와 Windows 승인 key 불일치 | `.android-adb/`에 Windows ADB key 재사용 |
| Integration test 직전 API 실패 | real API login test만 실패 | Baron/Ory runtime 중단 | `./scripts/api-smoke.sh` 선행 |
## 3. 이미 적용한 대응
현재 저장소에는 아래 대응이 이미 반영되어 있다.
- `scripts/flutter-docker.sh`
- `.android-adb/`를 Docker `/root/.android`로 마운트
- `.docker-cache/flutter/gradle`를 Docker `/root/.gradle`로 마운트
- `.docker-cache/flutter/pub`를 Docker `/root/.pub-cache`로 마운트
- `.docker-cache/flutter/android-sdk/licenses`를 Docker `/opt/android-sdk-linux/licenses`로 마운트
- `.docker-cache/flutter/android-sdk/ndk`를 Docker `/opt/android-sdk-linux/ndk`로 마운트
- `.docker-cache/flutter/android-sdk/cmake`를 Docker `/opt/android-sdk-linux/cmake`로 마운트
- `.gitignore`
- `.android-adb/`
- `.docker-cache/`
## 4. 권장 실행 순서
반복 지연과 실패를 줄이려면 아래 순서를 기본값으로 사용한다.
1. Windows emulator를 먼저 실행한다.
2. Windows `adb.exe devices`에서 `device` 상태를 확인한다.
3. `5555` portproxy까지 준비한다.
4. host 기준 `./scripts/api-smoke.sh`를 먼저 실행한다.
5. 아래 명령으로 Docker local ADB 상태를 확인한다.
```bash
TDC114_ADB_CONNECT_ADDRESS=172.21.128.1:5555 ./scripts/flutter-docker.sh devices
```
6. 이후 integration test를 실행한다.
```bash
TDC114_SMOKE_ENV_FILE=scripts/.env.android-emulator.local \
TDC114_ADB_CONNECT_ADDRESS=172.21.128.1:5555 \
./scripts/integration_tests.sh
```
## 5. 지연을 더 줄이는 추가 후보
아래는 아직 이번 턴에서 적용하지 않았지만, 추가로 검토할 가치가 있다.
### 5.1 Flutter Docker image 고정
`ghcr.io/cirruslabs/flutter:stable` 대신 검증된 tag를 고정하면 image 내부 Android SDK 구성이 갑자기 바뀌는 위험을 줄일 수 있다.
예:
```bash
FLUTTER_DOCKER_IMAGE=ghcr.io/cirruslabs/flutter:3.32.5
```
효과:
- 예측 가능한 SDK/Gradle 조합 유지
- cache 호환성 추적이 쉬워짐
주의:
- 프로젝트 Flutter 버전과 맞지 않는 tag는 피한다.
### 5.2 Android 빌드 전용 warm-up 명령
긴 integration test 전에 아래를 먼저 실행해 build cache를 예열할 수 있다.
```bash
TDC114_ADB_CONNECT_ADDRESS=172.21.128.1:5555 ./scripts/flutter-docker.sh build apk --debug
```
효과:
- 첫 integration test에서 체감 지연 감소
주의:
- 근본 해결은 cache 유지이며, warm-up은 보조 수단이다.
### 5.3 runtime health gate 자동화
integration test 시작 전에 `./scripts/check-baron-api-env.sh`와 `./scripts/api-smoke.sh`를 자동으로 선행하도록 `integration_tests.sh`를 확장할 수 있다.
효과:
- 앱 테스트 실패와 backend runtime 실패를 더 빨리 구분
주의:
- 테스트 시작 시간은 조금 늘어나지만, 재시도 횟수는 줄일 가능성이 크다.
## 6. 언제 cache를 비워야 하는가
아래 상황이 아니면 cache 삭제를 먼저 하지 않는다.
- Flutter Docker image를 크게 변경했다.
- Gradle/NDK/CMake 관련 이상한 충돌이 반복된다.
- cache 안 파일이 root 권한 꼬임으로 재사용되지 않는다.
부분 삭제 우선순위:
1. `.docker-cache/flutter/android-sdk/cmake`
2. `.docker-cache/flutter/android-sdk/ndk`
3. `.docker-cache/flutter/gradle`
4. `.docker-cache/flutter/pub`
전체 삭제는 마지막 수단으로 둔다.
## 7. 현재 결론
매번 너무 오래 걸리는 문제는 어느 정도 해결 또는 완화가 가능하다.
- 해결 가능한 부분:
- ADB unauthorized
- NDK/CMake 반복 설치
- Gradle/pub cache 반복 준비
- backend runtime 미감지 상태에서 앱 테스트를 먼저 돌리는 문제
- 완화만 가능한 부분:
- Android 첫 빌드 자체의 절대 시간
- Docker image pull 또는 변경 직후 초기 warm-up 비용
- emulator 자체 부팅 시간
다음 실행부터는 `5555 + Docker local ADB + cache 유지 + api-smoke 선행` 조합을 기본값으로 사용한다.