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단계: 시스템 패키지 설치

# 시스템 업데이트
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 설정

# 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단계: 애플리케이션 설치

# 작업 디렉토리 생성
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 파일 생성:

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단계: 데이터베이스 초기화

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

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

# 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 주소 확인:

   ip addr show | grep inet
   

2. 웹 브라우저에서 접속:

   http://[Orange_Pi_IP]:8000
   

   예: http://192.168.1.100:8000

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

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

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

다음 내용 입력:

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

활성화:

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로 복사:

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

데이터 가져오기

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

---

🔍 모니터링 및 관리

로그 확인

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

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

서비스 관리

# 시작
sudo systemctl start asset_pilot.service

# 중지
sudo systemctl stop asset_pilot.service

# 재시작
sudo systemctl restart asset_pilot.service

# 상태 확인
sudo systemctl status asset_pilot.service

데이터베이스 백업

# 백업 생성
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. 방화벽 설정:

   sudo ufw allow 8000/tcp  # 또는 Nginx 사용 시 80/tcp
   sudo ufw enable
   

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

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

4. HTTPS 설정 (선택적):

   • Let's Encrypt 인증서 사용
   • Nginx SSL 설정

---

🆘 문제 해결

서비스가 시작되지 않음

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

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

데이터베이스 연결 오류

# PostgreSQL 상태 확인
sudo systemctl status postgresql

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

포트 충돌

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

---

📱 모바일 접근

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

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

---

🔄 업데이트 절차

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 가상환경 생성
• 의존성 패키지 설치
• 환경 변수 설정
• 데이터베이스 초기화
• 서비스 등록 및 시작
• 웹 브라우저 접속 확인
• 데이터 수집 동작 확인
• 기존 데이터 마이그레이션 (선택적)

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