🚀 FastAPI 온프레미스 배포 가이드 – Linux 서버 환경 중심

🕒 약 2분 읽는 데 소요됩니다

이전 글 보기(Windows 기준 FastAPI 온프레미스 배포 가이드)

FastAPI로 백엔드 애플리케이션을 개발했다면, 이제 세상에 보여줄 차례다. 이번 글에서는 Linux 서버 환경에서 온프레미스로 FastAPI 애플리케이션을 배포하는 전 과정을 자세히 안내하겠다. 실무에서 많이 사용되는 Uvicorn + Gunicorn 조합, 그리고 Docker를 활용한 컨테이너 기반 배포 방식까지 다뤄보자.

이 글은 Ubuntu 기반의 Linux 서버에서 FastAPI를 배포한다고 가정하고 작성한다. 가장 흔하게 사용되는 배포 환경인 만큼 실전에서도 바로 적용할 수 있을 것이다.

---

🔧 Uvicorn 단독 실행 vs Gunicorn과 함께 실행

FastAPI는 ASGI 기반의 프레임워크이며, ASGI 서버로 가장 많이 사용하는 것이 바로 Uvicorn이다. 개발 중에는 Uvicorn만으로도 충분하지만, 운영 환경에서는 멀티 프로세싱을 지원하는 Gunicorn + Uvicorn worker 조합이 안정성과 성능 면에서 더 적합하다.

1. 환경 준비

sudo apt update
sudo apt install python3 python3-pip -y
python3 -m pip install --upgrade pip

2. 가상환경 생성 및 패키지 설치

python3 -m venv venv
source venv/bin/activate
pip install fastapi uvicorn gunicorn

FastAPI 앱은 예시로 main.py에 작성되어 있다고 가정한다.

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

3. Gunicorn + Uvicorn Worker 실행

운영 환경에서는 다음 명령어로 애플리케이션을 실행한다.

gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

• main:app: main.py의 app 객체
• -w 4: 4개의 워커 프로세스 사용
• -k: 워커 클래스 지정
• --bind: IP 및 포트 지정

이 구성을 통해 멀티코어 CPU 자원을 활용해 효율적인 요청 처리가 가능해진다.

---

🐳 Docker를 활용한 컨테이너 배포

리눅스 환경에서도 점점 더 Docker 기반 배포가 표준이 되고 있다. 애플리케이션을 하나의 이미지로 패키징하면, 어디서든 동일한 환경으로 실행할 수 있기 때문이다.

1. Docker 설치

Ubuntu에서는 다음 명령어로 Docker를 설치한다.

sudo apt update
sudo apt install docker.io -y
sudo systemctl enable --now docker

설치 확인은 아래 명령어로 가능하다.

docker --version

2. 프로젝트 구조

.
├── app
│   └── main.py
├── requirements.txt
└── Dockerfile

3. requirements.txt

fastapi
uvicorn[standard]

4. Dockerfile

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY ./app ./app

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Dockerfile은 가볍고 실행에 최적화된 구성으로 작성하며, 실제 서비스 환경에서도 손쉽게 이식 가능하다.

5. Docker 이미지 빌드

docker build -t fastapi-app .

6. Docker 컨테이너 실행

docker run -d -p 8000:8000 --name fastapi-container fastapi-app

이제 http://<서버 IP>:8000으로 접속하면 FastAPI 애플리케이션이 정상 작동하는 것을 확인할 수 있다.

---

🛡 Nginx와 함께 리버스 프록시 구성 (선택사항)

실제 운영 환경에서는 Nginx를 앞단에 두고, Gunicorn이나 Docker 컨테이너로 연결된 Uvicorn 서버에 요청을 전달하는 것이 일반적이다. 이 구성을 통해 HTTPS 설정, 로드 밸런싱, 정적 파일 처리 등 다양한 기능을 효과적으로 수행할 수 있다.

1. Nginx 설치

sudo apt install nginx -y

2. Nginx 설정 예시

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

설정을 /etc/nginx/sites-available/fastapi에 작성하고, sites-enabled에 심볼릭 링크를 생성한다.

sudo ln -s /etc/nginx/sites-available/fastapi /etc/nginx/sites-enabled/
sudo systemctl restart nginx

이제 Nginx가 80번 포트를 통해 들어온 요청을 내부 Uvicorn 서버로 전달하게 된다.

---

🔁 Supervisor를 이용한 프로세스 관리

Linux 서버에서는 FastAPI 앱을 항상 실행 상태로 유지하기 위해 Supervisor를 많이 사용한다. 이는 자동 재시작, 로그 관리 등을 쉽게 할 수 있도록 도와준다.

1. Supervisor 설치

sudo apt install supervisor -y

2. 설정 파일 생성

sudo nano /etc/supervisor/conf.d/fastapi.conf

설정 예시:

[program:fastapi]
command=/home/ubuntu/venv/bin/gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
directory=/home/ubuntu/app
autostart=true
autorestart=true
stderr_logfile=/var/log/fastapi.err.log
stdout_logfile=/var/log/fastapi.out.log

이후 설정을 반영하고 Supervisor를 재시작한다.

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start fastapi

이제 서버가 재부팅되어도 FastAPI 앱은 자동으로 시작된다.

---

📌 마무리하며

Linux 기반의 온프레미스 환경에서 FastAPI 애플리케이션을 배포하는 방법은 다양하지만, 운영 환경에 적합한 구조로 안정적으로 실행되도록 구성하는 것이 핵심이다. 단일 Uvicorn 서버보다 Gunicorn과 조합하여 멀티 프로세스로 실행하는 것이 일반적이며, Docker를 활용하면 이식성과 배포 자동화까지 노려볼 수 있다.

FastAPI 공식 문서 : https://fastapi.tiangolo.com/ko/