ZL-LicenseServer 授权服务
「ZL-LicenseServer」是独立部署的 Docker 授权服务,默认仅监听宿主机
127.0.0.1:18931,供 HTTPS 反向代理使用,为插件提供授权码签发、设备绑定与在线验证能力。
✨ 功能特性
| 功能 | 说明 |
|---|---|
| 授权签发 | 创建授权码时可设置有效天数、设备数量上限与备注 |
| 设备限制 | 一个授权码可限制设备数量 |
| 生命周期管理 | 支持授权到期、停用、恢复与设备解绑 |
| 可视化管理后台 | 通过网页创建授权、查看授权状态、停用/恢复授权、查看/解绑设备以及查看审计日志 |
| 管理接口 | 提供 REST 管理接口,请求需携带 X-Admin-Key 请求头 |
| 管理脚本 | 服务器附带管理脚本,无需手工读取管理密钥即可完成日常管理 |
| 审计日志 | 记录授权管理操作,可供审计查询 |
🚀 部署指南
服务部署
服务以独立 Docker 容器方式部署,默认仅监听宿主机 127.0.0.1:18931,不直接对公网开放,公网访问由 HTTPS 反向代理转发。
反向代理
将 HTTPS 域名代理到:
http://127.0.0.1:18931健康检查端点为 GET /health,部署完成后请先通过该端点确认服务状态。
可视化管理后台
- 访问
https://你的授权域名/manage; - 使用服务器文件
/opt/zl-keyword-license/admin.key中的管理密钥登录; - 登录后即可创建授权、查看授权状态、停用/恢复授权、查看/解绑设备以及查看审计日志。
管理密钥的保存方式
管理密钥仅保存在当前浏览器标签页的 sessionStorage 中,不会写入网页源码,也不会长期保存在浏览器中;关闭标签页后需重新读取密钥登录。
🧭 使用指南
管理脚本
服务器已附带管理脚本,不需要手工读取管理密钥:
cd /opt/zl-keyword-license
./license-admin.sh create 30 1 "客户备注"
./license-admin.sh list
./license-admin.sh devices <授权ID>
./license-admin.sh revoke <授权ID>管理接口
所有管理请求必须包含请求头:X-Admin-Key。
| 方法与路径 | 用途 |
|---|---|
POST /admin/licenses | 创建授权码,正文示例 {"days":30,"maxDevices":1,"note":"客户A"} |
GET /admin/licenses | 查询授权列表 |
POST /admin/licenses/{id}/revoke | 停用授权 |
POST /admin/licenses/{id}/enable | 恢复授权 |
GET /admin/licenses/{id}/devices | 查看授权绑定的设备列表 |
POST /admin/licenses/{id}/devices/{deviceId}/revoke | 解绑指定设备 |
GET /admin/audit | 查看审计日志 |
🔒 安全配置
服务在设计与部署层面包含以下安全机制,运维时请保持这些配置不被放宽:
- 授权码只保存带服务端 pepper 的 SHA-256 摘要;
- 一个授权码可限制设备数量;
- ECDSA P-256 私钥只在服务器数据目录生成和保存;
- 插件只内置公钥,验证 30 分钟短期签名凭证;
- 管理接口使用独立高强度
X-Admin-Key; - 公共激活和续租接口有限流;
- 容器使用非 root 用户、只读根文件系统和独立网络。
管理密钥与授权码
- 管理密钥保存在服务器文件
/opt/zl-keyword-license/admin.key中,请严格控制该文件的访问权限; - 授权码仅在创建响应中返回一次,请创建后立即妥善保存。
❓ 常见问题
管理密钥从哪里获取?
管理密钥保存在服务器文件 /opt/zl-keyword-license/admin.key 中,登录可视化管理后台时使用。该密钥仅保存在当前浏览器标签页的 sessionStorage,不会写入网页源码或长期保存在浏览器中。
授权码丢失了怎么办?
授权码仅在创建响应中返回一次,服务端只保存带 pepper 的 SHA-256 摘要。请在创建授权时立即保存授权码,避免遗失。
如何解绑设备?
可通过可视化管理后台查看并解绑设备;也可在服务器上执行 ./license-admin.sh devices <授权ID> 查看设备列表,或调用 POST /admin/licenses/{id}/devices/{deviceId}/revoke 接口解绑指定设备。
如何确认授权服务运行正常?
通过 GET /health 端点进行健康检查。
插件端如何完成授权验证?
插件只内置公钥,验证服务端签发的 30 分钟短期签名凭证;授权支持到期、停用和设备解绑控制。
🆘 获取帮助
- 部署或使用中遇到问题时,请先通过
GET /health端点确认服务状态; - 授权管理相关操作请优先使用服务器附带的管理脚本或可视化管理后台;
- 其他问题请通过 ZL 插件的官方发布与支持渠道反馈。
