Loafacto Hub 문서

Appearance

Loafacto 문서/참고 문서/루트 문서/Backend Server 구축 및 배포 가이드

Backend Server 구축 및 배포 가이드 ​

FastAPI(uvicorn) 기반 백엔드 서버를 Linux 환경에서 배포하는 운영 가이드입니다. 정적 페이지(web-ui/dist)는 nginx로 제공하고, API는 systemd + uvicorn 조합으로 운영합니다.

1. 사전 요구사항 ​

  • Linux 서버 (예: Ubuntu 22.04+)
  • Python 3.11+
  • Node.js + npm (웹 빌드 시 사용)
  • nginx, git, rsync
  • systemctl 동작 가능한 환경

2. 배포 디렉터리 예시 ​

text
/var/www/loafacto-hub/
  apps/
    backend-server/
      app/
      storage/
      requirements.txt
      .env
    web-ui/
      dist/

3. 배포 방법 ​

A. git pull 방식 ​

bash
cd /var/www/loafacto-hub
git clone <레포지토리 URL> .
# 이후 업데이트
git pull

B. rsync 방식 ​

bash
rsync -avz --exclude node_modules --exclude .env --exclude __pycache__ \
  ./apps/backend-server/ user@<서버IP>:/var/www/loafacto-hub/apps/backend-server/
  • .env 파일은 직접 전송하지 말고, 서버에 따로 생성/복사합니다.

4. 백엔드 실행 환경 구성 ​

bash
cd /var/www/loafacto-hub/apps/backend-server

# 가상환경 생성
python3.12 -m venv .venv
source .venv/bin/activate

# 패키지 설치
pip install -r requirements.txt

# 환경변수 설정
cp .env.example .env
nano .env   # PORT, CORS_ORIGINS, OPENAI_API_KEY 등

권장 값

  • APPLICATION_PORT: 8000
  • CORS_ORIGINS: 서비스 도메인(예: https://loafacto.com)

5. systemd 서비스 등록 ​

bash
sudo nano /etc/systemd/system/loafacto-backend.service
ini
[Unit]
Description=Loafacto-Hub Backend (FastAPI)
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/var/www/loafacto-hub/apps/backend-server
Environment="PATH=/var/www/loafacto-hub/apps/backend-server/.venv/bin"
ExecStart=/var/www/loafacto-hub/apps/backend-server/.venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
bash
sudo systemctl daemon-reload
sudo systemctl enable loafacto-backend
sudo systemctl start loafacto-backend
sudo systemctl status loafacto-backend

실행 상태 확인:

bash
journalctl -u loafacto-backend -f

6. 웹 빌드 및 반영 ​

bash
cd /var/www/loafacto-hub/apps/web-ui
npm install
npm run build
sudo rsync -avz --delete dist/ /var/www/loafacto-web/dist/

nginx는 dist 디렉터리를 서빙하고 /api 경로는 백엔드로 프록시합니다.