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

Đâ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 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:

• Thư mụcamd64-cpu-v1.5.0/

  • Thư mụcimages/

    • amd64-cpu-v1.5.0.images.tar.zst ba image dịch vụ, đã nén
    • manifest.txt tag image + checksum
  • Thư mụccompose/

    • docker-compose.release.yml stack dựa trên image (không có bước build)
    • docker-compose.certs.yml overlay chứng chỉ TLS của datasource (tùy chọn, xem bên dưới)
    • .env.template placeholder cho cổng + secret
  • Thư mụcmodels/

    • predictive_maintenance.onnx mô hình mầm demo (trọng số ngẫu nhiên)
  • Thư mụccerts/ CA + chứng chỉ/khóa client MQTT/OPC UA của datasource (tùy chọ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.

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

Chú ý

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 đó:

   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.

   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:

   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:

   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:

   # .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.

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

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

   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.

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

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

Chứng chỉ TLS của datasource

(v1.22.1) TLS phía datasource — CA / chứng chỉ client / khóa mà một datasource MQTT hoặc OPC UA dùng để tới một broker hoặc server đã bảo mật, tách biệt với chứng chỉ HTTPS của chính box — mặc định tắt trên đường dẫn gói offline. Đây là một cờ .env dựa trên tệp, đối xứng với AIBOARD_TLS_ENABLED:

.env

AIBOARD_CERTS_ENABLED=1

Khi cờ này bật, install.sh ghi lại một đường dẫn tuyệt đối AIBOARD_CERTS_DIR=<bundle>/certs và lớp overlay docker-compose.certs.yml đi kèm lên trên stack phát hành cơ bản. Hãy thả các tệp CA và chứng chỉ/khóa client MQTT/OPC UA của bạn vào thư mục certs/ của gói trước khi bật cờ.

Đường dẫn chứng chỉ ở phía server và bị giới hạn (jailed)

Các trường đường dẫn chứng chỉ của một datasource (tệp CA, chứng chỉ client, khóa client) được phân giải trên hệ thống tệp của container backend, giới hạn trong gốc certs/ đã mount — không phải một đường dẫn trên máy của người vận hành. Xem Kết nối nguồn dữ liệu đầu vào và Datasource đầu ra để biết nơi đặt chúng.

update.sh mang chứng chỉ của bạn sang gói mới

Chứng chỉ không thể được sinh lại theo cách chứng chỉ TLS riêng của box có thể. update.sh mang các tệp chứng chỉ của người vận hành từ gói trước sang gói mới trước khi trỏ lại AIBOARD_CERTS_DIR, để một lần cập nhật thông thường không làm mắc kẹt một cấu hình TLS MQTT/OPC UA đang hoạt động.

uid-101 phải đọc được certs/

Container backend đọc các tệp chứng chỉ với uid 101. Hãy đặt quyền sở hữu/quyền truy cập trên thư mục certs/ của gói (và mọi tệp bên trong nó) sao cho uid 101 có quyền đọc — nếu không, adapter datasource sẽ lỗi khi tải chứng chỉ lúc kết nối.

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ố đầ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 Truyền dữ liệu cảm biến vào runtime.

Triển khai một mô hình 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 Tạo mầm một mô hình và xem dự đoán trực tiếp.