서버를 직접 실행하기

서버를 직접 실행하기 (Run a Server Manually)

`fastapi run` 명령 사용하기

간단히 말하면, FastAPI 앱을 서빙할 때는 fastapi run을 쓰면 돼요:

fastapi run main.py
   FastAPI   Starting production server 🚀

             Searching for package file structure from directories
             with __init__.py files
             Importing from /home/user/code/awesomeapp

    module   🐍 main.py

      code   Importing the FastAPI app object from the module with
             the following code:

             from main import app

       app   Using import string: main:app

    server   Server started at http://0.0.0.0:8000
    server   Documentation at http://0.0.0.0:8000/docs

             Logs:

      INFO   Started server process [2306215]
      INFO   Waiting for application startup.
      INFO   Application startup complete.
      INFO   Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C
             to quit)

대부분의 경우 이걸로 충분해요. 😎

예를 들어 이 명령은 컨테이너나 서버 등에서 FastAPI 앱을 시작할 때 쓸 수 있어요.

출처: 공식문서

ASGI 서버

좀 더 자세한 내용으로 들어가 볼게요.

FastAPI는 Python 웹 프레임워크와 서버를 만들기 위한 표준인 ASGI를 사용해요. FastAPI는 ASGI 웹 프레임워크예요.

원격 서버 머신에서 FastAPI 앱(또는 다른 ASGI 앱)을 실행하기 위해 필요한 핵심은 Uvicorn 같은 ASGI 서버 프로그램이에요. fastapi 명령에 기본으로 딸려 오는 게 바로 그거죠.

그 밖에도 여러 대안이 있어요:

Uvicorn: 고성능 ASGI 서버.
Hypercorn: HTTP/2와 Trio 등과 호환되는 ASGI 서버.
Daphne: Django Channels를 위해 만들어진 ASGI 서버.
Granian: Python 앱을 위한 Rust HTTP 서버.

서버 머신과 서버 프로그램

이름과 관련된 작은 세부 사항을 명심해야 해요. 💡

" 서버(server) "라는 단어는 원격/클라우드 컴퓨터(물리적이든 가상 머신이든)와 그 머신에서 실행되는 프로그램(예: Uvicorn) 둘 다를 가리키는 데 흔히 쓰여요.

일반적으로 "서버"라는 표현을 읽을 때, 그게 그 둘 중 어떤 것을 가리키는지 명심하세요.

원격 머신을 가리킬 때는 서버라고 부르는 게 일반적이지만, 머신(machine), VM(가상 머신), 노드(node) 라고도 해요. 이 모두는 프로그램을 실행하는, 보통 Linux가 돌아가는 원격 머신의 한 종류를 가리켜요.

서버 프로그램 설치하기

FastAPI를 설치하면 프로덕션 서버인 Uvicorn이 함께 딸려 와서, fastapi run 명령으로 시작할 수 있어요.

하지만 ASGI 서버를 수동으로 설치할 수도 있어요.

프로젝트에 서버 앱을 추가해 보세요.

예를 들어 Uvicorn을 설치하려면:

uv add "uvicorn[standard]"

다른 ASGI 서버 프로그램에도 비슷한 과정이 적용돼요.

💡 팁: standard를 추가하면 Uvicorn이 권장하는 몇 가지 추가 의존성을 설치하고 사용하게 돼요.

여기에는 asyncio의 고성능 대체품(drop-in replacement)인 uvloop가 포함돼요. 덕분에 큰 동시성 성능 향상을 얻을 수 있죠.

uv add "fastapi[standard]" 같은 방식으로 FastAPI를 추가하면 이미 uvicorn[standard]도 함께 받아요.

서버 프로그램 실행하기

ASGI 서버를 수동으로 설치했다면, FastAPI 앱을 임포트하기 위해 특별한 형식의 임포트 문자열(import string)을 넘겨줘야 해요:

uv run uvicorn main:app --host 0.0.0.0 --port 80
INFO:     Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit)

📝 참고: uvicorn main:app 명령은 다음을 가리켜요:

main: 파일 main.py(Python "모듈").

app: main.py 안에서 app = FastAPI() 라는 줄로 만든 객체.

다음과 같다고 볼 수 있어요:
from main import app

각 대안 ASGI 서버 프로그램마다 비슷한 명령이 있을 거예요. 각자의 문서에서 더 자세히 읽을 수 있어요.

⚠️ 경고: Uvicorn과 다른 서버들은 개발 중 유용한 --reload 옵션을 지원해요.

--reload 옵션은 리소스를 훨씬 많이 소비하고, 더 불안정하기도 해요.

개발 중에는 큰 도움이 되지만, 프로덕션에서는 사용하면 안 돼요.

배포 개념

이 예시들은 서버 프로그램(예: Uvicorn)을 단일 프로세스로, 미리 정해진 포트(예: 80)에서 모든 IP(0.0.0.0)를 수신하면서 실행해요.

이게 기본 아이디어예요. 하지만 아마 몇 가지 추가 사항을 처리하고 싶을 거예요, 예를 들면:

보안 - HTTPS
시작 시 실행(Running on startup)
재시작(Restarts)
복제(Replication - 실행 중인 프로세스 수)
메모리(Memory)
시작 전 사전 단계(Previous steps before starting)

이 각각의 개념이 무엇인지, 어떻게 생각해야 하는지, 그리고 이를 처리하는 전략을 담은 구체적인 예시를 다음 장들에서 더 알려드릴게요. 🚀

서버를 직접 실행하기