FastAPI + NSSM 윈도우 서비스 배포 메뉴얼

📌 개요

이 문서는 Python FastAPI 프로젝트를 Windows 환경에서 가상환경 기반으로 NSSM을 통해 서비스로 실행하는 전체 과정을 정리한 매뉴얼입니다.

 

🧩 사전 요구사항

• Windows 10/11
• Python (Welcome to Python.org 버전)
• NSSM (Non-Sucking Service Manager)
• FastAPI 프로젝트 준비됨 (main.py에 app = FastAPI() 정의되어 있어야 함)

nssm-2.24.zip

0.34MB

 

✅ 1. Microsoft Store Python 제거 (필수)

Microsoft Store에서 설치된 Python은 NSSM 및 서비스 환경에서 작동에 문제가 많습니다.

제거 방법:

1. 시작 → 설정 → 앱 → 설치된 앱 → Python 검색 → 제거
2. PowerShell에서도 제거 가능:

Get-AppxPackage *Python* | Remove-AppxPackage

 

✅ 2. 파이썬 및 nssm설치

nssm-2.24.zip 압축해제 특정 폴더 이동

• 설치 시:
  • ✅ Add Python to PATH 체크
  • ✅ Install for all users 선택 권장
• 설치 경로 확인 (예: C:\Users\user\AppData\Local\Programs\Python\Python313\python.exe)

✅ 3. 환경 변수 설정

1. 시스템 환경 변수 편집 → “환경 변수”
2. Path 편집:
   • 아래 두 경로 추가 (버전 번호에 맞게 수정):

C:\Users\user\AppData\Local\Programs\Python\Python313\
C:\Users\user\AppData\Local\Programs\Python\Python313\Scripts\

 

아래 항목은 제거 또는 맨 아래로 이동:

C:\Users\user\AppData\Local\Microsoft\WindowsApps

 

 

CMD 재시작 → where python 실행:

C:\Users\user\AppData\Local\Programs\Python\Python313\python.exe

 

✅ 4. FastAPI 프로젝트 설정 및 가상환경 세팅

cd C:\Users\user\fastapi_v
python -m venv .venv
.venv\Scripts\activate
pip install fastapi uvicorn

 

✅ 5. start_server.bat 작성

@echo off
REM 이 파일이 있는 폴더로 이동합니다.
cd /d "%~dp0"

REM 가상 환경을 활성화합니다.
echo Activating virtual environment...
call .venv\Scripts\activate.bat

REM 가상 환경의 python.exe 절대 경로를 지정합니다.
REM  이것이 시스템 경로와 충돌하는 문제를 근본적으로 해결합니다.
set PYTHON_EXE=.venv\Scripts\python.exe

REM FastAPI 서버를 시작합니다.
echo Starting FastAPI server using: %PYTHON_EXE%
"%PYTHON_EXE%" -m uvicorn main:app --reload

REM 서버가 중지된 후 창이 바로 닫히지 않게 잠시 대기합니다.
echo Server stopped.
pause

 

✅ 6. NSSM으로 서비스 등록

NSSM 다운로드

nssm.exe 경로의 폴더에 가서 아래 명령어 실행

서비스 등록 (예: MyFastAPIServer)

 

#서비스 등록
nssm install MyFastAPIServer

 

설정 항목

Path	C:\Windows\System32\cmd.exe
Arguments	/c start_server.bat
Startup Directory	C:\Users\user\fastapi_v
Log on 탭	현재 사용자 계정으로 설정
I/O 탭	stdout, stderr 로그 경로 설정 (예: logs\out.log, logs\err.log)

 

로그는 테스트 용도로 NSSM에서도 설정해 주고 bat 파일에서도 남겨 주었습니다.

 

NSSM 명령어

#서비스 수정
nssm edit MyFastAPIServer

#서비스 삭제
nssm remove MyFastAPIServer

#서비스 시작
nssm start MyFastAPIServer

#서비스 중지
nssm stop MyFastAPIServer

 

✅ 7. 실행 확인

• 브라우저 접속: http://localhost:8000
• 로그 확인:
  • logs\server_stdout.log 에 Uvicorn running on ... 메시지 확인
  • logs\server_stderr.log 에 에러가 없어야 함

 

 

Api server를 cmd 창에서 실행하는 것이 아닌 서비스로 등록하여 보다 안전하게 api server를 운영하실 수 있게 되었습니다.

 

오늘도 보람찬 생존 ^.^