DEPLOYMENT_GUIDE.md

DigitalOcean 배포 가이드

목차

1. 사전 준비사항
2. Droplet 생성
3. 서버 초기 설정
4. Ollama 설치 및 설정
5. 프로젝트 배포
6. Nginx 설정
7. SSL 인증서 설정
8. systemd 서비스 설정
9. 백업 설정
10. 모니터링 설정
11. 문제 해결

---

사전 준비사항

필요한 것들:

• DigitalOcean 계정 (https://www.digitalocean.com/)
• 도메인 (선택사항, 있으면 좋음)
• GitHub/GitLab 저장소 (또는 프로젝트 파일)
• Gemini API 키 (사용하는 경우)

예상 비용:

• Droplet (8GB RAM): $48/월
• 도메인: $10-15/년 (선택사항)
• 총: 약 $48-50/월

---

Droplet 생성

1. DigitalOcean 로그인 및 Droplet 생성

1. https://www.digitalocean.com/ 접속 및 로그인
2. "Create" → "Droplets" 클릭
3. 다음 설정 선택:

이미지:

• Ubuntu 22.04 (LTS) x64

플랜:

• Regular (일반)
• 8GB RAM / 4 vCPUs / 160GB SSD ($48/월) 추천
• 또는 4GB RAM / 2 vCPUs / 80GB SSD ($24/월) - 최소 사양

데이터센터 지역:

• Singapore (싱가포르) - 한국에서 가장 가까움
• 또는 Seoul (서울) - 가능한 경우

인증:

• SSH 키 추가 (권장)
• 또는 비밀번호 설정

추가 옵션:

• Monitoring 활성화
• Backups 활성화 (선택사항, 추가 비용)

4. "Create Droplet" 클릭

2. 서버 접속 정보 확인

생성 완료 후 이메일로 IP 주소와 접속 정보를 받게 됩니다.

• IP 주소: 예) 123.45.67.89
• Root 비밀번호 (비밀번호 방식인 경우)

---

서버 초기 설정

1. SSH로 서버 접속

Windows (PowerShell):

ssh root@YOUR_SERVER_IP

Mac/Linux:

ssh root@YOUR_SERVER_IP

2. 시스템 업데이트

# 시스템 업데이트
apt update && apt upgrade -y

# 필수 패키지 설치
apt install -y \
    python3 \
    python3-pip \
    python3-venv \
    git \
    curl \
    wget \
    nginx \
    certbot \
    python3-certbot-nginx \
    supervisor \
    ufw \
    htop \
    nano \
    build-essential \
    libssl-dev \
    libffi-dev \
    python3-dev

3. 방화벽 설정

# UFW 방화벽 활성화
ufw allow OpenSSH
ufw allow 'Nginx Full'
ufw allow 11434/tcp  # Ollama 포트
ufw enable
ufw status

4. 사용자 생성 (선택사항, 보안을 위해 권장)

# 새 사용자 생성
adduser deploy
usermod -aG sudo deploy

# SSH 키 복사 (로컬에서)
# Windows: type C:\Users\YourName\.ssh\id_rsa.pub | ssh root@YOUR_SERVER_IP "cat >> /home/deploy/.ssh/authorized_keys"
# Mac/Linux: ssh-copy-id deploy@YOUR_SERVER_IP

# deploy 사용자로 전환
su - deploy

---

Ollama 설치 및 설정

1. Ollama 설치

# Ollama 설치 스크립트 실행
curl -fsSL https://ollama.com/install.sh | sh

# Ollama 서비스 확인
systemctl status ollama

# Ollama 자동 시작 설정
systemctl enable ollama

2. Ollama 모델 다운로드

# 사용할 모델 다운로드 (예: llama2)
ollama pull llama2

# 또는 다른 모델
# ollama pull mistral
# ollama pull qwen

# 설치된 모델 확인
ollama list

3. Ollama 서비스 확인

# Ollama가 정상 작동하는지 확인
curl http://localhost:11434/api/tags

# 서비스 재시작
systemctl restart ollama

---

프로젝트 배포

1. 프로젝트 디렉토리 생성

# 홈 디렉토리로 이동
cd ~

# 프로젝트 디렉토리 생성
mkdir -p /var/www
cd /var/www

# 소유권 설정 (deploy 사용자 사용 시)
# chown -R deploy:deploy /var/www

2. 프로젝트 파일 업로드

