이 글에서는 디스코드 봇을 디스호스트에 호스팅할 때 사이트는 온라인으로 표시되지만 실제 봇이 접속하지 않거나 일정 시간(약 30초) 후 오프라인으로 전환되는 증상 원인과 해결 절차를 정리한다. 주로 엔트리 포인트 파일명과 런타임 예외로 인한 프로세스 크래시가 원인이다.
증상
- 디스호스트 관리 페이지에는 애플리케이션이 "온라인"으로 표시되지만 디스코드에서는 봇이 오프라인 상태.
- 관리 페이지에서 잠시(약 30초) 후 자동으로 상태가 "오프라인"으로 바뀜.
- 로그에 에러가 찍히거나 프로세스가 즉시 종료되는 패턴 관찰 가능.
원인
- 호스팅 플랫폼이 특정 엔트리 포인트 파일(예:
app.py)을 기준으로 프로세스를 시작하도록 설정돼 있는 경우, 실제 코드가 다른 파일(main.py)에 있으면 실행을 못해 프로세스가 시작되지 않음. - 애플리케이션 시작 시
import또는 초기화 과정에서 예외가 발생하면 프로세스가 즉시 종료되고 플랫폼이 오프라인으로 표시함. - 엔트리 포인트 파일명 불일치 또는 시작 커맨드 미설정이 가장 흔한 원인이다.
해결 방법
1단계: 콘솔 로그와 로컬 실행으로 원인 확인
- 먼저 호스팅 로그를 확인해 어떤 에러가 발생하는지 파악한다. 디스호스트의 로그 뷰어를 사용하거나 배포 방법에 따라
git/웹 콘솔에서 로그 확인. - 로컬에서 동일한 환경으로 실행해 오류를 재현한다.
python main.py
# 또는
python app.py
- 로그/스택트레이스를 보고
ModuleNotFoundError,SyntaxError, 인증 토큰 관련 예외 등 구체적 원인을 확인한다.
2단계: 엔트리 포인트 파일명 맞추기
- 호스팅 플랫폼이
app.py를 엔트리 포인트로 사용하면 파일명을 맞춘다. 파일명을 변경하거나 시작 커맨드를 조정한다.
git mv main.py app.py
git add app.py
git commit -m "Rename main.py to app.py for deployment"
git push origin main
- 또는 디스호스트에서 시작 커맨드를 직접 설정할 수 있으면
python main.py로 수정한다(플랫폼 설정에서 Start command 또는 Procfile 사용).
예시 Procfile:
web: python app.py
3단계: 안전한 진입점과 예외 처리 적용
- 애플리케이션이 임포트 단계에서 예외로 종료되지 않도록 진입점을 명확히 하고 예외를 로깅한다.
import logging
from discord.ext import commands
logging.basicConfig(level=logging.INFO)
def main():
bot = commands.Bot(command_prefix='!')
# cog 등록, 초기화 작업 등
try:
bot.run("YOUR_TOKEN")
except Exception:
logging.exception("봇 실행 중 예외 발생")
if __name__ == "__main__":
main()
- 이 구조는 임포트 시점의 사이드 이펙트로 인한 즉시 종료를 줄여주고, 로그로 원인 파악이 쉬워진다.
4단계: 재시작 정책과 헬스체크 설정
- 플랫폼(디스호스트)에서 자동 재시작 정책이 활성화되어 있는지 확인한다. 크래시 시 자동으로 재시작하도록 설정하면 가용성이 개선된다.
- 헬스체크(healthcheck) 타임아웃을 너무 짧게 설정하지 않는다. 초기화 시간이 필요한 경우 타임아웃 연장 필요.
마무리
엔트리 포인트 파일명 불일치(app.py 없음)와 초기화 시 예외가 가장 흔한 원인이다. 콘솔 로그를 우선 확인하고, 엔트리 포인트를 맞추거나 시작 커맨드를 조정하며, 예외 처리를 적용해 안정적으로 디스코드 봇을 디스호스트에 호스팅하자.