# 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 선행` 조합을 기본값으로 사용한다.