🚀 FastAPI 온프레미스 배포 가이드 (Windows 환경 기준)

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

이전 글 보기(FastAPI 앱 테스트-PyTest)

애플리케이션을 개발하는 것만큼이나 중요한 것이 바로 배포다. FastAPI는 비동기 처리와 높은 성능 덕분에 현대적인 백엔드 개발에 적합하지만, 배포를 위해서는 몇 가지 구성 요소를 함께 사용하는 것이 좋다.

이번 글에서는 온프레미스 환경, 즉 자체 서버 혹은 Windows PC에서 직접 FastAPI 애플리케이션을 실행하고 서비스하는 방법을 중점적으로 다룬다. Uvicorn, Gunicorn, 그리고 Docker를 활용하여 실전에서 바로 적용할 수 있는 배포 과정을 함께 살펴보자.

---

🔧 Uvicorn으로 애플리케이션 실행하기

FastAPI는 자체적으로 ASGI(Asynchronous Server Gateway Interface)를 기반으로 동작한다. 이때, ASGI 서버 역할을 해주는 것이 바로 Uvicorn이다.

Uvicorn은 가볍고 빠른 Python ASGI 서버로, FastAPI의 기본 런처다.

Uvicorn 설치

먼저 아래 명령어로 Uvicorn을 설치하자.

pip install uvicorn

설치가 완료되면, main.py라는 파일이 있다고 가정하고 다음 명령어로 애플리케이션을 실행할 수 있다.

uvicorn main:app --reload

• main: FastAPI 인스턴스를 담고 있는 파일명 (확장자 제외)
• app: FastAPI 객체 이름
• --reload: 코드 변경 시 자동으로 서버 재시작 (개발용)

하지만 이 방식은 개발 환경용이기 때문에, 실제 운영 환경에서는 적합하지 않다. 운영에서는 --reload 없이 실행하거나, 더 나아가 Gunicorn과 함께 사용하는 것이 안정성과 성능 면에서 유리하다.

---

🔥 Gunicorn과 함께 Uvicorn 사용하기

Linux 환경에서는 Gunicorn + Uvicorn Worker 조합이 배포 표준으로 자리잡고 있다. 그러나 Windows 환경에서는 Gunicorn이 공식적으로 지원되지 않는다. 따라서 온프레미스 Windows 환경에서는 Uvicorn 단독 실행, 또는 Docker를 이용한 Linux 환경 가상화를 통해 Gunicorn을 사용하는 것이 좋다.

운영 환경에서 Uvicorn을 사용하는 가장 기본적인 명령은 다음과 같다.

uvicorn main:app --host 0.0.0.0 --port 8000

• --host 0.0.0.0: 외부에서 접근 가능하게 함
• --port: 원하는 포트 설정

이 명령은 실행 콘솔에서 직접 입력하거나 .bat 파일로 만들어 자동 실행될 수 있다.

---

🐳 Docker로 배포하기

Windows 환경에서 FastAPI 애플리케이션을 안정적으로 실행하기 위한 최고의 방법 중 하나는 Docker를 활용하는 것이다. Docker는 컨테이너 기반 가상화 기술로, 어떤 환경에서든 동일하게 실행할 수 있도록 해준다.

Docker 설치 (Windows)

1. Docker Desktop 공식 홈페이지에서 Docker Desktop을 다운로드한다.
2. 설치 후, 재부팅하고 Docker가 정상적으로 실행되는지 확인한다.
3. PowerShell에서 아래 명령어로 정상 동작 여부를 확인한다.

docker --version

Dockerfile 작성

다음은 FastAPI + Uvicorn을 Docker로 패키징하기 위한 Dockerfile 예제이다.

# 베이스 이미지
FROM python:3.11

# 작업 디렉토리 설정
WORKDIR /app

# 필요한 파일 복사
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 앱 복사
COPY . .

# 포트 오픈
EXPOSE 8000

# 실행 명령
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

requirements.txt 작성

FastAPI와 Uvicorn이 포함된 의존성 파일을 작성하자.

fastapi
uvicorn

Docker 이미지 빌드

다음 명령어로 Docker 이미지를 빌드한다.

docker build -t fastapi-app .

Docker 컨테이너 실행

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

• -d: 백그라운드 실행
• -p: 호스트 포트:컨테이너 포트 매핑
• --name: 컨테이너 이름

이제 브라우저에서 http://localhost:8000으로 접속하면 FastAPI 애플리케이션이 정상적으로 실행되는 것을 확인할 수 있다.

---

🧱 Windows 서비스로 등록하기

온프레미스 환경에서는 애플리케이션을 자동으로 실행하고 계속 살아 있도록 유지하는 것이 중요하다. 이를 위해 NSSM(Non-Sucking Service Manager)이라는 툴을 사용해보자.

NSSM 설치 및 사용

1. NSSM을 다운로드하고 압축을 푼다.
2. 관리자 권한 CMD 또는 PowerShell을 열고 다음을 실행한다.

nssm install fastapi-service

3. 실행 파일 위치에는 Python 실행 경로를, 인자에는 Uvicorn 실행 스크립트를 넣는다.

예:

• Path: C:\Users\username\venv\Scripts\python.exe
• Arguments: -m uvicorn main:app --host 0.0.0.0 --port 8000

이제 시스템 부팅 시 FastAPI가 자동으로 실행되는 윈도우 서비스가 완성된다.

---

📋 보안 및 성능 팁

• 방화벽 예외 등록: Windows 방화벽에서 8000번 포트를 허용해야 외부에서 접속 가능하다.
• 리버스 프록시 설정: 실제 서비스 환경에서는 Nginx나 Apache를 앞단에 두고 리버스 프록시를 구성하는 것이 일반적이다. 이는 HTTPS 적용, 로드 밸런싱, 캐싱 등을 가능하게 한다.
• 모니터링: 온프레미스 환경에서는 prometheus, grafana, logrotate 등을 활용해 로그 및 상태 모니터링을 구성하면 좋다.

---

✅ 마무리하며

FastAPI는 가볍고 강력한 프레임워크인 만큼, 배포 또한 단순하고 효율적으로 구성할 수 있다. 특히 Windows 환경에서도 Docker를 활용하면 리눅스 기반의 배포 구조를 동일하게 사용할 수 있어 이식성과 유지보수가 쉬워진다.

이번 글에서는 온프레미스 환경에서의 배포에 중점을 두었지만, 이후에는 AWS, Vercel 등 클라우드 기반의 배포 방법도 소개할 예정이다. 로컬 환경에서 충분히 테스트하고, 안정적인 배포가 가능해졌다면 다음 단계로 클라우드 이전도 고려해보자.

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