# Cài đặt từ gói offline

> Cài đặt Xisom Edge AI Box tại một site air-gapped từ gói phát hành offline — nạp images, chạy trình cài đặt, thiết lập secret, khởi chạy stack và kiểm tra tình trạng.

Đây là cách cài đặt được khuyến nghị tại một site biên của khách hàng khi **không có internet, không
truy cập được registry, và không build image trên box**. Bạn cài đặt mọi thứ từ
một **gói phát hành** tự chứa duy nhất, được giao trên thiết bị USB.

**Khi nào dùng trang này**

Dùng gói offline cho các box biên sản xuất tại nhà máy hoặc site OT. Để đánh giá nhanh
trên laptop có truy cập internet, [Bắt đầu nhanh](/vi/install-deploy/quickstart/)
sẽ nhanh hơn.

## Bạn nhận được gì

Một gói phát hành là một thư mục, được đặt tên theo hồ sơ phần cứng và phiên bản
(ví dụ `amd64-cpu-v1.5.0`). Chọn gói khớp với phần cứng của bạn:

| Hồ sơ gói | Dùng khi box có… |
|----------------|---------------------------|
| `amd64-cpu`    | CPU x86_64, không GPU — suy luận chỉ bằng CPU |
| `amd64-gpu`    | CPU x86_64 + NVIDIA GPU — tăng tốc bằng TensorRT |
| `jetson`       | Module biên NVIDIA Jetson (arm64 / L4T) |

Bên trong gói:

- amd64-cpu-v1.5.0/
  - images/
    - amd64-cpu-v1.5.0.images.tar.zst   ba image dịch vụ, đã nén
    - manifest.txt                       tag image + checksum
  - compose/
    - docker-compose.release.yml         stack dựa trên image (không có bước build)
    - .env.template                      placeholder cho cổng + secret
  - models/
    - predictive_maintenance.onnx        mô hình mầm demo (trọng số ngẫu nhiên)
  - install.sh
  - update.sh
  - uninstall.sh
  - README.txt                           tờ hướng dẫn một trang cho người vận hành

**Mô hình mầm chỉ là demo**

