Windows 서버에서 FastAPI 자동 실행 시 발생한 서비스 오류 대응기

상황

회사 업무로 특정 사이트에 특정 시스템 구축을 해줘야 하는 상황이었다.

• 제반 환경

* 배포 환경(서버 os): Windows 2022 Server
* 개발 환경(내 os): ubuntu 22.04 lts
* python을 이용한 FastAPI 서버 구축
* 해당 서버는 특정 클라이언트들에서 감지한 정보를 서버의 특정 경로(static 폴더)로 수집한다

Ubuntu 개발 환경에서 구축한 FastAPI 서버를 Windows Server 2022 환경에 배포하고, 해당 서버가 자동으로 실행되도록 커스텀 서비스화(nssm 이용)하여 구축하였다.
하지만 배포 후 자동 실행이 되지 않는 문제가 발생했고, 오류 로그도 남지 않아 디버깅이 어려웠다.
아래는 static 경로 문제, 인코딩 문제, Windows 서비스 실행 특성 등 여러 복합적인 이슈를 해결해나간 과정을 정리한 것이다.

---

1. static 폴더 경로 문제

🔸 문제 상황

Ubuntu 개발 환경에서는 특정 절대 경로를 사용하고 있었다.

app.mount("/static", StaticFiles(directory="~/{home경로 아래의 특정 경로}"), name="static")

하지만 Windows 서버에서는 해당 경로가 존재하지 않아 FastAPI 앱이 기동 중 실패함을 확인

또한 Windows OS에서 NSSM을 사용하여 서비스를 등록해 자동 실행할 경우, Python 프로세스는 SYSTEM 계정으로 실행된다.
이때 os.path.expanduser("~") 또는 상대 경로를 사용할 경우:

❗ 홈 디렉토리가 C:\Windows\System32\config\systemprofile 로 인식되며
→ static 폴더를 찾지 못해 앱이 즉시 실패하게 된다.

✅  해결

FastAPI 앱의 실행 경로 기준으로 static 경로를 명시적이고 안전하게 설정한다:

해당 프로젝트의 static 폴더 경로로 저장되도록 설정

import os

# Windows 서비스 환경에서도 안전하게 static 경로 설정
BASE_DIR = os.path.dirname(os.path.abspath(__file__))
static_dir = os.path.join(BASE_DIR, 'static')

app.mount("/static", StaticFiles(directory=static_dir), name="static")

이 방식은 다음의 장점이 있다:

* 운영체제 무관
* 서비스 계정으로 실행되어도 정상 동작
* 상대 경로가 아닌 실행 파일 기준 경로이므로 재배포가 쉬움

---

2. main.py / app.py에서의 인코딩 문제

🔸 문제 상황

다음과 같은 로그 출력 코드에서 Windows CMD 환경에서 UnicodeEncodeError 발생:

print("💥🚀 SERVER START ⚗️💥")

로그 확인 결과 Windows 기본 인코딩(cp949)이 이모지(유니코드)를 처리하지 못해 서버 실행 중 crash 발생함을 확인

✅  해결

로그용 이모지를 제거하거나, 예외처리를 추가하여 인코딩 문제 방지:

try:
    print("SERVER START 🚀")
except UnicodeEncodeError:
    print("SERVER START")

---

3. 서비스 실행 실패 (서비스에서 오류가 반환되지 않았습니다)

🔸 문제 상황

나는 해당 서비스를 autorun.bat 파일을 만들어 batch 파일을 통해 자동 실행되도록 구축하였다.

그런데 해당 서비스 실행과 관련해서 아래와 같은 에러가 발생함을 확인

Windows 서비스 등록 후, .bat 파일을 통해 FastAPI를 자동 실행했지만 서비스는 아래 메시지를 남기며 실패:

❌ “로컬 컴퓨터에서 서비스를 시작하지 못했습니다. 서비스에서 오류가 반환되지 않았습니다.”

서비스 관리자 창에서 보기에는 "단순 실패"처럼 보이지만, 실제로는 내부적으로 오류 로그도 없고 프로세스도 남지 않으며 즉시 종료되는 상태였다.

🔍 디버깅 과정

문제의 정체를 밝히기 위해 다음과 같은 시도를 했다.

1. 서비스 등록된 .bat 파일을 관리자 콘솔에서 수동 실행
   → 예상과 달리 콘솔이 바로 닫히고, 아무런 메시지도 출력되지 않았다.
2. .bat 파일에 디버그 로그 삽입 (echo, date, time)
   → 로그파일이 생성되지 않아, bat 내부 코드 진입 자체가 실패한 것으로 판단
3. 의심되는 부분: 한글 주석
   → echo ===== 백엔드 시작 ===== 와 같은 한글 주석을 제거하고 다시 저장하니, 로그파일 생성이 시작됨
4. 이후 .bat 파일을 열어보니, 인코딩이 UTF-8 with BOM으로 저장되어 있었음
   → Windows CMD 환경에서 BOM이 포함된 UTF-8 파일은 한글 깨짐 + 실행 실패를 유발한다는 걸 확인

🔸 원인 정리

1. .bat 파일 내부에 한글 주석/출력문이 있었고, 인코딩이 UTF-8 with BOM이어서 Windows 서비스 환경에서 깨짐

✅ 해결

• .bat 파일에서 한글 주석 제거, 또는 인코딩을 ANSI 또는 UTF-8 without BOM으로 저장
• 배치 파일 작성 시에는 근본 언어인 영어를 지켜야 한다는 것

---

마무리

서비스 자동화 환경에서는 경로 문제, 인코딩 문제, 권한 문제가 복합적으로 발생할 수 있다.

Ubuntu에서는 잘 되던 코드가 Windows에서는 실패하는 이유는, 대부분 OS 특성 + 서비스 실행 환경 차이 에서 오는 경우가 많다

또한 배치 파일 및 코드 작성 시에는 웬만하면 코드 근본 언어인 english로 작성하도록 하자