[19편] part 4 배포 배포 명령어/의미 + 오류 로그 대응표 + 체크리스트

 

🚀 Aura AI 배포 기록 (Part 4)

배포 명령어 정리 · 의미 설명 · 장애 대응 매뉴얼 · 운영 체크리스트

이번 글은 FastAPI + Next.js + Vercel + Amazon Web Services EC2 환경에서 실제 운영 시 사용하는 배포 명령어와 장애 대응 방법을 한 번에 정리한 실전 매뉴얼입니다.

👉 서버 운영을 하다 보면 매번 검색하게 되는 것들만 모았습니다.

• 접속 명령어
• 실행/재시작/백그라운드 실행
• systemd 영구 실행
• 에러 대응법
• 최종 점검 체크리스트

이 글 하나면 운영/복구/재배포 전부 가능합니다.

---

---

✅ 1️⃣ 배포용 핵심 명령어 + 의미 정리

---

🔹 EC2 서버 접속

ssh -i "C:\Users\dddd3\aura_ai\aura-key.pem" ubuntu@51.21.202.235

의미

• EC2 인스턴스 접속
• PEM 키 기반 인증 (비밀번호 대신 사용)

핵심 포인트

✔ PEM 없으면 접속 불가
✔ 경로는 반드시 따옴표 사용

---

---

🔹 백엔드 폴더 이동

cd ~/aura_ai/backend

의미

• FastAPI 프로젝트 위치로 이동
• uvicorn 실행 기준 디렉토리

---

---

🔹 가상환경 활성화

source .venv/bin/activate

의미

• Python 가상환경 활성화
• 패키지가 해당 환경에서만 동작

이유

✔ 시스템 Python 오염 방지
✔ 의존성 충돌 방지

---

---

🔹 패키지 설치

pip install -r requirements.txt

의미

• 프로젝트 의존성 전체 설치

언제 실행?

• 최초 배포
• requirements 수정 후
• 서버 재구성 후

---

---

🔹 서버 실행 (임시 실행)

uvicorn main:app --host 0.0.0.0 --port 8000

의미

• FastAPI 서버 실행
• 0.0.0.0 → 외부 접속 허용
• 8000 포트 사용

특징

❌ 터미널 종료 시 서버 종료

👉 테스트용/디버깅용

---

---

🔹 서버 실행 (백그라운드 임시)

nohup uvicorn main:app --host 0.0.0.0 --port 8000 > uvicorn.log 2>&1 &

의미

• 터미널 닫아도 유지
• 로그를 uvicorn.log에 저장

특징

✔ 간단한 임시 운영 가능
❌ 재부팅 시 자동 시작 안 됨

👉 임시 운영 전용

---

---

🔹 프로세스 종료

pkill -f uvicorn

의미

• 실행 중인 uvicorn 프로세스 전체 종료

사용 상황

• 포트 충돌
• 서버 재시작 전
• 좀비 프로세스 제거

---

---

🚀 ⭐ 권장 방식 — systemd (영구 실행)

운영 서버는 반드시 systemd 사용 권장합니다.

---

🔹 systemd 서비스 등록

sudo tee /etc/systemd/system/aura-api.service > /dev/null <<'EOF'
[Unit]
Description=Aura FastAPI (Uvicorn)
After=network.target

[Service]
User=ubuntu
WorkingDirectory=/home/ubuntu/aura_ai/backend
EnvironmentFile=/home/ubuntu/aura_ai/backend/.env
ExecStart=/home/ubuntu/aura_ai/backend/.venv/bin/uvicorn main:app --host 0.0.0.0 --port 8000
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
EOF

---

의미

핵심 기능

✔ 서버 부팅 시 자동 실행
✔ 오류 발생 시 자동 재시작
✔ SSH 종료와 무관하게 유지

---

옵션 설명

옵션의미

WorkingDirectory	프로젝트 위치
EnvironmentFile	.env 자동 로드
ExecStart	서버 실행 명령
Restart=always	항상 재시작
RestartSec	재시작 딜레이

---

---

🔹 systemd 적용/실행

sudo systemctl daemon-reload
sudo systemctl enable aura-api
sudo systemctl restart aura-api

의미

• 새 서비스 등록 적용
• 부팅 시 자동 실행 설정
• 즉시 서버 실행

---

---

🔹 실행 상태 확인

sudo systemctl status aura-api --no-pager

의미

• 서비스 실행 여부 확인

정상 상태

active (running)

---

---

🔹 포트 리스닝 확인

sudo ss -tlnp | grep 8000

의미

• 8000 포트가 열렸는지 확인
• uvicorn 실제 실행 여부 체크

---

---

---

✅ 2️⃣ 오류 로그 대응표 (실전 트러블슈팅)

운영 중 가장 많이 겪은 오류만 모았습니다.

---

❌ Mixed Content 오류

증상

HTTPS 페이지에서 HTTP API 호출 시 차단

해결

✔ /api/proxy 적용
✔ 프론트는 프록시 경유만 사용
✔ Vercel 내부 HTTPS 브릿지 활용

---

---

❌ ECONNREFUSED 127.0.0.1:3306

증상

MySQL 접속 실패

원인

Vercel 서버리스 → DB 직접 연결 불가

해결

✔ DB 접근은 전부 FastAPI 로 이동
✔ Vercel은 프록시만 담당

---

---

❌ Form data requires python-multipart

증상

파일 업로드 시 서버 실행 실패

해결

pip install python-multipart

---

---

❌ ModuleNotFoundError: bcrypt

증상

회원가입 시 비밀번호 해시 오류

해결

pip install bcrypt

---

---

❌ 이메일 형식 오류 (모든 이메일 실패)

원인

정규식 이중 이스케이프

해결

EMAIL_REGEX = re.compile(r"^[^\s@]+@[^\s@]+\.[^\s@]+$")

---

---

❌ SSH 접속 멈춤

증상

접속 후 아무 반응 없음

해결

✔ EC2 콘솔 → Reboot
✔ 또는 SSH 재시작

sudo systemctl restart ssh

---

---

---

✅ 3️⃣ 배포 최종 체크리스트 (운영 전 필수)

배포 완료 후 반드시 확인합니다.

---

🔹 Vercel 환경 변수

• NEXT_PUBLIC_API_BASE_URL=/api/proxy
• 백엔드 서버: 51.21.202.235:8000

---

🔹 EC2 상태 확인

systemctl status aura-api

👉 active (running)

ss -tlnp | grep 8000

👉 uvicorn 리스닝 확인

---

🔹 기능 테스트

✔ 회원가입 성공
✔ 소셜 로그인 성공
✔ /users/me 정상
✔ /sessions 정상

---

---

✅ Part 4 전체 요약

이번 파트에서 정리한 내용

✔ 서버 접속/실행 명령어 정리
✔ systemd 영구 실행 설정
✔ 실제 발생 오류 대응법
✔ 운영 체크리스트

---

🎯 최종 결론

👉 운영 환경에서는 반드시

• systemd 사용
• 프록시 구조 유지
• 의존성 관리
• 체크리스트 점검

이 4가지를 습관화하면 장애가 거의 발생하지 않습니다.

---