o2o-infrakit/README.md

o2o-infrakit

aio2o의 분산된 인프라 서비스 및 설정을 단일 프로젝트로 통합하여 구축한 범용 인프라 솔루션입니다.

주요 기능

• FastAPI 애플리케이션 서버: Gunicorn + Uvicorn ASGI 워커 기반의 비동기 Python 웹 서버
• Nginx 리버스 프록시: SSL/TLS 지원, 정적 파일 서빙, WebSocket 지원
• 데이터베이스: PostgreSQL 및 MySQL(Percona) 지원
• 캐싱 및 메시지 브로커: Redis 기반 캐싱 및 Celery 태스크 큐 지원
• SSL 인증서 자동화: Let's Encrypt + Certbot 자동 갱신
• 로그 관리: 일별 로그 로테이션 및 30일 보관

기술 스택

구분	기술
언어	Python 3.13
프레임워크	FastAPI
ASGI 서버	Gunicorn + Uvicorn
웹 서버	Nginx 1.26
데이터베이스	PostgreSQL, MySQL (Percona)
캐시/브로커	Redis
태스크 큐	Celery + Celery Beat
컨테이너	Docker, Docker Compose

디렉토리 구조

o2o-infrakit/
├── compose/                    # Docker Compose 설정
│   ├── docker-compose.yml      # 메인 오케스트레이션 파일
│   ├── .env                    # 환경 변수
│   ├── mysql/                  # MySQL 데이터 볼륨
│   ├── pgdata/                 # PostgreSQL 데이터 볼륨
│   ├── redis/                  # Redis 설정 및 데이터
│   └── ssl/                    # SSL 인증서 및 Let's Encrypt
│
├── config/                     # 서비스별 설정
│   ├── app-server/             # 애플리케이션 서버 설정
│   │   └── gunicorn_uvicorn.conf.py
│   ├── database/               # 데이터베이스 설정
│   │   ├── mysql/              # MySQL 설정 (my.cnf, init.sql)
│   │   └── postgresql/         # PostgreSQL 설정
│   └── web-server/             # 웹 서버 설정
│       ├── nginx_conf/         # Nginx 메인 설정
│       ├── conf.d/             # 도메인별 Nginx 설정
│       └── proxy_params/       # 프록시 헤더 설정
│
├── docker/                     # Docker 이미지
│   ├── gunicorn/               # Python 앱 서버 Dockerfile
│   └── nginx/                  # Nginx Dockerfile
│
├── script/                     # 유틸리티 스크립트
│   ├── letsencrypt.sh          # SSL 인증서 설정
│   ├── crontab_gunicorn_set.sh # Cron 작업 설정
│   └── logrotate/              # 로그 로테이션 설정
│
├── log/                        # 로그 디렉토리 (볼륨)
│   ├── mysql/                  # MySQL 로그
│   ├── nginx/                  # Nginx 액세스/에러 로그
│   ├── postgresql/             # PostgreSQL 로그
│   └── uvicorn/                # Uvicorn/FastAPI 로그
│
└── www/                        # 애플리케이션 코드 볼륨

시스템 요구사항

• CPU: 4코어 이상
• RAM: 4GB 이상
• 스토리지: SSD 권장
• OS: Linux (Ubuntu 24.04 권장)
• Docker: 20.10 이상
• Docker Compose: 2.0 이상

빠른 시작

1. 환경 변수 설정

cd compose
cp .env.example .env
# .env 파일을 프로젝트에 맞게 수정

주요 환경 변수:

• PROJECT_DIR: 애플리케이션 프로젝트 디렉토리명
• POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD: PostgreSQL 접속 정보
• CELERY_BROKER_URL: Celery 브로커 URL

2. 데이터베이스 볼륨 권한 설정

cd compose
chmod +x set_mysql_permission.sh
./set_mysql_permission.sh

3. SSL 인증서 설정 (선택)

cd script
chmod +x letsencrypt.sh
./letsencrypt.sh

4. 컨테이너 실행

cd compose
docker compose up -d

서비스 구성

Docker Compose 서비스

서비스	설명	포트
nginx	리버스 프록시, SSL 종료	80, 443
uvicorn-app	FastAPI 애플리케이션	8000 (내부)
redis	캐시 및 메시지 브로커	6379 (내부)
postgresql	데이터베이스	5432 (내부)
mysql	데이터베이스 (선택)	3306 (내부)

Gunicorn 설정 (config/app-server/gunicorn_uvicorn.conf.py)

• 워커 수: 4 (4GB RAM 기준 최적화)
• 워커 타입: Uvicorn (비동기 I/O)
• 타임아웃: 300초 (장시간 작업 지원)
• 최대 요청: 1000 (메모리 누수 방지)
• 바인드: 0.0.0.0:8000

Nginx 설정 (config/web-server/nginx_conf/nginx.conf)

• 워커 프로세스: auto (CPU 코어 수에 맞게 자동 조정)
• 워커 연결: 1024/프로세스
• Keep-alive: 30초
• 최대 요청 본문: 50MB
• 프록시 타임아웃: 300초

운영 기능

로그 로테이션

• 주기: 일별
• 보관 기간: 30일
• 최대 파일 크기: 100MB
• 설정 위치: script/logrotate/

SSL 인증서 자동 갱신

• 주기: 매주 월요일 오전 5시
• 방식: Certbot + Nginx 리로드
• 설정: Nginx Dockerfile 내 crontab

자동 재시작

• 주기: 매주 월요일 오전 6시 (선택적)
• 설정 스크립트: script/crontab_gunicorn_set.sh

주요 스크립트

스크립트	설명
script/letsencrypt.sh	Let's Encrypt SSL 인증서 발급
compose/set_mysql_permission.sh	데이터베이스 볼륨 권한 설정
script/crontab_gunicorn_set.sh	컨테이너 자동 재시작 cron 설정