Giao diện

Câu hỏi thường gặp — Queue Adapter Redis ​

Cài đặt ​

Không kết nối được đến Redis? ​

Kiểm tra:

  1. Redis đang chạy: redis-cli ping → trả về PONG
  2. Firewall cho phép kết nối từ server Digiforce
  3. URL đúng format: redis://[password@]host:port/db
  4. Redis phiên bản >= 5.0 (yêu cầu Streams)

Đã bật plugin nhưng queue không hoạt động? ​

Kiểm tra biến môi trường QUEUE_ADAPTER. Plugin bắt buộc QUEUE_ADAPTER=redis mới kích hoạt. Nếu thiếu, plugin ghi log debug và thoát:

"process.env.QUEUE_ADAPTER" is not set to "redis", event queue will not work on redis.

Plugin sử dụng BullMQ hay Redis Streams? ​

Plugin sử dụng Redis Streams với Consumer Groups (XREADGROUP / XADD), không phải BullMQ. Đây là implementation nhẹ hơn, tích hợp trực tiếp với redis package (node-redis v4).

Sử dụng ​

Mỗi subscription tạo Redis client riêng — có tốn tài nguyên không? ​

Mỗi channel/queue subscription tạo một Redis client riêng. Điều này cần thiết vì XREADGROUP BLOCK là blocking operation — nếu dùng chung client, các channel sẽ chặn lẫn nhau.

Với 5 queues, plugin tạo 5 Redis connections. Đây là overhead chấp nhận được — mỗi connection tiêu thụ rất ít memory.

Retry hoạt động như thế nào? ​

Khi job thất bại:

  1. Plugin XACK + XDEL message gốc
  2. Nếu retried < maxRetries, plugin XADD message mới với retried + 1
  3. Message mới được đẩy vào cuối stream, consumer sẽ xử lý lại
  4. Nếu hết lượt retry, message bị bỏ qua

Retry là immediate (không có backoff delay) — message mới được publish ngay lập tức.

Message có bị mất khi Redis restart không? ​

Phụ thuộc cấu hình Redis persistence:

  • AOF (appendonly yes): Hầu như không mất message
  • RDB (snapshot): Có thể mất message kể từ snapshot cuối
  • Không persistence: Mất toàn bộ

Khuyến nghị bật AOF cho production nếu dùng Redis làm queue.

Consumer Group "DIGIFORCE_APP" là gì? ​

Tất cả instance Digiforce sử dụng chung Consumer Group DIGIFORCE_APP. Mỗi instance là một consumer với clientId = app.instanceId. Redis đảm bảo mỗi message trong stream chỉ được giao cho 1 consumer trong group.

Khi consumer tắt đột ngột, message chưa ACK sẽ ra sao? ​

Message nằm trong PEL (Pending Entries List) của Redis Streams. Plugin hiện tại không tự động xử lý PEL entries. Để khôi phục:

bash
# Xem PEL
redis-cli XPENDING <stream> DIGIFORCE_APP - + 10

# Claim message cho consumer khác
redis-cli XCLAIM <stream> DIGIFORCE_APP <consumer-id> 0 <message-id>

Lỗi thường gặp ​

Lỗi "ECONNREFUSED" ​

Redis không chạy hoặc không lắng nghe trên port cấu hình. Kiểm tra:

  • redis-cli -h <host> -p <port> ping
  • Firewall rules

Lỗi "NOAUTH" ​

Mật khẩu không đúng hoặc thiếu. Kiểm tra URL: redis://:correct-password@host:port/db

Lỗi "BUSYGROUP Consumer Group name already exists" ​

Đây là lỗi bình thường — xảy ra khi Consumer Group đã tồn tại từ lần khởi động trước. Plugin đã xử lý lỗi này (bỏ qua nếu message chứa "BUSYGROUP").

Lỗi "ERR unknown command 'xreadgroup'" ​

Redis phiên bản quá cũ (< 5.0). Cần nâng cấp Redis.

Message bị xử lý nhiều lần ​

Có thể xảy ra khi consumer bận → message bị re-publish → consumer khác nhận lại. Handler cần thiết kế idempotent để tránh side effect khi xử lý trùng.