서버 배포 환경에서만 터지는 연결 문제 디버깅하기

로컬에서 괜찮던 설정이 배포 환경에서는 다르게 보일 수 있다. 서버에서만 문제가 터질 때는 단편적으로 한 가지만 붙잡지 말고, 운영 환경 전체 흐름에서 원인을 좁혀나가야 한다.

먼저 확인할 것: 포트와 방화벽

가장 기본이면서도 자주 놓치는 게 포트 상태다. 애플리케이션이 실제로 어느 포트에서 리슨하고 있는지부터 확인하자.

sudo ss -lntp

이 명령으로 현재 바인딩된 포트를 모두 볼 수 있다. 예상한 포트가 없다면 애플리케이션이 실행되지 않았거나 다른 포트에서 실행 중일 가능성이 높다.

서버 상태 파악: 디스크와 메모리

다음으로 서버의 리소스 상태를 점검한다.

df -h
free -h

디스크가 꽉 찼거나 메모리 부족이 원인일 수도 있다. 특히 데이터베이스 연결이나 파일 작성에서 자주 만난다.

로그 확인: 시스템 메시지와 애플리케이션 로그

시스템 저널에서 최근 에러 메시지를 본다.

sudo journalctl -n 80

HTTP 상태 코드나 에러 문구는 화면만 보고 판단하면 놓치는 게 많다. 로그, 응답, 설정 중 최소 하나는 증거로 잡아야 원인을 정확히 찾을 수 있다.

권한 확인: 파일과 디렉토리 접근권

배포 후 권한 문제로 막히는 경우가 흔하다.

ls -la /path/to/app
sudo systemctl status app-name

권한이 애매하면 다른 부분을 어떻게 고쳐도 결과가 바뀌지 않는다. 특히 Docker나 systemd를 사용할 때는 실행 사용자를 정확히 확인해야 한다.

검증 순서 정하기

다음 번 비슷한 증상이 나오면 이 순서를 고정해서 진행하자:

1. 원래 증상이 같은 조건에서 다시 나는지 재현한다.
2. 로그나 응답에서 바뀐 부분을 한 줄로 설명할 수 있어야 한다.
3. 공개 화면, 빌드 결과, 실제 요청 중 최소 하나로 마지막 확인을 한다.

작은 확인이 쌓이면 원인 후보가 자연스럽게 줄어든다. 관련 기록을 짧게라도 남겨두면 다음 확인이 훨씬 빨라진다.