오프라인 번들 설치

🤖 이 번역은 기계 초벌 번역이며 사람 검수 대기 중입니다. 영어 페이지가 기준입니다.

이 방법은 인터넷이 없고, 레지스트리 접근이 불가능하며, 박스에서 이미지를 빌드하지 않는 고객 엣지 현장에 설치하는 방식입니다. USB 미디어로 제공되는 단일 자체 완결형 릴리스 번들에서 모든 것을 설치합니다.

이 페이지를 사용할 시점

모든 프로덕션 박스에는 오프라인 번들을 사용하세요. 프로덕션은 NVIDIA Jetson TX2에서만 실행됩니다. 하드웨어 설정을 참조하세요. 노트북 데모는 대시보드를 둘러보기 위한 것이며 배포용이 아닙니다.

받게 되는 것

릴리스 번들은 프로파일과 버전을 이름으로 하는 단일 디렉터리입니다(예: jetson-gpu-v1.58.4). jetson-gpu 프로파일은 JetPack 4.5의 Jetson TX2를 대상으로 하며, CUDA를 통해 GPU에서 추론을 실행합니다.

번들 내부:

• 디렉터리jetson-gpu-v1.58.4/

  • 디렉터리images/

    • jetson-gpu-v1.58.4.images.tar.zst 세 개의 서비스 이미지, 압축됨
    • manifest.txt 프로파일, 버전, 이미지 태그, 체크섬
  • 디렉터리compose/

    • docker-compose.release.yml 이미지 기반 스택 (빌드 단계 없음)
    • docker-compose.tls.yml HTTPS 오버레이 (선택 사항)
    • docker-compose.certs.yml 데이터소스 TLS 인증서 오버레이 (선택 사항, 아래 참고)
    • .env.template 포트 및 설정 플레이스홀더
  • 디렉터리models/

    • predictive_maintenance_op15.onnx 데모 시드 모델 (랜덤 가중치)
  • 디렉터리lib/ 설치 프로그램 도우미

    • …
  • 디렉터리systemd/ 부팅 시작 유닛 템플릿

    • …
  • 디렉터리certs/

    • …
  • 디렉터리tls/

    • …
  • install.sh
  • update.sh
  • uninstall.sh
  • compact-db.sh 데이터베이스 디스크 공간 회수
  • README.txt

시드 모델은 데모입니다

번들에 포함된 모델은 랜덤 가중치를 가집니다 — 학습된 모델로 교체하기 전까지 예측값은 의미가 없습니다. 설치 런북의 5단계를 참고하세요.

실행 중인 스택의 위치

설치 프로그램은 실행 중인 스택에 필요한 것을 **/opt/aiboard**로 복사합니다: compose 파일, 시드 모델, 생성된 .env, tls/, certs/, 그리고 업데이트 전 backups/. 설치나 업데이트가 성공한 뒤에는 실행 중인 박스가 번들 디렉터리를 더 이상 필요로 하지 않습니다.

시작하기 전에

대상 Jetson에는 다음이 이미 설치되어 있어야 합니다. 골든 JetPack 이미지에 포함되어 제공됩니다. 설치 프로그램은 이를 확인하고 누락된 것이 있으면 중단합니다. 대신 설치해 주지는 않습니다.

• Docker Engine 20.10 이상, docker compose v2 플러그인 포함
• zstd 및 openssl
• Docker에 등록된 NVIDIA 컨테이너 런타임
• 번들을 복사하는 위치에 약 6 GB의 여유 디스크

주의

깨끗한 대상에 설치하세요. 릴리스 스택은 개발 스택과 같은 호스트 포트(80, 3000, 5000)를 사용합니다. 한 박스에서 둘을 함께 실행하면 충돌이 발생합니다.

설치 런북

1. 박스로 번들 복사

   USB 미디어에서 전체 번들 디렉터리를 Jetson으로 복사한 뒤, 그 안에서 터미널을 엽니다:

   cd jetson-gpu-v1.58.4/

