FastAPI로 API 서버를 만들었다면 개발 환경에서는 보통 다음과 같은 명령어로 실행합니다.
uvicorn main:app --host0.0.0.0 --port8000
브라우저에서 서버 IP와 8000번 포트를 입력하면 API에 접근할 수 있습니다.
하지만 실제 서비스를 운영하면서 사용자가 example.com과 같은 도메인으로 접속하도록 만들고 HTTPS까지 적용하려면 조금 더 체계적인 서버 구성이 필요합니다.
이때 많이 사용하는 프로그램이 Nginx입니다.
FastAPI와 Nginx의 역할
전체적인 구조를 단순하게 표현하면 다음과 같습니다.
사용자↓도메인↓Nginx↓FastAPI↓Python 프로그램
Nginx는 외부 요청을 먼저 받은 뒤 내부에서 실행 중인 FastAPI 애플리케이션으로 전달하는 Reverse Proxy 역할을 할 수 있습니다.
예를 들어 사용자는 다음 주소에 접속합니다.
https://example.com
하지만 실제 FastAPI는 서버 내부에서 다음 주소로 실행할 수 있습니다.
127.0.0.1:8000
외부 사용자가 FastAPI 포트에 직접 접근하지 않고 Nginx를 거치게 만드는 것입니다.
Nginx 설치하기
Ubuntu 서버에서는 다음과 같이 설치할 수 있습니다.
sudo apt updatesudo apt install nginx
설치가 끝나면 상태를 확인합니다.
sudo systemctl status nginx
정상적으로 실행되고 있다면 브라우저에서 서버 IP로 접속했을 때 Nginx 기본 페이지가 나타날 수 있습니다.
FastAPI 서버 실행하기
간단한 FastAPI 예제를 만들어보겠습니다.
main.py
fromfastapiimportFastAPIapp=FastAPI()@app.get("/")defhome():return {"message": "FastAPI server is running" }
실행합니다.
uvicorn main:app --host127.0.0.1 --port8000
여기서 127.0.0.1을 사용하는 이유는 FastAPI를 서버 내부에서만 접근하게 구성하기 위해서입니다.
외부 요청은 Nginx가 대신 받습니다.
Nginx Reverse Proxy 설정하기
Nginx 설정 파일을 생성합니다.
예를 들어 다음과 같은 형태입니다.
server { listen 80; server_name example.com www.example.com; location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; }}
여기서 example.com은 실제 사용할 도메인으로 변경해야 합니다.
설정한 뒤에는 문법을 확인합니다.
sudo nginx -t
문제가 없다면 Nginx를 다시 불러옵니다.
sudo systemctl reload nginx
도메인의 DNS 설정
Nginx 설정만 한다고 도메인이 자동으로 서버를 찾아가는 것은 아닙니다.
도메인을 관리하는 DNS 서비스에서 서버 IP를 연결해야 합니다.
일반적으로 A 레코드를 사용하여 다음과 같이 구성합니다.
example.com → VPS 공인 IP
www.example.com도 사용한다면 별도의 레코드가 필요할 수 있습니다.
DNS 변경은 인터넷 전체에 즉시 반영되지 않을 수 있으므로 설정 후 일정 시간이 필요한 경우도 있습니다.
UFW 방화벽 설정
Ubuntu에서 UFW를 사용한다면 HTTP와 HTTPS 접근을 허용해야 합니다.
예를 들어 Nginx 관련 프로필을 확인할 수 있습니다.
sudo ufw app list
환경에 맞는 규칙을 적용한 뒤 상태를 확인합니다.
sudo ufw status
서버 보안에서 중요한 점은 필요하지 않은 포트를 무조건 열지 않는 것입니다.
FastAPI가 내부 127.0.0.1:8000에서 실행되고 있다면 일반적으로 외부에서 8000번 포트를 공개할 필요가 없습니다.
HTTPS가 필요한 이유
HTTP는 브라우저와 서버 사이의 통신을 암호화하지 않습니다.
HTTPS는 TLS를 이용하여 전송되는 데이터를 보호합니다.
로그인이나 개인정보가 없는 단순 API라고 하더라도 현대적인 웹서비스에서는 HTTPS 사용이 기본적인 운영 요소에 가깝습니다.
검색엔진과 브라우저 측면에서도 HTTPS 사이트를 사용하는 것이 좋습니다.
무료 SSL 인증서 적용
개인 프로젝트에서는 Let’s Encrypt 인증서를 이용하는 경우가 많습니다.
Ubuntu에서는 Certbot을 설치하고 Nginx와 연동하는 방식이 일반적입니다.
인증서를 발급하기 전에는 먼저 다음 조건을 확인하는 것이 좋습니다.
- 도메인이 실제 서버 IP를 가리키는가?
- 80번 포트에 외부에서 접근할 수 있는가?
- Nginx 설정에 도메인이 정확하게 입력되어 있는가?
설정이 잘못된 상태에서 인증서부터 발급하려 하면 오류가 발생하기 쉽습니다.
Certbot을 이용할 경우 인증서 갱신 방식도 함께 확인해야 합니다.
무료 인증서라고 해서 한 번 발급한 뒤 영원히 유지되는 것은 아니기 때문입니다.
FastAPI를 터미널에서 직접 실행하면 안 될까?
테스트 단계에서는 가능합니다.
하지만 SSH 접속을 종료했을 때 프로그램이 같이 종료될 수 있으며 오류로 프로세스가 중단되면 API 서비스도 멈춥니다.
따라서 실제 운영에서는 systemd 같은 서비스 관리 도구를 사용하는 편이 좋습니다.
예를 들어 전체 구조를 다음과 같이 만들 수 있습니다.
인터넷↓443 HTTPS↓Nginx↓127.0.0.1:8000↓Uvicorn / FastAPI↓systemd 프로세스 관리
이 구조는 작은 개인 프로젝트에서도 충분히 활용할 수 있습니다.
로그 확인도 중요하다
API가 작동하지 않을 때는 무작정 설정을 변경하기보다 어느 구간에서 문제가 발생하는지 확인해야 합니다.
Nginx 오류인지, FastAPI 오류인지, 방화벽 문제인지 분리해야 합니다.
Nginx 로그와 systemd 로그를 확인하면 원인을 찾는 데 도움이 됩니다.
FastAPI 프로그램 내부에도 Python Logging을 적용하면 특정 API 요청에서 발생한 예외를 추적하기 쉬워집니다.
보안상 주의할 점
Nginx와 HTTPS를 사용한다고 모든 서버 보안이 해결되는 것은 아닙니다.
SSH 보안, 운영체제 업데이트, UFW, API 인증, 데이터베이스 접근 제어 등도 함께 관리해야 합니다.
FastAPI의 /docs 페이지 역시 운영환경에서 누구에게 공개할 것인지 판단할 필요가 있습니다.
API에 중요한 기능이 있다면 인증 없이 URL만 알면 실행 가능한 구조를 만들어서는 안 됩니다.
자주 묻는 질문
Nginx 없이 FastAPI만 사용할 수 있나요?
개발이나 단순 테스트는 가능합니다. 실제 공개 서비스를 운영한다면 Reverse Proxy와 HTTPS 등을 고려해 Nginx 등의 웹서버를 함께 사용하는 구성이 일반적입니다.
8000번 포트를 외부에 열어야 하나요?
Nginx가 같은 서버에서 FastAPI로 요청을 전달하고 FastAPI를 localhost에 바인딩했다면 일반적으로 외부에 공개할 필요가 없습니다.
도메인이 없어도 테스트할 수 있나요?
IP와 포트를 이용한 테스트는 가능합니다. 하지만 정상적인 HTTPS 인증서와 실제 서비스 환경을 구성하려면 도메인을 사용하는 것이 편리합니다.
마무리
FastAPI로 API 코드를 작성하는 것과 실제 인터넷 서비스를 운영하는 것은 조금 다른 문제입니다.
개발 단계에서는 Uvicorn 하나만 실행해도 충분하지만 서비스 단계에서는 Nginx, 도메인, DNS, 방화벽, HTTPS, 프로세스 관리까지 고려해야 합니다.
처음에는 복잡해 보이지만 각각의 역할을 나누어 이해하면 어렵지 않습니다.
FastAPI는 애플리케이션을 실행하고, Nginx는 외부 요청을 받아 전달하며, systemd는 프로세스가 계속 실행되도록 관리한다고 생각하면 전체 구조를 쉽게 이해할 수 있습니다.