# MD Global University 학사관리 시스템 — 로컬 개발 및 신규 운영 서버 구축·배포 가이드

- 문서 버전: v0.1 / 2026-10-12
- 도메인: https://g-dts.com
- 저장소: https://github.com/GilbertMoon/university-academic-system
- 관련 문서: [상세 요구사항](REQUIREMENTS_V1.md)
- **상태: 실행 가이드 초안. Django 소스, Dockerfile, Compose, CI/CD workflow의 실제 존재 및 실행 가능 여부는 별도 확인해야 한다. 이 문서는 서버 구축이나 배포를 수행하지 않는다.**

## 0. 운영 원칙과 단계별 게이트

**핵심:** 교회 CMS와 Python/Django/PostgreSQL/Nginx/Docker Compose/GitHub Actions라는 기반 스택은 통일하되, 학사관리는 Wagtail 대신 Django Admin + 커스텀 업무 화면을 사용한다.

| 구분 | 권장 기술 |
| --- | --- |
| 로컬 | Windows, VS Code, Git, Python 3.12, venv, PostgreSQL 16 |
| 서버 | 별도 Ubuntu 24.04 LTS VPS (예: Cafe24) |
| 애플리케이션 | Django 5.2 LTS(호환성 검증 후 고정), Templates, Bootstrap 5, HTMX/Alpine.js 선택 |
| DB | PostgreSQL 16(호환성 검증 후 고정) |
| 문서 | WeasyPrint(PDF), openpyxl(Excel) |
| 서비스 | Gunicorn + Nginx + Let's Encrypt |
| 배포 | Docker Compose + GitHub Actions 승인형 배포 |
| 인증 | 승인된 직원의 ID/PW, 카카오/Google 로그인; OTP는 v1 제외 |

**단계별 완료 조건**
1. A: 신규 VPS SSH 접속 및 OS 확인
2. B: DNS `g-dts.com`/선택적 `www.g-dts.com` 연결
3. C: Nginx HTTP 임시 안내 페이지 표시
4. D: Let's Encrypt HTTPS 발급·갱신 검증
5. E: Windows 로컬 Django/PostgreSQL 접속
6. F: 인증·권한·개인정보 분리 설계 및 보안 검증
7. G: Docker 기반 최소 앱/DB 연동
8. H: GitHub Actions 테스트 및 승인형 배포
9. I: 운영 백업/복원·감사로그·접근통제 인수 검증

**중요:** C/D 단계의 임시 페이지에는 개인정보가 없고, 실사용 직원 계정도 열지 않는다. 학사 기능과 운영 DB 공개는 P0 보안 검증 및 대학 승인 후에만 허용한다.

## 1. 신규 VPS 생성과 SSH

1. Cafe24 등에서 Ubuntu 24.04 LTS OS-only VPS 생성. 권장 시작 사양은 2 vCPU, RAM 4GB 이상, SSD 40GB 이상이며 PDF 처리량·데이터 규모에 따라 조정한다.
2. 공인 IP, 서버 관리 계정, SSH 키, DNS 관리 권한 확인.
3. 방화벽 TCP 22(관리 IP만), 80, 443 허용. **5432(DB), 8000(Gunicorn)은 외부에 공개 금지.**
4. 학사관리 시스템과 교회 홈페이지는 **별도 VPS, 별도 DB, 별도 계정, 별도 SSH 키/비밀키, 별도 백업** 사용 권장.

Windows PowerShell:
```powershell
ssh <SERVER_USER>@<SERVER_IP>
```
호스트키 지문을 별도 신뢰 경로에서 확인한 뒤 접속한다.

Ubuntu:
```bash
cat /etc/os-release
df -h
free -h
timedatectl
sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl ca-certificates gnupg nginx certbot python3-certbot-nginx ufw
sudo systemctl enable --now nginx
```
정상 결과: Ubuntu 버전 확인, nginx active. UFW는 SSH 허용 및 두 번째 SSH 세션 재접속을 검증한 뒤 활성화한다.
```bash
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose
```
SSH 사용자 지정 포트 사용 시 `OpenSSH` 규칙 대신 실제 포트를 허용한다. 서버 콘솔 복구 수단을 먼저 확인한다.

## 2. 도메인 DNS 설정

도메인 DNS를 실제 관리하는 업체의 레코드 설정에서 다음을 적용한다.

| 종류 | 호스트 | 값 |
| --- | --- | --- |
| A | @ | <SERVER_IP> |
| CNAME | www | g-dts.com (www를 사용할 경우) |
| AAAA | @ / www | 실제 IPv6가 정상 서비스되지 않으면 잘못된 AAAA 제거 |

