Hướng dẫn Docker Lab

Hướng dẫn này dựng lên docker-industrial-lab — một sandbox simulator OPC UA + MQTT cục bộ đi kèm trong repository này — cạnh stack Xisom của bạn, để bạn có thể thực hành adapter datasource MQTT và OPC UA từ đầu đến cuối mà không cần một mạng nhà máy thật.

Nó nằm ở đâu

Lab là một phần của repository này tại docker-industrial-lab/ — nó không phải một repo riêng để clone. Nó có docker-compose.yml riêng, một .env được sinh ra, và một Makefile với các target up / down / smoke.

Bạn sẽ dựng những gì

• Simulator OPC UA (lab-opcua) — một server đã bảo mật phơi bày các tag nhà máy, các setpoint có thể ghi (để kiểm thử ghi đầu ra của AIBOARD), và các tag mẫu để kiểm thử quy mô.
• Broker MQTT (lab-mosquitto, Eclipse Mosquitto) — bảo mật theo mặc định (TLS + username/password, hoặc mutual-TLS), có một profile dự phòng ẩn danh.
• MQTT publisher + sniffer — mô phỏng một thiết bị publish dữ liệu nhà máy, và xác nhận sink đầu ra của AIBOARD thực sự ghi ra cái gì.
• Stack Xisom của bạn (suy luận + backend + frontend) — gắn vào mạng Docker của lab qua overlay tùy chọn docker-compose.lab.yml ở gốc repo, hoặc được truy cập qua host loopback mà không cần nó.

Các bước

1. Bootstrap secret và khởi chạy lab. Stack được bảo mật theo mặc định; một script chạy một lần sinh ra một CA riêng, chứng chỉ client, và thông tin xác thực broker/OPC UA ở lần chạy đầu tiên:

   cd docker-industrial-lab
   ./scripts/bootstrap-secrets.sh   # or: make certs
   docker compose up -d             # or: make up
   docker compose ps                # expect every service "healthy" within ~30s

   Đừng tự tay sao chép .env.example

   bootstrap-secrets.sh sinh ra .env thật (mật khẩu ngẫu nhiên + COMPOSE_PROFILES=secure). Tự sao chép .env.example sang .env sẽ bỏ qua bước sinh PKI — dịch vụ certs-guard sau đó sẽ lỗi ngay cho đến khi bạn chạy script.

2. Chạy smoke test để xác nhận stack đã bảo mật từ đầu đến cuối:

   ./scripts/smoke-test.sh   # or: make smoke

3. Gắn stack Xisom của bạn vào mạng lab (từ gốc repo, lên một cấp):

   cd ..
   docker compose -f docker-compose.yml -f docker-compose.lab.yml up -d

   Việc này gắn service backend vào mạng Docker industrial-lab của lab để nó tới được các simulator qua container DNS (opcua, mosquitto) — không cần cổng host nào. Các URL host-loopback (host.docker.internal:...) cũng hoạt động mà không cần overlay này.

4. Thêm các datasource trong dashboard Xisom — một đầu vào OPC UA tại opc.tcp://opcua:4840/factory/line1 (hoặc host.docker.internal nếu không dùng overlay), và/hoặc một đầu vào MQTT tại mqtt://mosquitto:8884 (TLS + username/password). Thông tin xác thực nằm trong docker-industrial-lab/.env đã được sinh ra.

Kiểm tra

• docker compose ps (bên trong docker-industrial-lab/) hiện mọi service healthy.
• Trong dashboard Xisom, bật và Start datasource, rồi mở Inference Stats — bạn sẽ thấy thông lượng trực tiếp từ các tag mô phỏng.
• Xác nhận một lần ghi đầu ra của AIBOARD thực sự đi tới đâu: docker logs lab-opcua | grep WRITE hoặc docker logs lab-mqtt-sniffer.

Các knob env mẫu (kiểm thử tải/quy mô)

(v1.28.0, chỉ dành cho lab — không ảnh hưởng đến runtime sản phẩm.) Cả hai simulator đều phơi bày thêm các knob env trong docker-industrial-lab/.env để đẩy số lượng tag và tốc độ cao hơn demo nhà máy mặc định, hữu ích để thực hành adapter của AIBOARD dưới tải:

Biến env	Mặc định	Mục đích
SAMPLE_TAG_COUNT	100	Các tag mẫu bổ sung trên cả hai giao thức — MQTT aiboard/sample_mqtt/topic_1..N, OPC UA ns=2;s=SampleOpcua_Tag_1..N. 0 để tắt.
SAMPLE_RATE_HZ	chưa đặt (tốc độ cũ)	Tốc độ lấy mẫu toàn vòng lặp tính bằng Hz cho cả hai simulator, ví dụ 10/20/50. Ghi đè PUBLISH_INTERVAL (MQTT) và mặc định 1 Hz của OPC UA.
SAMPLE_WALK_STEP	4.0	Kích thước bước Gaussian mỗi mẫu của random walk hồi quy về trung bình (lớn hơn = nhảy nhiều hơn).
SAMPLE_WALK_CENTER	50.0	Giá trị mà walk hồi quy về.
SAMPLE_WALK_REVERSION	0.05	Cường độ kéo về tâm, 0–1 (0 = random walk thuần túy).
SAMPLE_MQTT_QOS	0	QoS chỉ cho các topic MQTT mẫu — kiểm thử adapter ở 0/1/2. Các topic nhà máy luôn giữ QoS 0.
SAMPLE_MQTT_RETAIN	false	Cờ retain chỉ cho các topic MQTT mẫu.

Mẹo

Ở SAMPLE_RATE_HZ cao kết hợp với SAMPLE_TAG_COUNT lớn (ví dụ 50 Hz × 100 tag ≈ 5k lần ghi/giây mỗi giao thức), một vòng lặp simulator có thể vượt quá ngân sách của nó và tốc độ thực tế giảm xuống dưới mục tiêu — hãy giảm một knob nếu bạn cần đảm bảo thông lượng cứng.

Dọn dẹp

cd docker-industrial-lab
make down   # docker compose --profile secure --profile insecure --profile dashboard down -v

Việc này xóa các container và volume nhưng giữ lại PKI đã sinh (certs/, mosquitto/secrets/) để một lần up trong tương lai không cần bootstrap lại. Xoay vòng thông tin xác thực bằng ./scripts/bootstrap-secrets.sh --force.

Nếu có gì đó trục trặc

Các service không đạt healthy, hoặc không có lưu lượng trong dashboard — xem runbook Khắc phục sự cố, và cụ thể là Đầu vào MQTT dừng hoặc lỗi cho các nguyên nhân phía broker.