NaizVL 오프라인 설치 키트

외부망이 차단된 폐쇄망 서버에 NaizVL VLM 추론 서버를 설치하기 위한 오프라인 키트.

문서 구성

문서	대상	내용
BUILD.md	개발자 (키트 제작)	`make-offline-kit.sh` 실행, wheel 캐시, flash-attn 빌드, APT 패키지 정책
INSTALL.md	운영자 (현장 설치)	USB Ubuntu 22.04.5 LTS 설치부터 `tar` 해제 → `install.sh` → 서비스 기동 → admin 키 발급
INSTALL_FRONTEND.md	운영자 (웹 UI 설치)	NaizVL 서버 설치 후 `frontend-linux.tar.gz` → `install.sh` → 127.0.0.1:3001
HARDENING.md	운영자 (안정화)	/infer 500 인시던트 분석 + traceback 로깅 fix + watchdog cron 자동 재시작

신규 OS 설치 환경 (Ubuntu 22.04.5 ISO, kernel 6.8.0-40-generic) 검증 중 발견된 2건 fix + 문서 재편.

make-offline-kit.sh
APT_PKGS 에 gcc-12 g++-12 cpp-12 추가 — 22.04.5 default kernel 이 gcc-12 로 빌드되어 dkms 가 -ftrivial-auto-var-init=zero 옵션을 요구. gcc-11 로는 nvidia-open-570 dkms compile 실패.
APT_PKGS 에 python3.10-dev libpython3.10-dev 추가 — vLLM 의 Triton JIT compiler 가 런타임에 cuda_utils.c 를 gcc 로 빌드하면서 #include <Python.h> 요구. 빠지면 vLLM 첫 inference 직전 profile_run 단계에서 fatal error: Python.h: No such file or directory. libexpat1-dev/zlib1g-dev 는 apt-rdepends 가 transitive 로 펼치므로 명시 불필요.
install.sh (Step 4)
/usr/bin/gcc-12 감지 시 update-alternatives --install /usr/bin/cc cc /usr/bin/gcc-12 60 + --set cc 자동 실행 → nvidia dkms 가 자동으로 gcc-12 사용.
운영 서버 hotfix 절차 — 키트 재제작 전 4개 .deb (libexpat1-dev, zlib1g-dev, libpython3.10-dev, python3.10-dev, 총 ~5.5MB) 만 USB 전송 후 일괄 dpkg -i 로 즉시 대응 가능.
문서 분리 — README.md 를 BUILD.md (제작) + INSTALL.md (USB Ubuntu 설치부터 정식 가동까지) 두 문서로 분리.

install.sh 개선
set -o pipefail + nvidia-smi | head SIGPIPE 종료 → nvidia-smi --query-gpu CSV 출력으로 우회
단계 6 분할: user-local 잔재 정리(6-1) → --force-reinstall 설치(6-2) → NCCL ldconfig 등록(6-3) → PYTHONNOUSERSITE=1 검증(6-4)
systemd/naizvl.service
Environment=PYTHONNOUSERSITE=1 추가 → 운영 시 user-local 영구 무시
Environment=LD_LIBRARY_PATH=/usr/local/lib/.../nvidia/nccl/lib → torch 동봉 NCCL 우선
make-offline-kit.sh
02-app 최소화 — naizvl_server_replica.py / config.example.yaml / systemd/naizvl.service 3개 파일만 명시 복사 (이전 5.3GB → 45KB)
REQUIRED_EXTRAS=(scipy scikit-learn) 자동 보강
LOCAL_WHEEL_CACHE 자동 감지 → flash-attn 등 수동 빌드 wheel 통합
flash-attn 빌드 가이드 (BUILD.md §6) — multi-arch wheel 직접 빌드 절차