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

Tổng quan

Plugin @digiforce-nc/plugin-license-manager là công cụ dành cho nhà phân phối phần mềm (vendor), cho phép cấp phát license key cho khách hàng từ file license request. Trong khi plugin-license dùng ở phía khách hàng (nhận và cài đặt license), plugin này dùng ở phía vendor (tạo và quản lý license đã cấp).

Phân biệt hai plugin

Tiêu chí	`plugin-license`	`plugin-license-manager`
Vai trò	Phía khách hàng — nhận và cài đặt license	Phía vendor — cấp phát license key
Dùng cho	Mọi instance DigiForce cần license	Nhà phân phối phần mềm
Chức năng chính	Tạo request, upload license, kiểm tra trạng thái	Nhận request file, sinh license key có chữ ký số

Yêu cầu trước khi cài đặt

Server DigiForce đang chạy (đây là server của vendor)
Private key cho việc ký license (RSA PEM format)
Biến môi trường LICENSE_SIGNING_PRIVATE_KEY_PATH trỏ đến file private key

Bước 1: Chuẩn bị RSA Key Pair

License key được ký bằng chữ ký số RSA. Vendor cần tạo cặp key:

bash

# Tạo private key (giữ bí mật trên server vendor)
openssl genrsa -out license-private.pem 2048

# Tạo public key (đưa cho khách hàng cài vào instance)
openssl rsa -in license-private.pem -pubout -out license-public.pem

Cấu hình biến môi trường trên server vendor:

bash

# Đường dẫn đến file private key (tuyệt đối hoặc tương đối)
LICENSE_SIGNING_PRIVATE_KEY_PATH=./storage/license-private.pem

# Encryption key cho dữ liệu license (tuỳ chọn)
LICENSE_ENCRYPTION_KEY=your-secret-encryption-key

Bảo mật

File private key cho phép tạo license hợp lệ. Không bao giờ chia sẻ file này cho bất kỳ ai ngoài hệ thống vendor. Chỉ public key mới được phân phối.

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

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

Khi kích hoạt, plugin tạo:

Collection issuedLicenses để lưu lịch sử license đã cấp
Resource licenseManager với action issueLicense
Hai trang Settings: Issue License và Issued Licenses

Bước 3: Cấp phát license cho khách hàng

Quy trình tổng thể

Thao tác trên giao diện

Vào Settings → License Manager → Issue License:

Upload file request (.lic): Dán nội dung hoặc upload file. Plugin tự nhận dạng base64-encoded JSON hoặc plain JSON
Khi parse thành công, thông tin server fingerprint, hostname, domain, IP hiển thị trong alert xanh
Điền thông tin license:

Trường	Mô tả	Bắt buộc
License name	Tên gợi nhớ (VD: "ACME Corp — Production")	✅
Expires at	Ngày hết hạn (mặc định: 30 ngày từ hôm nay)	✅
Bind to domain	Ràng buộc license với domain cụ thể	❌
Domain	Domain cho phép (tự lấy từ request nếu có)	❌
Bind to IP	Ràng buộc license với IP cụ thể	❌
IP address	IP cho phép (tự lấy từ request nếu có)	❌
Features	Bảng key-value giới hạn tính năng	❌

Nhấn Generate License để sinh license key
Download file license.key hoặc copy nội dung

Features mặc định

Plugin cung cấp bảng features dạng key-value:

Key	Giá trị mẫu	Mô tả
`type`	`trial`, `professional`, `ultimate`...	Loại license
`collections`	`100`	Giới hạn số collection
`users`	`100`	Giới hạn số user
`datasources`	`1`	Giới hạn số data source
`workflows`	`100`	Giới hạn số workflow

Vendor có thể thêm/xoá feature tuỳ ý bằng nút Add Feature.

Bước 4: Quản lý license đã cấp

Vào Settings → License Manager → Issued Licenses để xem danh sách license đã cấp:

Cột	Mô tả
Name	Tên license
Hostname	Hostname server khách hàng
Issued At	Thời điểm cấp
Expires At	Ngày hết hạn (đỏ nếu đã quá hạn)
Status	`active` / `expired` / `revoked`
Fingerprint	Server fingerprint (hiển thị rút gọn)
Actions	View chi tiết, Download file license.key

Database Schema

Collection `issuedLicenses`

Trường	Kiểu	Mô tả
`id`	`bigInt` (PK)	ID tự tăng
`name`	`string`	Tên license
`description`	`text`	Mô tả
`issuedAt`	`date`	Thời điểm cấp
`expiresAt`	`date`	Ngày hết hạn
`licenseKey`	`text`	License key đã sinh (signature.encrypted_data)
`requestFile`	`text`	Nội dung file request gốc
`serverFingerprint`	`string`	Dấu vân tay server khách hàng
`hostname`	`string`	Hostname 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`	Features (JSON string)
`status`	`string`	Trạng thái: `active` / `expired` / `revoked`
`issuedBy`	`string`	Người cấp (username admin)

API Actions

Action	Mô tả	Quyền
`licenseManager:issueLicense`	Sinh license key từ request file	`loggedIn`
`issuedLicenses:list`	Danh sách license đã cấp	`loggedIn`
`issuedLicenses:get`	Chi tiết một license	`loggedIn`

Biến môi trường

Biến	Mô tả	Bắt buộc
`LICENSE_SIGNING_PRIVATE_KEY_PATH`	Đường dẫn file RSA private key để ký license	✅
`LICENSE_ENCRYPTION_KEY`	Key mã hoá dữ liệu license (tuỳ chọn, tăng bảo mật)	❌

Lưu ý quan trọng

Plugin sử dụng LicenseNative.create() từ @digiforce-nc/server để sinh license key với chữ ký số
License key có format signature.encrypted_data — phía khách hàng cần public key tương ứng để xác minh
File request .lic chứa thông tin server dưới dạng base64-encoded JSON hoặc plain JSON
Nếu thiếu biến LICENSE_SIGNING_PRIVATE_KEY_PATH, action issueLicense trả lỗi PRIVATE_KEY_NOT_CONFIGURED
ACL snippet pm.license-manager kiểm soát quyền truy cập
Tất cả action yêu cầu người dùng đã đăng nhập (loggedIn)