배포 장애 대응: JWT 환경변수 강제화 및 Swagger 서버 분리

1. 개요

이번 서버 리팩토링 이후 새로운 배포 과정에서 다음 두 가지 운영 이슈가 발생하였다.

1. JWT 관련 필수 환경변수 미설정으로 인한 애플리케이션 부팅 실패
2. Swagger 서버 URL이 로컬 환경으로 고정되어 발생한 실행 혼선

본 문서는 각 이슈에 대해 장애 증상, 원인 분석, 대응 조치 및 재발 방지 방안을 정리하여,
향후 유사 장애 발생 가능성을 최소화하는 것을 목적으로 한다.

---

2. 장애 원인 ①

JWT 환경변수 누락으로 인한 애플리케이션 기동 실패

2.1 장애 증상

배포 이후 애플리케이션이 정상적으로 기동되지 않았으며,
Coolify 로그 상에서 다음 에러가 반복적으로 출력되었다.

 

Error: JWT_SECRET is required

해당 에러로 인해 컨테이너가 지속적으로 재시작되는 현상이 발생하였다.

---

2.2 원인 분석

• JWT 보안 강화를 목적으로, 기존에 존재하던 JWT Secret 기본값(fallback) 을 제거함
• JWT_SECRET, JWT_REFRESH_SECRET를 필수 환경변수(required) 로 변경
• 그러나 배포 환경(Coolify)에 해당 환경변수가 사전에 설정되지 않음
• 결과적으로 애플리케이션 초기화 단계에서 예외가 발생하며 부팅 실패

---

2.3 대응 조치

Coolify의 환경변수 설정에 아래 항목을 추가한 후 애플리케이션을 재시작하였다.

 

JWT_SECRET JWT_REFRESH_SECRET

---

2.4 조치 결과

• 애플리케이션 정상 기동 확인
• API 요청 및 인증 플로우 정상 동작 확인

---

3. 장애 원인 ②

Swagger 서버 URL 설정 혼선

3.1 장애 증상

배포 도메인에서 Swagger UI에 접근하여 API 요청을 실행할 경우,
서버 URL이 아래와 같이 로컬 주소로 고정되어 있었다.

 

http://localhost:3000

이로 인해 배포 환경에서 Swagger 테스트가 정상적으로 수행되지 않았다.

---

3.2 원인 분석

• Swagger 설정 파일 내 servers.url 값이 하드코딩되어 있었음
• 실행 환경(local / production)에 따른 서버 URL 분기가 고려되지 않음

---

3.3 개선 사항

Swagger 서버 URL을 환경변수 기반으로 동적으로 설정하도록 개선하였다.

 

servers: [ { url: process.env.BASE_URL, description: 'API Server', }, ];

---

3.4 개선 결과

실행 환경에 따라 Swagger 서버가 명확히 분리된다.

생각보다 이거를 빼먹는 가능성이 꽤 크다.

• Local 환경 
• => https//localhost:3000
• Production 환경
   => https://be.eternalmarketing.co.kr

Swagger UI에서의 API 실행 혼선이 해소되었으며,
환경 간 동작 차이가 명확해졌다.

---

4. 배포 환경 변수 정리 (Coolify 기준)

4.1 필수 환경변수 목록

아래 환경변수는 애플리케이션 정상 동작을 위해 반드시 설정되어야 한다.

 

 

JWT_SECRET

JWT_REFRESH_SECRET

DB_HOST

DB_NAME

DB_USER

DB_PASSWORD

DB_PORT

BASE_URL

NODE_ENV

 

---

5. Preview Environment vs Production Environment

5.1 Preview Environment

• PR 또는 브랜치 단위 테스트를 위한 임시 환경
• 운영 DB 및 운영 도메인과 반드시 분리되어야 함

5.2 Production Environment

• 실제 서비스 운영 환경
• 실서비스 DB 및 공식 도메인 사용

Preview 환경과 Production 환경을 혼용할 경우
데이터 오염 및 치명적인 운영 장애로 이어질 수 있으므로
환경 분리는 필수 운영 원칙으로 유지해야 한다.

---

결론

본 장애는 “보안 강화를 위한 코드 변경 → 배포 환경 변수 미적용” 으로 인해 발생한전형적인 운영 이슈였다.

 

이번 사례를 통해 다음 사항을 재확인하였다.

• 배포 자동화뿐만 아니라
  환경변수 관리 및 검증 프로세스의 중요성
• 보안 관련 변경 사항은
  코드 변경과 운영 설정이 반드시 함께 반영되어야 함

향후에는 사측 고객 데이터베이스 보안을 위하여, 또한 필수 환경변수 검증과 배포 절차적 방어를 강화하여
동일 유형의 장애를 사전에 차단하는 방향으로 운영하도록 하겠다.