배포 (Gunicorn + Uvicorn + Nginx)

gunicorn UvicornWorker systemd nginx 워커 수

이 서버의 운영 구조. 자세한 초기 세팅은 FastAPI 서버구축 가이드 참고, 여기서는 요점만.

1. 왜 Gunicorn + Uvicorn worker

역할 분담

Gunicorn — 프로세스 매니저 (워커 생성·재시작·graceful reload)
UvicornWorker — 각 워커가 ASGI 앱을 실제로 구동
Nginx — TLS 종료, 정적 파일, 리버스 프록시, 타임아웃

2. 실행 커맨드

gunicorn app.main:app \
  -k uvicorn.workers.UvicornWorker \
  -w 4 \
  -b 127.0.0.1:8001 \
  --timeout 60 --graceful-timeout 30 \
  --access-logfile - --error-logfile -

워커 수 -w: CPU 코어 기준 2 × cores + 1 에서 시작해 부하 보고 조정. DB 커넥션 상한과 함께 계산 (풀·트랜잭션).

3. systemd 서비스

# /etc/systemd/system/fastapi-school.service
[Unit]
Description=fastapi-school
After=network.target postgresql.service

[Service]
User=ubuntu
Group=ubuntu
WorkingDirectory=/home/ubuntu/offset0xf/school
EnvironmentFile=/home/ubuntu/offset0xf/school/.env
ExecStart=/home/ubuntu/offset0xf/school/venv/bin/gunicorn main:app \
  -k uvicorn.workers.UvicornWorker -w 4 -b 127.0.0.1:8001 --timeout 60
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl restart fastapi-school
sudo journalctl -u fastapi-school -f

4. Nginx 프록시 요점

location / {
    proxy_pass http://127.0.0.1:8001;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 300s;
}

X-Forwarded-Proto 를 넘겨야 앱이 https 를 인식합니다. 필요 시 --forwarded-allow-ips / ProxyHeadersMiddleware.

5. 무중단 배포

git pull
source venv/bin/activate && pip install -r requirements.txt
alembic upgrade head
sudo systemctl reload fastapi-school   # HUP -> 워커 graceful 교체

체크리스트

/docs 는 운영에서 노출 여부 결정 (FastAPI(docs_url=None) 또는 Nginx 에서 차단)
.env 권한 chmod 600, git 제외
헬스체크 엔드포인트(/health) 추가

"커넥션은 요청마다 열지 말고 풀에서 빌려 쓴다"