백엔드 설치 가이드

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`	학교 서버 HTTP 통신
`beautifulsoup4`	웹메일 SSO 로그인 폼·메일함 트리·본문 HTML 파싱/정제
`PyMySQL`	MariaDB/MySQL 드라이버
`gunicorn`	프로덕션 WSGI 서버

4. 환경변수 설정

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

# backend/.env

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

# 세션 암호화 키 — base64 인코딩된 32바이트 (필수, 없으면 로그인 불가)
# 생성: python -c "import os,base64;print(base64.b64encode(os.urandom(32)).decode())"
MASTER_KEY=

# 데이터베이스 (MariaDB)
DB_NAME=soonlife
DB_USER=soonlife
DB_PASSWORD=your-db-password
DB_HOST=192.168.1.122
DB_PORT=3306

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

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

# 신뢰할 리버스 프록시 홉 수 — X-Forwarded-For에서 실제 클라이언트 IP를 찾는 데 쓴다
# TRUSTED_PROXY_HOPS=1

# 로그인 Cloudflare Turnstile — 두 키가 모두 있어야 활성화 (없으면 자동으로 꺼짐)
# TURNSTILE_SITE_KEY=
# TURNSTILE_SECRET_KEY=
# TURNSTILE_TIMEOUT=5
# TURNSTILE_FAIL_OPEN=False

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

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

python manage.py migrate

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

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

마이그레이션 0006~0011은 제거된 챗봇 모델(chat_*)을 만드는 이력입니다. 모델은 지워졌지만 삭제 마이그레이션이 없어, 새 DB에서는 쓰이지 않는 chat_* 테이블이 함께 생성됩니다. 자세한 내용은 아키텍처를 참고하세요.

공지사항 테이블(academic_notices, career_notices, meal_menus 등)은 별도 스크래퍼가 적재하며 Django 모델이 아닙니다. 마이그레이션으로 만들어지지 않고 raw SQL로 읽습니다.

6. 개발 서버 실행

python manage.py runserver

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

프로덕션 배포

# 프로덕션에서는 gunicorn 사용 — gthread 워커 (scripts/server-setup.sh와 동일 설정)
gunicorn portal.wsgi:application \
    --bind 0.0.0.0:8000 \
    --workers 3 \
    --worker-class gthread \
    --threads 8 \
    --timeout 600

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

평소 배포는 손으로 하지 않습니다 — main 브랜치에 push하면 GitHub Actions가 처리합니다. 배포 문서를 참고하세요.

서버의 backend/.env가 정본입니다. 배포 스크립트도 워크플로도 이 파일을 덮어쓰지 않으므로, 키를 추가하려면 서버에서 직접 편집하고 sudo systemctl restart sch-portal을 실행해야 합니다.

CORS 허용 오리진

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

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

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

백엔드 설치 가이드

On this page