Giao diện

Hướng dẫn cài đặt — PubSub Adapter Redis ​

Yêu cầu ​

  • Server Digiforce đang chạy
  • Redis server (>= 5.0 — yêu cầu hỗ trợ Streams)

Bước 1: Kích hoạt Plugin ​

Vào Settings → Plugin Manager, tìm plugin-pubsub-adapter-redis và bật. Khởi động lại server.

Bước 2: Cấu hình kết nối Redis ​

Đặt biến môi trường:

bash
PUBSUB_ADAPTER_REDIS_URL=redis://localhost:6379/0

Nếu Redis yêu cầu xác thực:

bash
PUBSUB_ADAPTER_REDIS_URL=redis://:your-password@redis-host:6379/0

Tất cả biến môi trường ​

BiếnMặc địnhMô tả
PUBSUB_ADAPTER_REDIS_URL(bắt buộc)URL kết nối Redis
PUBSUB_CONNECTION_RETRY_MAX_ATTEMPTS20Số lần retry tối đa
PUBSUB_CONNECTION_RETRY_DELAY200Delay giữa các lần retry (ms)

Chiến lược retry: delay tăng tuyến tính theo công thức retries × delay. Ví dụ với delay = 200ms: lần 1 = 200ms, lần 2 = 400ms, lần 3 = 600ms, ..., lần 20 = 4000ms.

Bước 3: Kiểm tra ​

Khởi động lại server và kiểm tra log:

[info] pubsub redis client connected

Nếu kết nối thất bại:

[error] pubsub redis client error ...
[error] can not connect redis at url: redis://localhost:6379/0

Cách hoạt động chi tiết ​

Publish message ​

Plugin sử dụng XADD với auto-trim:

XADD <channel> * content "<message>" MAXLEN ~ 1000
  • *: Redis tự sinh message ID (timestamp-based)
  • MAXLEN ~ 1000: Giữ khoảng 1000 entries gần nhất (approximate trim)

Subscribe và đọc message ​

Plugin sử dụng vòng lặp XREAD BLOCK:

  • BLOCK 1000: Chờ tối đa 1 giây nếu không có message mới
  • COUNT 10: Đọc tối đa 10 message mỗi lần
  • ID khởi tạo: Timestamp khi adapter được tạo — chỉ đọc message mới hơn thời điểm khởi động

Sơ đồ kết nối ​

Plugin sử dụng 1 Redis connection duy nhất (khác với Redis Pub/Sub truyền thống cần 2 connection riêng biệt cho pub và sub). Điều này vì Redis Streams sử dụng XREAD (command bình thường) thay vì SUBSCRIBE (blocking mode đặc biệt).

Khi nào nên dùng plugin này ​

Trường hợpNên dùng?
Chạy nhiều instance (cluster) cần đồng bộ sự kiện✅ Có
Cache invalidation giữa các instance✅ Có
Single instance❌ Không cần — dùng adapter mặc định (in-memory)
Cần guaranteed delivery (không mất message)⚠️ Hạn chế — dùng queue adapter thay thế

Lưu ý triển khai ​

  • Redis cần accessible từ tất cả instance của Digiforce
  • Redis >= 5.0 (yêu cầu Streams support)
  • Stream auto-trim giữ ~1000 entries — message cũ hơn sẽ bị xóa
  • Nếu instance offline quá lâu, có thể bỏ lỡ message đã bị trim
  • Khuyến nghị dùng Redis riêng hoặc database index riêng để tránh xung đột