업그레이드 절차 (evo 납품본)

이 문서는 납품 번들(evo-chat-<버전>.tar.gz, v0.1.4 까지는 evomind-chat-<버전>.tar.gz)에 UPGRADE.md 로 함께 들어 있다.

원칙

• 임의의 이전 버전에서 최신 버전으로 한 번에 올릴 수 있다. DB 스키마는 Flyway 가 앱 기동 시 미적용 마이그레이션(V<n>__*.sql)을 번호 순으로 모두 적용한다. 중간 버전을 거칠 필요가 없다.
• 이미 배포된 마이그레이션 파일은 수정하지 않는다(Flyway 체크섬 검증). 스키마 변경은 항상 새 V<n> 파일로 추가된다.
• Flyway Community 는 자동 롤백(undo)을 제공하지 않는다. 롤백 = 업그레이드 직전 DB 백업 복원 + 이전 이미지로 재기동이다. upgrade.sh 가 업그레이드 전에 백업을 만든다.
• 버전은 SemVer 다. MINOR/PATCH 는 하위 호환, MAJOR 는 호환을 깨는 변경(OpenAI 호환 API 계약 변경·설정/환경변수 제거·마이그레이션 선행 조건)을 뜻하며 릴리스 노트에 별도 절차를 적는다.

지원 매트릭스

현재 → 대상	방법	비고
0.1.x → 0.1.y (y 최신)	새 번들로 upgrade.sh 한 번	중간 버전 불필요
0.x → 1.0 이후 MAJOR	릴리스 노트의 MAJOR 업그레이드 절차	해당 릴리스에서 이 표에 행을 추가

현재 게시된 번들은 0.1.0 하나다. 이전 버전 설치본이 생기면 릴리스마다 이 표를 갱신한다.

절차 (Docker Compose)

1. 새 번들을 받아 무결성을 확인한다: sha256sum -c evo-chat-<버전>.tar.gz.sha256 (번들 내부는 upgrade.sh 가 sha256sums 로 다시 검증).
2. 새 번들을 이전 설치와 다른 디렉터리에 푼다: tar -xzf evo-chat-<버전>.tar.gz && cd evo-chat-<버전>.
3. 이전 설치의 .env 를 새 디렉터리로 복사한다(cp <이전>/.env .). 새 번들에 추가된 설정이 있으면 .env.example 과 비교해 반영한다.
4. 실행: ./upgrade.sh
   • 무결성 검증 → backups/evomind_chat-<시각>.sql.gz 로 DB 백업 → 새 이미지 로드 → 앱 컨테이너 재생성.
   • Compose 프로젝트 이름(evomind-chat)과 볼륨이 같아 데이터는 그대로 이어진다.
5. 앱이 healthy 가 되면 완료: docker compose ps. 로그에서 마이그레이션 적용 내역을 확인한다: docker compose logs app | grep -i flyway.
6. 화면 확인: 로그인 → 새 대화 → 응답. 버전 확인: /actuator/info 의 build.version.

롤백

1. docker compose down (볼륨은 유지).
2. DB 복원: 볼륨을 비우고(docker compose down -v — 데이터 삭제 주의) postgres 만 기동한 뒤 gunzip -c backups/<파일> | docker compose exec -T postgres psql -U evomind -d evomind_chat.
3. 이전 번들 디렉터리에서 docker compose up -d (이전 .env·이미지 사용).

장애 시 확인

• 앱이 계속 재시작: docker compose logs app — Flyway 오류(체크섬 불일치·실패한 마이그레이션)가 보이면 파일을 고치지 말고 백업 복원 후 지원 담당에 문의한다.
• .env 필수 값 누락: compose 가 어떤 변수가 비었는지 오류로 알려 준다.
• 폐쇄망: 번들만으로 동작한다(외부 접속 없음). LLM 연결은 관리자 화면에서 내부 엔드포인트로 등록하며, OpenAI 호환 주소는 /v1 까지 입력한다.