Giao diện
@digiforce-nc/plugin-ip-restriction
Plugin giới hạn truy cập theo IP — cho phép hoặc chặn truy cập dựa trên địa chỉ IP của client, bảo vệ hệ thống khỏi truy cập trái phép.
Plugin này làm gì?
Trong môi trường doanh nghiệp, không phải mọi IP đều được phép truy cập hệ thống. Plugin này cung cấp whitelist (chỉ cho phép IP trong danh sách) và blacklist (chặn IP cụ thể). Middleware kiểm tra IP của mọi request trước khi xử lý.
Cơ chế hoạt động
Tính năng chính
| # | Tính năng | Mô tả |
|---|---|---|
| 1 | Whitelist mode | Chỉ cho phép IP trong danh sách trắng |
| 2 | Blacklist mode | Chặn IP trong danh sách đen |
| 3 | CIDR support | Hỗ trợ dải IP (VD: 10.0.0.0/24) |
| 4 | IPv6 | Hỗ trợ cả IPv4 và IPv6 |
| 5 | Proxy-aware | Đọc IP thật từ X-Forwarded-For khi qua reverse proxy |
| 6 | Per-role rules | Giới hạn IP khác nhau cho từng role |
API endpoints
| Endpoint | Mô tả |
|---|---|
ipRestriction:list | Danh sách rule IP hiện tại |
ipRestriction:create | Thêm rule mới (whitelist/blacklist) |
ipRestriction:update | Cập nhật rule |
ipRestriction:delete | Xóa rule |
ipRestriction:config | Cấu hình chế độ (whitelist/blacklist) |
Database
| Bảng | Mô tả |
|---|---|
ipRules | Danh sách rule IP (address/CIDR, type, roleName) |
ipRestrictionConfig | Cấu hình mode (whitelist/blacklist), enabled |
Thành phần client
| Thành phần | Mô tả |
|---|---|
IPRuleList | Danh sách rule IP với thêm/sửa/xóa |
IPRuleForm | Form nhập IP hoặc CIDR range |
IPModeSwitch | Chuyển đổi giữa whitelist và blacklist mode |
CurrentIPDisplay | Hiển thị IP hiện tại của admin (tránh tự lock) |
Dependencies
| Package | Vai trò |
|---|---|
@digiforce-nc/server | Server framework — middleware |
@digiforce-nc/database | Database ORM |
@digiforce-nc/client | Client UI framework |
ip-range-check | Kiểm tra IP thuộc CIDR range |
Lưu ý triển khai
- Khi bật whitelist mode, luôn thêm IP admin trước để tránh tự lock
- Nếu qua reverse proxy (nginx), cần cấu hình trusted proxy để đọc IP thật
- Rule thay đổi có hiệu lực ngay lập tức (không cần restart)