Hướng dẫn cài đặt và sử dụng — Lock Adapter Redis

Yêu cầu hệ thống

Thành phần	Yêu cầu tối thiểu
Digiforce Server	Đang chạy và hoạt động bình thường
Redis Server	Phiên bản 6.0 trở lên, có thể kết nối từ tất cả instance Digiforce
Node.js	Phiên bản tương thích với Digiforce (xem `package.json` gốc)
Mạng	Các instance Digiforce phải truy cập được Redis qua TCP (mặc định port `6379`)

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

Truy cập Settings → Plugin Manager, tìm plugin-lock-adapter-redis và bật plugin. Khởi động lại server để plugin có hiệu lực.

Bước 2: Cấu hình biến môi trường

Plugin đọc URL kết nối Redis từ biến môi trường LOCK_ADAPTER_REDIS_URL. Nếu không cấu hình, plugin sẽ ghi log lỗi và không hoạt động.

bash

# .env
LOCK_ADAPTER_REDIS_URL=redis://localhost:6379

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

bash

LOCK_ADAPTER_REDIS_URL=redis://:matkhau_redis@redis-host:6379/0

Với Redis qua TLS:

bash

LOCK_ADAPTER_REDIS_URL=rediss://:matkhau_redis@redis-host:6380/0

Bảng tham số kết nối

Tham số trong URL	Mô tả	Ví dụ
host	Địa chỉ Redis server	`redis-host`, `10.0.0.5`
port	Cổng kết nối	`6379` (mặc định)
password	Mật khẩu Redis (nếu có)	`:matkhau@`
db	Database index	`/0` (mặc định)
protocol	`redis://` hoặc `rediss://` (TLS)	`rediss://` cho kết nối mã hoá

Bước 3: Kiểm tra kết nối

Sau khi cấu hình, khởi động lại server và kiểm tra log:

bash

yarn digiforce start

Nếu kết nối thành công, plugin sẽ đăng ký adapter redis vào LockManager. Nếu thất bại, bạn sẽ thấy lỗi:

[error] process.env.LOCK_ADAPTER_REDIS_URL is not configured.

Mẹo kiểm tra nhanh

Dùng redis-cli để xác nhận Redis đang hoạt động trước khi bật plugin:

bash

redis-cli -u redis://localhost:6379 ping
# Kết quả mong đợi: PONG

Cách hoạt động bên trong

Khi plugin được load, nó thực hiện:

Đọc URL từ this.options.url hoặc process.env.LOCK_ADAPTER_REDIS_URL
Đăng ký RedisLockAdapter vào app.lockManager với adapter name là redis
Khi cần lock, RedisLockAdapter sử dụng thư viện Redlock (thuật toán Redlock) để acquire/release lock

Cấu hình nâng cao

Tham số Redlock (bên trong Plugin)

Plugin sử dụng Redlock với các tham số mặc định:

Tham số	Giá trị	Mô tả
`retryCount`	`-1` (vô hạn)	Số lần retry khi lock bị chiếm — `-1` nghĩa là retry không giới hạn
`retryDelay`	`100` ms	Thời gian chờ giữa các lần retry
`retryJitter`	`100` ms	Jitter ngẫu nhiên thêm vào delay để tránh thundering herd
`automaticExtensionThreshold`	`350` ms	Ngưỡng tự động gia hạn lock

Sử dụng với Redis Sentinel

bash

# Cấu hình sentinel thông qua URL
LOCK_ADAPTER_REDIS_URL=redis+sentinel://sentinel1:26379,sentinel2:26379/mymaster/0

Sử dụng với Redis Cluster

bash

LOCK_ADAPTER_REDIS_URL=redis://cluster-node1:6379,cluster-node2:6379,cluster-node3:6379

Lưu ý khi triển khai Production

Redis phải accessible từ tất cả instance Digiforce trong cluster
Khuyến nghị Redis riêng cho lock — không chia sẻ với cache hoặc session
Theo dõi memory/CPU của Redis khi tải cao
Cấu hình persistence (AOF hoặc RDB) để tránh mất dữ liệu khi Redis restart
TTL cần hợp lý: đủ dài để task hoàn thành, đủ ngắn để recovery nhanh khi instance crash
Nếu Redis restart, tất cả lock bị mất — các task sẽ tự động retry nhờ cơ chế retryCount: -1

Cảnh báo

Nếu LOCK_ADAPTER_REDIS_URL không được cấu hình, plugin sẽ không hoạt động và hệ thống sẽ fallback về lock adapter mặc định (in-memory). Điều này có thể gây race condition trong môi trường multi-instance.