Hướng dẫn cài đặt — License

Tổng quan

Plugin @digiforce-nc/plugin-license quản lý license cho instance DigiForce hiện tại. Plugin cung cấp cơ chế tạo yêu cầu license (license request), upload và xác minh license key, kiểm tra domain/IP binding, và theo dõi trạng thái license.

Yêu cầu

• Server DigiForce đang chạy
• License key hợp lệ (lấy từ nhà cung cấp hoặc từ License Manager)

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

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

Bước 2: Tạo yêu cầu license (License Request)

Trước khi nhận license, bạn cần tạo license request chứa thông tin server (fingerprint). Vào Settings → License và thực hiện:

Tạo request trực tiếp

Gọi action generateRequest — plugin thu thập thông tin server và trả về:

Thông tin	Mô tả
requestId	Mã yêu cầu duy nhất (nanoid)
serverFingerprint	Dấu vân tay server (duy nhất cho mỗi máy)
hostname	Tên máy chủ
os	Hệ điều hành
cpu	Thông tin CPU
macAddress	Địa chỉ MAC (nếu có)
machineId	Machine ID
isDocker	Có đang chạy trong Docker không
containerId / containerName	Thông tin container (nếu Docker)
domain	Domain của ứng dụng (từ APP_URL)
ip	Địa chỉ IP
nodeVersion	Phiên bản Node.js

Xuất file request

Gọi action exportRequest — plugin tạo file .lic (base64 encoded) chứa thông tin request. Gửi file này cho nhà cung cấp để nhận license key.

Bước 3: Upload license key

Sau khi nhận license key từ nhà cung cấp, upload vào hệ thống:

Kiểm tra binding

License có thể bị ràng buộc với:

Binding	Kiểm tra	Lỗi nếu không khớp
Domain binding (bindDomain)	Hostname trong APP_URL phải khớp với domain trong license	DOMAIN_MISMATCH
IP binding (bindIp)	IP request phải khớp với ip trong license	IP_MISMATCH

Bước 4: Kiểm tra trạng thái license

Gọi action validateLicense để xem thông tin license hiện tại:

Trường	Mô tả
name	Tên license
expiresAt	Ngày hết hạn
features	Danh sách tính năng được bật
status	Trạng thái: active, expired, revoked, pending
serverFingerprint	Fingerprint server đã gắn
bindDomain / domain	Domain binding
bindIp / ip	IP binding

Database Schema

Collection licenses

Trường	Kiểu	Mô tả
id	bigInt (PK)	ID tự tăng
name	string	Tên license
description	text	Mô tả
expiresAt	date	Ngày hết hạn
licenseKey	text (ẩn)	License key đã mã hoá
requestFile	text (ẩn)	Nội dung file request
serverFingerprint	string	Dấu vân tay server
bindDomain	boolean	Có ràng buộc domain không
domain	string	Domain được phép
bindIp	boolean	Có ràng buộc IP không
ip	string	IP được phép
features	text	Danh sách features (JSON)
status	string	Trạng thái: active / expired / revoked / pending
issuedBy	string	Người/tổ chức cấp license

API Actions

Action	Mô tả	Quyền
licenses:generateRequest	Tạo thông tin request license	loggedIn
licenses:exportRequest	Xuất file request .lic để tải về	loggedIn
licenses:uploadLicense	Upload và cài đặt license key	loggedIn
licenses:validateLicense	Kiểm tra trạng thái license hiện tại	loggedIn
licenses:removeLicense	Xoá license (file + database)	loggedIn

Lưu trữ license

License key được lưu tại 2 nơi:

1. File system: storage/apps/{appName}/license.key (hoặc path từ biến môi trường LICENSE_KEY_PATH)
2. Database: Collection licenses

Khi upload license mới, nếu đã có license cho cùng serverFingerprint, bản ghi sẽ được cập nhật thay vì tạo mới.

Biến môi trường

Biến	Mô tả
APP_URL	URL ứng dụng — dùng để kiểm tra domain binding
LICENSE_KEY_PATH	Đường dẫn tuỳ chỉnh cho file license.key

Lưu ý quan trọng

• License key có format signature.encrypted_data — nếu không đúng format sẽ bị từ chối
• Sau khi upload license, plugin gọi licenseManager.reload() để áp dụng ngay
• Xoá license (removeLicense) sẽ xoá cả file trên disk và bản ghi trong database
• Tất cả action yêu cầu người dùng đã đăng nhập (loggedIn)
• ACL snippet pm.plugin-license kiểm soát quyền truy cập