Flutter 앱의 이미지가 Docker 배포 후 로딩 안 될 때

Flutter 앱이 로컬 개발 환경에서는 이미지를 제대로 로딩하지만, Docker 컨테이너로 배포한 후에는 이미지가 나타나지 않는 문제가 있다. 이는 보통 이미지 경로, 환경 변수, 또는 컨테이너 내부의 리소스 접근 권한 때문이다.

현재 컨테이너 상태 확인

먼저 배포된 컨테이너가 정상적으로 실행 중인지, 또는 반복적으로 재시작되고 있는지 확인해야 한다.

docker ps

STATUS 컬럼에서 Up 상태인지 Exited 상태인지 보자. 만약 Exited 상태라면, 어떤 이유로 멈췄는지 로그에서 확인할 수 있다.

컨테이너 로그 확인

Flutter 앱이 시작하지 못했거나 이미지 로딩 중 에러가 났는지 확인하자.

docker logs --tail=100 service-name

로그에서 보야할 것들:

• 앱이 시작되는 메시지가 있는가
• 이미지를 찾지 못했다는 에러가 있는가
• 권한 부족 에러(Permission denied)가 있는가

마운트된 볼륨 확인

Flutter 앱에서 사용하는 이미지 파일들이 컨테이너 내부에서 실제로 접근 가능한지 확인해야 한다.

docker inspect service-name

결과에서 Mounts 섹션을 보면:

• 이미지 파일이 있는 호스트 경로
• 그것이 컨테이너 내부의 어느 경로로 마운트되었는지
• 마운트 권한이 읽기만 가능한지 읽기/쓰기인지

Flutter 앱 코드에서 이미지를 로딩할 때 사용하는 경로가, 마운트된 컨테이너 경로와 일치하는지 확인하자.

환경 변수와 이미지 경로

Flutter 앱이 이미지 경로를 환경 변수로 받는 경우, 로컬과 Docker 환경에서 다를 수 있다. 예를 들어:

• 로컬: /home/user/app/assets/images
• Docker: /app/assets/images (또는 다른 경로)

컨테이너 내부에서 실제 경로가 무엇인지 확인하고, Flutter 앱 코드에서 그 경로를 제대로 사용하고 있는지 봐야 한다.

Flutter의 Image.file() 또는 Image.asset()을 쓸 때, 경로가 런타임에 제대로 해석되는지 테스트하자.

검증: 수정 후 재배포

마운트 경로나 환경 변수를 수정한 후:

1. 컨테이너를 다시 시작하고 docker ps로 상태 확인
2. docker logs로 에러 메시지가 사라졌는지 확인
3. 앱의 UI에서 이미지가 나타나는지 확인
4. 지속적으로 재시작되지는 않는지 모니터링

작은 테스트 이미지 파일로 먼저 테스트한 후, 전체 이미지 집합을 배포하는 것도 좋은 방법이다.