엔터프라이즈급 글로벌 서비스를 운영하면서 레거시 인프라를 새로운 아키텍처로 이전하는 작업은 ‘시속 100km로 달리는 자동차의 바퀴를 교체하는 것’만큼이나 리스크가 크다. 데이터 유실이나 서비스 중단은 비즈니스에 치명적인 타격을 입히기 때문에, 완벽한 하위 호환성과 안전장치를 확보하는 것이 마이그레이션 엔지니어링의 핵심이다.
최근 진행된 ‘translation-manager’ 프로젝트의 17번째 스프린트에서는 레거시 Supabase 환경에서 SQLite 프로바이더로 데이터를 안전하게 이전하기 위한 ‘Pilot Migration 시스템’을 완전히 구축하고 성공적으로 배포를 마쳤음.
이 과정에서 정립한 4단계 롤아웃 전략, Feature Flag 설계, 그리고 유기적인 리팩토링 및 트러블슈팅 노하우를 상세히 공유한다.
1. 리스크 최소화를 위한 4단계 마이그레이션 롤아웃 전략
시스템을 한 번에 전환하는 빅뱅(Big-Bang) 방식의 마이그레이션 위험성을 배제하기 위해, 인프라의 안정성을 검증하며 단계적으로 권한을 이양하는 4단계 아키텍처 파이프라인을 수립하였음.
1. Shadow Mode (섀도우 모드): 모든 쓰기(Write) 작업을 레거시와 신규 프로바이더에 병렬로 실행하되, 결과만 상호 비교하고 사용자에게는 기존 레거시 시스템의 결과만 반환하여 실데이터 정합성을 검증함.
2. Dark Launch (다크 런치): 읽기(Read) 작업을 두 인프라에서 병렬로 수행하여 데이터 조회 속도 및 반환 값의 일치 여부를 모니터링 시스템 모듈에서 검증함.
3. Dual Write (이중 쓰기): 두 데이터베이스에 동시에 쓰기 작업을 수행하며 복구 큐(Queue)를 가동하되, 여전히 레거시 시스템을 최종 진실의 소스(Source of Truth)로 판정함.
4. Full Cutover (전체 전환): 신규 프로바이더(SQLite)만을 메인 엔진으로 전격 사용하며, 예기치 못한 에러 발생 시에만 레거시 인프라로 폴백(Fallback)되도록 차단벽을 형성함.
2. 유연한 제어를 위한 Feature Flag 및 런타임 우선순위 엔진 설계
코드 수정과 재배포 없이 프로덕션 배포 환경에서 시스템 흐름을 즉각 통제할 수 있도록 10개의 핵심 피처 플래그(Feature Flag) 시스템을 아키텍처 단에 이식하였음
1. 핵심 플래그 정의:
USE_SQLITE_REPOSITORY,SQLITE_DUAL_WRITE_MODE,SQLITE_SHADOW_MODE등을 선언하여 인프라 분기를 미세 조정함.2. 계층형 우선순위 알고리즘: 환경 변수 셋과 Admin API를 통한 런타임 설정 간의 충돌을 방지하기 위해
isEnabled()제어 함수 내부에FULL_CUTOVER>DUAL_WRITE>SHADOW_MODE>DARK_LAUNCH순의 엄격한 실행 우선순위를 부여하였음.
3. JSON 데이터 정규화를 통한 결과 비교 엔진 구현
두 시스템의 반환 데이터를 실시간으로 비교 검증하기 위해, 자바스크립트의 고유 특성인 Date 객체 참조계 차이로 인한 오탐을 방지하는 정규화 비교 함수를 도입하였음.
4. 기술적 부채 해결: 인터페이스 충돌 해소 및 Next.js 15 패치
인프라 공급자를 동적으로 갈아끼우는 프로바이더 패턴(Provider Pattern)과 레포지토리 패턴(Repository Pattern)을 구현하는 과정에서, 다수의 백엔드 인터페이스 규격이 충돌하는 기술적 병목이 발생하였음.
ㄱ. 인터페이스 확장 시그니처 충돌 해결
추상화된 고수준 레포지토리와 구체적인 SQLite/Supabase 구현체 간에 create() 메서드의 인자 값 및 시그니처가 불일치하여 컴파일 단계에서 빌드 크래시가 관측되었음.
해결 방안: 상속 구조에서 발생하는 모호성을 제거하기 위해 단일
create명칭을 도메인이 명확히 드러나는 형태로 우회 설계하였음.명세 교정:
IAuditableRepository와의 충돌을 피하기 위해IExtendedTranslationAuditRepository내 메서드를createAndReturn()으로 명명하고, 용어집 오딧 관련 함수를createGlossaryAuditLog()로 정밀 격리하여 정적 타입 시스템의 명확성을 확보하였음.
5. Next.js 15 Request Handler 비동기 파라미터 컨텍스트 대응
프레임워크 버전 업그레이드에 따라 라우트 핸들러의 context.params 인자가 Promise 스펙으로 변경되면서 기존 코드 전반에 타입 에러가 발생하였음.
이와 같은 프론트엔드·백엔드 코어 단의 19개 핵심 타입 오류를 전수 교정함으로써 컴파일러 경고가 전혀 없는 ✓ Compiled successfully 빌드 클린 상태를 이룩하였음.
6. 시스템 안정성 요약 및 운영 SOP 구축
8시간의 고집중 스프린트를 통해 총 20개의 마이크로 커밋이 완전 무결하게 마스터 브랜치에 안착하였음. 롤백 플레이북(ROLLBACK_PLAYBOOK.md), 안전 롤아웃 계획서(SAFE_ROLL_OUT_PLAN.md), 데이터 및 보안 운영 정책서 등 총 14종의 고품질 표준 운영 절차(SOP) 문서를 패키징하여 팀 온보딩 비용을 획기적으로 낮추었음.
종합 테스트 통과율 94.1% (528/561)를 기점으로 든든한 안정장치를 확보한 데이터 파이프라인은 향후 섀도우 모드 활성화를 시작으로 대규모 엔터프라이즈 인프라 이전을 차질 없이 수행할 준비를 마쳤음