WuYongJie/flnxi-Wu
WuYongJie/flnxi-Wu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
flnxi-Wu/docs/许可证服务接入说明.md

7.8 KiB
Raw Blame History

许可证服务接入说明

本文档只说明当前项目与 license-server 的真实接入方式。

1. 必填环境变量

主应用至少需要：

LICENSE_SERVER_URL=https://your-license-server.example.com
LICENSE_PROJECT_CODE=flnxi-sucai
LICENSE_REQUEST_SIGNING_SECRET=replace-with-same-secret-on-license-server
LICENSE_PUBLIC_KEY=<license-server-rsa-public-key>
LOCAL_ENCRYPTION_KEY=<generate-a-32-char-or-longer-local-key>

含义：

  • LICENSE_SERVER_URL 许可证服务地址
  • LICENSE_PROJECT_CODE 当前主应用所属项目编码，必须和 license-server 主库中的 projects.code 一致
  • LICENSE_REQUEST_SIGNING_SECRET 主应用和许可证服务共享的 HMAC 签名密钥，至少 32 字符，两边必须一致；不要写入 Git 或对外文档
  • LICENSE_PUBLIC_KEY 许可证服务签发许可证时使用的 RSA 公钥，主应用本地验签和缓存恢复会用到
  • LOCAL_ENCRYPTION_KEY 主应用本地加密保存许可证缓存时使用的密钥，至少 32 字符，不能使用示例值

Node Agent 如果需要版本检查，也必须配置同样两项：

LICENSE_SERVER_URL=https://your-license-server.example.com
LICENSE_PROJECT_CODE=flnxi-sucai

Go Agent 目前走的是另一条现状链路，文档和脚本还没有和 Node Agent 完全统一；接入时不要默认它也已经接好了同一套 LICENSE_SERVER_URL / LICENSE_PROJECT_CODE 版本检查流程。

license-server 自身还需要配置付费模块的镜像站位置：

PREMIUM_MODULE_REGISTRY_BASE=registry.example.com/flnxi/premium
PREMIUM_MODULE_VERSION=1.0.0

如某个模块要单独指定镜像，可使用 PREMIUM_MODULE_CUSTOM_TEMPLATES_CORE_IMAGE、PREMIUM_MODULE_INTRANET_PENETRATION_CORE_IMAGE 这类变量覆盖。原则是：模块核心本体在镜像站，验证服务器只发授权清单和小型凭证。

2. 联调入口规则

历史文档里曾记录过内部联调 IP、测试机连通性和临时域名状态。那些信息属于一次性现场快照，不是当前项目默认事实来源，也不应写入客户交付环境。

正式部署或联调时，必须重新确认：

  • 当前真实 LICENSE_SERVER_URL
  • 当前真实 LICENSE_PROJECT_CODE
  • 主应用和许可证服务是否使用同一个 LICENSE_REQUEST_SIGNING_SECRET
  • license-server 后台是否存在对应项目
  • 主应用所在机器到许可证服务的网络连通性
  • 证书、域名、反向代理是否匹配当前入口

3. 当前公开接口规则

现在所有真正可用的 license-server 公开接口都必须带项目编码：

POST /api/license/{projectCode}/activate
POST /api/license/{projectCode}/verify
POST /api/license/{projectCode}/heartbeat
POST /api/license/{projectCode}/register-free
POST /api/license/{projectCode}/premium-modules
POST /api/license/{projectCode}/premium-modules/{moduleId}
POST /api/license/{projectCode}/generate

GET  /api/version/{projectCode}/check
GET  /api/version/{projectCode}/agent

旧的无项目接口：

/api/license/activate
/api/license/verify
/api/license/heartbeat
/api/license/register-free
/api/license/generate
/api/version/check
/api/version/agent

现在统一返回 410，不能再继续使用。

4. 主应用当前调用方式

主应用本地仍然暴露自己的代理接口：

/api/license/activate
/api/license/activate-free
/api/license/verify
/api/license/heartbeat
/api/license/check
/api/license/info