기존 메일용 MX/TXT/SPF/DKIM/DMARC 레코드를 함부로 변경하지 않는다. 다른 서비스가 현재 도메인을 사용 중이면 **기존 DNS를 교체하기 전에 서비스 영향과 전환 시간을 승인받는다.**

Windows에서:
```powershell
nslookup g-dts.com
Resolve-DnsName g-dts.com -Type A
Resolve-DnsName g-dts.com -Type AAAA
```
정상 결과: A 레코드가 새 서버 공인 IP를 반환. TTL/캐시로 반영 지연 가능.

## 3. 앱 없이 Nginx HTTP 임시 페이지부터 배포

서버:
```bash
sudo mkdir -p /var/www/g-dts-bootstrap
echo '<!doctype html><html lang="ko"><meta charset="utf-8"><title>학사관리 시스템</title><body><h1>학사관리 시스템</h1><p>신규 서버 연결 테스트 성공</p></body></html>' | sudo tee /var/www/g-dts-bootstrap/index.html >/dev/null
sudo tee /etc/nginx/sites-available/g-dts.conf >/dev/null <<'EOF'
server {
    listen 80;
    server_name g-dts.com www.g-dts.com;
    root /var/www/g-dts-bootstrap;
    index index.html;
    location / { try_files $uri $uri/ =404; }
}
EOF
sudo ln -s /etc/nginx/sites-available/g-dts.conf /etc/nginx/sites-enabled/g-dts.conf
sudo nginx -t && sudo systemctl reload nginx
```
이미 symlink가 있다면 생성 생략. 다른 Nginx virtual host가 있다면 server_name 충돌을 점검한다.

Windows:
```powershell
curl.exe -I http://g-dts.com/
```
정상 결과: HTTP 200 및 임시 안내 페이지. 실패 시 DNS, 방화벽, `sudo systemctl status nginx`, `sudo journalctl -u nginx -n 50 --no-pager` 확인.

## 4. Let's Encrypt 인증서 설치 및 자동 갱신

사전 조건: DNS가 신규 서버를 가리키고 80/443 접근 가능.

```bash
sudo certbot --nginx -d g-dts.com --redirect
```
www도 DNS/HTTP가 검증되고 사용할 예정이면 `-d www.g-dts.com`을 추가한다. Certbot에서 운영 관리자 이메일과 약관을 입력한다.

```bash
sudo nginx -t
sudo certbot certificates
sudo certbot renew --dry-run
curl -I https://g-dts.com/
systemctl list-timers | grep -i certbot
```
정상 결과: 유효한 인증서, HTTPS 200, HTTP→HTTPS 리다이렉트, dry-run PASS. 자동 갱신 방식은 설치 환경에 따라 timer 또는 cron.

**주의:** HTTPS가 정상이라는 사실만으로 학사관리 시스템의 개인정보 보호가 완료된 것은 아니다.

## 5. Windows + VS Code 로컬 개발환경

공식 설치:
- Git: https://git-scm.com/downloads/win
- Python: https://www.python.org/downloads/
- VS Code: https://code.visualstudio.com/
- PostgreSQL: https://www.postgresql.org/download/windows/

PowerShell:
```powershell
git --version
py -3.12 --version
code --version
psql --version
mkdir C:\DEV -ErrorAction SilentlyContinue
cd C:\DEV
git clone https://github.com/GilbertMoon/university-academic-system.git
cd university-academic-system
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
```
실행 정책 때문에 activate가 차단되면 `.\.venv\Scripts\python.exe`를 직접 사용한다. PowerShell 정책을 무분별하게 전역 변경하지 않는다.

### Django 초기화(소스 구현 단계에서만)

현재 코드 유무를 확인한 뒤, **기존 manage.py나 프로젝트 디렉터리가 있으면 덮어쓰지 않는다.**

```powershell
python -m pip install "Django>=5.2,<6" "psycopg[binary]" python-dotenv openpyxl
# 신규 프로젝트이고 manage.py가 없을 때만:
python -m django startproject config .
```
Django Templates/Bootstrap 5를 사용하고 HTMX/Alpine.js는 필요한 업무 화면에만 적용한다. Gunicorn은 Linux 운영에서 사용한다. WeasyPrint는 OS 라이브러리·다국어 폰트 의존성을 검증하고 Linux/Docker에서 PDF 테스트를 우선 수행한다.

