NaizVL 웹페이지(Frontend) 설치 가이드
NaizVL 서버 설치 (INSTALL.md) 완료 후 관제용 웹 UI + 비디오 미들웨어 설치 절차.
0. 사전 조건
| 항목 | 확인 |
|---|---|
| NaizVL 서버 | sudo systemctl status naizvl — active (running) |
| 서버 응답 | curl http://127.0.0.1:7860/status — {"status":"running"} |
| 설치 파일 | frontend-linux.tar.gz (~1.6GB, bundled Node/Python/ffmpeg 포함) |
| 디스크 여유 | /opt 5GB+ |
| 사용 포트 | TCP/3001 (frontend) + TCP/8002 (middleware) |
| 실행 계정 | sudo 가능한 일반 사용자 (예: naiz). root 직접 실행 금지 (PM2 가 user-level crontab 필요) |
포트 점유 확인:
sudo ss -tlnp | grep -E ':(3001|8002)'
1. 파일 카피
cp frontend-linux.tar.gz /tmp
2. 압축 해제
cd /tmp
tar zxvf frontend-linux.tar.gz
내부 구성:
frontend/ # tar 안 폴더명 (또는 frontend-linux)
├── install.sh # 본 설치 스크립트
├── start.sh # 실제 빌드·기동 스크립트
├── ecosystem.config.cjs # PM2 설정 (frontend + middleware)
├── .env # FE_PORT=3001 / MW_PORT=8002
├── ai-video/ # Next.js 프론트
├── middleware/video_mw/ # FastAPI 비디오 미들웨어
└── downloads/ # bundled Node.js / Python / ffmpeg (오프라인)
3. 설치
압축 풀린 폴더로 이동 후 sudo 로 install.sh 실행:
cd /tmp/frontend # (또는 압축 해제된 실제 폴더명)
sudo bash install.sh
install.sh 가 자동 수행 (5단계, 약 5~10분):
| # | 동작 |
|---|---|
| 1 | /opt/naizvl/frontend 로 이동 (기존 설치 있으면 .bak.<timestamp> 자동 백업) |
| 2 | 디렉토리 소유자를 sudo 호출 사용자 (예: naiz) 로 변경 — 이후 일상 명령에 sudo 불필요 |
| 3 | pm2 / node / npm 을 /usr/local/bin 에 심볼릭 링크 — 어느 셸에서도 즉시 사용 가능 |
| 4 | start.sh 실행 — Python venv 생성, 오프라인 pip/npm 설치, Next.js 빌드, PM2 로 두 서비스 기동 |
| 5 | 사용자 crontab @reboot 에 등록 — 부팅 시 PM2 자동 시작 |
install.sh 는 root 직접 실행 거부 —
sudo bash install.sh형태로만 동작 (PM2 가 user-level 자원 필요).
4. 동작 확인
4.1 PM2 서비스 상태
pm2 ls
# ┌─────┬──────────────────────┬─────────┬──────┬─────────┐
# │ id │ name │ status │ cpu │ memory │
# ├─────┼──────────────────────┼─────────┼──────┼─────────┤
# │ 0 │ ai-video-frontend │ online │ 0% │ 250 MB │
# │ 1 │ video-middleware │ online │ 0% │ 120 MB │
# └─────┴──────────────────────┴─────────┴──────┴─────────┘
두 서비스 모두 online 이어야 정상.
4.2 로컬 브라우저
http://127.0.0.1:3001
NaizVL 관제 화면 표시 확인.
4.3 원격 접속
운영 PC 에서:
http://<서버IP>:3001
서버 IP 확인: hostname -I 또는 ip a | grep 'inet '
원격 안 되면 §7 문제 해결 참고.
5. 일상 운영 명령 (sudo 불필요)
설치 후 install.sh 가 소유자를 일반 사용자로 바꿔놨으니 sudo 없이:
pm2 ls # 두 서비스 상태
pm2 logs # 두 서비스 통합 로그 (Ctrl+C 로 빠져나옴)
pm2 logs ai-video-frontend # frontend 만
pm2 logs video-middleware # middleware 만
pm2 restart all # 둘 다 재시작
pm2 stop all # 둘 다 정지 (재부팅 시 다시 시작)
pm2 start all # 정지 상태에서 재기동
로그 파일 (PM2 가 기록):
/opt/naizvl/frontend/logs/
├── frontend-out.log
├── frontend-err.log
├── middleware-out.log
└── middleware-err.log
6. 설정 변경
6.1 포트 변경
sudo nano /opt/naizvl/frontend/.env
# FE_PORT=3001 ← frontend (Next.js)
# MW_PORT=8002 ← middleware (FastAPI)
# MW_HOST=127.0.0.1
변경 후 재시작:
pm2 restart all
6.2 재빌드·재설치
코드 일부만 교체 후 의존성 재설치까지 한 번에:
cd /opt/naizvl/frontend
./start.sh --reinstall
7. 문제 해결
| 증상 | 조치 |
|---|---|
error: must run with sudo |
sudo bash install.sh (직접 실행 X) |
error: SUDO_USER is empty or root |
root 로 직접 sudo 한 경우. 일반 사용자로 로그인 후 sudo bash install.sh |
Cannot read properties of undefined (reading 'pm2_env') |
PM2 이전 상태 잔재. install.sh 가 자동 정리하지만 수동: pm2 kill && rm -rf ~/.pm2 후 재실행 |
Cross-filesystem — copying ... (1.6GB 복사 느림) |
/tmp 와 /opt 가 다른 파일시스템. 정상 — cp -a 로 처리됨. 완료 후 /tmp/frontend* 수동 삭제 |
| 127.0.0.1:3001 접속 안 됨 | pm2 ls 로 ai-video-frontend online 확인. pm2 logs ai-video-frontend 로 에러 확인 |
| 관제 화면은 뜨는데 데이터 없음 | (a) middleware 확인 pm2 logs video-middleware. (b) NaizVL 서버 curl http://127.0.0.1:7860/status |
| 로컬은 되는데 원격 접속 안 됨 | 방화벽: sudo ufw allow 3001/tcp. middleware 는 127.0.0.1 만 바인딩이라 외부 노출 안 됨 (ecosystem.config.cjs 기본) |
| 재부팅 후 서비스 안 켜짐 | crontab -l \| grep pm2-vlm 으로 등록 확인. 없으면 pm2 startup 으로 재등록 |
port 3001 already in use |
sudo ss -tlnp \| grep 3001 로 점유 프로세스 확인. 충돌 시 해당 프로세스 중지 또는 .env 의 FE_PORT 변경 |
| 디스크 부족 | /tmp 의 임시 압축 파일 정리: rm -rf /tmp/frontend* (install.sh 완료 후) |
8. 업데이트
새 버전 받았을 때 — install.sh 가 기존 /opt/naizvl/frontend 를 자동 백업 (.bak.<timestamp>):
cp frontend-linux-v<NEW>.tar.gz /tmp
cd /tmp
tar zxvf frontend-linux-v<NEW>.tar.gz # → /tmp/frontend (또는 frontend-linux)
cd /tmp/frontend
sudo bash install.sh
# → 기존 /opt/naizvl/frontend → /opt/naizvl/frontend.bak.YYYYMMDD-HHMMSS
# → 새 버전 설치 + PM2 재기동
문제 발생 시 백업 복원:
sudo pm2 kill
sudo mv /opt/naizvl/frontend /opt/naizvl/frontend.failed
sudo mv /opt/naizvl/frontend.bak.<TS> /opt/naizvl/frontend
cd /opt/naizvl/frontend && ./start.sh
오래된 백업 정리:
sudo rm -rf /opt/naizvl/frontend.bak.*
9. 운영 서버 2대 설치 체크리스트
각 서버마다 반복:
- [ ] NaizVL 서버 (port 7860) active
- [ ]
frontend-linux.tar.gz전송 →/tmp/ - [ ]
tar zxvf압축 해제 - [ ]
sudo bash install.sh(일반 사용자에서 sudo) - [ ]
pm2 ls— 두 서비스 모두 online - [ ] 로컬
http://127.0.0.1:3001접속 — 관제 화면 - [ ] 원격
http://<서버IP>:3001— (방화벽 정책 OK 시) - [ ] 데이터 표시 — middleware 연동 OK
- [ ] 재부팅 →
crontab -l | grep pm2-vlm→ 자동 시작 확인
10. 시스템 구성 요약
┌─────────────┐ ┌──────────────────────────────────────┐
│ 운영 PC │ │ 운영 서버 (Ubuntu 22.04.5) │
│ (브라우저) │ │ │
│ │ │ ┌─────────────────────────────────┐ │
│ Chrome/ │ ─HTTP─→ │ │ ai-video-frontend (Next.js) │ │
│ Firefox │ :3001 │ │ /opt/naizvl/frontend │ │
│ │ │ └────────────┬────────────────────┘ │
└─────────────┘ │ │ HTTP │
│ ↓ :8002 (127.0.0.1) │
│ ┌─────────────────────────────────┐ │
│ │ video-middleware (FastAPI) │ │
│ └────────────┬────────────────────┘ │
│ │ HTTP │
│ ↓ :7860 │
│ ┌─────────────────────────────────┐ │
│ │ naizvl (vLLM + Qwen3-VL) │ │
│ │ /opt/naizvl │ │
│ └─────────────────────────────────┘ │
└──────────────────────────────────────┘
ai-video-frontend: Next.js, port 3001, 외부 노출video-middleware: FastAPI, port 8002, 127.0.0.1 만 (frontend 만 접근)naizvl: vLLM 서버, port 7860, systemd 관리 (INSTALL.md)
11. 관련 문서
- INSTALL.md — NaizVL 서버 본체 설치 (USB Ubuntu 부터)
- BUILD.md — 키트 제작
- README.md — 인덱스 + 변경 이력
/opt/naizvl/frontend/README.md— 설치 후 frontend 패키지 자체 README (영문)