Next.js 빌드 아티팩트 드리프트 복구 플레이북

배포 직후에 가장 혼란스러운 상황은 “같은 커밋을 올렸는데 인스턴스마다 화면이 다르다”는 제보가 동시에 들어오는 순간입니다. 지난달 우리 팀은 결제 완료 페이지에서 정확히 이 문제를 겪었습니다. 일부 Pod에서는 새 문구가 보였고, 다른 Pod에서는 이전 문구와 구 버전 API 경로를 계속 호출했습니다. 처음엔 CDN 캐시 문제라고 보고 무효화를 반복했지만, 15분이 지나도 증상이 섞여 나왔고 에러 비율만 더 올라갔습니다. 나중에 보니 원인은 코드가 아니라 빌드 아티팩트 드리프트였습니다. CI 캐시가 꼬인 상태에서 next build 산출물이 런너마다 다르게 생성됐고, 이미지 최적화 관련 환경값도 런타임에 부분 적용돼 결과가 갈렸습니다. 이때 핵심은 “사용자 증상”을 먼저 줄이는 것보다 “분기점”을 정확히 잡는 것입니다. 서비스 레벨에서 동일 라우트 응답 해시를 수집해 노드별로 비교하면, 네트워크 이슈인지 산출물 이슈인지 5분 내로 분리할 수 있습니다.

판단 기준은 네 가지를 고정해두면 흔들리지 않습니다. 첫째, 동일 경로의 HTML/JS 응답 ETag가 노드마다 다른지 확인합니다. 둘째, 각 노드의 BUILD_ID와 정적 파일 경로(/_next/static/...)가 일치하는지 비교합니다. 셋째, 런타임 환경 변수 스냅샷을 배포 시점과 대조해 누락 키를 찾습니다. 넷째, 오류가 특정 기능이 아니라 특정 노드에 몰리는지 본 뒤 로드밸런서 분포를 겹쳐 봅니다. 우리 팀은 이 네 항목을 대시보드 한 화면에 묶어두고, 두 항목 이상 불일치가 나오면 즉시 드리프트 모드로 전환합니다. 여기서 자주 하는 실수는 “일단 재배포하면 맞겠지”라는 기대로 파이프라인을 연속 실행하는 겁니다. 실제로는 오염된 캐시가 그대로 재사용돼 불일치가 유지되는 경우가 많고, 오히려 정상 노드까지 흔들립니다. 저는 이 단계에서 재배포 횟수를 1회로 제한하고, 실패 시 즉시 캐시 키 강제 변경과 클린 빌드로 전환하는 규칙을 운영합니다.

실행 절차는 트래픽 보호와 기술 복구를 분리해야 안정적입니다. 먼저 트래픽 보호 단계에서 문제 노드를 풀에서 제거하고, 읽기 중심 페이지는 짧은 TTL의 임시 캐시를 적용해 사용자 체감 오류를 줄입니다. 동시에 주문·결제처럼 상태 변경이 있는 엔드포인트는 기능 플래그로 신규 경로를 잠시 닫아 데이터 불일치를 막습니다. 다음으로 기술 복구 단계에서 클린 워크스페이스로 아티팩트를 다시 만들고, 산출물 해시를 배포 전후 비교해 일치한 빌드만 승격합니다. 이때 “롤백 vs 전진 배포” 결정을 감으로 하지 않기 위해, 우리 팀은 10분 기준으로 의사결정합니다. 10분 안에 해시 불일치 원인이 캐시인지 환경값인지 확정되면 전진 배포, 아니면 직전 안정 아티팩트로 롤백 후 원인 분석을 이어갑니다. 실제 사고 때도 이 기준으로 롤백을 먼저 택했고, 결제 실패율을 3.8%에서 0.6%까지 12분 만에 낮췄습니다. 회의에서 가장 도움이 된 문장은 “원인 미확정 상태의 수정 배포는 금지”였습니다.

복구 후 운영 체크리스트는 다음 장애의 비용을 결정합니다. 저는 종료 전에 반드시 다섯 가지를 남깁니다. 첫째, 장애 시간대별 노드 응답 해시 샘플. 둘째, 캐시 키·빌드 옵션·환경 변수의 차이점 표. 셋째, 효과 없었던 액션과 중단 기준. 넷째, 롤백 판단 시각과 승인자. 다섯째, 재발 방지를 위한 파이프라인 수정 항목입니다. 특히 next build 이전에 의존성 잠금 파일 검증, 빌드 컨테이너 이미지 다이제스트 고정, 배포 게이트에서 BUILD_ID 전 노드 일치 검사를 넣어두면 같은 장애가 크게 줄어듭니다. 마지막 주의사항은 “문제 재현이 됐다고 바로 해결로 착각하지 말 것”입니다. 재현은 원인 후보를 줄이는 단계일 뿐, 운영에서 중요한 건 사용자를 안전한 경로로 빨리 돌려놓는 것입니다. 그래서 런북에는 기술 설명보다 의사결정 순서, 중단 조건, 커뮤니케이션 문구를 더 구체적으로 적어두는 편이 실제 현장에서 훨씬 강력합니다. 운영 채널에 남기는 첫 공지 템플릿까지 미리 정해두면 혼선이 더 줄어듭니다.