로컬 PostgreSQL 관리자 계정에서:
```sql
CREATE ROLE university_dev LOGIN PASSWORD 'CHANGE_TO_UNIQUE_LOCAL_PASSWORD';
CREATE DATABASE university_dev OWNER university_dev ENCODING 'UTF8';
```
로컬 `.env.local` 예시(**Git에 커밋 금지**):
```dotenv
DJANGO_DEBUG=True
DJANGO_SECRET_KEY=GENERATE_UNIQUE_LOCAL_SECRET
DJANGO_ALLOWED_HOSTS=127.0.0.1,localhost
DATABASE_URL=postgresql://university_dev:URL_ENCODED_PASSWORD@127.0.0.1:5432/university_dev
```
이 변수들은 **settings.py에서 읽도록 별도 구현해야 한다.** 로컬 테스트에는 운영 학생 정보 대신 합성 데이터를 사용한다.

Django 설정 구현 후:
```powershell
python manage.py check
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver 127.0.0.1:8000
```
정상 결과: http://127.0.0.1:8000/ 및 /admin/ 접속. 관리자 화면은 **초기 개발 확인용**이며 실제 학사관리 업무 화면은 별도 구현한다.

## 6. P0 개인정보·학사 데이터 분리 — 운영 공개 전 필수 게이트

기존 [REQUIREMENTS_V1.md](REQUIREMENTS_V1.md)의 NFR-SEC-001~010을 그대로 적용한다.

1. 학생·지원자·교원 직접 식별정보(이름, 연락처 등)는 학사 데이터에서 분리하고, 학사 업무 테이블은 **무작위 내부 식별자**만 참조한다. 학번을 비식별 키로 간주하지 않는다.
2. 개인정보와 학사정보의 스키마/접근권한을 분리한다. 별도 물리 DB 또는 별도 서비스가 필요한지는 위협모델 후 결정한다.
3. 직접 식별정보와 민감한 첨부파일은 저장 시 암호화. 암호화 키는 DB 및 백업과 분리하고 키 교체·분실 대응 절차를 만든다.
4. 직원별 역할/권한과 최소권한 적용. 학생 조회, 개인정보 복호화, 성적 정정, 납부 변경, 증명서 발급, Excel 내보내기 등 감사 기록.
5. 개발·테스트 데이터는 합성/비식별 데이터만 사용. 운영 DB를 개발 노트북에 복사하지 않는다.
6. 비밀번호는 안전한 해시 사용. 로그인 실패 제한, 세션 만료, 계정 비활성화, CSRF/XSS/SQL injection/파일 업로드 방어.
7. 카카오/Google 로그인은 **사전 승인된 내부 직원 계정에만 연결**한다. 이메일만으로 자동 계정 연결 금지. OTP는 v1 제외.
8. Excel/PDF 임시파일·로그·백업·오류 보고에 개인정보 평문 노출 최소화.
9. 개인정보 보존·파기·법적 근거는 대학의 실제 정책 및 적용 법령 확인 후 확정.
10. 인가되지 않은 직접 URL/내보내기/API 요청을 차단하는 자동 테스트를 필수화.

**공개 게이트:** 위협모델/데이터 흐름도/ERD/권한 매트릭스/암호화 키 관리/백업 복원/접근 로그 테스트의 승인 없이는 실제 학생 데이터 입력 및 운영 전환 금지.

## 7. 운영 Docker 설치

Ubuntu 서버에서 Docker 공식 문서 https://docs.docker.com/engine/install/ubuntu/ 기준:
```bash
sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo ${UBUNTU_CODENAME:-$VERSION_CODENAME}) stable" | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker version
sudo docker compose version
```
정상 결과: Docker 및 Compose 버전 출력. Docker 그룹 가입은 root 수준 권한이므로 배포 사용자에게 무조건 부여하지 않는다.

## 8. 운영 앱/DB 구성 (필요한 코드 파일은 별도 개발)

### 8.1 배포 디렉터리
```bash
sudo mkdir -p /opt/university-academic-system /var/backups/university-academic-system
sudo chown <DEPLOY_USER>:<DEPLOY_GROUP> /opt/university-academic-system
```
비공개 GitHub 저장소에는 서버 전용 **읽기 전용 Deploy Key**를 등록하고, GitHub SSH 호스트키 지문을 검증한 후 배포 계정으로:
```bash
git clone git@github.com:GilbertMoon/university-academic-system.git /opt/university-academic-system
```
서버에서 개인 PAT·암호를 명령어에 하드코딩하지 않는다.

