AssetPilot/.TemporaryDocument/MIGRATION_GUIDE.md

# Asset Pilot - Windows → Orange Pi 5 Plus 전환 가이드

## 📋 개요

**목적**: Windows PyQt5 데스크톱 애플리케이션을 Orange Pi 5 Plus (Ubuntu 24.04) 기반 웹 애플리케이션으로 전환

**주요 변경사항**:
- PyQt5 GUI → FastAPI + HTML/JavaScript 웹 인터페이스
- CSV 파일 저장 → PostgreSQL 데이터베이스
- Windows 토스트 알림 → 웹 푸시 알림 (선택적)
- 로컬 실행 → 네트워크 기반 접근 가능

---

## 🔧 시스템 요구사항

### 하드웨어
- Orange Pi 5 Plus (ARM64 아키텍처)
- 최소 2GB RAM (4GB 권장)
- 최소 8GB 저장공간

### 소프트웨어
- Ubuntu 24.04 LTS (Joshua Riek 버전)
- PostgreSQL 14+ 
- Python 3.10+
- Nginx (선택적, 프로덕션 배포용)

---

## 📦 설치 단계

### 1단계: 시스템 패키지 설치

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

# PostgreSQL 설치
sudo apt install -y postgresql postgresql-contrib

# Python 및 개발 도구 설치
sudo apt install -y python3 python3-pip python3-venv python3-dev
sudo apt install -y build-essential libpq-dev

# Nginx 설치 (선택적)
sudo apt install -y nginx
```

### 2단계: PostgreSQL 설정

```bash
# PostgreSQL 서비스 시작
sudo systemctl start postgresql
sudo systemctl enable postgresql

# 데이터베이스 및 사용자 생성
sudo -u postgres psql << EOF
CREATE DATABASE asset_pilot;
CREATE USER asset_user WITH ENCRYPTED PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE asset_pilot TO asset_user;
\q
EOF
```

### 3단계: 애플리케이션 설치

```bash
# 작업 디렉토리 생성
mkdir -p ~/asset_pilot_web
cd ~/asset_pilot_web

# 제공된 파일 압축 해제
unzip asset_pilot_orangepi.zip
cd asset_pilot_orangepi

# Python 가상환경 생성
python3 -m venv venv
source venv/bin/activate

# 의존성 패키지 설치
pip install --upgrade pip
pip install -r requirements.txt
```

### 4단계: 환경 변수 설정

`.env` 파일 생성:

```bash
cat > .env << 'EOF'
# 데이터베이스 설정
DATABASE_URL=postgresql://asset_user:your_secure_password@localhost/asset_pilot

# 서버 설정
APP_HOST=0.0.0.0
APP_PORT=8000
DEBUG=False

# 데이터 수집 간격 (초)
FETCH_INTERVAL=5
EOF
```

### 5단계: 데이터베이스 초기화

```bash
# 가상환경 활성화 상태에서
python init_db.py
```

### 6단계: 서비스 등록 (자동 실행)

```bash
# systemd 서비스 파일 복사
sudo cp asset_pilot.service /etc/systemd/system/

# 서비스 파일 편집 (경로 확인)
sudo nano /etc/systemd/system/asset_pilot.service

# 서비스 활성화
sudo systemctl daemon-reload
sudo systemctl enable asset_pilot.service
sudo systemctl start asset_pilot.service

# 상태 확인
sudo systemctl status asset_pilot.service
```

---

## 🌐 웹 인터페이스 접근

### 로컬 네트워크에서 접근

1. Orange Pi의 IP 주소 확인:
   ```bash
   ip addr show | grep inet
   ```

2. 웹 브라우저에서 접속:
   ```
   http://[Orange_Pi_IP]:8000
   ```
   예: `http://192.168.1.100:8000`

### Nginx 리버스 프록시 설정 (선택적)

프로덕션 환경에서는 Nginx를 통한 접근 권장:

```bash
sudo nano /etc/nginx/sites-available/asset_pilot
```

다음 내용 입력:

```nginx
server {
    listen 80;
    server_name your_domain_or_ip;

    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;
    }

    location /api/stream {
        proxy_pass http://127.0.0.1:8000/api/stream;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_cache off;
    }
}
```

활성화:

```bash
sudo ln -s /etc/nginx/sites-available/asset_pilot /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
```

---

## 📊 데이터 마이그레이션

### Windows 앱에서 데이터 내보내기

