백엔드 설치 가이드

1. 저장소 클론 및 디렉터리 이동

git clone <repository-url>
cd SCH-WEB-PORTAL/backend

2. 가상환경 생성 및 활성화

# 가상환경 생성
python -m venv .venv

# 활성화 (macOS/Linux)
source .venv/bin/activate

# 활성화 (Windows)
.venv\Scripts\activate

3. 의존성 설치

pip install -r requirements.txt

설치되는 주요 패키지:

패키지	역할
`Django 6.0.5`	웹 프레임워크
`djangorestframework`	REST API
`django-cors-headers`	CORS 허용
`python-dotenv`	환경변수 로드
`cryptography`	세션 암호화
`requests`	SCH 서버 HTTP 통신
`PyMySQL`	MySQL 드라이버
`gunicorn`	프로덕션 WSGI 서버

AI 챗봇 첨부파일 처리용 (docx/hwp 렌더링은 LibreOffice soffice 별도 설치 필요):

패키지	역할
`pymupdf`	pdf/hwp/docx → 페이지 PNG 렌더링
`pdfminer.six`	pdf 텍스트 추출 폴백
`python-docx`	docx 텍스트 추출 폴백
`openpyxl`	xlsx → CSV 텍스트
`pyhwp`	hwp 변환 (`hwp5odt`/`hwp5html`)
`six`	`pyhwp`의 런타임 의존성 (메타데이터에 미선언이라 별도 명시)

4. 환경변수 설정

backend/ 디렉터리에 .env 파일을 생성합니다.

# backend/.env

SECRET_KEY=your-secret-key-here
DEBUG=True

# 데이터베이스
DB_NAME=sch_portal
DB_USER=sch_portal
DB_PASSWORD=your-db-password
DB_HOST=localhost
DB_PORT=3306

# 쿠키 설정 (개발환경은 생략 가능)
# SCH_COOKIE_DOMAIN=
# SCH_COOKIE_SECURE=false

# 허용 호스트 (프로덕션)
# ALLOWED_HOSTS=yourdomain.com

# AI 챗봇 — 자체 호스팅 vLLM 서버 (OpenAI 호환 API)
VLLM_BASE_URL=http://localhost:8000/v1
VLLM_MODEL=soonlife-qwen
# VLLM_CONTEXT_LEN=0        # 0이면 /models로 자동 감지
# AGENT_MAX_TURNS=10        # 도구 호출 루프 최대 반복 횟수
# VLLM_TIMEOUT=180
# VLLM_TEMPERATURE=0.3
# VLLM_MAX_TOKENS=4096
# ENABLE_THINKING=true

# AI 챗봇 — 시맨틱 검색 서버 (BGE-M3 + Qdrant + reranker). 비워두면 키워드 검색으로 대체
# EMBED_SEARCH_URL=
# EMBED_SEARCH_TIMEOUT=20

챗봇 관련 환경변수를 비워두면 해당 기능만 대체 동작(키워드 검색 등)하고, VLLM_BASE_URL이 가리키는 서버가 없으면 챗봇 응답 자체가 실패합니다. 로컬 개발 중 챗봇을 쓰지 않는다면 그대로 두어도 나머지 API는 정상 동작합니다.

MASTER_KEY는 세션 암호화에 사용됩니다. 절대 외부에 노출하지 마세요.

5. 데이터베이스 마이그레이션

python manage.py migrate

마이그레이션으로 생성되는 테이블:

테이블	설명
`student_favorites`	즐겨찾기 항목
`timetable_themes`	시간표 테마
`student_timetable_themes`	학생별 적용 테마
`academic_events`	학사일정 캐시

6. 개발 서버 실행

python manage.py runserver

서버가 http://localhost:8000에서 실행됩니다.

프로덕션 배포

# 프로덕션에서는 gunicorn 사용 — gthread 워커로 챗봇의 긴 스트리밍 응답을 지원
gunicorn portal.wsgi:application \
    --bind 0.0.0.0:8000 \
    --workers 3 \
    --worker-class gthread \
    --threads 8 \
    --timeout 600

sync 워커(기본값)는 요청 처리 중 하트비트를 보내지 못해 챗봇처럼 오래 걸리는 스트리밍 응답이 타임아웃으로 강제 종료됩니다(브라우저에는 network error로 표시). 챗봇을 운영한다면 반드시 gthread 워커 + 넉넉한 --timeout을 사용하세요.

프로덕션 배포 시 .env에서 DEBUG=False, SECRET_KEY를 반드시 설정하고 ALLOWED_HOSTS를 지정하세요.

CORS 허용 오리진

portal/settings.py에서 관리됩니다.

CORS_ALLOWED_ORIGINS = [
    "http://localhost:5173",     # 개발용 Vite
    "http://127.0.0.1:5173",
    "https://sch.wonchan.net",   # 프로덕션
    "http://sch.wonchan.net",
]

새 배포 환경을 추가할 경우 이 목록에 오리진을 추가합니다.

백엔드 설치 가이드

On this page