2. 설치 프로그램 실행

   설치 프로그램은 Jetson을 감지하고, 컨테이너 이미지를 로드하며, 시크릿을 생성하고, 스택을 기동한 뒤 상태가 정상이 될 때까지 대기합니다.

   sudo ./install.sh

   유용한 옵션:

   sudo ./install.sh --profile jetson-gpu   # force the profile
   sudo ./install.sh --with-systemd         # also start on boot
   sudo ./install.sh --no-backup            # skip the pre-migration snapshot (see below)

   내부적으로 install.sh는 다음 단계를 순서대로 실행합니다:

   1. 사전 점검 — CPU 아키텍처, Docker, Compose, zstd, openssl, Jetson과 NVIDIA 컨테이너 런타임, 여유 디스크를 확인합니다.
   2. 이미지 아카이브 체크섬을 검증합니다. 손상되거나 변조된 미디어를 감지합니다.
   3. 이미지 로드 — 번들된 아카이브에서 docker load. 풀 없음, 빌드 없음.
   4. 런타임 파일 배치 — /opt/aiboard로 복사합니다.
   5. 시크릿 생성 — 박스에서 JWT 서명 시크릿과 관리자 비밀번호를 생성하고, 시크릿을 /opt/aiboard/.env(모드 600)에 기록합니다. 어떤 시크릿도 번들 내부에 포함되어 제공되지 않습니다.
   6. 데이터베이스 스냅샷 — 박스에 이미 데이터베이스가 있으면, 새 릴리스가 마이그레이션하기 전에 백업합니다. 데이터베이스 스냅샷을 참고하세요.
   7. 스택 시작 — docker compose up -d.
   8. 상태 게이트 — 서비스가 정상(healthy)을 보고할 때까지 대기합니다.
   9. 관리자 시드 생성 후 대시보드 URL과 관리자 비밀번호를 한 번만 출력합니다.

3. 관리자 비밀번호 저장

   단 한 번만 출력됨

   설치 프로그램은 실행이 끝날 때 대시보드 URL과 생성된 관리자 비밀번호를 단 한 번만 출력합니다. 즉시 비밀번호 관리자에 복사하세요. 다시 읽어볼 수 있는 곳에 저장되지 않습니다.

4. 시크릿이 기록되었는지 확인

   설치 프로그램은 JWT 서명 시크릿을 자동으로 생성합니다. 보통은 손댈 일이 없지만, 보호된 .env가 존재하는지 확인할 수 있습니다:

   sudo ls -l /opt/aiboard/.env   # expect mode -rw------- (600)

   기업 정책상 직접 값을 사용해야 한다면 이 파일에 값을 설정한 뒤, 설치에 사용한 번들에서 sudo ./update.sh를 다시 실행해 적용하세요. 시크릿이 바뀌면 로그인된 모든 세션이 종료됩니다.

   # /opt/aiboard/.env  (placeholder — generate a strong random value, do not reuse)
   AIBOARD_JWT_SECRET=your-strong-random-jwt-secret

5. 데모 모델 교체

   번들에는 랜덤 가중치를 가진 데모 모델이 포함되어 있습니다. 예측값이 의미를 갖도록 학습된 모델로 교체하세요. TX2용 모델은 ONNX opset 15 이하를 사용해야 합니다.

   • 대시보드에서 업로드(권장). 모델 배포를 참고하세요.
   • 첫 설치 이전에는 번들의 models/predictive_maintenance_op15.onnx를 덮어쓸 수 있습니다. 업데이트할 때마다 새 번들의 시드 모델로 다시 교체되므로, 지속적인 변경은 대시보드를 사용하세요.

6. 상태 확인

   서비스가 실행 중인지 확인합니다:

   docker ps --filter name=aiboard- --format 'table {{.Names}}\t{{.Status}}'

   aiboard-inference-real과 aiboard-backend-real은 (healthy), aiboard-frontend-real은 Up으로 표시되어야 합니다. 그런 다음 설치 프로그램이 출력한 대시보드 URL을 열고 관리자 계정으로 로그인하세요.

   첫 시작에는 시간이 조금 걸립니다

   추론 서비스는 첫 시작 시 CUDA를 초기화합니다. 헬스 체크에 90초의 시작 유예 기간이 있으므로, 최대 약 1분 30초 동안 starting으로 표시됩니다. 정상적인 동작입니다. 기다린 뒤 다시 확인하세요.

