Appearance
Backend Server 환경 설정
이 문서는 백엔드 서버를 로컬/개발 환경에서 실행하고, 운영 배포를 준비할 때 필요한 최소 절차를 정리합니다.
필수 조건
- Python 기반 런타임 환경(프로젝트 요구 버전 확인 필요)
- Node 기반 관리 도구를 함께 쓰는 경우가 있으므로 Git, Docker, 터미널 도구는 최신 버전 권장
- Supabase 프로젝트 또는 상응하는 벡터 저장소
- 외부 LLM API 키 또는 임베딩 서비스 접근 권한
환경 변수
| 변수 | 설명 | 예시 |
|---|---|---|
ENV | 실행 모드 (local, staging, production) | local |
PORT | API 수신 포트 | 8080 |
DATABASE_URL | 메타데이터 DB 연결 문자열 | postgres://... |
SUPABASE_URL | Supabase 프로젝트 URL | https://xxx.supabase.co |
SUPABASE_SERVICE_ROLE_KEY | 서비스 역할 키 | ey... |
OPENAI_API_KEY 또는 LLM_API_KEY | 임베딩/LLM 호출용 키 | sk-... |
JWT_SECRET | 토큰 서명 키 | 복잡한 랜덤 문자열 |
ALLOWED_ORIGINS | CORS 허용 오리진(쉼표 구분) | http://localhost:5173 |
로컬 실행 흐름(예시)
- 의존성 설치
- 환경 변수 적용
- DB 마이그레이션 또는 초기 시드 적용
- API 서버 실행
- 필요 시 백그라운드 작업기 실행
bash
# 예시. 실제 경로/스크립트는 저장소 버전에 맞춰 조정
cp .env.example .env
# 패키지 설치
pip install -r requirements.txt
# 서버 실행
uvicorn app.main:app --reload --host 0.0.0.0 --port 8080배포 체크리스트
- 민감 값은 시크릿 스토어로 관리
- CORS는 운영 도메인만 허용
- 요청 로깅, 오류 추적, 지연시간 지표 수집
- 작업 큐 크기/타임아웃/재시도 정책 적용
- 벡터 인덱스 재빌드 정책 정기화
문제해결
500급 에러가 반복되면 DB 연결 문자열, API 키, 권한 정책을 먼저 점검- 검색 결과 누락 시 임베딩 수집 여부와 chunking 상태 확인
- Agent 실행 실패 시 작업 로그, 타임아웃, 외부 LLM 응답 상태를 분리해서 추적