로컬에서 안 나는 버그가 서버에서만 터질 때

로컬과 서버 환경의 차이는 미묘하지만 치명적이다. 데이터베이스, 환경변수, 파일 시스템 권한, 네트워크 설정 등 여러 요인이 복합적으로 작용한다.

먼저 서버의 현재 상태를 기록하기

문제가 발생한 시점의 서버 상태를 스냅샷으로 남긴다. 이 정보가 없으면 나중에 원인을 추적하기 어렵다.

# 열려있는 포트 확인
sudo ss -lntp
# 디스크 상태 (저장공간 부족 문제 제외)
df -h
# 최근 시스템 로그
sudo journalctl -n 80

데이터베이스 상태가 다른가

로컬의 데이터와 서버의 데이터가 다를 수 있다. 테스트 데이터만 있는 로컬 DB에서는 정상이지만 실제 데이터가 들어간 서버 DB에서는 예상치 못한 케이스가 나타날 수 있다. DB에 접속해서 데이터 크기, 인덱스, 락 상태 등을 확인한다.

환경변수가 실제로 설정되어 있는가

서버에서만 특정 환경변수가 필요하다면 정말로 설정되어 있는지 확인한다. Docker 컨테이너라면 환경 변수가 제대로 전달되었는지, 설정 파일이 있다면 로드되는지 체크한다.

# 컨테이너 내에서 환경변수 확인
docker exec service-name env | grep -E 'APP_|API_'
# 또는 실행 중인 프로세스의 환경
cat /proc/$(pgrep -f app)/environ | tr '\0' '\n'

파일 권한과 경로

서버에서 파일을 읽거나 쓸 때 권한이 없거나 경로가 잘못되었을 수 있다. 로컬에서는 사용자 홈 디렉토리를 쓸 수 있지만 서버에서는 특정 경로만 접근 가능할 수 있다.

네트워크와 외부 서비스 호출

로컬에서는 외부 API가 빠르게 응답하지만 서버에서는 느리거나 타임아웃할 수 있다. 특히 외부 서버에 접근할 때 방화벽이나 프록시 설정이 필요할 수 있다. curl이나 telnet으로 실제 연결을 테스트한다.

해결 후 체크리스트

문제를 해결했다면:

1. 로컬과 서버에서 동시에 테스트
2. 변경 사항을 기록 (어떤 설정을 바꿨는지, 왜 바꿨는지)
3. 비슷한 문제가 다시 나올 때를 대비해 모니터링 설정

이런 기록들이 쌓이면 다음에 비슷한 환경 차이 문제를 훨씬 빠르게 해결할 수 있다.