tdc114plus/docs/troubleshooting/flutter-docker-repeated-delay-countermeasures-2026-07-03.md

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 상태를 확인한다.

TDC114_ADB_CONNECT_ADDRESS=172.21.128.1:5555 ./scripts/flutter-docker.sh devices

6. 이후 integration test를 실행한다.

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 구성이 갑자기 바뀌는 위험을 줄일 수 있다.

예:

FLUTTER_DOCKER_IMAGE=ghcr.io/cirruslabs/flutter:3.32.5

효과:

• 예측 가능한 SDK/Gradle 조합 유지
• cache 호환성 추적이 쉬워짐

주의:

• 프로젝트 Flutter 버전과 맞지 않는 tag는 피한다.

5.2 Android 빌드 전용 warm-up 명령

긴 integration test 전에 아래를 먼저 실행해 build cache를 예열할 수 있다.

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