초기 커밋

2026-03-01 07:44:19 +09:00
commit 09359f30be
146 changed files with 6120 additions and 0 deletions
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -0,0 +1,260 @@
+# 배포 가이드
+
+## 1. 전제 조건
+
+### 호스트에 직접 설치 (Docker 외부)
+- **MariaDB** 10.6+ — 관계형 데이터 저장
+- **MongoDB** 7.0+ — 문서 데이터 저장
+
+### Docker로 관리
+- **Docker** 24.0+
+- **Docker Compose** v2
+
+---
+
+## 2. 최초 설정
+
+### 2.1 환경변수
+
+```bash
+cp .env.example .env
+```
+
+`.env` 파일에서 반드시 변경해야 할 항목:
+
+```bash
+# 보안 키 (반드시 변경)
+SECRET_KEY=<랜덤 문자열>
+JWT_SECRET_KEY=<랜덤 문자열>
+
+# MariaDB 접속 정보
+MARIADB_HOST=127.0.0.1
+MARIADB_PORT=3306
+MARIADB_USER=core_api_user
+MARIADB_PASSWORD=<강력한 비밀번호>
+MARIADB_DATABASE=core_api
+
+# MongoDB 접속 정보
+MONGODB_URL=mongodb://127.0.0.1:27017
+MONGODB_DATABASE=core_api
+```
+
+### 2.2 MariaDB 준비
+
+```sql
+CREATE DATABASE core_api CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE USER 'core_api_user'@'%' IDENTIFIED BY 'your_password';
+GRANT ALL PRIVILEGES ON core_api.* TO 'core_api_user'@'%';
+FLUSH PRIVILEGES;
+```
+
+### 2.3 MongoDB 준비
+
+```javascript
+use core_api
+db.createUser({
+  user: "core_api_user",
+  pwd: "your_password",
+  roles: [{ role: "readWrite", db: "core_api" }]
+})
+```
+
+---
+
+## 3. 개발 환경
+
+### 3.1 로컬 실행
+
+```bash
+# 의존성 설치
+pip install -e ".[dev]"
+
+# DB 마이그레이션
+alembic upgrade head
+
+# 시드 데이터
+python -m scripts.init_db
+
+# 관리자 계정 생성
+python -m scripts.create_superuser admin@example.com password123
+
+# 인프라 시작 (Redis + Mosquitto)
+docker-compose up -d redis mosquitto
+
+# 앱 서버
+uvicorn app.asgi:app --reload --host 0.0.0.0 --port 8000
+
+# Celery 워커 (별도 터미널)
+celery -A app.tasks.celery_app worker --loglevel=info \
+  -Q default,analytics,notifications,devices
+
+# Celery 스케줄러 (별도 터미널)
+celery -A app.tasks.celery_app beat --loglevel=info
+```
+
+### 3.2 Docker 전체 스택
+
+```bash
+docker-compose up -d
+```
+
+서비스 확인:
+- API: http://localhost:8000/docs
+- Flower: http://localhost:5555
+
+---
+
+## 4. 프로덕션 배포
+
+### 4.1 Docker Compose
+
+```bash
+docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+```
+
+프로덕션 차이점:
+- Uvicorn 워커 4개 (`--workers 4`)
+- Celery 동시성 4, Worker 레플리카 2
+- Flower 기본 인증 활성화
+- 소스 코드 볼륨 마운트 없음 (이미지 내장)
+- 로그 레벨 `warning`
+
+### 4.2 환경변수 (프로덕션 추가)
+
+```bash
+APP_ENV=production
+DEBUG=false
+LOG_LEVEL=WARNING
+
+# Flower 인증
+FLOWER_USER=admin
+FLOWER_PASSWORD=<강력한 비밀번호>
+
+# CORS (실제 도메인)
+CORS_ORIGINS=["https://your-domain.com"]
+```
+
+### 4.3 리버스 프록시 (Nginx 예시)
+
+```nginx
+upstream core_api {
+    server 127.0.0.1:8000;
+}
+
+server {
+    listen 80;
+    server_name api.your-domain.com;
+
+    location / {
+        proxy_pass http://core_api;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    location /socket.io/ {
+        proxy_pass http://core_api;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}
+```
+
+---
+
+## 5. 서비스 구성
+
+```
+┌────────────────────────────────────────────────────┐
+│                Docker Compose                       │
+│                                                    │
+│  ┌─────────┐  ┌─────────┐  ┌────────┐  ┌───────┐ │
+│  │   App   │  │ Worker  │  │  Beat  │  │Flower │ │
+│  │ :8000   │  │ (x2)    │  │        │  │ :5555 │ │
+│  └────┬────┘  └────┬────┘  └───┬────┘  └───┬───┘ │
+│       │            │           │            │     │
+│  ┌────┴────┐  ┌────┴──────────┴────────────┘     │
+│  │  Redis  │  │                                   │
+│  │ :6379   │  │                                   │
+│  └─────────┘  │                                   │
+│  ┌────────────┘                                   │
+│  │ Mosquitto │                                    │
+│  │ :1883     │                                    │
+│  └───────────┘                                    │
+└────────────────────────────────────────────────────┘
+         │                    │
+    ┌────┴────┐          ┌───┴────┐
+    │ MariaDB │          │MongoDB │
+    │ (호스트) │          │(호스트) │
+    └─────────┘          └────────┘
+```
+
+---
+
+## 6. 헬스체크
+
+```bash
+# 기본 헬스체크
+curl http://localhost:8000/api/v1/system/health
+# → {"status": "ok", "service": "core-api", "version": "0.1.0"}
+
+# 상세 시스템 상태 (인증 필요)
+curl -H "Authorization: Bearer <token>" \
+  http://localhost:8000/api/v1/monitoring/health
+
+# Docker 서비스 상태
+docker-compose ps
+
+# Celery 워커 상태
+docker-compose logs worker
+
+# Celery 활성 태스크
+docker-compose exec worker celery -A app.tasks.celery_app inspect active
+```
+
+---
+
+## 7. 로그
+
+### 개발 환경
+- structlog 콘솔 렌더러 (사람이 읽기 좋은 형식)
+- 로그 레벨: DEBUG
+
+### 프로덕션 환경
+- structlog JSON 렌더러 (ELK/Grafana 연동)
+- 로그 레벨: WARNING
+
+```bash
+# 실시간 로그 확인
+docker-compose logs -f app
+docker-compose logs -f worker
+```
+
+---
+
+## 8. 백업
+
+### MariaDB
+```bash
+mysqldump -u root -p core_api > backup_$(date +%Y%m%d).sql
+```
+
+### MongoDB
+```bash
+mongodump --db core_api --out backup_$(date +%Y%m%d)
+```
+
+---
+
+## 9. 트러블슈팅
+
+| 증상 | 원인 | 해결 |
+|------|------|------|
+| `Cannot connect to MySQL` | MariaDB 미실행 또는 접속 정보 오류 | `.env` 확인, MariaDB 상태 확인 |
+| `MongoDB not initialized` | MongoDB 미실행 | MongoDB 서비스 시작 |
+| `Redis connection refused` | Redis 미실행 | `docker-compose up -d redis` |
+| Celery 태스크 실행 안 됨 | Worker 미실행 또는 큐 불일치 | Worker 로그 확인, 큐 이름 확인 |
+| Socket.IO 연결 실패 | CORS 설정 누락 | `CORS_ORIGINS`에 클라이언트 URL 추가 |
+| MQTT 연결 실패 | Mosquitto 미실행 | `docker-compose up -d mosquitto` |