2일차 운영

업데이트

더 새로운 번들을 배포합니다. 번들을 박스로 복사하고, 그 안에서 터미널을 연 뒤 실행합니다:

sudo ./update.sh

update.sh는 /opt/aiboard/.env에서 운영 중인 구성을 읽으므로, 번들 디렉터리 사이에 아무것도 복사할 필요가 없습니다. 이후 다음을 수행합니다:

1. 쓰기 작업자를 멈춘 상태에서 데이터베이스를 스냅샷하고 아카이브를 검증합니다. 데이터베이스 스냅샷을 참고하세요.
2. 새 이미지를 로드하고 구성이 이를 가리키도록 합니다.
3. 스택을 다시 생성합니다. 백엔드가 시작하면서 데이터베이스를 마이그레이션합니다.
4. 상태를 기다립니다. 스택이 정상이 되지 않으면 업데이트가 중단되고, 롤백 방법을 출력하며, 아무것도 삭제하지 않습니다.
5. 새 릴리스가 정상이 된 후에만 정리합니다:
   • 가장 최근 AIBOARD_BACKUP_KEEP개의 스냅샷 아카이브(기본값 3)를 유지하고 그보다 오래된 것은 삭제합니다. 모든 아카이브를 유지하려면 /opt/aiboard/.env에 AIBOARD_BACKUP_KEEP=0을 설정하세요. 환경 변수를 참고하세요.
   • 방금 설치한 릴리스와 그것이 대체한 릴리스의 이미지를 유지하고, 더 오래된 Xisom 이미지는 삭제합니다. 같은 릴리스를 다시 실행하면(예: 상태 게이트 실패 후) 이전 릴리스를 롤백용으로 남겨 두기 위해 이미지 정리를 건너뜁니다.

스냅샷을 건너뛰려면 --no-backup을 전달하세요. 다른 방법으로 스냅샷을 확보한 경우에만 사용하세요. 데이터베이스 마이그레이션은 앞으로만 진행됩니다.

/opt/aiboard 이전에 설치된 박스인가요?

오래된 설치는 .env를 번들 디렉터리 안에 보관합니다. update.sh는 중단하고 sudo ./update.sh --migrate로 한 번 이동하라고 안내합니다. 이 명령은 .env(JWT 시크릿과 모든 세션이 유지됨), tls/, certs/를 /opt/aiboard로 복사합니다. 아무것도 삭제하지 않습니다.

제거

sudo ./uninstall.sh          # stop the stack, KEEP all data
sudo ./uninstall.sh --purge  # also delete the database, models, and logs (confirmation prompt)

데이터베이스 스냅샷

install.sh와 update.sh 모두 새 릴리스가 마이그레이션하기 전에 데이터베이스를 백업합니다:

• 스냅샷은 데이터베이스의 쓰기 작업자를 멈춘 상태에서 생성되므로 아카이브가 일관됩니다. 실행이 계속되면 스택이 다시 시작됩니다. 그 전에 실행이 실패하면 멈춘 컨테이너를 다시 시작합니다.
• 다른 변경을 하기 전에 아카이브를 다시 읽어 검증합니다. 읽을 수 없으면 현재 데이터베이스가 그대로인 상태에서 실행을 중단합니다.
• 아카이브는 /opt/aiboard/backups/에 backup-<UTC timestamp>.tgz로 저장됩니다. 실행 시 아카이브 이름 옆에 정확한 복원 명령을 출력합니다.
• 스냅샷은 데이터베이스만 포함하며 업로드된 모델은 포함하지 않습니다. 모델을 롤백해야 한다면 모델 볼륨을 별도로 백업하세요.
• --no-backup은 두 스크립트 모두에서 스냅샷을 건너뜁니다.

데이터소스 TLS 인증서

