update readme.md
Dohyun Lim
parent
ac3b5b3015
commit
c7da4bb2da
170
README.md
170
README.md
|
|
@ -1,9 +1,171 @@
|
||||||
# aio2o-infrakit
|
# o2o-infrakit
|
||||||
|
|
||||||
aio2o의 분산된 인프라 서비스 및 설정을 단일 프로젝트로 통합하여 구축한 범용 인프라 솔루션입니다.
|
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. 환경 변수 설정
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd compose
|
||||||
|
cp .env.example .env
|
||||||
|
# .env 파일을 프로젝트에 맞게 수정
|
||||||
|
```
|
||||||
|
|
||||||
|
주요 환경 변수:
|
||||||
|
- `PROJECT_DIR`: 애플리케이션 프로젝트 디렉토리명
|
||||||
|
- `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`: PostgreSQL 접속 정보
|
||||||
|
- `CELERY_BROKER_URL`: Celery 브로커 URL
|
||||||
|
|
||||||
|
### 2. 데이터베이스 볼륨 권한 설정
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd compose
|
||||||
|
chmod +x set_mysql_permission.sh
|
||||||
|
./set_mysql_permission.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. SSL 인증서 설정 (선택)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd script
|
||||||
|
chmod +x letsencrypt.sh
|
||||||
|
./letsencrypt.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. 컨테이너 실행
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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 설정 |
|
||||||
|
|
||||||
이 프로젝트는 임도현 책임연구원의 [devspoon-web](https://github.com/devspoons/devspoon-web) 오픈소스를 기반으로 개발되었습니다.
|
|
||||||
|
|
||||||
#
|
|
||||||
Loading…
Reference in New Issue