방법 1: Git 사용 (권장)

# Git 저장소 클론
git clone YOUR_REPOSITORY_URL "soy-nv-ai"
cd soy-nv-ai

# 또는 직접 파일 업로드
# scp -r "D:\SOY NV AI\*" deploy@YOUR_SERVER_IP:/var/www/soy-nv-ai/

방법 2: SCP로 파일 전송 (Windows PowerShell)

# 프로젝트 폴더 전체 업로드
scp -r "D:\SOY NV AI\*" deploy@YOUR_SERVER_IP:/var/www/soy-nv-ai/

3. 가상환경 설정

cd /var/www/soy-nv-ai

# 가상환경 생성
python3 -m venv venv

# 가상환경 활성화
source venv/bin/activate

# pip 업그레이드
pip install --upgrade pip

# 의존성 설치
pip install -r requirements.txt

# 설치 확인
python --version
pip list

4. 환경 변수 설정

# .env 파일 생성
nano .env

.env 파일 내용:

# Flask 설정
SECRET_KEY=your-super-secret-key-change-this-in-production
FLASK_ENV=production
FLASK_DEBUG=False

# 데이터베이스
DATABASE_URL=sqlite:///var/www/soy-nv-ai/instance/finance_analysis.db

# Ollama 설정
OLLAMA_BASE_URL=http://localhost:11434

# Gemini API (사용하는 경우)
GEMINI_API_KEY=your-gemini-api-key-here

# 업로드 폴더
UPLOAD_FOLDER=/var/www/soy-nv-ai/uploads
VECTOR_DB_PATH=/var/www/soy-nv-ai/vector_db
KNOWLEDGE_GRAPH_PATH=/var/www/soy-nv-ai/knowledge_graphs

# 임베딩 모델
EMBEDDING_MODEL_NAME=sentence-transformers/all-MiniLM-L6-v2
RERANKER_MODEL_NAME=BAAI/bge-reranker-base

SECRET_KEY 생성 방법:

python3 -c "import secrets; print(secrets.token_hex(32))"

5. 디렉토리 권한 설정

# 필요한 디렉토리 생성
mkdir -p instance uploads vector_db knowledge_graphs logs

# 권한 설정
chmod -R 755 /var/www/soy-nv-ai
chown -R deploy:deploy /var/www/soy-nv-ai  # deploy 사용자 사용 시

# 업로드 폴더 쓰기 권한
chmod -R 775 uploads
chmod -R 775 instance
chmod -R 775 vector_db

6. 애플리케이션 테스트

# 가상환경 활성화
source venv/bin/activate

# 데이터베이스 초기화
python -c "from app import create_app; app = create_app(); app.app_context().push(); from app.database import db; db.create_all()"

# 서버 테스트 실행
python run.py

다른 터미널에서 테스트:

curl http://localhost:5001

정상 작동하면 Ctrl+C로 중지합니다.

---

Nginx 설정

1. Nginx 설정 파일 생성

sudo nano /etc/nginx/sites-available/soy-nv-ai

설정 파일 내용:

