• 목차
• 🟥 Epic 1 — Task 1
  • FastAPI 디렉토리 구조 정의
    • 📌 작업 개요
    • 📌 설계 목적
    • 📌 설계 근거 및 의도
    • 📌 산출물

🟥 Epic 1 — Task 1¶

FastAPI 디렉토리 구조 정의¶

📌 작업 개요¶

FastAPI 기반의 새로운 mgmt 서버를 구축하기 위해, 전체 프로젝트의 디렉토리 구조를 체계적으로 설계한다.
이 구조는 향후 기능 확장, 유지보수, 서버 배포, MQTT worker 분리 운영 등을 고려하여 장기적으로 안정적인 아키텍처를 목표로 한다.

📌 설계 목적¶

• FastAPI 서버와 MQTT Worker를 명확히 분리하여 프로세스 충돌을 방지하고 운영 안정성을 확보한다.

• SQLAlchemy 모델, 라우터, 스키마를 모듈화하여 코드 가독성과 유지보수성을 높인다.

• Reverse SSH, 서버 제어, 장비 상태 관리 등 기능별로 라우터를 분리하여 API 구조를 명확하게 한다.

• AlmaLinux 배포 환경(systemd, scripts)을 고려한 디렉토리 구성으로 실제 운영 환경과 개발 환경의 차이를 최소화한다.

• 테스트 코드, 문서, 설정 파일을 표준화하여 프로젝트 품질을 유지한다.

📁 프로젝트 루트 구조

mkMgmtCloudFastAPI/
│
├─ app/                     # FastAPI 메인 서버
│   ├─ main.py              # FastAPI 엔트리포인트
│   ├─ db.py                # DB 연결 (SQLAlchemy + PostgreSQL)
│   ├─ models/              # SQLAlchemy 모델
│   │    ├─ server_master.py
│   │    ├─ server_status.py
│   │    ├─ server_control.py
│   │    └─ server_detail.py
│   ├─ routers/             # API 라우터
│   │    ├─ server.py       # 서버 상태/목록 API
│   │    ├─ control.py      # 제어 API (shutdown/reboot/WOL)
│   │    ├─ ssh.py          # reverse SSH API
│   │    └─ health.py       # ping/health check
│   ├─ core/
│   │    ├─ config.py       # 환경 설정
│   │    └─ utils.py        # 공용 유틸
│   └─ schemas/             # Pydantic 스키마
│        ├─ server.py
│        ├─ control.py
│        └─ ssh.py
│
├─ worker/                  # MQTT Worker (독립 프로세스)
│   ├─ mqtt_worker.py       # MQTT 메시지 수신 및 처리
│   ├─ handlers/            # 메시지 핸들러
│   │    ├─ status_handler.py
│   │    └─ control_handler.py
│   └─ utils.py
│
├─ scripts/                 # 배포/운영 스크립트
│   ├─ start_mgmt.sh
│   ├─ start_worker.sh
│   └─ migrate.sh
│
├─ systemd/                 # systemd 서비스 파일 템플릿
│   ├─ mgmt.service
│   └─ mqtt-worker.service
│
├─ tests/                   # 테스트 코드
│   ├─ test_server.py
│   ├─ test_control.py
│   └─ test_mqtt.py
│
├─ .env                     # 환경 변수
├─ requirements.txt         # Python 패키지 목록
└─ README.md                # 프로젝트 문서

📌 설계 근거 및 의도¶

✔ FastAPI / MQTT Worker 분리

• MQTT는 비동기 이벤트 기반이므로 FastAPI와 같은 웹 서버 프로세스와 분리해야 안정적이다.
• 따라서 worker/ 디렉토리를 별도로 구성하여 독립 실행이 가능하도록 설계했다.

✔ SQLAlchemy 모델 분리

• 기존 Django 모델 구조를 그대로 유지하면서도 FastAPI 스타일에 맞게 모듈화했다.
• 모델을 파일별로 분리하면 유지보수와 마이그레이션이 쉬워진다.

✔ 라우터 구조 분리

• 서버 상태, 제어, SSH, 헬스체크 등 기능별로 라우터를 분리하여 API 문서 자동 생성 시 구조가 명확해진다.

✔ systemd / scripts 포함

• AlmaLinux 운영 환경에서 바로 사용할 수 있도록 systemd 서비스 템플릿과 운영 스크립트를 포함했다.
• 이는 배포 자동화와 서버 안정성 확보에 필수적이다.

✔ 테스트 코드 포함

• FastAPI는 테스트 자동화가 매우 쉬우므로, 초기부터 테스트 디렉토리를 포함하여 품질 관리 기반을 마련했다.

📌 산출물¶

• FastAPI mgmt 서버의 전체 디렉토리 구조 설계 문서

• Gitea 초기 커밋에 사용할 표준 프로젝트 구조

• 향후 모든 개발 작업의 기반이 되는 아키텍처 정의