Câu hỏi thường gặp (FAQ) — License Manager

Câu hỏi chung

Plugin này dùng cho ai?

Plugin dành cho nhà phân phối phần mềm (vendor) — những người cần cấp phát license key cho khách hàng. Nếu bạn là khách hàng cần cài đặt license, hãy dùng plugin-license.

Quy trình cấp license hoạt động thế nào?

File request `.lic` chứa gì?

File request là JSON (hoặc base64-encoded JSON) chứa thông tin server khách hàng:

Trường	Mô tả
`serverFingerprint`	Dấu vân tay duy nhất của server
`hostname`	Tên máy chủ
`os`	Hệ điều hành
`cpu`	Thông tin CPU
`macAddress`	Địa chỉ MAC
`domain`	Domain ứng dụng (từ `APP_URL`)
`ip`	Địa chỉ IP server
`isDocker`	Đang chạy trong Docker hay không

License key được sinh ra có format gì?

License key có format signature.encrypted_data:

signature: Chữ ký số RSA — dùng để xác minh tính toàn vẹn
encrypted_data: Dữ liệu license đã mã hoá (tên, features, expiry, binding...)

Phía khách hàng cần public key tương ứng để xác minh chữ ký.

Có thể cấp nhiều license cho cùng một khách hàng không?

Có. Mỗi lần cấp tạo một bản ghi riêng trong bảng issuedLicenses. Tuy nhiên, phía khách hàng (plugin-license) chỉ dùng một license tại một thời điểm — upload license mới sẽ ghi đè license cũ cho cùng server fingerprint.

Cài đặt và cấu hình

Lỗi "PRIVATE_KEY_NOT_CONFIGURED" khi sinh license?

Plugin không tìm thấy file private key. Kiểm tra:

Biến môi trường LICENSE_SIGNING_PRIVATE_KEY_PATH đã được đặt
File tại đường dẫn đó tồn tại và có quyền đọc
File là RSA private key hợp lệ (PEM format, bắt đầu bằng -----BEGIN RSA PRIVATE KEY-----)

bash

# Kiểm tra biến môi trường
echo $LICENSE_SIGNING_PRIVATE_KEY_PATH

# Kiểm tra file tồn tại
ls -la $LICENSE_SIGNING_PRIVATE_KEY_PATH

# Kiểm tra format
head -1 $LICENSE_SIGNING_PRIVATE_KEY_PATH
# Kỳ vọng: -----BEGIN RSA PRIVATE KEY----- hoặc -----BEGIN PRIVATE KEY-----

Lỗi "Failed to read private key file" khi sinh license?

File private key không đọc được. Nguyên nhân phổ biến:

Quyền file: Process Node.js không có quyền đọc file. Chạy chmod 600 trên file key
Đường dẫn sai: Plugin hỗ trợ cả đường dẫn tuyệt đối và tương đối (so với process.cwd())
File bị hỏng: Mở file kiểm tra nội dung, đảm bảo là PEM format hợp lệ

Lỗi "INVALID_REQUEST_FILE" khi upload file request?

File request không đúng format. Kiểm tra:

Nội dung phải là JSON hợp lệ hoặc base64-encoded JSON
Nếu copy-paste, đảm bảo không bị thiếu ký tự hoặc thừa khoảng trắng
Thử mở file .lic bằng text editor để kiểm tra nội dung

Lỗi "Request file does not contain server fingerprint"?

File request thiếu trường serverFingerprint. Điều này xảy ra khi:

File request được tạo bởi phiên bản cũ của plugin-license
File bị chỉnh sửa thủ công và mất trường fingerprint
File không phải license request (nhầm file khác)

Sử dụng

Features dùng để làm gì?

Features là bảng key-value cho phép vendor giới hạn tính năng theo gói license:

Key	Ý nghĩa	Ví dụ
`type`	Loại license	`trial`, `professional`, `ultimate`
`collections`	Số collection tối đa	`100`
`users`	Số user tối đa	`50`
`datasources`	Số data source	`1`
`workflows`	Số workflow	`100`

Phía khách hàng, hệ thống đọc features để bật/tắt tính năng tương ứng.

Bind Domain và Bind IP là gì?

Đây là cơ chế ràng buộc license với môi trường cụ thể:

Binding	Tác dụng	Khi nào dùng
Bind Domain	License chỉ hoạt động trên domain chỉ định	Ngăn khách hàng dùng license trên domain khác
Bind IP	License chỉ hoạt động trên IP chỉ định	Ngăn chuyển license sang server khác

Khi không bật binding, license hoạt động trên bất kỳ server nào có fingerprint khớp.

Làm sao download license key đã cấp trước đó?

Vào Settings → License Manager → Issued Licenses, tìm license cần tải và nhấn nút Download. Plugin sẽ tải file license.key chứa license key.

Trạng thái license có tự cập nhật không?

Trên giao diện danh sách, nếu expiresAt đã qua thời điểm hiện tại, trạng thái tự động hiển thị expired (dù trong database vẫn lưu active). Đây chỉ là hiển thị phía client — vendor có thể cập nhật trạng thái thủ công trong database nếu cần.

Câu hỏi kỹ thuật

Plugin sử dụng thư viện nào để ký license?

Plugin sử dụng LicenseNative.create() từ @digiforce-nc/server. Hàm này nhận dữ liệu license, private key (PEM), và encryption key (tuỳ chọn), rồi trả về chuỗi signature.encrypted_data.

Có cần kết nối đến License Server bên ngoài không?

Không. Plugin hoạt động hoàn toàn local trên server vendor. License key được sinh bằng private key lưu trên disk, không cần kết nối bất kỳ dịch vụ bên ngoài nào.

ACL được cấu hình thế nào?

Plugin đăng ký ACL snippet pm.license-manager với quyền truy cập:

licenseManager:* — Tất cả action trên resource licenseManager
issuedLicenses:* — Tất cả action trên collection issuedLicenses

Tất cả action yêu cầu người dùng đã đăng nhập (loggedIn). Chỉ admin có quyền truy cập Settings mới thấy trang License Manager.

Dữ liệu license có được mã hoá trong database không?

License key lưu dạng plaintext trong cột licenseKey của bảng issuedLicenses. Tuy nhiên, bản thân license key đã được mã hoá (phần encrypted_data), nên dù bị lộ, không ai có thể đọc nội dung license mà không có encryption key.