Hàng đợi ingest trên Pano Server: xử lý burst ảnh từ hàng trăm agent

Luồng kỹ thuật POST /api/agent/data, INGEST_MODE async/sync, worker pool, SQLite + captures JPEG, health queue_depth và tham số scale server.env cho fleet tới 300 máy.

Vì sao Pano Server cần hàng đợi ingest

Khi vài chục đến vài trăm agent Windows gửi ảnh JPEG và metadata về Server cùng lúc, endpoint nhận dữ liệu không thể ghi SQLite và lưu file ảnh đồng bộ trong từng HTTP request mà không làm chậm agent hoặc timeout. Pano Server (FastAPI trên Windows) dùng hàng đợi ingest bất đồng bộ: request trả về nhanh, worker nền xử lý ghi đĩa.

Bài viết mô tả luồng kỹ thuật từ agent POST tới gallery trên Admin — dành cho kỹ sư triển khai và người đánh giá kiến trúc self-hosted, không lặp lại nội dung chọn gói license hay giám sát nhân viên.

Luồng dữ liệu: Agent → API → Queue → SQLite + JPEG

Bước 1: Agent gửi payload định kỳ

Pano Client cấu hình API_URL trỏ tới http://server:8010/api/agent/data (hoặc cổng tương đương trong gói cài). Mỗi chu kỳ, agent POST JSON gồm:

• agent_id — định danh máy
• Ảnh màn hình base64 (JPEG nén)
• Metadata: ứng dụng foreground, tab trình duyệt, trạng thái online
• Sự kiện phụ: USB, cảnh báo mạng (khi bật trong cấu hình)

Chu kỳ mặc định khoảng 5–10 giây tùy gói license. Với 100 máy, Server có thể nhận 10–20 request/giây ở peak — chưa kể burst khi nhiều agent đồng bộ theo cùng nhịp đồng hồ.

Bước 2: API xác thực và enqueue

Endpoint POST /api/agent/data kiểm tra:

• Bearer token hoặc cơ chế đăng ký agent hợp lệ
• Kích thước body (giới hạn mặc định khoảng 6 MB mỗi request — đủ cho ảnh JPEG nén)
• License còn hiệu lực (trial hết hạn trả 403)

Nếu INGEST_MODE=async (mặc định trên gói scale), payload không ghi đĩa ngay mà đưa vào hàng đợi. HTTP response trả về nhanh để agent không bị treo chờ ghi file.

Bước 3: Worker ghi SQLite và thư mục captures

Worker nền (thread pool trong process, hoặc Redis queue nếu cấu hình) lấy job và:

1. Giải mã JPEG, lưu vào thư mục captures theo agent_id và timestamp 2. Cập nhật SQLite: registry máy, last_seen, index gallery 3. Ghi metadata ứng dụng, lịch sử trình duyệt, log cảnh báo tùy loại payload

Admin đọc gallery qua API index — không quét thư mục ảnh trực tiếp từ trình duyệt mỗi lần refresh.

Chế độ async và sync

Async (mặc định — khuyến nghị production)

Biến môi trường INGEST_MODE=async trên Pano Server.

• Request chỉ enqueue; worker pool xử lý song song
• Số worker mặc định scale theo CPU: thường 4–8 thread, tối đa 16
• Hàng đợi in-process tối đa khoảng 15.000 job; vượt ngưỡng có thể drop hoặc từ chối tùy cấu hình health

Phù hợp fleet từ vài chục máy trở lên, đặc biệt gói Business tới 300 agent.

Sync (hành vi cũ / debug)

INGEST_MODE=sync — ghi đĩa trong cùng request HTTP.

• Đơn giản khi pilot 3–5 máy
• Dễ debug khi gallery không cập nhật
• Không khuyến nghị khi đồng thời nhiều agent: latency tăng, agent retry, tạo thêm burst

Tham số scale trên server.env

Các biến thường chỉnh trên máy Server (file server.env trong gói cài):

• INGEST_MODE — async hoặc sync
• INGEST_WORKERS — số thread worker (mặc định tự tính từ CPU)
• INGESTQUEUEMAX — độ sâu hàng đợi (mặc định 15000)
• REDIS_URL — tùy chọn: chuyển queue sang Redis nếu chạy multi-instance (nâng cao)
• MAXINGESTBODY_BYTES — giới hạn kích thước POST

Gói Enterprise scale thường ship INGEST_MODE=async sẵn trong server.env. Pilot Trial trên 10 máy có thể chạy mặc định mà không cần chỉnh.

