AutonetSellCar/DEPLOYMENT_GUIDE.md

사이트 배포 가이드

개요

이 문서는 Next.js Frontend + FastAPI Backend 사이트를 Ubuntu 서버에 배포하는 전체 과정을 설명합니다.

---

배포 순서도

┌─────────────────────────────────────────────────────────────────────────────┐
│                         사이트 배포 전체 흐름                                │
└─────────────────────────────────────────────────────────────────────────────┘

1. 사전 준비
   │
   ├─→ DNS 설정 (도메인 → 공인 IP)
   │     ├─ example.com → 59.14.158.123
   │     ├─ www.example.com → 59.14.158.123
   │     └─ api.example.com → 59.14.158.123  ★ 중요: API 서브도메인 필수
   │
   ├─→ 공유기 포트포워딩
   │     ├─ 80 → 192.168.0.201:80 (NPM)
   │     └─ 443 → 192.168.0.201:443 (NPM)
   │
   └─→ 서버 준비
         ├─ Docker 설치
         ├─ Node.js 설치
         └─ Python 설치

2. 소스코드 전송
   │
   ├─→ 압축 (node_modules 제외)
   │     └─ 7z a -tzip project.zip frontend backend -xr!node_modules
   │
   ├─→ 전송 (내부망 경유 권장)
   │     └─ scp project.zip damon@192.168.0.203:~/sites/project/
   │
   └─→ 압축 해제
         └─ unzip project.zip

3. Backend 배포
   │
   ├─→ 가상환경 생성
   │     └─ python3 -m venv venv && source venv/bin/activate
   │
   ├─→ 의존성 설치
   │     └─ pip install -r requirements.txt
   │
   ├─→ ★★★ CORS 설정 수정 ★★★
   │     └─ config.py의 CORS_ORIGINS에 도메인 추가
   │         - http://example.com
   │         - https://example.com
   │         - http://www.example.com
   │         - https://www.example.com
   │
   ├─→ Admin 계정 생성/리셋
   │     └─ python init_admin.py 또는 reset_pw.py 실행
   │
   └─→ 서버 실행
         └─ nohup uvicorn app.main:app --host 0.0.0.0 --port 8001 > ~/logs/backend.log 2>&1 &

4. Frontend 배포
   │
   ├─→ 의존성 설치
   │     └─ npm install
   │
   ├─→ ★★★ 환경변수 설정 ★★★
   │     └─ echo "NEXT_PUBLIC_API_URL=http://api.example.com/api" > .env.local
   │
   ├─→ 빌드
   │     └─ npm run build
   │
   └─→ 서버 실행
         └─ nohup sh -c 'PORT=3001 npm start' > ~/logs/frontend.log 2>&1 &

5. NPM (Nginx Proxy Manager) 설정
   │
   ├─→ Frontend Proxy Host
   │     ├─ Domain: example.com, www.example.com
   │     ├─ Forward: 192.168.0.203:3001
   │     └─ SSL: Let's Encrypt
   │
   └─→ ★★★ API Proxy Host ★★★
         ├─ Domain: api.example.com
         ├─ Forward: 192.168.0.203:8001
         └─ SSL: Let's Encrypt

6. 테스트
   │
   ├─→ 사이트 접속: http://example.com
   ├─→ API 접속: http://api.example.com/api/health
   └─→ Admin 로그인: http://example.com/admin/login

---

핵심 체크리스트

배포 전 필수 확인 사항

• DNS에 api 서브도메인 A 레코드 추가했는가?
• NPM에 api.도메인 프록시 설정했는가?
• Backend CORS_ORIGINS에 도메인 추가했는가?
• Frontend .env.local에 API URL 설정했는가?
• Admin 계정이 DB에 존재하는가?

---

자주 발생하는 문제와 해결법

1. 사이트 로딩만 계속됨 (뱅글뱅글)

원인: Frontend가 API에 연결하지 못함

확인 순서:

# 1. Backend 실행 확인
ps aux | grep uvicorn

# 2. API 직접 테스트
curl http://api.example.com/api/health

# 3. .env.local 확인
cat ~/sites/project/frontend/.env.local

# 4. 빌드에 환경변수 적용 확인
grep -r "api.example" ~/sites/project/frontend/.next/ | head -3

