배포 환경에서만 드러난 인증 흐름 오류 수정과 배포 자동화

배포 자동화 스크립트를 손보다가 인증 설정 버그도 같이 발견해서 한 커밋에 묶어 처리했다.

배경: 왜 두 가지가 한 커밋에 묶였나

publish.sh랑 auth.ts — 얼핏 보면 전혀 관계없는 두 파일이 같은 커밋에 들어가 있어서 의아할 수 있다. 근데 실제 맥락을 보면 자연스럽다. 자동화 배포 스크립트를 정리하면서 로컬이 아닌 실제 배포 환경에서 앱을 띄워봤고, 그때서야 NextAuth가 NEXTAUTH_URL을 못 잡거나 호스트 신뢰 문제로 인증 흐름이 통째로 깨지는 걸 확인했다. 배포 파이프라인을 직접 돌려보지 않으면 잘 안 드러나는 류의 문제였음.

팀에서 자동화 작업을 진행하다 보면 이런 경우가 생각보다 잦다. 인프라 레이어를 건드리면서 그동안 로컬 환경의 암묵적인 가정에 가려져 있던 설정 이슈가 수면 위로 올라오는 것. 이걸 그냥 다음 커밋으로 미루지 않고 묶어서 처리한 건 맞는 판단이었다고 본다.

trustHost: true — 이게 왜 필요한가

NextAuth v5는 v4 대비 호스트 검증을 훨씬 엄격하게 가져간다. 내부적으로 요청의 Host 헤더를 확인해서 신뢰할 수 없는 출처로 판단되면 콜백 자체를 막아버린다. 로컬에서 localhost로 돌릴 때는 별 문제가 없는데, 리버스 프록시나 컨테이너 환경, 혹은 커스텀 도메인 앞에 레이어가 하나 더 낀 배포 환경에서는 Host가 달라 보일 수 있어서 인증이 조용히 실패한다.

// src/lib/auth.ts
export const { handlers, signIn, signOut, auth } = NextAuth({
  trustHost: true,
  // ...providers, callbacks
});

trustHost: true는 이 호스트 검증을 우회하는 옵션이다. 프록시 뒤에서 동작하는 배포 환경이라면 거의 필수에 가깝다. 다만 이 옵션을 켜는 게 만능은 아니고, 그만큼 앞단 인프라(nginx, 로드밸런서 등)에서 신뢰할 수 없는 Host 헤더가 들어오지 않도록 통제가 되어 있어야 한다는 전제가 붙는다.

publish.sh 자동화

scripts/publish.sh는 배포 단계를 스크립트로 묶은 것이다. 수동으로 여러 명령어를 순서대로 치던 걸 하나의 진입점으로 통합한 형태. 규모가 작은 팀일수록 이런 스크립트 하나가 실질적인 생산성 차이를 만든다.

자동화 스크립트를 만들 때 내가 챙기는 포인트는 몇 가지 있다:

• 멱등성: 같은 스크립트를 두 번 돌려도 상태가 꼬이지 않을 것
• 실패 시 즉시 중단: set -e 또는 각 단계에 명시적인 에러 핸들링
• 로그 출력: 어느 단계에서 멈췄는지 바로 알 수 있게
• 환경 변수 검증: 필수 값이 빠져 있으면 스크립트 초반에 바로 죽도록

#!/bin/bash
set -euo pipefail

# 필수 환경 변수 검증
: "${DEPLOY_TARGET:?DEPLOY_TARGET is required}"

echo "[publish] 빌드 시작..."
# ... build / push / deploy 단계

set -euo pipefail 조합은 거의 관용구처럼 쓴다. 파이프라인 중간에서 뭔가 실패해도 그냥 넘어가지 않고 스크립트 자체가 죽어주기 때문에 "배포가 됐다고 착각하는" 상황을 막아준다.

회고

이번 작업에서 다시 확인한 건, 자동화를 실제로 돌려보는 것 자체가 테스트라는 점이다. 스크립트를 아무리 잘 짜도 실제 배포 환경에 붙이기 전까지는 로컬에서 보이지 않는 가정들이 숨어 있다. trustHost 이슈처럼 "왜 로컬에선 잘 됐지?"라는 질문이 나올 때는 거의 항상 환경 차이에서 답이 나온다.

팀원들이 이 스크립트를 처음 쓸 때 NextAuth 설정 때문에 삽질하지 않아도 된다는 게 이 작업의 실질적인 가치다. 버그를 고친 게 아니라 앞으로 발생할 삽질을 예방한 것.

다음

🛒 이 글과 어울리는 추천 상품

• 노트북 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 모니터암 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.