플랫폼에는 롤백 성공으로 표시되지만 이전 코드가 새 데이터베이스 구조를 읽지 못한다면, OpenShip 롤백은 생산 복구에 실패한 것입니다. 가장 빠른 해법은 버튼을 누르는 데서 끝내지 않고, 이전 산출물·설정·데이터베이스·트래픽·백그라운드 작업을 함께 검증하는 것입니다.
이 글은 OpenShip으로 AI SaaS, 관리자 서비스, Agent API를 생산 배포하려는 팀을 위한 내용입니다. 롤백 증거와 승인 절차를 만들어야 하는 운영 담당자, 데이터베이스와 Worker를 함께 운영하는 개발자에게 특히 적합합니다.
버튼 성공과 서비스 복구를 분리해서 판정해야 합니다
OpenShip 공식 페이지는 배포를 변경할 수 없는 스냅샷으로 만들고, 이전 버전을 롤백 대상으로 유지하며, 건강 검사와 트래픽 전환을 제공한다고 설명합니다. 다만 이는 플랫폼 기능에 대한 설명입니다. 애플리케이션 데이터와 외부 서비스까지 자동으로 과거 상태로 돌아간다는 뜻은 아닙니다. (openship.io)
생산 승인 전에 아래 세 층위를 분리해 기록해야 합니다.
| 판정 층위 | 확인할 대상 | 통과 기준 | 실패했을 때 |
|---|---|---|---|
| 플랫폼 상태 | 롤백 작업 상태, 배포 식별자, 실행 로그 | 대상 버전이 선택되고 새 인스턴스가 시작됨 | 배포 로그와 대상 버전을 보존하고 재시도하지 않음 |
| 컨테이너 상태 | 시작 명령, 포트, 건강 검사 | 새 인스턴스가 정상 응답하고 검사 경로가 통과함 | 트래픽을 보내지 않고 시작 로그 확인 |
| 업무 상태 | 로그인, 결제, 핵심 API, 스트리밍, 작업 처리 | 실제 사용자의 핵심 요청과 부작용이 정상임 | 신규 트래픽 차단, 데이터 복구 담당자 호출 |
여기서 팀이 먼저 정해야 할 것은 복구 목표입니다. 어떤 API를 핵심 경로로 볼지, 읽기 전용으로 낮춰도 되는지, 스트리밍 연결을 다시 맺게 해도 되는지, 데이터 중복이 허용되는지를 문서로 남겨야 합니다. 복구 시간이나 허용 오류율을 임의의 업계 기준으로 쓰지 말고, 프로젝트 요구사항이나 기존 운영 기록을 근거로 정해야 합니다.
첫 번째 확인: 이전 산출물이 실제로 다시 실행되는가
OpenShip은 배포 때 버전이 붙은 산출물을 만들고, 새 컨테이너를 시작하는 흐름을 설명합니다. 따라서 롤백 테스트의 핵심은 “남아 있던 이전 컨테이너가 살아 있는가”가 아니라 “새 인스턴스에서 같은 버전이 다시 실행되는가”입니다. (openship.io)
다음 순서로 확인합니다.
- 롤백 대상 버전의 커밋 식별자와 이미지 식별자를 기록합니다.
- 해당 이미지와 의존성 파일을 새 실행 환경에서 가져올 수 있는지 확인합니다.
- 기존 컨테이너를 중지한 뒤 새 인스턴스에서 대상 버전을 시작합니다.
- 시작 명령, 포트, 작업 디렉터리, 런타임 버전을 배포 로그와 대조합니다.
- 새 인스턴스에서 핵심 API를 호출하고 응답 결과를 저장합니다.
공식 설치 문서는 자체 운영 환경의 최소 기준으로 2코어, 메모리 2GB, 디스크 20GB를 제시합니다. 이는 애플리케이션의 생산 권장 사양이 아니라 플랫폼 설치 기준이므로, 롤백 검증에서는 실제 서비스가 필요한 자원과 별도로 기록해야 합니다. (openship.io)
통과 증거: 버전 식별자, 새 인스턴스 생성 기록, 시작 로그, 핵심 API 응답입니다.
실패 동작: 이미지가 없거나 의존성을 다시 받을 수 없다면 롤백을 반복하지 말고, 마지막 정상 산출물을 별도로 보존한 뒤 배포 담당자에게 원인을 넘깁니다.
OpenShip 롤백이 환경 변수를 되돌린다고 가정하면 안 됩니다
코드만 이전 버전으로 돌아가고 환경 변수는 새 버전 그대로라면, 애플리케이션은 정상 실행처럼 보이면서 잘못된 외부 서비스에 연결할 수 있습니다. OpenShip은 환경 범위별 비밀값과 설정 관리를 제공한다고 설명하지만, 특정 프로젝트의 이전 시점 설정이 자동으로 업무적으로 맞는지까지는 별도 검증이 필요합니다. (openship.io)
롤백 전후로 다음 항목을 비교합니다.
- 환경 변수의 이름과 적용 범위
- 비밀값의 버전 또는 갱신 시점
- 외부 API 주소와 데이터베이스 주소
- 인증서, 토큰, 권한 만료 상태
- 저장소와 큐의 이름
- 기능 플래그와 모델 선택 설정
민감한 값 자체를 배포 기록에 남기면 안 됩니다. 값의 해시, 버전 식별자, 마지막 변경 시각만 기록합니다.
| 설정 검증 항목 | 기록할 증거 | 통과 기준 | 실패 조치 |
|---|---|---|---|
| 환경 변수 | 적용 버전, 범위, 변경 기록 | 대상 코드가 기대하는 이름과 값의 버전이 일치함 | 이전 설정 묶음으로 복원 후 재검사 |
| 비밀값 | 해시 또는 버전 | 권한이 살아 있고 대상 서비스에 접근 가능함 | 새 키 발급 또는 권한 복구 |
| 외부 주소 | 서비스 이름과 주소 | 이전 코드가 새 서비스로 잘못 연결되지 않음 | 라우팅과 주소를 수동으로 되돌림 |
| 기능 플래그 | 플래그 상태 기록 | 이전 코드가 이해하지 못하는 기능이 꺼져 있음 | 호환 가능한 플래그로 변경 |
특히 OpenShip 롤백 중에는 코드와 설정의 변경 시점이 다를 수 있습니다. 배포 기록에 “코드 버전”만 적지 말고 “설정 버전”도 같은 행에 기록해야 합니다.
두 번째 확인: 데이터베이스 마이그레이션은 별도 복구 대상입니다
데이터베이스 마이그레이션이 끝난 뒤에도 애플리케이션 롤백은 가능합니다. 단, 이전 코드가 새 스키마를 읽을 수 있어야 합니다. 반대로 열 삭제, 형식 변경, 필수 값 추가처럼 되돌리기 어려운 변경이 있었다면 애플리케이션 롤백만으로는 복구가 끝나지 않습니다.
OpenShip 공식 페이지는 PostgreSQL과 여러 저장 서비스를 제공하고 백업 기능을 설명하지만, 배포 산출물의 롤백과 데이터베이스 시점 복구는 서로 다른 작업으로 봐야 합니다. (openship.io)
마이그레이션은 다음 세 종류로 나눠 승인합니다.
- 가역 변경: 새 필드 추가처럼 이전 코드가 무시할 수 있는 변경입니다.
- 하위 호환 변경: 새 코드와 이전 코드가 잠시 함께 실행되어도 읽기와 쓰기가 가능한 방식입니다.
- 파괴적 변경: 필드 삭제, 타입 변경, 데이터 변환처럼 이전 코드가 더 이상 처리하지 못할 수 있는 변경입니다.
생산 테스트에서는 최소한 다음을 실행합니다.
- 새 스키마에 이전 코드가 접속합니다.
- 핵심 읽기 API와 쓰기 API를 각각 호출합니다.
- 새 코드와 이전 코드가 같은 데이터 행을 교차 처리합니다.
- 마이그레이션 로그와 오류 로그를 저장합니다.
- 파괴적 변경이면 별도 백업에서 복원한 데이터베이스로 복구 절차를 재현합니다.
주의: 애플리케이션을 이전 버전으로 돌리는 행위는 데이터베이스를 자동으로 과거 시점으로 되돌리는 행위가 아닙니다. 백업 복구를 주장하려면 복원된 데이터베이스, 복원 로그, 검증 쿼리라는 독립 증거가 필요합니다.
세 번째 확인: 건강 검사 뒤에 실제 트래픽을 전환해야 합니다
건강 검사가 통과했다는 것은 지정된 검사 경로가 응답했다는 뜻입니다. 사용자의 로그인, 긴 응답, WebSocket 연결, 외부 도구 호출이 모두 정상이라는 의미는 아닙니다. OpenShip은 건강 검사, 가중치 라우팅, 고정 세션, WebSocket 지원을 기능으로 소개하므로, 서비스 유형에 맞는 실제 검사를 추가해야 합니다. (openship.io)
검증 대상은 세 갈래로 나눕니다.
- 일반 HTTP: 인증, 핵심 조회, 쓰기 요청, 오류 응답
- 스트리밍: AI 응답이 중간에 끊기지 않는지, 재연결이 가능한지
- 장기 연결: WebSocket 세션이 이전 인스턴스에 남아 있거나 새 인스턴스로 정상 이동하는지
트래픽 전환 전후에 요청 식별자, 상태 코드, 응답 본문 요약, 오류 로그를 저장합니다. “대시보드가 정상”이라는 한 줄만으로 무중단을 판정하지 않습니다. 공식 페이지의 무중단 배포 설명도 팀 서비스의 모든 연결 유형에서 같은 결과를 보장하는 실측 자료는 아닙니다. (openship.io)
네 번째 확인: 백그라운드 작업은 중복 실행을 입증해야 합니다
OpenShip은 예약 작업, 재시도, 실행별 로그를 제공한다고 설명합니다. 그러나 새 버전과 이전 버전이 잠시 함께 실행되면 예약 작업이나 큐 소비자가 같은 작업을 두 번 처리할 수 있습니다. (openship.io)
검증할 때는 성공 여부보다 부작용을 확인합니다.
- 작업 식별자가 한 번만 완료됐는가
- 큐 메시지의 상태가 중복으로 바뀌지 않았는가
- 이메일, 결제, 파일 생성, 외부 도구 호출이 두 번 발생하지 않았는가
- 재시도 이후에도 같은 결과를 유지하는가
- Worker를 중지했을 때 새 메시지가 쌓이는가
중복이 발견되면 즉시 소비자를 멈추고, 처리 중인 작업과 완료된 작업을 분리합니다. 이미 외부 부작용이 발생했다면 중복 취소나 보상 처리를 실행합니다. 이 절차와 담당자를 배포 기록에 미리 적어 두지 않으면, 장애 중에 같은 작업을 다시 실행하는 실수가 생깁니다.
생산 배포 전에는 이 순서로 검증하십시오
아래 목록은 OpenShip 롤백을 승인하기 위한 최소 실행 목록입니다.
- [ ] 롤백 대상 버전의 커밋 식별자와 산출물 식별자를 기록했습니다.
- [ ] 기존 컨테이너가 아닌 새 인스턴스에서 대상 버전을 시작했습니다.
- [ ] 시작 명령, 포트, 의존성, 런타임 버전을 확인했습니다.
- [ ] 롤백 후 실제 적용된 환경 변수와 비밀값 버전을 대조했습니다.
- [ ] 외부 API 주소와 데이터베이스 주소가 이전 코드에 맞는지 확인했습니다.
- [ ] 새 스키마에서 이전 코드의 읽기 요청을 실행했습니다.
- [ ] 새 스키마에서 이전 코드의 쓰기 요청을 실행했습니다.
- [ ] 파괴적 마이그레이션이 있다면 별도 백업 복원을 실행했습니다.
- [ ] 일반 HTTP 요청의 전환 전후 결과를 저장했습니다.
- [ ] 스트리밍 응답과 WebSocket 연결을 확인했습니다.
- [ ] 예약 작업과 큐 소비자의 중복 실행 여부를 확인했습니다.
- [ ] 중복 발생 시 중지, 분리, 보상 처리 담당자를 지정했습니다.
- [ ] 승인자, 롤백 담당자, 데이터 복구 담당자를 배포 기록에 적었습니다.
최종 판정은 통과, 제한 승인, 배포 금지로 나누십시오
모든 항목을 이분법으로 처리하면 현장에서 위험한 타협이 생깁니다. 다음 세 가지 결론을 사용하십시오.
통과: 이전 산출물이 새 인스턴스에서 실행되고, 설정이 일치하며, 데이터베이스가 호환되고, 핵심 요청과 작업이 정상입니다.
제한 승인: 읽기 기능만 복구되거나, WebSocket 재연결이 필요하거나, 특정 작업을 일시 중지해야 합니다. 제한 범위와 해제 조건을 사용자 공지 및 운영 기록에 적습니다.
배포 금지: 이전 코드가 새 스키마를 읽지 못하거나, 산출물을 다시 구할 수 없거나, 비밀값 권한이 확인되지 않거나, 큐 작업의 중복 처리가 통제되지 않는 경우입니다.
생산 배포를 앞둔 팀이라면 최소 한 번은 의도적으로 잘못된 건강 검사, 호환되지 않는 설정, 읽기 전용 데이터베이스를 사용해 롤백 절차를 연습해야 합니다. 연습의 목적은 버튼이 작동하는지 확인하는 것이 아니라, 누가 언제 어떤 증거를 보고 트래픽과 데이터를 어떻게 통제하는지 확인하는 데 있습니다.
현재 로컬 환경에서만 이 절차를 수행하면 빌드 머신이 꺼지거나, 팀원이 같은 산출물을 재현하지 못하거나, 외부에서 접근할 검증 지점이 부족해질 수 있습니다. 반대로 Kvmzen의 한국 데이터센터 클라우드 맥 구성 안내를 이용하면 별도 Mac 환경에서 빌드와 임시 승인 테스트를 분리할 수 있습니다. SSH와 VNC 접속 절차가 필요한 경우에는 클라우드 맥 운영 지원 안내도 함께 확인할 수 있습니다. 다만 장기간 무거운 빌드를 계속 실행하거나 물리 장치 연결이 필요한 팀이라면 임시 대여보다 자체 장비가 더 적합합니다. 중요한 것은 OpenShip 롤백을 실제 생산과 같은 조건에서 한 번 끝까지 실행한 뒤, 그 기록을 다음 배포 승인에 재사용하는 것입니다.