해결:

# .env.local 설정 후 재빌드
echo "NEXT_PUBLIC_API_URL=http://api.example.com/api" > .env.local
rm -rf .next
npm run build

---

2. CORS 에러

원인: Backend에서 Frontend 도메인을 허용하지 않음

증상: 브라우저 Network 탭에서 "CORS error" 표시

확인:

cat ~/sites/project/backend/app/core/config.py | grep CORS

해결: config.py의 CORS_ORIGINS에 도메인 추가

CORS_ORIGINS: list = [
    "http://localhost:3000",
    "http://example.com",
    "https://example.com",
    "http://www.example.com",
    "https://www.example.com"
]

Backend 재시작:

pkill -f uvicorn
nohup uvicorn app.main:app --host 0.0.0.0 --port 8001 > ~/logs/backend.log 2>&1 &

---

3. 로그인 안 됨

원인: DB에 admin 계정이 없거나 비밀번호가 다름

확인:

# API 직접 테스트
curl -X POST "http://api.example.com/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"비밀번호"}'

해결: 비밀번호 리셋 스크립트 실행

cd ~/sites/project/backend
source venv/bin/activate
cat > reset_pw.py << 'EOF'
from app.core.database import SessionLocal
from app.models.admin import Admin
from app.core.security import get_password_hash
db = SessionLocal()
admin = db.query(Admin).filter(Admin.username == 'admin').first()
if admin:
    admin.password_hash = get_password_hash('새비밀번호')
    db.commit()
    print('Password reset')
else:
    print('Admin not found')
db.close()
EOF
python reset_pw.py

---

4. 포트 충돌 (EADDRINUSE)

원인: 기존 프로세스가 포트를 점유 중

확인:

sudo netstat -tlnp | grep 3001
sudo netstat -tlnp | grep 8001

해결:

# PID 확인 후 종료
sudo kill -9 <PID>

# 또는 프로세스 이름으로 종료
pkill -f "npm start"
pkill -f uvicorn

---

5. 500 Internal Server Error (정적 파일)

원인: 빌드 파일 손상 또는 캐시 문제

해결:

cd ~/sites/project/frontend
pkill -f "npm start"
rm -rf .next
rm -rf node_modules/.cache
npm run build
nohup sh -c 'PORT=3001 npm start' > ~/logs/frontend.log 2>&1 &

---

유용한 명령어 모음

프로세스 관리

# 프로세스 확인
ps aux | grep -E "npm|uvicorn|node"

# 포트 사용 확인
sudo netstat -tlnp | grep -E "3001|8001"

# 로그 확인
tail -f ~/logs/frontend.log
tail -f ~/logs/backend.log

서비스 재시작

# Frontend 재시작
pkill -f "npm start"
cd ~/sites/project/frontend
nohup sh -c 'PORT=3001 npm start' > ~/logs/frontend.log 2>&1 &

# Backend 재시작
pkill -f uvicorn
cd ~/sites/project/backend
source venv/bin/activate
nohup uvicorn app.main:app --host 0.0.0.0 --port 8001 > ~/logs/backend.log 2>&1 &

API 테스트

# Health check
curl http://api.example.com/api/health

# 로그인 테스트
curl -X POST "http://api.example.com/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password"}'

---

서버 정보

네트워크 구성

서버	내부 IP	역할
Server1	192.168.0.201	NPM, PostgreSQL, Redis, 모니터링
Server2	192.168.0.202	MongolCar (autonetsellcar.com)
Server3	192.168.0.203	Grantech, Cylinx
Server4	192.168.0.204	Windows PC (파일 전송 중계)

외부 접속

포트	용도
80, 443	NPM (웹 서비스)
81	NPM 관리 페이지
201, 202, 203	SSH (각 서버)

도메인

도메인	서비스
autonetsellcar.com	MongolCar
grantech.kr	Grantech
api.grantech.kr	Grantech API
cylinx.kr	Cylinx (예정)

---

버전 정보

• Node.js: 20.x
• Python: 3.10
• Next.js: 16.x
• FastAPI: Latest
• Ubuntu: 22.04

---

최종 업데이트: 2025-12-05