### 8.2 서버 전용 환경변수 계약(예시)
`/opt/university-academic-system/.env.production`:
```dotenv
DJANGO_DEBUG=False
DJANGO_SECRET_KEY=GENERATE_UNIQUE_PRODUCTION_SECRET
DJANGO_ALLOWED_HOSTS=g-dts.com
DJANGO_CSRF_TRUSTED_ORIGINS=https://g-dts.com
POSTGRES_DB=university
POSTGRES_USER=university
POSTGRES_PASSWORD=GENERATE_STRONG_DB_PASSWORD
DATABASE_URL=postgresql://university:URL_ENCODED_PASSWORD@db:5432/university
```
`chmod 600` 적용. 위 설정은 **예시 계약이며 실제 Django settings와 Compose에 구현해야 작동**한다. 암호화 키는 별도 보안 저장소/권한 체계에서 관리하고, 동일 `.env`·DB 백업에 무분별하게 함께 저장하지 않는다. 비밀값은 GitHub Actions 로그에 출력하지 않는다.

### 8.3 실제 구현해야 할 파일
- `Dockerfile`: Python 고정 버전, WeasyPrint 네이티브 라이브러리·한글/중문 폰트, non-root, Gunicorn.
- `compose.prod.yml`: `web`/PostgreSQL `db`, healthcheck, 영속 볼륨, 내부 네트워크, 최소 권한.
- `requirements*.txt` 또는 lockfile, `.env.example`, `.gitignore`.
- Django production settings: DEBUG=False, secure cookies, CSRF, ALLOWED_HOSTS, 보안 헤더, 정적/보호 파일 경로, 감사 로그.
- `/health/` 비민감 상태 엔드포인트.
- `.github/workflows/ci.yml`, 승인형 `deploy.yml`.
- 개인정보 분리·암호화·접근 제어 구현 및 테스트.

**현재 파일 생성 여부를 확인하지 않은 상태에서는 `docker compose up`과 운영 migration을 실행하지 않는다.**

### 8.4 컨테이너 외부 노출 금지
- PostgreSQL 5432: host publish 금지.
- Gunicorn 8000: **127.0.0.1:8000에만 바인딩** 또는 Unix socket.
- Nginx: 외부 80/443만.
- 학생 첨부서류는 Nginx 공개 media URL로 직접 제공하지 말고 **인가 검증 후 보호된 다운로드 경로**를 사용한다.

### 8.5 Docker 파일 구현 후 배포 명령
```bash
cd /opt/university-academic-system
sudo docker compose -f compose.prod.yml --env-file .env.production build
sudo docker compose -f compose.prod.yml --env-file .env.production up -d
sudo docker compose -f compose.prod.yml --env-file .env.production ps
sudo docker compose -f compose.prod.yml --env-file .env.production exec web python manage.py check --deploy
sudo docker compose -f compose.prod.yml --env-file .env.production exec web python manage.py migrate --plan
```
**주의:** Compose `config` 명령이나 로그에 비밀값이 출력될 수 있으므로 외부에 공유하지 않는다. 운영 DB migration은 **DB 백업, 변경 계획, 승인, 롤백 전략** 검토 후에만:
```bash
sudo docker compose -f compose.prod.yml --env-file .env.production exec web python manage.py migrate
sudo docker compose -f compose.prod.yml --env-file .env.production exec web python manage.py collectstatic --noinput
```
처음부터 실제 학생정보를 넣지 않고 합성 데이터로 전체 업무 흐름을 확인한다.

## 9. Nginx ↔ Gunicorn 연결

HTTP/HTTPS 임시 페이지 검증을 마치고 Gunicorn이 `127.0.0.1:8000`에서 정상 응답할 때만 Certbot이 생성한 기존 HTTPS 서버 블록의 `location /`를 다음과 같이 변경한다.

```nginx
location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_connect_timeout 10s;
    proxy_read_timeout 60s;
}
```
Certbot이 설정한 `listen 443 ssl`, `ssl_certificate`, `ssl_certificate_key`, HTTP→HTTPS 리다이렉트는 유지한다. Django에서 `SECURE_PROXY_SSL_HEADER`를 설정할 경우 신뢰하는 프록시 경로를 제한한다. 정적 자산만 공개 서빙하고 **개인정보·성적표·증명서·첨부서류는 공개 alias로 서빙 금지**.

```bash
sudo nginx -t && sudo systemctl reload nginx
curl -I http://127.0.0.1:8000/
curl -I https://g-dts.com/
```
정상 결과: HTTPS 정상, 비승인 사용자는 업무 화면 접근 불가. 관리자 계정 생성·로그인은 안전한 서버 세션에서 진행한다.

## 10. CI/CD — GitHub Actions