데이터소스 측 TLS — MQTT 또는 OPC UA 데이터소스가 보안된 브로커나 서버에 연결하는 데 사용하는 CA, 클라이언트 인증서, 키 — 는 박스 자체의 HTTPS 인증서와 별개입니다. 기본적으로 꺼져 있습니다. AIBOARD_TLS_ENABLED와 대칭을 이루는 .env 플래그로 켭니다:

/opt/aiboard/.env

AIBOARD_CERTS_ENABLED=1

MQTT/OPC UA CA와 클라이언트 인증서/키 파일을 **/opt/aiboard/certs/**에 넣으세요. 플래그가 켜지면 설치 프로그램과 update.sh가 번들에 포함된 docker-compose.certs.yml 오버레이를 릴리스 스택 위에 겹쳐 적용하고, 백엔드는 그 디렉터리를 읽기 전용으로 마운트합니다. 첫 설치 전에는 번들의 compose/.env.template에 플래그를 설정하세요. 실행 중인 박스에서는 플래그를 바꾼 뒤 sudo ./update.sh를 다시 실행하세요.

인증서 경로는 서버 측이며 격리되어 있습니다

데이터소스의 인증서 경로 필드(CA 파일, 클라이언트 인증서, 클라이언트 키)는 운영자 자신의 머신이 아니라 마운트된 인증서 루트로 한정된 백엔드 컨테이너의 파일 시스템에서 해석됩니다. 값을 설정할 위치는 데이터소스 연결과 출력 데이터소스를 참고하세요.

업데이트해도 인증서는 유지됩니다

인증서는 박스 자체의 TLS 인증서처럼 재생성할 수 없습니다. /opt/aiboard/certs/는 어떤 번들에도 속하지 않으므로 업데이트가 이를 그대로 둡니다. 인증서를 번들 안에 보관하던 오래된 설치에서는 update.sh가 먼저 이를 /opt/aiboard/certs/로 복사합니다.

uid 1001이 인증서를 읽을 수 있어야 합니다

백엔드 컨테이너는 uid 1001로 인증서 파일을 읽습니다. /opt/aiboard/certs/ 디렉터리(및 그 안의 모든 파일)에 소유권/권한을 설정하여 uid 1001이 읽을 수 있도록 하세요. 그렇지 않으면 데이터소스가 연결 시점에 인증서를 로드하지 못합니다.

문제가 발생하면

증상	의미
Bundle manifest missing	조립된 번들이 아니라 소스 폴더에서 설치 프로그램을 실행했습니다. USB에서 복사한 번들 디렉터리를 사용하세요.
Architecture mismatch	번들은 arm64 Jetson용인데 이 머신은 Jetson이 아닙니다. 번들을 Jetson으로 복사하세요.
/etc/nv_tegra_release is absent	이 머신은 L4T를 실행하는 Jetson이 아닙니다. Jetson TX2에 설치하세요.
NVIDIA container runtime not wired into Docker	이 Jetson의 Docker에 nvidia 런타임이 없습니다. Docker가 이를 표시하도록 JetPack 이미지를 수정하세요.
Low disk	이미지를 위한 여유 공간이 부족합니다. 약 6 GB를 확보한 뒤 다시 시도하세요.
추론이 starting으로 표시됨	첫 시작 시 CUDA 초기화에 최대 약 90초가 걸립니다 — 기다리세요. 이후 unhealthy로 바뀌면 docker logs aiboard-inference-real을 확인하세요.
Found an existing install at: …	/opt/aiboard가 생기기 전에 설치된 박스입니다. 같은 스크립트를 --migrate와 함께 한 번 실행하세요.
아카이브 체크섬 불일치	손상되거나 변조된 USB 미디어입니다. 번들을 다시 복사하고 재시도하세요.

증상별 해결책은 전체 문제 해결 런북을 참고하세요.

다음 단계

입력 데이터소스 연결 센서 데이터를 런타임으로 스트리밍합니다.

모델 배포 학습된 모델을 업로드하고 활성화합니다.

첫 추론 모델을 시드하고 실시간 예측값을 확인합니다.