Redis queue (tùy chọn)

Khi REDIS_URL trỏ tới instance Redis nội bộ, ingest job đẩy vào key pano:ingest. Worker vẫn chạy trong process Server hoặc có thể tách sau này.

Use case:

• Chuẩn bị kiến trúc nhiều node Server sau này
• Tách ingest khỏi API process trong triển khai tùy chỉnh

Đa số doanh nghiệp SMB: một Server Windows + queue in-process là đủ tới 300 máy nếu ổ SSD và RAM phù hợp.

Index gallery và SQLite

SQLite lưu bảng registry agent, metadata và capture index — map từ agent_id + timestamp tới đường dẫn file JPEG. Khi Admin mở gallery trang 2, 3… Server query index thay vì liệt kê toàn bộ thư mục captures mỗi request.

Backfill index chạy khi nâng cấp phiên bản hoặc restore backup — đồng bộ lại DB với file ảnh còn trên ổ. Chi tiết backup: Backup và retention dữ liệu trên Pano Server.

Health check và giám sát hàng đợi

Server expose endpoint health (trong Admin hoặc API nội bộ) báo:

• ingest_workers — số worker đang chạy
• ingestqueuemax — giới hạn hàng đợi
• queue_depth — số job đang chờ

Khi queuedepth tiến gần ingestqueue_max:

• Ổ đĩa ghi chậm (HDD đầy hoặc antivirus quét từng file JPEG)
• CPU Server quá tải — cân nhắc tăng INGEST_WORKERS hoặc nâng phần cứng
• Burst đồng bộ — nhiều agent cùng chu kỳ; có thể jitter nhẹ ở phía agent trong bản tùy chỉnh

Không nên public health ra Internet; chỉ truy cập trong LAN hoặc VPN.

Liên hệ với chụp màn hình trên Agent

Agent dùng backend mss trên Windows (mặc định) để chụp framebuffer không vẽ con trỏ — giảm nháy chuột so với ImageGrab. Multi-monitor: ghép các màn vật lý vào một khung ảnh trước khi nén JPEG.

Pipeline đầy đủ:

1. mss capture → PIL resize/JPEG encode 2. POST base64 tới /api/agent/data 3. Ingest queue → file trên thư mục captures 4. Admin gallery refresh đọc index

Bài chuyên sâu chụp ảnh: Cơ chế chụp ảnh màn hình định kỳ trên Pano Agent.

So sánh với SaaS cloud

Cloud monitoring thường đẩy ingest lên CDN + object storage (S3 tương đương). Pano self-hosted gom ingest + SQLite + filesystem trên một máy Server trong LAN — queue nội bộ thay cho hàng đợi managed cloud.

Trade-off:

• Không trả phí egress upload ảnh
• Bạn chịu trách nhiệm sizing ổ và RAM Server
• Dữ liệu không rời firewall công ty

Khuyến nghị sizing nhanh

• 10–30 agent — async mặc định; Server 4 GB RAM, SSD 256 GB+
• 50–100 agent — async, 4–8 workers; 8 GB RAM, SSD 512 GB–1 TB
• 100–300 agent — async, tăng workers nếu queue_depth cao; 16 GB RAM, SSD/NVMe 1 TB+, monitor health

Đo thực tế sau pilot một tuần: xem queue_depth, dung lượng thư mục captures và latency gallery. Công thức ước lượng ổ: Backup và retention.

Câu hỏi kỹ thuật thường gặp

Gallery trống nhưng agent báo gửi OK

Kiểm tra INGEST_MODE, worker có chạy không, ổ đĩa còn trống, quyền ghi thư mục captures. Thử sync tạm trên 1 máy để loại trừ lỗi queue.

Có cần Redis cho 50 máy không

Không. In-process queue đủ. Redis chỉ khi kiến trúc multi-node tùy chỉnh.

Agent timeout khi POST

Thường do Server ghi sync dưới tải, firewall, hoặc body quá lớn. Chuyển async, giảm độ phân giải JPEG phía agent nếu đã tùy chỉnh.

Trial có dùng ingest async không

Có — cùng stack với bản trả phí; giới hạn 10 máy và 7 ngày license, không giới hạn kiến trúc queue.

Bước tiếp theo

• Kiến trúc tổng thể PANO: Pano là gì — self-hosted Windows
• Scale 300 máy: Self-hosted 300 máy trên Pano Server
• Cấu hình agent: agent.env — Server URL và token
• Pilot: panosoftware.com/trial