FastAPI와 Celery로 구현하는 게임 서버용 FSM(Finite State Machine) 처리 시스템 (기초)

게시 2025/04/19

By SouthGlory

6 분읽는 시간

[영상]

안녕하세요!

오늘은 게임 서버에서 자주 사용되는 상태 기반 로직을 효율적으로 처리하기 위한 FSM(Finite State Machine) 처리 시스템을 소개하려고 합니다.

프로젝트 소개 ** 게임 서버를 개발하다 보면 퀘스트, 매칭, 보상, 유닛 생성 등 다양한 상태 기반 로직을 처리해야 합니다.

이러한 상태 관리를 중앙 집중식으로 처리하고 로깅까지 담당하는 기초적인 백엔드 서버를 만들어보았습니다.

테스트로는 '퀘스트'에 대한 상태 정의와 상태 전이를 구현했습니다.

상태 전이 API (FSM 상태 변경)
상태 조회 API
비동기 로깅 시스템
JSON 기반 FSM 정의
실시간 모니터링

FastAPI: 비동기 API 서버
Redis: 상태 저장소 및 메시지 브로커
Celery: 비동기 작업 처리
Flower: 작업 모니터링
Docker Compose: 컨테이너 관리

비동기 처리FastAPI의 비동기 처리로 높은 동시성 지원
Celery를 통한 비동기 로깅
상태 관리Redis를 활용한 빠른 상태 저장/조회
JSON 기반의 유연한 FSM 정의
모니터링Flower 대시보드로 실시간 작업 모니터링
상태 전이 로그 추적

사용 예시: 퀘스트 시스템

{
  "name": "Quest FSM",
  "initial_state": "ready",
  "transitions": {
    "ready": {
      "start": "in_progress"
    },
    "in_progress": {
      "complete": "completed",
      "fail": "failed"
    },
    "failed": {
      "retry": "in_progress"
    },
    "completed": {}
  }
}

확장성새로운 FSM 타입을 JSON으로 쉽게 추가
워커 스케일 아웃 가능
안정성상태 전이 실패 시 명확한 오류 응답
워커 장애 시 자동 재시도
개발 편의성로컬 개발 환경 핫리로드 지원
Docker 기반 간편한 배포

퀘스트 진행 상태 관리
매칭 시스템 상태 관리
게임 세션 상태 관리
보상 지급 프로세스
유닛 생성/파괴 라이프사이클

동시에 여러 FSM 인스턴스 처리 가능
Redis를 통한 빠른 상태 조회
비동기 처리로 응답 지연 최소화

설치 및 실행

# Redis 및 Celery 실행
docker-compose up --build

# FastAPI 서버 실행 (개발 모드)
uvicorn app.main:app --reload

마치며 이 프로젝트를 통해 게임의 상태 업데이트를 fastapi + redis + celery 의 조합으로 구현해보았습니다. ** **아시다시피 redis 큐와 celery 비동기 worker는 그 안정성이 검증되었습니다. ** **이 작은 프로젝트는 앞으로 Fastapi로 게임 서버를 구현해보는 작업의 초석이 될 것 같습니다. ** **전체 소스 코드는 GitHub에서 확인하실 수 있습니다. ** ** https://github.com/southglory/game_fsm_server_01.git

GitHub - southglory/game_fsm_server_01: 해보는거지~ 해보는거지~. Contribute to southglory/game_fsm_server_01 development by creating an account on GitHub. 해보는거지~. Contribute to southglory/game_fsm_server_01 development by creating an account on GitHub.

게임 서버 개발과 파이썬 서버 개발에 도움이 되길 바랍니다! 😊 ** **행코~! **

역할:게임 중 발생하는 주요 이벤트(이동, 스킬 사용, 판정 결과 등)를 기록하여 재생 가능한 로그로 저장
밸런싱 분석, 리플레이 기능, 클립 하이라이트 등에 사용
비동기 큐 서버가 필요한 이유:실시간 동기 기록은 성능 저하 유발 → 이벤트만 큐에 넣고 비동기 저장이 안정적
트래픽이 많을수록 비동기 구조가 필요함
방법:POST /replay/log로 이벤트 로그 등록
Celery 워커가 JSON 로그 포맷으로 저장 (파일 or DB)
추후 /replay/:id API로 불러서 재생

역할:유저의 클릭, 탭, 구매 등 행동 이벤트 트래킹
마케팅, 게임 디자인 피드백, AB 테스트 등 데이터 분석 기반 마련
비동기 큐 서버가 필요한 이유:수집 빈도가 높고 처리량이 크기 때문에 실시간 DB 저장은 부하 유발
이벤트를 큐에 넣고 비동기로 DB 저장 → 안정성과 확장성 확보
방법:POST /event/track로 유저 이벤트 등록
Celery 워커가 MongoDB, PostgreSQL 등 분석 DB에 저장
Redis에 최근 이벤트 캐싱 가능

개발, 백엔드

인기 태그