Giao diện

Hướng dẫn cài đặt và sử dụng — IP Restriction ​

Tổng quan ​

Plugin @digiforce-nc/plugin-ip-restriction kiểm soát truy cập hệ thống dựa trên địa chỉ IP. Hỗ trợ hai chế độ: whitelist (chỉ cho phép IP trong danh sách) và blacklist (chặn IP trong danh sách). Middleware kiểm tra IP trên mọi request trước khi xử lý, sử dụng thư viện ip-range-check để hỗ trợ CIDR notation.

Yêu cầu ​

  • Server DigiForce đang chạy
  • Biết địa chỉ IP cần hạn chế hoặc cho phép

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

Vào Settings → Plugin Manager, tìm plugin-ip-restriction và bật lên.

Khi cài đặt lần đầu, plugin tự tạo cấu hình mặc định:

  • Chế độ: blacklist (chặn IP trong danh sách, cho phép tất cả còn lại)
  • Danh sách IP: rỗng (không chặn gì)

Bước 2: Chọn chế độ hoạt động ​

Vào Settings → IP Restriction, chọn chế độ:

Chế độHành viKhi nào dùng
Blacklist (mặc định)Chặn các IP trong danh sách, cho phép tất cả IP khácChặn IP xấu, bot, attacker
WhitelistChỉ cho phép các IP trong danh sách, chặn tất cả IP khácHệ thống nội bộ, truy cập hạn chế

Cẩn thận với Whitelist mode

Khi chuyển sang whitelist mode, hãy thêm IP hiện tại của bạn vào danh sách trước. Nếu quên, bạn sẽ bị khoá ngoài hệ thống.

Bước 3: Thêm IP vào danh sách ​

Định dạngVí dụMô tả
IP đơn192.168.1.100Một địa chỉ IP cụ thể
CIDR range192.168.1.0/24Dải 256 địa chỉ (192.168.1.0 → 192.168.1.255)
CIDR range lớn10.0.0.0/8Toàn bộ dải 10.x.x.x

Danh sách IP có thể nhập nhiều dòng hoặc phân cách bằng dấu phẩy:

192.168.1.100
10.0.0.0/24
172.16.0.0/16

Bước 4: Kiểm tra ​

  1. Truy cập từ IP được phép → hệ thống hoạt động bình thường
  2. Truy cập từ IP bị chặn → nhận lỗi 403 Forbidden với mã BLOCKED_IP

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

Luồng kiểm tra IP ​

Cấu hình được cache ​

Cấu hình IP restriction được cache trong memory để tăng hiệu suất. Cache tự động cập nhật khi admin thay đổi cấu hình (qua hook afterSave trên collection ipRestrictionConfig). Không cần restart server.

Bypass cho app:getLang ​

Action app:getLang (lấy ngôn ngữ) được bypass khỏi kiểm tra IP để trang lỗi 403 vẫn hiển thị đúng ngôn ngữ.

Cấu hình database ​

Collection ipRestrictionConfig ​

TrườngKiểuMô tả
keystringKhoá cấu hình (cố định: ip-restriction-config)
configjsonCấu hình JSON chứa mode và ipList

Cấu trúc config:

typescript
{
  mode: 'blacklist' | 'whitelist',  // Chế độ hoạt động
  ipList: string                     // Danh sách IP/CIDR, phân cách bằng dấu xuống dòng hoặc dấu phẩy
}

Cấu hình Reverse Proxy ​

Khi DigiForce chạy sau reverse proxy (Nginx, Cloudflare, AWS ALB...), IP gốc của client nằm trong header X-Forwarded-For. Plugin đọc IP từ ctx.state.clientIp (được middleware extractClientIp xử lý trước).

Nginx ​

nginx
location / {
    proxy_pass http://localhost:13000;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Real-IP $remote_addr;
}

Cloudflare ​

Cloudflare sử dụng header CF-Connecting-IP. Đảm bảo DigiForce trust header này.

Log và giám sát ​

Plugin ghi log vào thư mục ip-restriction/ khi có IP bị chặn:

IP 203.0.113.5 is not allowed to access

Log bao gồm module, method, và IP address để dễ dàng debug.

Lưu ý quan trọng ​

  • Whitelist mode rất nguy hiểm nếu quên thêm IP admin — có thể bị khoá hoàn toàn
  • Thay đổi cấu hình có hiệu lực ngay lập tức (qua cache invalidation)
  • Plugin áp dụng cho tất cả API và giao diện web (trừ app:getLang)
  • ACL snippet pm.ip-restriction.ip-restriction-config kiểm soát quyền cấu hình
  • Nếu bị khoá ngoài, cần truy cập trực tiếp database để tắt plugin hoặc sửa cấu hình