ν”„λ‘œμ νŠΈ

일반

μ‚¬μš©μžμ •λ³΄

μƒˆκΈ°λŠ₯ #46

minkyu park이(κ°€) 21일 전에 λ³€κ²½

{{>toc}} 

 # πŸŸ₯ Epic 1 β€” Task 1 

 ## FastAPI 디렉토리 ꡬ쑰 μ •μ˜ 

 ### πŸ“Œ μž‘μ—… κ°œμš” 

 FastAPI 기반의 μƒˆλ‘œμš΄ mgmt μ„œλ²„λ₯Ό κ΅¬μΆ•ν•˜κΈ° μœ„ν•΄, 전체 ν”„λ‘œμ νŠΈμ˜ 디렉토리 ꡬ쑰λ₯Ό μ²΄κ³„μ μœΌλ‘œ μ„€κ³„ν•œλ‹€. 
 이 κ΅¬μ‘°λŠ” ν–₯ν›„ κΈ°λŠ₯ ν™•μž₯, μœ μ§€λ³΄μˆ˜, μ„œλ²„ 배포, MQTT worker 뢄리 운영 등을 κ³ λ €ν•˜μ—¬ μž₯기적으둜 μ•ˆμ •μ μΈ μ•„ν‚€ν…μ²˜λ₯Ό λͺ©ν‘œλ‘œ ν•œλ‹€. 

 ### πŸ“Œ 섀계 λͺ©μ  

 - FastAPI μ„œλ²„μ™€ MQTT Workerλ₯Ό λͺ…ν™•νžˆ λΆ„λ¦¬ν•˜μ—¬ ν”„λ‘œμ„ΈμŠ€ μΆ©λŒμ„ λ°©μ§€ν•˜κ³  운영 μ•ˆμ •μ„±μ„ ν™•λ³΄ν•œλ‹€. 

 - SQLAlchemy λͺ¨λΈ, λΌμš°ν„°, μŠ€ν‚€λ§ˆλ₯Ό λͺ¨λ“ˆν™”ν•˜μ—¬ μ½”λ“œ 가독성과 μœ μ§€λ³΄μˆ˜μ„±μ„ 높인닀. 

 - Reverse SSH, μ„œλ²„ μ œμ–΄, μž₯λΉ„ μƒνƒœ 관리 λ“± κΈ°λŠ₯λ³„λ‘œ λΌμš°ν„°λ₯Ό λΆ„λ¦¬ν•˜μ—¬ API ꡬ쑰λ₯Ό λͺ…ν™•ν•˜κ²Œ ν•œλ‹€. 

 - AlmaLinux 배포 ν™˜κ²½(systemd, scripts)을 κ³ λ €ν•œ 디렉토리 κ΅¬μ„±μœΌλ‘œ μ‹€μ œ 운영 ν™˜κ²½κ³Ό 개발 ν™˜κ²½μ˜ 차이λ₯Ό μ΅œμ†Œν™”ν•œλ‹€. 

 - ν…ŒμŠ€νŠΈ μ½”λ“œ, λ¬Έμ„œ, μ„€μ • νŒŒμΌμ„ ν‘œμ€€ν™”ν•˜μ—¬ ν”„λ‘œμ νŠΈ ν’ˆμ§ˆμ„ μœ μ§€ν•œλ‹€. 

 πŸ“ ν”„λ‘œμ νŠΈ 루트 ꡬ쑰 

 ```plaintext 
 mkMgmtCloudFastAPI/ mgmt-fastapi-server/ 
 β”‚ 
 β”œβ”€ 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 초기 컀밋에 μ‚¬μš©ν•  ν‘œμ€€ ν”„λ‘œμ νŠΈ ꡬ쑰 

 - ν–₯ν›„ λͺ¨λ“  개발 μž‘μ—…μ˜ 기반이 λ˜λŠ” μ•„ν‚€ν…μ²˜ μ •μ˜ 
 -

λ’€λ‘œ