server {
    listen 80;
    server_name YOUR_DOMAIN.com www.YOUR_DOMAIN.com;
    # 또는 IP 주소만 사용: server_name YOUR_SERVER_IP;

    # 로그 설정
    access_log /var/log/nginx/soy-nv-ai-access.log;
    error_log /var/log/nginx/soy-nv-ai-error.log;

    # 클라이언트 최대 업로드 크기 (100MB)
    client_max_body_size 100M;

    # 프록시 설정
    location / {
        proxy_pass http://127.0.0.1:5001;
        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;
        
        # WebSocket 지원 (필요한 경우)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        # 타임아웃 설정 (AI 응답이 오래 걸릴 수 있음)
        proxy_connect_timeout 600s;
        proxy_send_timeout 600s;
        proxy_read_timeout 600s;
    }

    # 정적 파일 직접 제공 (선택사항)
    location /static {
        alias /var/www/soy-nv-ai/static;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}

2. 설정 파일 활성화

# 심볼릭 링크 생성
sudo ln -s /etc/nginx/sites-available/soy-nv-ai /etc/nginx/sites-enabled/

# 기본 설정 비활성화 (선택사항)
sudo rm /etc/nginx/sites-enabled/default

# Nginx 설정 테스트
sudo nginx -t

# Nginx 재시작
sudo systemctl restart nginx
sudo systemctl enable nginx

3. 방화벽 확인

# Nginx 포트 확인
sudo ufw status

---

SSL 인증서 설정

1. Let's Encrypt SSL 인증서 설치

도메인이 있는 경우:

# Certbot으로 SSL 인증서 발급
sudo certbot --nginx -d YOUR_DOMAIN.com -d www.YOUR_DOMAIN.com

# 자동 갱신 테스트
sudo certbot renew --dry-run

도메인이 없는 경우 (IP만 사용):

• SSL 인증서는 발급할 수 없습니다
• HTTP로만 접속 가능 (보안상 권장하지 않음)
• 내부 네트워크나 VPN 사용 고려

2. 자동 갱신 설정

# Certbot 자동 갱신은 이미 systemd 타이머로 설정됨
sudo systemctl status certbot.timer

---

systemd 서비스 설정

1. 서비스 파일 생성

sudo nano /etc/systemd/system/soy-nv-ai.service

서비스 파일 내용:

[Unit]
Description=SOY NV AI Flask Application
After=network.target ollama.service

[Service]
Type=simple
User=deploy
Group=deploy
WorkingDirectory=/var/www/soy-nv-ai
Environment="PATH=/var/www/soy-nv-ai/venv/bin"
Environment="FLASK_ENV=production"
ExecStart=/var/www/soy-nv-ai/venv/bin/python /var/www/soy-nv-ai/run.py
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=soy-nv-ai

# 리소스 제한 (선택사항)
LimitNOFILE=65535
MemoryLimit=6G

[Install]
WantedBy=multi-user.target

2. 서비스 활성화 및 시작

# systemd 재로드
sudo systemctl daemon-reload

# 서비스 활성화 (부팅 시 자동 시작)
sudo systemctl enable soy-nv-ai

# 서비스 시작
sudo systemctl start soy-nv-ai

# 서비스 상태 확인
sudo systemctl status soy-nv-ai

# 로그 확인
sudo journalctl -u soy-nv-ai -f

3. 서비스 관리 명령어

# 서비스 시작
sudo systemctl start soy-nv-ai

# 서비스 중지
sudo systemctl stop soy-nv-ai

# 서비스 재시작
sudo systemctl restart soy-nv-ai

# 서비스 상태 확인
sudo systemctl status soy-nv-ai

# 로그 확인
sudo journalctl -u soy-nv-ai -n 50
sudo journalctl -u soy-nv-ai -f  # 실시간 로그

---

백업 설정

1. 백업 스크립트 생성

nano /var/www/soy-nv-ai/backup.sh

백업 스크립트 내용:

#!/bin/bash

# 백업 디렉토리
BACKUP_DIR="/var/backups/soy-nv-ai"
DATE=$(date +%Y%m%d_%H%M%S)

# 백업 디렉토리 생성
mkdir -p $BACKUP_DIR

# 데이터베이스 백업
cp /var/www/soy-nv-ai/instance/finance_analysis.db $BACKUP_DIR/db_$DATE.db

# 업로드 파일 백업
tar -czf $BACKUP_DIR/uploads_$DATE.tar.gz /var/www/soy-nv-ai/uploads

# 벡터 DB 백업
tar -czf $BACKUP_DIR/vector_db_$DATE.tar.gz /var/www/soy-nv-ai/vector_db

# 오래된 백업 삭제 (30일 이상)
find $BACKUP_DIR -type f -mtime +30 -delete

echo "Backup completed: $DATE"

2. 백업 스크립트 실행 권한 부여

chmod +x /var/www/soy-nv-ai/backup.sh

3. Cron으로 자동 백업 설정

# Crontab 편집
crontab -e

# 매일 새벽 2시에 백업 실행
0 2 * * * /var/www/soy-nv-ai/backup.sh >> /var/log/soy-nv-ai-backup.log 2>&1

---

모니터링 설정

1. 서버 리소스 모니터링

# htop 설치 (이미 설치됨)
htop

# 또는 기본 top
top

2. 디스크 사용량 확인

df -h
du -sh /var/www/soy-nv-ai/*

3. 외부 모니터링 서비스 (선택사항)

Uptime Robot (무료):

• https://uptimerobot.com/
• 5분마다 서버 상태 확인
• 다운타임 알림

Pingdom:

• https://www.pingdom.com/
• 더 상세한 모니터링

---

문제 해결

1. 서비스가 시작되지 않는 경우

# 서비스 상태 확인
sudo systemctl status soy-nv-ai

# 로그 확인
sudo journalctl -u soy-nv-ai -n 100

# 수동 실행으로 오류 확인
cd /var/www/soy-nv-ai
source venv/bin/activate
python run.py

2. Ollama 연결 오류

# Ollama 서비스 상태 확인
sudo systemctl status ollama

# Ollama 재시작
sudo systemctl restart ollama

# Ollama 로그 확인
sudo journalctl -u ollama -n 50

# Ollama 포트 확인
netstat -tlnp | grep 11434

3. Nginx 오류

# Nginx 설정 테스트
sudo nginx -t

# Nginx 로그 확인
sudo tail -f /var/log/nginx/error.log
sudo tail -f /var/log/nginx/soy-nv-ai-error.log

4. 메모리 부족

# 메모리 사용량 확인
free -h

# 프로세스별 메모리 사용량
ps aux --sort=-%mem | head

# 필요시 서버 재시작
sudo reboot

5. 디스크 공간 부족

# 디스크 사용량 확인
df -h

# 큰 파일 찾기
du -h /var/www/soy-nv-ai | sort -rh | head -20

# 로그 파일 정리
sudo journalctl --vacuum-time=7d  # 7일 이상 된 로그 삭제

6. 포트 충돌

# 포트 사용 확인
sudo netstat -tlnp | grep 5001
sudo lsof -i :5001

# 프로세스 종료
sudo kill -9 PID

---

배포 후 체크리스트

• 서버 접속 확인
• Ollama 설치 및 모델 다운로드 확인
• 프로젝트 파일 업로드 완료
• 가상환경 설정 및 의존성 설치 완료
• 환경 변수 설정 완료
• 데이터베이스 초기화 완료
• Nginx 설정 및 테스트 완료
• SSL 인증서 설치 완료 (도메인 있는 경우)
• systemd 서비스 설정 및 자동 시작 확인
• 백업 스크립트 설정 완료
• 방화벽 설정 확인
• 웹사이트 접속 테스트
• 파일 업로드 기능 테스트
• AI 채팅 기능 테스트
• 모니터링 설정 완료

---

유용한 명령어 모음

# 서비스 관리
sudo systemctl start/stop/restart/status soy-nv-ai
sudo systemctl start/stop/restart/status ollama
sudo systemctl start/stop/restart/status nginx

# 로그 확인
sudo journalctl -u soy-nv-ai -f
sudo journalctl -u ollama -f
sudo tail -f /var/log/nginx/soy-nv-ai-error.log

# 프로세스 확인
ps aux | grep python
ps aux | grep ollama

# 포트 확인
netstat -tlnp | grep 5001
netstat -tlnp | grep 11434

# 디스크/메모리 확인
df -h
free -h
htop

# 백업 실행
/var/www/soy-nv-ai/backup.sh

---

추가 최적화

1. Gunicorn 사용 (선택사항)

Flask 개발 서버 대신 Gunicorn 사용 권장:

# Gunicorn 설치
pip install gunicorn

# systemd 서비스 파일 수정
ExecStart=/var/www/soy-nv-ai/venv/bin/gunicorn \
    --bind 127.0.0.1:5001 \
    --workers 4 \
    --timeout 600 \
    --access-logfile - \
    --error-logfile - \
    run:app

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

SQLite 대신 PostgreSQL 사용 고려 (대규모 사용자):

# PostgreSQL 설치
sudo apt install postgresql postgresql-contrib

# requirements.txt에 추가
# psycopg2-binary==2.9.9

3. CDN 설정

Cloudflare 사용 (무료):

• https://www.cloudflare.com/
• 도메인 DNS를 Cloudflare로 변경
• 캐싱 및 DDoS 보호

---

지원 및 도움말

문제가 발생하면:

1. 서버 로그 확인
2. Nginx 로그 확인
3. systemd 서비스 로그 확인
4. DigitalOcean 문서 참조: https://docs.digitalocean.com/

---

배포 완료 후 웹사이트 접속:

• HTTP: http://YOUR_SERVER_IP 또는 http://YOUR_DOMAIN.com
• HTTPS: https://YOUR_DOMAIN.com (SSL 설정 후)

축하합니다! 배포가 완료되었습니다! 🎉