systemd 서비스가 배포 후 시작 안 될 때

Linux 서버에서 systemd로 관리하는 서비스가 배포 후 시작 안 되면 정말 답답하다. 에러 메시지가 명확하지 않을 때도 많다. 이런 상황을 체계적으로 진단하는 방법을 정리했다.

서비스 상태 먼저 확인하기

서비스가 실행 중인지, 아니면 실패한 상태인지부터 본다. 상태별로 다음 확인 사항이 달라진다.

• 먼저 볼 값: systemd 서비스 상태(active/failed/inactive)
• 같이 비교할 값: 배포 전의 정상 상태
• 기록해둘 것: 서비스 시작 시간, 실패 메시지, 최근 변경 사항

systemd 명령어로 상태 확인하기

# 서비스 상태 확인
sudo systemctl status myservice

# 상세한 로그 보기
sudo journalctl -u myservice -n 50

# 실시간 로그 따라가기
sudo journalctl -u myservice -f

서비스 파일의 경로와 권한 확인

serviceD가 실행할 파일이나 스크립트가 존재하는지, 그리고 권한이 올바른지 확인한다. 파일이 없거나 읽기 권한이 없으면 서비스가 시작되지 않는다.

# 서비스 파일 위치 확인
sudo systemctl show -p FragmentPath myservice

# 실행 파일 존재 확인
ls -la /path/to/executable

# 소유권과 권한 확인
stat /path/to/executable

서비스 파일 내용 확인

.service 파일에서 ExecStart 명령이 정확한지, 작업 디렉토리가 맞는지 본다. 배포 후 경로가 바뀌었다면 서비스 파일도 수정해야 한다.

# 서비스 파일 보기
sudo cat /etc/systemd/system/myservice.service

# 또는 systemctl에서
sudo systemctl cat myservice

환경 변수와 의존성 확인

서비스가 필요로 하는 환경 변수가 설정되어 있는지 확인한다. 특히 After= 또는 Requires= 지시어로 다른 서비스에 의존한다면, 그 서비스들이 먼저 시작되어야 한다.

# 서비스 의존성 확인
sudo systemctl list-dependencies myservice

서비스 리로드와 재시작

serviceD 파일을 수정했다면, 데몬을 리로드한 다음 서비스를 재시작해야 한다.

# 데몬 리로드
sudo systemctl daemon-reload

# 서비스 재시작
sudo systemctl restart myservice

# 서비스 활성화 (부팅 시 자동 시작)
sudo systemctl enable myservice

디스크 공간과 파일 디스크립터 확인

드물지만, 디스크가 가득 차거나 열 수 있는 파일 수 제한이 가득 차도 서비스가 시작 안 될 수 있다.

# 디스크 사용량
df -h

# 파일 디스크립터 제한
ulimit -n

배포 스크립트에서 체크하기

배포할 때 서비스 상태를 자동으로 확인하는 스크립트를 만들면, 문제를 빨리 알 수 있다.

#!/bin/bash
npm run build
sudo systemctl restart myservice
sleep 2
if ! sudo systemctl is-active --quiet myservice; then
  echo "Service failed to start!"
  sudo journalctl -u myservice -n 20
  exit 1
fi

systemd 서비스 문제는 로그를 꼼꼼히 읽는 것이 가장 중요하다. 로그에서 '권한 거부', '파일 없음', '포트 사용 중' 같은 구체적인 에러 메시지가 나온다. 그 메시지에 따라 다음 확인 사항이 결정된다.