기존 Windows 앱의 `user_assets.csv` 파일을 Orange Pi로 복사:

```bash
# Windows에서 SCP로 전송 (예시)
scp user_assets.csv orangepi@192.168.1.100:~/asset_pilot_web/
```

### 데이터 가져오기

```bash
cd ~/asset_pilot_web/asset_pilot_orangepi
source venv/bin/activate
python import_csv.py ../user_assets.csv
```

---

## 🔍 모니터링 및 관리

### 로그 확인

```bash
# 실시간 로그 보기
sudo journalctl -u asset_pilot.service -f

# 최근 100줄 로그
sudo journalctl -u asset_pilot.service -n 100
```

### 서비스 관리

```bash
# 시작
sudo systemctl start asset_pilot.service

# 중지
sudo systemctl stop asset_pilot.service

# 재시작
sudo systemctl restart asset_pilot.service

# 상태 확인
sudo systemctl status asset_pilot.service
```

### 데이터베이스 백업

```bash
# 백업 생성
pg_dump -U asset_user -h localhost asset_pilot > backup_$(date +%Y%m%d).sql

# 복원
psql -U asset_user -h localhost asset_pilot < backup_20260210.sql
```

---

## 🔐 보안 권장사항

1. **방화벽 설정**:
   ```bash
   sudo ufw allow 8000/tcp  # 또는 Nginx 사용 시 80/tcp
   sudo ufw enable
   ```

2. **PostgreSQL 외부 접근 차단**: 기본 설정 유지 (localhost만 허용)

3. **강력한 비밀번호 사용**: `.env` 파일의 데이터베이스 비밀번호 변경

4. **HTTPS 설정** (선택적):
   - Let's Encrypt 인증서 사용
   - Nginx SSL 설정

---

## 🆘 문제 해결

### 서비스가 시작되지 않음

```bash
# 로그 확인
sudo journalctl -u asset_pilot.service -n 50

# 수동 실행으로 오류 확인
cd ~/asset_pilot_web/asset_pilot_orangepi
source venv/bin/activate
python main.py
```

### 데이터베이스 연결 오류

```bash
# PostgreSQL 상태 확인
sudo systemctl status postgresql

# 연결 테스트
psql -U asset_user -h localhost -d asset_pilot
```

### 포트 충돌

```bash
# 8000번 포트 사용 중인 프로세스 확인
sudo lsof -i :8000
```

---

## 📱 모바일 접근

### 홈 화면에 추가 (PWA 스타일)

1. 모바일 브라우저에서 접속
2. 브라우저 메뉴 → "홈 화면에 추가"
3. 앱처럼 사용 가능

---

## 🔄 업데이트 절차

```bash
cd ~/asset_pilot_web/asset_pilot_orangepi
source venv/bin/activate

# 최신 코드 적용
git pull  # 또는 새 파일 복사

# 의존성 업데이트
pip install -r requirements.txt --upgrade

# 데이터베이스 마이그레이션 (필요시)
python migrate_db.py

# 서비스 재시작
sudo systemctl restart asset_pilot.service
```

---

## 📞 지원

문제 발생 시:
1. 로그 확인: `sudo journalctl -u asset_pilot.service -n 100`
2. 데이터베이스 상태 확인: `sudo systemctl status postgresql`
3. 네트워크 연결 확인: `ping 8.8.8.8`

---

## 🎯 주요 차이점 요약

| 기능 | Windows 앱 | Orange Pi 웹앱 |
|------|-----------|---------------|
| UI | PyQt5 | HTML/JavaScript |
| 저장소 | CSV 파일 | PostgreSQL |
| 접근성 | 로컬 실행 | 네트워크 접근 |
| 알림 | Windows 토스트 | 브라우저 알림 |
| 멀티 기기 | 불가 | 가능 |
| 자동 시작 | Windows 작업 스케줄러 | systemd |

---

## ✅ 체크리스트

설치 완료 확인:
- [ ] PostgreSQL 설치 및 실행
- [ ] 데이터베이스 생성
- [ ] Python 가상환경 생성
- [ ] 의존성 패키지 설치
- [ ] 환경 변수 설정
- [ ] 데이터베이스 초기화
- [ ] 서비스 등록 및 시작
- [ ] 웹 브라우저 접속 확인
- [ ] 데이터 수집 동작 확인
- [ ] 기존 데이터 마이그레이션 (선택적)

모든 항목 완료 시 시스템 사용 준비 완료! 🎉