update readme.md
Dohyun Lim
parent
ac3b5b3015
commit
c7da4bb2da
170
README.md
170
README.md
|
|
@ -1,9 +1,171 @@
|
|||
# aio2o-infrakit
|
||||
# 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. 환경 변수 설정
|
||||
|
||||
```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