[seohyun27]

#️⃣ 연관된 이슈

Related #48 (배포 워크플로 실패 표시·동시 배포 문제), #40 (DB 스키마 변경)

#️⃣ 작업 내용

2026-10-14 운영 서버 장애를 대응하며 서버에서 직접 수행한 조치를 infra/ec2/README.md에 절차서로 정리했습니다.
문서만 변경하며, 애플리케이션 코드와 배포 동작에는 영향이 없습니다.

배경: 2026-10-14 장애 대응 요약

증상

• 10-12에 머지한 [Bug] 생성·구간 재생성 요청 API가 HTTP 202로 응답하도록 수정 (#38) #43, [Bug] 구간 재생성 반복 시 곡 이름이 30자를 넘어 500이 나는 문제 수정 (#44) #45, #47이 운영에 반영되지 않음 (Actions는 모두 성공 표시)

원인

1. 배포 두 건이 동시에 실행되면서 Created 상태의 임시 컨테이너(0f7482c38e11_humix-backend-prod 등)가 남아, 이후 배포가 이름 충돌로 실패
2. 디스크 8GB 중 여유 1.2GB로 AI 서버 이미지 빌드 중 No space left on device
3. 배포 스크립트가 중간 실패를 성공으로 표시해 발견이 늦어짐 → [Fix] 배포 워크플로가 실패해도 성공으로 표시되고 동시 배포가 충돌함 #48 PR에서 수정

서버에서 수행한 조치 (순서대로)

1. Created 상태 임시 컨테이너 2개 삭제
2. 사용하지 않는 Docker 이미지 정리 (약 1.7GB 확보)
3. 스왑 2GB 추가 (메모리 1.8GB, 기존 스왑 없음)
4. PR [Feat] 음악 버전 목록 조회·되돌리기 API 추가 (#26) #40 스키마 변경(duration_seconds DOUBLE, root id 추가) 반영을 위해 DB 백업 후 초기화
   • 백업: 서버 ~/backup_20261014.sql
5. 스왑 파일로 디스크가 다시 부족해져 EBS 볼륨 8GB → 20GB 확장 (growpart, xfs_growfs)
6. 서버에서 docker-compose로 수동 배포

알게 된 점

• 서버에는 docker compose(v2)가 없고 docker-compose(v1)만 설치되어 있음
• ddl-auto: update는 빈 DB에 테이블은 만들어 주지만, 기존 컬럼 타입은 바꾸지 않음
• 배포마다 이미지를 서버에서 빌드하므로 디스크 여유가 최소 3GB 필요
• EC2 콘솔 볼륨 목록에서 체크박스를 선택해야 "작업" 메뉴가 활성화됨

README 변경 사항

• 서버 구조: AI 서버, DB 컨테이너와 배포 경로 추가
• 서버 사양 표 추가: 메모리, 스왑, EBS 크기, Docker Compose 버전
• 트러블슈팅 절차 4개 추가
• 장애 기록에 2026-10-14 건 추가

README 사용법 (증상별로 보는 곳)

상황	README에서 볼 섹션
Actions는 성공인데 서버에 반영이 안 됨	트러블슈팅 → 배포 후 서버가 바뀌지 않을 때
배포 로그에 No space left on device	트러블슈팅 → 디스크 공간이 부족할 때
서버를 새로 만들었거나 빌드 중 서버가 멈춤	트러블슈팅 → 메모리가 부족할 때 (스왑 설정)
엔티티 타입 변경 등으로 DB를 다시 만들어야 함	트러블슈팅 → DB 스키마 변경으로 DB를 초기화해야 할 때
브라우저에 인증서 경고	트러블슈팅 → net::ERR_CERT_DATE_INVALID
서버 사양이나 구조가 궁금함	서버 구조, 서버 사양

각 절차는 위에서부터 순서대로 실행하면 되도록 작성했습니다. 서버 접속 후 명령어를 그대로 복사해 사용할 수 있습니다.

#️⃣ 테스트 결과

문서에 적은 명령어는 2026-10-14 운영 서버에서 실제로 실행해 확인했습니다.

• 수동 배포 후 humix-backend-prod, humix-ai-cpu-prod 컨테이너 재생성 및 Started ApiApplication 확인
• DB 테이블 4개 자동 생성 확인 (humming, melody_score, member, music_generation)
• EBS 확장 후 df -h / 결과: Size 20G, Avail 14G
• 스왑 적용 후 free -h 결과: Swap 2.0Gi

#️⃣ 셀프 체크리스트

• (Server) 로컬 환경에서 정상적으로 빌드되나요? → 해당 없음 (문서 변경)
• (Server) 예시 데이터를 통해 테스트를 마쳤나요? → 해당 없음
• (Client) 화면이 깨지지 않고 렌더링되나요? → 해당 없음
• Swagger 문서가 최신화되었나요? (API 변경 시) → 해당 없음
• 코드 컨벤션을 준수했나요?

#️⃣ 리뷰 요구사항

• 서버에 직접 수행한 조치라 코드 리뷰보다 문서 내용 확인 위주로 봐주시면 됩니다.
• 공개 레포라 DB 비밀번호는 <비밀번호>로 표기했습니다.
• 앞으로 서버에 직접 설정을 바꾸면 infra/ec2/README.md의 서버 사양과 장애 기록도 함께 갱신해 주세요.

📎 참고 자료 (Optional)

• 장애 대응 기록: [Fix] 배포 워크플로가 실패해도 성공으로 표시되고 동시 배포가 충돌함 #48 코멘트
• EBS 볼륨 크기 조정 후 파일 시스템 확장 (AWS 문서)