🐳 로컬 Docker 환경 문제 해결 가이드

로컬에서는 잘 되는데 Docker에서 안 될 때 확인할 사항들

⚠️ 참고: 예시의 doll_gacha 이름은 이전 프로젝트 참조입니다. 실제 프로젝트명에 맞게 변경하세요.

📁 파일 경로 결합 문제

문제 현상

• 에디터에서 이미지 업로드 → 201 성공, 하지만 이미지 표시 안됨
• 첨부파일 다운로드 → 404 에러
• <img src="/uploads/xxx.png"> 이미지 깨짐

  원인

  경로 결합 시 문자열 단순 결합(+) 사용 및 application.yml에는 ./uploads application-prod.yml에는 /app/uploads 이렇게 뒤에 / 가 있냐 없냐 차이였다. ```java // ❌ 문자열 단순 결합 - yml 설정에 따라 결과가 달라짐 uploadDir + filename = “/app/uploads” + “test.png” = “/app/uploadstest.png” ❌ uploadDir + filename = “/app/uploads/” + “test.png” = “/app/uploads/test.png” ✅

// ✅ Paths.resolve() - yml 설정에 상관없이 항상 정상 작동 Paths.get(“/app/uploads”).resolve(“test.png”) = “/app/uploads/test.png” ✅ Paths.get(“/app/uploads/”).resolve(“test.png”) = “/app/uploads/test.png” ✅

### 왜 Paths.resolve()인가?
- **yml 설정에 `/` 붙이든 안 붙이든 상관없음** → 설정 실수 방지
- **근본적인 해결책** - 경로 관련 버그 원천 차단
#### 3. Docker 볼륨 매핑 확인
```yaml
# docker-compose.yml
services:
  app:
    volumes:
      - ./uploads:/app/uploads  # 호스트 ↔ 컨테이너 연결

참고 : yml에서 윈도우든 리눅스든 / 로 경로해도 알아서 jvm이 처리함

---

🎯 1. 환경별 설정 체크리스트

로컬 → Docker 배포 시 확인사항

체크	항목	적용 위치
✅	파일 경로 결합 시 Paths.resolve() 사용	FileUtil.java, FileController.java
✅	볼륨 매핑으로 파일 영속성 확보	docker-compose.yml → ./uploads:/app/uploads
✅	환경변수 전달	docker-compose.yml → environment: 섹션
✅	DB 연결 문자열 (localhost → 컨테이너명)	application-prod.yml + docker-compose.yml
✅	브라우저 쿠키 정리	환경 전환 시 수동 삭제 필요

---

각 항목 상세 설명

1️⃣ 볼륨 매핑 (docker-compose.yml)

app:
  volumes:
    - ./uploads:/app/uploads  # 호스트 ↔ 컨테이너 연결

• 역할: 컨테이너 재시작해도 업로드 파일 유지
• 로컬 폴더 ./uploads ↔ 컨테이너 폴더 /app/uploads 동기화

2️⃣ 환경변수 전달 (docker-compose.yml)

app:
  environment:
    # DB 설정 - 컨테이너명 'db' 사용
    SPRING_DATASOURCE_URL: jdbc:mariadb://db:3306/doll_gacha
    SPRING_DATASOURCE_USERNAME: doll_gacha
    SPRING_DATASOURCE_PASSWORD: ${DB_PASSWORD:-ckdlsk13!}
    
    # OAuth2 설정 - .env 파일에서 읽어옴
    KAKAO_CLIENT_ID: ${KAKAO_CLIENT_ID}
    KAKAO_CLIENT_SECRET: ${KAKAO_CLIENT_SECRET}
    GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID}
    GOOGLE_CLIENT_SECRET: ${GOOGLE_CLIENT_SECRET}
    
    # JWT 설정
    JWT_SECRET_KEY: ${JWT_SECRET_KEY}
    
    # 앱 URL
    APP_BASE_URL: ${APP_BASE_URL:-http://localhost:8080}

• 역할: .env 파일의 값을 컨테이너에 전달
• ${VAR:-default} 형태로 기본값 지정 가능

3️⃣ DB 연결 문자열 변경

# application.yml (로컬)
url: jdbc:mariadb://localhost:3406/doll_gacha

# application-prod.yml (Docker)
url: ${SPRING_DATASOURCE_URL:jdbc:mariadb://localhost:3406/doll_gacha}
# → docker-compose에서 jdbc:mariadb://db:3306/doll_gacha 로 덮어씀

• 핵심: Docker 네트워크에서는 localhost 대신 컨테이너명(db) 사용
• 포트도 내부 통신이므로 3306 사용 (호스트 매핑 포트 3407 아님)

4️⃣ 브라우저 쿠키 정리

로컬 → Docker 전환 시:
1. F12 (개발자도구) → Application 탭
2. Cookies → localhost
3. access_token, refresh_token 삭제
4. 새로고침

• 이유: 로컬에서 발급받은 JWT가 Docker 환경에서 유효하지 않을 수 있음

---

환경별 설정 비교

설정	로컬 (application.yml)	Docker (application-prod.yml + docker-compose.yml)
DB URL	localhost:3406	db:3306 (컨테이너명)
파일 경로	C:/workspace/.../uploads	/app/uploads
프로파일	default	prod (Dockerfile에서 지정)
포트	8080	8080:8080 (호스트:컨테이너)
OAuth redirect	localhost:8080	${APP_BASE_URL} (환경변수)

---

📝 2. 디버깅 명령어 모음

Docker 로그 확인

# 실시간 로그 확인
docker-compose logs -f app

# 최근 100줄만 확인
docker-compose logs --tail=100 app

컨테이너 내부 확인

# 업로드 폴더 파일 목록
docker exec -it doll_gacha_app ls -la /app/uploads/

# 환경변수 확인
docker exec -it doll_gacha_app env | grep -E "(SPRING|FILE)"

# 컨테이너 쉘 접속
docker exec -it doll_gacha_app /bin/sh

🔑 4. 핵심 교훈

❌ 흔한 착각들

1. “로컬에서 되면 Docker에서도 된다”
   • 경로, DB, 환경변수 모두 다름
2. “상대 경로가 편하다”
   • Docker에서는 절대 경로가 안전

     ✅ 권장 사항

3. 경로 처리는 항상 Paths.get().toAbsolutePath().normalize() 사용

4. 충분한 로그 남기기 (Docker 디버깅은 로그가 생명)

   📚 관련 파일 목록

   • src/main/resources/application-prod.yml - Docker 환경 설정
   • docker-compose.yml - Docker 구성
   • Dockerfile - 이미지 빌드 설정