其中：

  • activate、activate-free、verify、heartbeat 会根据 LICENSE_PROJECT_CODE 转发到远端项目维度接口。
  • activate、activate-free、verify、heartbeat 转发到远端前会加入 timestamp、nonce 和 HMAC signature；远端会拒绝签名缺失、签名错误、过期和重复 nonce 请求。
  • activate、activate-free、verify、heartbeat 返回的签名许可证必须包含 projectCode、licenseKey、instanceId 和 fingerprintHash；主应用保存和读取本地许可证时会核对这些绑定字段，缺少绑定字段的旧许可证需要重新激活。
  • activate、verify、heartbeat 在付费许可证保存或续证成功后会尝试同步 premium-modules 付费模块授权清单和对应授权凭证；免费版会跳过，不访问远端模块接口。
  • check 用于在本地许可证缓存存在时恢复激活状态，会先读取并验签本地许可证。
  • info 用于读取当前许可证类型、用量和功能开关。

主应用内部已经不会再直接访问无项目的 license-server 路径，而是会根据 LICENSE_PROJECT_CODE 转发到：

${LICENSE_SERVER_URL}/api/license/${LICENSE_PROJECT_CODE}/...

所以主应用部署时，LICENSE_PROJECT_CODE 现在是必填项。

补充：

  • 远端 POST /api/license/{projectCode}/generate 是付费激活码生成接口，当前要求 X-API-Key、timestamp 和 sign，不应被普通前端直接调用。
  • 远端 POST /api/license/{projectCode}/premium-modules 是付费模块清单接口，要求同一套 HMAC 请求签名；免费版、禁用、过期或硬件指纹明显不匹配会被拒绝。
  • 远端 POST /api/license/{projectCode}/premium-modules/{moduleId} 是单个付费模块授权凭证接口，要求 premium-module-download HMAC 请求签名，并复查许可证状态、硬件指纹和模块权限。
  • premium-modules 返回签名 manifest（模块清单），每个模块会带镜像站上的模块本体地址、实例绑定信息、授权凭证大小和 SHA256；主应用随后只获取实例绑定的小型授权凭证，校验大小和 SHA256 后再本地加密缓存。
  • 付费模块核心本体应放在镜像站或等价的私有制品仓库，验证服务器只负责授权判断、签名清单和授权凭证，不承担大文件下载站职责。
  • 主应用的自定义模板和内网穿透服务端入口已经依赖本地已验签 manifest 和对应授权凭证；许可证功能开关开启但没有有效授权凭证时，服务端仍会拒绝。
  • activate / verify / heartbeat / register-free / premium-modules / premium-modules/{moduleId} 当前会校验请求 HMAC 签名；返回的许可证、付费模块清单和授权凭证必须通过签名、hash、大小、租约、实例和许可证类型检查后才能缓存或放行。

5. 后台管理入口

license-server 后台现在按项目维度工作：

/admin/select-project
/admin/{projectCode}
/admin/{projectCode}/licenses
/admin/{projectCode}/alerts
/admin/{projectCode}/versions
/admin/{projectCode}/customers
/admin/{projectCode}/api-keys

说明：

  • 普通管理员只能进入被分配的项目
  • 超级管理员可以进入所有项目
  • 超级管理员还可以在项目维度管理该项目的 API Key

旧的无项目后台页现在只做跳转或废弃提示，不再承载真实管理逻辑。

6. 接入前检查

上线前至少确认这 5 项：

  1. license-server 主库里已存在目标项目，且 projects.code = LICENSE_PROJECT_CODE
  2. 该项目对应的项目库连接配置正确
  3. 主应用 .env 已配置 LICENSE_SERVER_URL、LICENSE_PROJECT_CODE、LICENSE_REQUEST_SIGNING_SECRET、LICENSE_PUBLIC_KEY 和 LOCAL_ENCRYPTION_KEY
  4. Node Agent 如启用版本检查，也已配置相同的远端通信两项
  5. 不再调用任何旧的无项目公开接口

7. 推荐联调方式

可以按这个顺序联调：

  1. 先在 license-server 后台进入 /admin/select-project
  2. 选中目标项目，确认项目后台数据正常
  3. 再从主应用激活页走一次激活
  4. 最后检查主应用的验证与心跳是否正常

如果主应用激活失败，优先检查：

  • LICENSE_PROJECT_CODE 是否写错
  • LICENSE_REQUEST_SIGNING_SECRET 是否和许可证服务配置一致
  • 目标项目是否已禁用
  • license-server 是否仍被旧地址或旧接口调用