Mô hình đi kèm có trọng số ngẫu nhiên — các dự đoán của nó vô nghĩa cho đến khi bạn
thay bằng mô hình đã huấn luyện của mình. Xem bước 5 của [runbook cài đặt](#runbook-cài-đặt).

## Trước khi bắt đầu

Box đích phải đã cài sẵn những thành phần này (chúng đi kèm trên golden OS
image — trình cài đặt **kiểm tra** chúng và dừng lại nếu thiếu bất kỳ thứ gì; nó
không tự cài chúng cho bạn):

- Docker Engine 20.10 trở lên, kèm plugin `docker compose` v2
- `zstd` và `openssl`
- **NVIDIA Container Toolkit** — chỉ với gói GPU và Jetson

Cài đặt trên một **box đích sạch**. Stack phát hành dùng lại cùng tên container,
volume và cổng host như stack phát triển — chạy nó trên một box đã có
Xisom đang chạy sẽ gây xung đột.

## Runbook cài đặt

1. ### Sao chép gói vào box

   Sao chép toàn bộ thư mục gói từ thiết bị USB của bạn vào box đích, rồi
   mở một terminal trong đó:

   ```bash
   cd amd64-cpu-v1.5.0/
   ```

2. ### Chạy trình cài đặt

   Trình cài đặt tự phát hiện hồ sơ phần cứng của bạn, nạp các image container,
   sinh secret, khởi chạy stack, và chờ tình trạng khỏe mạnh.

   ```bash
   sudo ./install.sh
   ```

   Để ép một hồ sơ cụ thể, hoặc để cài thêm dịch vụ tự khởi động khi boot:

   ```bash
   sudo ./install.sh --profile amd64-cpu   # force the profile
   sudo ./install.sh --with-systemd        # also start on boot
   ```

   Bên dưới, `install.sh` chạy các bước này theo thứ tự:

   1. **Preflight** — kiểm tra Docker, GPU toolkit (GPU/Jetson), và dung lượng đĩa.
   2. **Xác minh** checksum của kho lưu trữ image (phát hiện media hỏng hoặc bị giả mạo).
   3. **Nạp images** — `docker load` từ kho lưu trữ đi kèm (không pull, không build).
   4. **Sinh secret** — tạo secret ký JWT và mật khẩu admin trên
      box và ghi chúng vào một `.env` được bảo vệ (mode `600`). Không có secret nào
      đi kèm bên trong gói.
   5. **Khởi chạy stack** — `docker compose up -d`.
   6. **Cổng tình trạng** — chờ cả ba dịch vụ báo cáo khỏe mạnh.
   7. **Tạo mầm admin** và **in URL bảng điều khiển + mật khẩu admin một lần**.

3. ### Lưu lại mật khẩu admin

   
**Chỉ in một lần**

   Trình cài đặt in URL bảng điều khiển và mật khẩu admin được sinh ra **một
   lần duy nhất** ở cuối lần chạy. Sao chép ngay vào trình quản lý mật khẩu của bạn
   — nó không được lưu ở bất kỳ nơi nào bạn có thể đọc lại.
   

4. ### Xác nhận secret đã được ghi

   Trình cài đặt sinh secret ký JWT tự động. Bạn thường không bao giờ
   động đến nó, nhưng có thể xác nhận `.env` được bảo vệ tồn tại:

   ```bash
   ls -l .env        # expect mode -rw------- (600)
   ```

   Nếu bạn cần cung cấp giá trị của riêng mình (ví dụ một chính sách quản lý secret
   của doanh nghiệp), hãy chỉnh sửa `.env` trước lần `up` đầu tiên và đặt một giá trị ngẫu nhiên mạnh:

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

5. ### Thay thế mô hình demo

   Gói đi kèm một mô hình demo với trọng số ngẫu nhiên. Thay nó bằng
   `predictive_maintenance.onnx` đã huấn luyện của bạn để các dự đoán có ý nghĩa:

   - **Trước lần cài đặt đầu tiên:** ghi đè `models/predictive_maintenance.onnx` trong
     gói, rồi chạy `install.sh`.
   - **Sau khi cài đặt:** thả mô hình của bạn vào volume model-data tại `/data/models`
     và khởi động lại dịch vụ suy luận.

   Bạn cũng có thể tải lên mô hình sau từ bảng điều khiển — xem
   [Triển khai mô hình](/vi/configure/models/).

6. ### Kiểm tra tình trạng

   Xác nhận cả ba dịch vụ đều khỏe mạnh:

   ```bash
   docker compose -f compose/docker-compose.release.yml ps
   ```

   Mong đợi ba container ở trạng thái `healthy`. Sau đó mở URL bảng điều khiển mà
   trình cài đặt đã in và đăng nhập bằng tài khoản admin.

   
**Lần chạy đầu trên GPU bị chậm**

   Trên hồ sơ GPU và Jetson, dịch vụ suy luận có thể ở trạng thái `unhealthy` trong
   2–3 phút ở lần boot đầu trong khi nó biên dịch engine TensorRT. Đây là
   điều dự kiến — hãy chờ, rồi kiểm tra lại `ps`.
   

## Vận hành ngày-2

  
**Cập nhật**

   Triển khai một gói mới hơn. Quá trình cập nhật chụp nhanh cơ sở dữ liệu trước để bạn có
   đường rollback.

   ```bash
   sudo ./update.sh
   ```

   
**Mang .env đang chạy của bạn vào gói mới**

   `update.sh` đọc `.env` từ thư mục gói — nó giữ
   secret theo từng lần triển khai, các cổng, và tham chiếu image của bạn. Một gói vừa tải xuống
   không có gì cả, nên hãy sao chép `.env` của bản cài đặt hiện có vào thư mục gói mới
   trước khi chạy cập nhật, nếu không nó sẽ hủy bỏ.
   

   Ảnh chụp nhanh trước cập nhật chỉ bao gồm **cơ sở dữ liệu** (không bao gồm mô hình đã tải lên hoặc
   cache TensorRT). Hãy sao lưu các volume đó riêng nếu bạn cần rollback mô hình.

  
  
**Gỡ cài đặt**

   ```bash
   ./uninstall.sh          # stop the stack, KEEP all data
   ./uninstall.sh --purge  # also delete models + database (confirmation prompt)
   ```

  

## Nếu có gì đó sai

| Triệu chứng | Nó có nghĩa gì |
|---------|---------------|
| `Bundle manifest missing` | Bạn đã chạy trình cài đặt từ một thư mục nguồn, không phải một gói đã lắp ráp. Dùng thư mục gói bạn đã sao chép từ USB. |
| `Architecture mismatch` | Sai hồ sơ gói cho CPU của box này. Dùng hồ sơ khớp. |
| `NVIDIA toolkit not wired in` | Gói GPU/Jetson trên một box không có container toolkit. Dùng gói `amd64-cpu`, hoặc sửa stack GPU trên OS image. |
| Suy luận kẹt ở `unhealthy` | Biên dịch TensorRT lần chạy đầu (GPU) mất 2–3 phút — hãy chờ. Nếu không, hãy kiểm tra nhật ký suy luận. |
| Checksum kho lưu trữ không khớp | Thiết bị USB bị hỏng hoặc bị giả mạo. Sao chép lại gói và thử lại. |

Xem runbook [Khắc phục sự cố](/vi/troubleshooting/) đầy đủ để có các cách sửa theo từng triệu chứng.

## Tiếp theo

  - [Kết nối một nguồn dữ liệu đầu vào](/vi/configure/input-datasources/) — Truyền dữ liệu cảm biến vào runtime.
  - [Triển khai một mô hình](/vi/configure/models/) — Tải lên và kích hoạt mô hình đã huấn luyện của bạn.
  - [Lần suy luận đầu tiên của bạn](/vi/install-deploy/first-inference/) — Tạo mầm một mô hình và xem dự đoán trực tiếp.