### CI
- PR/push 시 Django system check, 단위·통합 테스트, PostgreSQL 테스트 DB, migration drift 검사.
- 인증: 미승인 ID/PW, 카카오/Google 계정 연결, 세션 만료, 권한 우회 테스트.
- 개인정보: 가명 식별자, 암호화, 복호화 권한, 대량 추출, 로그 평문 유출 테스트.
- 성적·납부·학적 변경 감사 로그 및 동시성 테스트.
- 국문·영문·중문 PDF 출력과 Excel import/export 검증.
- 운영 데이터·실제 비밀키는 CI에 전달하지 않음.

### CD
- 초기에는 `workflow_dispatch` 수동 트리거 및 `production` 환경 승인형 배포 권장.
- CI PASS, 배포 commit SHA 고정, 서버 접근 키/호스트키 검증, DB 백업 확인.
- migration은 자동 실행하지 않고 별도 승인 게이트로 수행.
- 배포 후 HTTPS, 로그인 차단, 핵심 업무 smoke test.
- GitHub Actions의 무료 사용량/예산 및 한도 초과 차단 설정 확인.

## 11. 백업·복구·모니터링

- DB·보호 파일·증명서 생성물·감사 로그를 범위에 맞게 암호화 백업.
- **암호화 키는 DB 백업과 별도 위치/권한으로 관리**; 키 분실 시 복구 불가 위험에 대비한 안전한 복구 정책 마련.
- 일일 백업, 오프사이트 보관, 보존·파기 기간, 복구 목표(RPO/RTO)는 대학과 확정.
- 분리된 테스트 환경에서 백업 복원 및 권한/암호화 복구 테스트.
- 로그에 주민/여권번호, 이름, 연락처, 성적, 비밀번호, 토큰 등이 불필요하게 기록되지 않도록 차단.

점검:
```bash
sudo systemctl status nginx
sudo journalctl -u nginx -n 100 --no-pager
sudo certbot renew --dry-run
df -h
free -h
sudo docker compose -f /opt/university-academic-system/compose.prod.yml --env-file /opt/university-academic-system/.env.production ps
```

## 12. 장애 진단

| 증상 | 점검 |
| --- | --- |
| DNS 오류 | 실제 네임서버, A/AAAA/CNAME, TTL |
| HTTP 미접속 | Cafe24 방화벽, UFW, nginx 상태 |
| TLS 발급 실패 | DNS, 80 포트, Certbot 로그 |
| HTTPS 502 | Gunicorn, 127.0.0.1:8000, Docker 로그 |
| Django 400/403 | ALLOWED_HOSTS, CSRF_TRUSTED_ORIGINS, proxy 설정 |
| 로그인 불가 | 승인된 직원 계정, 외부 OAuth 설정, 로그인 제한 |
| DB 연결 실패 | DB healthcheck, 내부 네트워크, 인증정보 |
| PDF 글꼴 오류 | 한글/영문/중문 폰트, WeasyPrint 의존성 |
| 권한 누출 | RBAC, 파일 다운로드 권한, 로그/감사 |
| 배포 실패 | Git SHA, CI 결과, 서버 리소스, 승인 여부 |

## 13. 완료 체크리스트

- [ ] 신규 VPS SSH 접속 및 방화벽 확인
- [ ] g-dts.com DNS 연결 확인
- [ ] Nginx 임시 HTTP 페이지 정상
- [ ] HTTPS 인증서 발급 및 renew dry-run PASS
- [ ] Windows VS Code/Python venv/PostgreSQL 준비
- [ ] Django 초기 프로젝트 및 로컬 실행
- [ ] 개인정보 분리 ERD·위협모델·암호화 키 정책 승인
- [ ] 승인 직원 로그인·권한/감사 기능 구현
- [ ] Dockerfile/Compose/production settings 구현
- [ ] 운영 DB 최초 migration 백업·승인 후 완료
- [ ] Nginx/Gunicorn/PostgreSQL 연결
- [ ] 학생/학적/성적/등록금 핵심 업무 테스트
- [ ] 3개 언어 증명서 PDF 및 Excel 테스트
- [ ] GitHub Actions CI PASS 및 승인형 CD
- [ ] 암호화 백업 및 별도 환경 복원 검증
- [ ] 대학 담당자 UAT·개인정보 보안 승인 후 운영 개시

## 14. 다음 개발 작업

이 문서 다음 단계는 **Django 최소 실행 프로젝트, DB 설정, Dockerfile, Compose, .env.example, healthcheck, GitHub Actions CI**를 실제 코드로 추가하는 것이다. 그 다음 개인정보 분리·암호화·RBAC·로그인부터 구현하고, 업무 모듈을 단계적으로 개발한다.

**문서에 실계정, 공인 IP, 비밀번호, API 키, 학생정보를 기재하지 않는다.**
