regInfo.exe 许可证校验流程.md 27 KB

regInfo.exe 许可证校验流程

本文引用的文件

  • LicenseUtil.java
  • LicenseFilter.java
  • PathConst.java
  • SystemService.java
  • SystemController.java
  • SystemInfo.java
  • LicenseErrorEnum.java
  • login.ts
  • authorization/index.vue
  • AuthorizationInfoModal.vue
  • useWatermark.ts
  • AppLogo.vue
  • license.ts
  • readme.md
  • AI_AGENT.md

目录

  1. 简介
  2. 项目结构与 regInfo.exe 部署位置
  3. regInfo.exe 命令行规范与返回值约定
  4. 后端调用链:从接口到本机进程
  5. 前端集成:机器码、授权信息与授权页
  6. 授权状态判定与系统行为
  7. 展示位置与水印渲染机制
  8. 错误处理与回退策略
  9. 部署、首次激活与更新许可证操作示例
  10. 依赖关系图
  11. 常见问题排查
  12. 结论

简介

本文说明本仓库中 regInfo.exe 在清鉴平台中的角色、部署位置、命令用法,以及后端如何调用它、前端如何获取机器码和授权信息、如何判断授权是否有效、已过期或即将到期,并把单位信息和授权状态展示到界面和水印中。

核心要点如下:

  • regInfo.exe 是运行期本地工具,负责读取并校验 license.xlts 授权文件、输出机器码和字段值。
  • 后端通过 LicenseUtil 以子进程方式调用 regInfo.exe,并将结果缓存 60 秒。
  • 前端通过 /sys/info、/sys/code、/sys/checkAuth 等接口间接使用 regInfo.exe。
  • 授权信息最终在前端授权页面、授权信息弹窗、应用标题标签和全局水印中体现。

[本节未直接分析具体代码行]

项目结构与 regInfo.exe 部署位置

regInfo.exe 不是源码,而是运行时随产品分发的本机工具。根据仓库说明,它位于仓库根下的 cmd/lib 区域;后端实际加载路径由 PathConst 决定,最终落在 QingJian 工作空间的 license 目录下。

graph TB
    Root["仓库根"] --> QingJian["QingJian 运行期工作空间"]
    Root --> CmdLib["cmd / lib(分发 regInfo.exe)"]
    QingJian --> LicenseDir["QingJian/license"]
    LicenseDir --> RegInfoWin["regInfo.exe"]
    LicenseDir --> RegInfoLinux["regInfo"]
    LicenseDir --> LicenseFile["license.xlts"]

图表来源

  • PathConst.java:16-26
  • PathConst.java:28-36
  • AI_AGENT.md:1-40

关键路径常量含义: | 常量 | 含义 | |---|---| | ROOT_PATH | user.dir,即启动时工作目录 | | RUN_QINGJIAN_PATH | <用户工作目录>/QingJian | | LICENSE_PATH | QingJian/license | | ACTIVATOR_PATH_WIN | QingJian/license/regInfo.exe | | ACTIVATOR_PATH_LINUX | QingJian/license/regInfo | | LICENSE_PATH_FILE | QingJian/license/license.xlts |

章节来源

  • PathConst.java:16-36
  • AI_AGENT.md:20-40

regInfo.exe 命令行规范与返回值约定

根据仓库文档中的激活说明,regInfo.exe 提供以下能力:

命令 作用 典型参数
machinecode 获取当前设备的唯一机器码 无
read licensefile 读取并显示授权文件中的所有字段 licensefile 为 .xlts 文件路径
-f licensefile -field 显示授权文件中指定字段 字段包括 name、machinecode、phone、unit、authdatetime、over、update
-f licensefile -verify 校验授权有效性 返回一个数字表示校验结果

字段说明:

  • name:客户名称。
  • machinecode:机器码。
  • phone:手机号。
  • unit:单位。
  • authdatetime:授权时间。
  • over / overdatetime:过期时间。
  • updatedatetime:更新时间。

授权校验返回码: | 返回码 | 含义 | |---|---| | 0 | 注册文件有效 | | 10001 | 授权文件无效 | | 10002 | 授权已过期 | | 10004 | 机器码不匹配 |

后端在调用 -verify 时还额外处理了 10003,用于表示机器码不匹配的情况。

需要注意:

  • 文档中列出的是 10004,但后端分支对 10003 做了专门映射;两者都应视为“机器码不匹配”类错误。
  • 除 0 以外的非预期返回码会被后端当作通用未授权错误。

章节来源

  • readme.md:52-76
  • LicenseUtil.java:52-79
  • LicenseErrorEnum.java:11-44

后端调用链:从接口到本机进程

后端对 regInfo.exe 的调用集中在三个层次:

  1. 控制器层:暴露 /sys/info、/sys/code、/sys/noNet、/sys/checkAuth 等接口。
  2. 服务层:封装离线授权、机器码获取、数据库写入等业务逻辑。
  3. 工具层:通过 LicenseUtil 启动本机进程执行 regInfo.exe。

    sequenceDiagram
    participant Client as "前端"
    participant Controller as "SystemController"
    participant Service as "SystemService"
    participant Util as "LicenseUtil"
    participant OS as "操作系统进程"
    participant Tool as "regInfo.exe"
    
    Client->>Controller: GET /sys/code
    Controller->>Service: machineCode()
    Service->>Util: exec("regInfo.exe machinecode")
    Util->>OS: ProcessBuilder.start()
    OS-->>Tool: 启动 regInfo.exe
    Tool-->>OS: 标准输出机器码
    OS-->>Util: 读取 stdout/stderr
    Util-->>Service: ExeCmdDTO(code=0, msg=机器码)
    Service-->>Controller: 机器码字符串
    Controller-->>Client: Result{data=机器码}
    

图表来源

  • SystemController.java:78-90
  • SystemService.java:128-145
  • LicenseUtil.java:91-113

授权校验主流程

授权校验的主入口是 checkAuthStatus()。其核心流程如下:

flowchart TD
    Start["进入 checkAuthStatus"] --> CheckCache["检查 60 秒缓存"]
    CheckCache -->|命中| ReturnCache["返回缓存状态"]
    CheckCache -->|未命中| CheckFile["检查 license.xlts 是否存在"]
    CheckFile -->|不存在| ReturnNoFile["返回授权文件不存在"]
    CheckFile -->|存在| RunVerify["执行 regInfo.exe -f license.xlts -verify"]
    RunVerify --> ParseCode{"解析返回码"}
    ParseCode -->|0| ReturnOk["返回授权成功"]
    ParseCode -->|10001| ReturnInvalid["返回授权文件无效"]
    ParseCode -->|10002| ReturnExpired["返回授权已过期"]
    ParseCode -->|10003| ReturnMismatch["返回机器码不匹配"]
    ParseCode -->|其他| ReturnUnknown["返回通用未授权错误"]
    ReturnOk --> CacheAndReturn["写入缓存并返回"]
    ReturnInvalid --> CacheAndReturn
    ReturnExpired --> CacheAndReturn
    ReturnMismatch --> CacheAndReturn
    ReturnUnknown --> CacheAndReturn
    ReturnNoFile --> CacheAndReturn

图表来源

  • LicenseUtil.java:37-79

关键实现细节:

  • 校验结果有 60 秒 TTL 缓存,避免每次请求都拉起子进程。
  • 如果 license.xlts 不存在,直接返回“授权文件不存在”。
  • 子进程的标准输出和标准错误分别用虚拟线程异步读取,最多保留前 10 行。
  • Windows 下通过 cmd.exe /c 执行命令;Linux 下通过 sh -c 执行。

章节来源

  • LicenseUtil.java:37-163

离线授权流程

当用户在前端上传 .xlts 授权文件时,后端执行以下步骤:

  1. 校验上传文件非空且后缀为 .xlts。
  2. 将文件覆盖写入 QingJian/license/license.xlts。
  3. 非 Windows 环境下对授权文件执行权限修正。
  4. 再次调用 checkAuthStatus() 验证新授权文件。
  5. 若校验成功,读取授权信息并写入 system_info 表。
  6. 返回成功响应。

    sequenceDiagram
    participant Frontend as "前端授权页"
    participant LoginApi as "offlineAuthorizationApi"
    participant Controller as "SystemController.noNet"
    participant Service as "SystemService.noNet"
    participant Util as "LicenseUtil"
    participant DB as "system_info 表"
    
    Frontend->>LoginApi: 上传 .xlts 文件
    LoginApi->>Controller: POST /sys/noNet
    Controller->>Service: noNet(file)
    Service->>Service: 校验文件名与后缀
    Service->>Service: 写入 license.xlts
    Service->>Util: checkAuthStatus()
    Util->>Util: 执行 -verify
    Util-->>Service: CheckAuthStatus
    Service->>Service: 读取授权字段
    Service->>DB: saveOrUpdate(SystemInfo)
    Service-->>Frontend: 授权成功
    

图表来源

  • login.ts:116-139
  • SystemController.java:96-108
  • SystemService.java:147-190

章节来源

  • SystemService.java:128-190
  • SystemController.java:96-108
  • login.ts:116-139

前端集成:机器码、授权信息与授权页

前端并不直接调用 regInfo.exe,而是通过后端提供的 REST 接口完成所有与本机工具相关的操作。

主要接口

前端 API 后端路径 用途
authorizationInfoApi GET /sys/info 获取授权信息、单位、剩余天数、过期时间
machineCodeApi GET /sys/code 获取当前设备机器码
offlineAuthorizationApi POST /sys/noNet 上传 .xlts 授权文件进行离线授权
checkAuthApi GET /sys/checkAuth 检查当前授权状态,用于授权拦截判断
healthApi GET /sys/health 健康检查,不参与授权逻辑

机器码获取流程

  1. 用户在授权页点击“获取机器码”。
  2. 前端调用 machineCodeApi()。
  3. 后端调用 SystemService.machineCode()。
  4. 非 Windows 环境先执行权限修正。
  5. 调用 regInfo.exe machinecode。
  6. 成功后返回机器码;失败时返回“获取机器码失败”。
  7. 前端提示复制成功或直接展示机器码。

    sequenceDiagram
    participant User as "用户"
    participant AuthPage as "authorization/index.vue"
    participant Api as "machineCodeApi"
    participant SysApi as "/sys/code"
    participant Svc as "SystemService"
    participant LUtil as "LicenseUtil"
    participant Tool as "regInfo.exe"
    
    User->>AuthPage: 点击“获取机器码”
    AuthPage->>Api: GET /sys/code
    Api->>SysApi: 发起 HTTP 请求
    SysApi->>Svc: machineCode()
    Svc->>LUtil: exec("regInfo.exe machinecode")
    LUtil->>Tool: 启动本机进程
    Tool-->>LUtil: 输出机器码
    LUtil-->>Svc: code=0 + 机器码
    Svc-->>SysApi: 机器码字符串
    SysApi-->>Api: 返回数据
    Api-->>AuthPage: 展示机器码
    

图表来源

  • authorization/index.vue:470-520
  • login.ts:94-100
  • SystemService.java:128-145
  • LicenseUtil.java:91-113

授权信息获取流程

前端在授权信息弹窗和登录页授权摘要中都会使用 /sys/info。后端从 system_info 表查询最新记录,并计算剩余天数。

后端字段 前端展示字段 含义
clientNo 客户编号 客户编号
unit 所属单位 授权单位
phone 联系电话 联系方式
machinecode 机器码 绑定设备标识
authdatetime 授权时间 授权文件生成时间
overdatetime 授权到期 过期时间
activeDateTime 激活时间 本次导入激活时间
remainingDate 剩余天数 后端计算后附加字段

章节来源

  • login.ts:86-100
  • SystemController.java:70-90
  • SystemService.java:100-145
  • SystemInfo.java:13-71

授权状态判定与系统行为

授权状态主要由前端基于后端返回的过期时间和消息判断。

状态分类

状态 判定条件 前端表现
正式授权 overdatetime 等于特殊长期值 显示“正式授权”,剩余期限显示“长期”
试用授权 有有效期但不是长期值 显示“试用授权”,剩余天数按日期计算
已过期 过期时间早于当前时间 显示“已过期”,并提示重新导入授权文件
未知 没有有效过期时间 显示“授权信息”,状态区显示未知样式

前端状态逻辑

前端工具函数 license.ts 提供:

  • getAuthorizationExpirationTime:解析过期时间。
  • isAuthorizationExpired:判断是否已过期。
  • getAuthorizationExpiredMessage:生成过期提示文案。
  • isFormalAuthorization:判断是否为长期正式授权。
  • getAuthorizationLabel:生成“试用”或空标签。
  • extractAuthorizationCache:从接口响应中提取单位、过期时间和授权标签。

    flowchart TD
    Input["授权过期时间"] --> Normalize["标准化文本"]
    Normalize --> IsLong{"是否长期正式授权"}
    IsLong -->|是| Formal["正式授权"]
    IsLong -->|否| HasDate{"是否有可解析日期"}
    HasDate -->|否| Unknown["未知状态"]
    HasDate -->|是| Compare{"当前时间是否晚于到期时间"}
    Compare -->|是| Expired["已过期"]
    Compare -->|否| Trial["试用授权"]
    

图表来源

  • license.ts:1-124
  • AuthorizationInfoModal.vue:230-340

后端剩余天数计算

后端在 SystemService.info() 中计算剩余天数:

  • 查询最新一条 system_info 记录。
  • 如果 overdatetime 不为空,则计算今天到过期日的天数。
  • 剩余天数至少为 0。
  • 将 remainingDate 附加到返回对象中。

章节来源

  • license.ts:1-124
  • AuthorizationInfoModal.vue:230-340
  • SystemService.java:100-125

展示位置与水印渲染机制

授权信息会在多个前端位置展示:

授权信息弹窗

AuthorizationInfoModal.vue 是查看授权详情的主要入口。它展示:

  • 授权状态卡片:正式授权、试用授权、已过期。
  • 剩余天数或长期标识。
  • 客户编号、单位、电话。
  • 授权类型、激活时间、授权时间、授权到期。
  • 机器码及复制按钮。
  • 后端返回的提示消息。

开发环境下如果没有真实授权数据,会切换到演示模式,支持模拟正式、试用、已过期三种状态。

章节来源

  • AuthorizationInfoModal.vue:1-200
  • AuthorizationInfoModal.vue:200-789

授权页登录卡片

authorization/index.vue 在登录态下会展示授权摘要,包括:

  • 授权单位。
  • 授权到期时间。
  • 机器码获取与复制。
  • 离线授权步骤。
  • 授权失败时的警告消息。

章节来源

  • authorization/index.vue:200-260
  • authorization/index.vue:470-600

应用标题授权标签

AppLogo.vue 会从用户存储中读取 authorizationLabel,并在应用 Logo 标题旁显示授权标签。

  • “试用”标签使用红色样式。
  • 非试用标签使用蓝色样式。
  • 该标签来自 extractAuthorizationCache 的结果。

章节来源

  • AppLogo.vue:1-100
  • license.ts:96-124

水印渲染机制

水印由 useWatermark.ts 提供,核心机制如下:

  1. 创建不可点击的水印 DOM 节点。
  2. 使用 Canvas 把水印文字绘制成 Base64 图片。
  3. 将水印作为背景重复铺满目标容器。
  4. 监听容器尺寸变化,动态更新宽高。
  5. 使用 MutationObserver 监控 DOM 变更,防止水印被删除或篡改。
  6. 组件卸载时清理监听器和 DOM。

    flowchart TD
    Init["调用 useWatermark"] --> CreateNode["创建水印 div"]
    CreateNode --> DrawCanvas["Canvas 绘制水印文字"]
    DrawCanvas --> SetBackground["设置背景图为 Base64 图片"]
    SetBackground --> AppendDom["插入目标元素"]
    AppendDom --> ObserveDOM["监听 DOM 变动"]
    ObserveDOM --> Resize["监听窗口尺寸变化"]
    Resize --> UpdateBg["更新背景尺寸"]
    ObserveDOM --> PreventTamper["检测删除或属性修改并重写水印"]
    

图表来源

  • useWatermark.ts:1-200

注意:当前分析的代码中,水印工具是通用基础设施,授权模块通过它渲染水印文本,但授权内容本身来源于业务侧传入的水印字符串。水印不会自动把单位或机器码拼进背景图,除非上层业务逻辑显式构造水印文本。

章节来源

  • useWatermark.ts:1-200

错误处理与回退策略

授权文件缺失

当 license.xlts 不存在时,LicenseUtil.checkAuthStatus() 直接返回“授权文件无效”。前端会将其视为未授权状态,引导用户完成离线授权。

机器码获取失败

SystemService.machineCode() 在 regInfo.exe machinecode 返回非 0 时,返回枚举中的“获取机器码失败”消息。前端捕获错误后清空机器码字段,并允许用户重试。

授权校验失败

后端过滤器 LicenseFilter 当前是透传实现,不做全局拦截;授权校验下沉到业务接口。这意味着 /sys/info、/sys/checkAuth 等接口各自决定是否拒绝访问。

前端回退策略

  • 授权信息为空时,开发环境切换演示模式,生产环境展示“暂无授权信息”。
  • 授权校验失败时,授权页提示授权单位或到期时间可能不可用。
  • 离线授权失败时,前端提示错误消息,不跳转业务页。
  • 授权成功后,前端刷新授权缓存并根据是否已有登录态决定跳转目标。

章节来源

  • LicenseUtil.java:52-79
  • SystemService.java:128-145
  • LicenseFilter.java:1-74
  • AuthorizationInfoModal.vue:540-700
  • authorization/index.vue:520-600

部署、首次激活与更新许可证操作示例

部署 regInfo.exe

  1. 确保产品运行期的 QingJian 工作空间存在。
  2. 将 regInfo.exe 放入 QingJian/license。
  3. Linux 环境下将对应二进制命名为 regInfo。
  4. 确保 QingJian/license/license.xlts 存在。
  5. 非 Windows 环境确保授权文件可被后端进程读取。

首次激活

  1. 启动后端服务。
  2. 打开授权页,选择“连接后端服务”,填写管理员提供的服务地址。
  3. 点击“获取机器码”,从 /sys/code 返回的设备机器码复制给授权方。
  4. 授权方生成 .xlts 授权文件。
  5. 在授权页“上传授权文件”中选择该文件。
  6. 点击“离线授权”,后端写入 license.xlts 并校验。
  7. 成功后系统进入登录页;登录后进入案件工作台。

更新许可证

  1. 登录系统后打开“授权信息”弹窗。
  2. 确认当前单位、到期时间、剩余天数。
  3. 如需更换设备或续期,重新获取机器码并申请新的 .xlts。
  4. 通过授权页重新上传新授权文件。
  5. 后端替换旧 license.xlts,重新校验并更新 system_info。

命令行示例

场景 命令
获取机器码 regInfo.exe machinecode
读取全部授权信息 regInfo.exe read license.xlts
只查看单位 regInfo.exe -f license.xlts -field unit
校验授权 regInfo.exe -f license.xlts -verify

章节来源

  • PathConst.java:28-36
  • readme.md:52-76
  • authorization/index.vue:200-600
  • AuthorizationInfoModal.vue:200-789

依赖关系图

graph TB
    Frontend["前端 Vue 页面"] --> LoginApi["login.ts 接口封装"]
    LoginApi --> SystemController["SystemController"]
    SystemController --> SystemService["SystemService"]
    SystemService --> LicenseUtil["LicenseUtil"]
    LicenseUtil --> PathConst["PathConst"]
    LicenseUtil --> OsProcess["操作系统进程"]
    OsProcess --> RegInfo["regInfo.exe"]
    SystemService --> Database["system_info 表"]
    Frontend --> AuthorizationModal["AuthorizationInfoModal.vue"]
    Frontend --> AuthorizationPage["authorization/index.vue"]
    AuthorizationModal --> Watermark["useWatermark.ts"]
    AuthorizationPage --> LicenseUtils["license.ts"]

图表来源

  • login.ts:86-139
  • SystemController.java:70-108
  • SystemService.java:100-190
  • LicenseUtil.java:37-163
  • PathConst.java:16-36

常见问题排查

现象 可能原因 排查建议
获取机器码失败 regInfo.exe 不存在或无执行权限 检查 QingJian/license/regInfo.exe 是否存在
授权文件无效 license.xlts 缺失或损坏 重新上传授权文件,确认后缀为 .xlts
授权已过期 过期时间早于当前时间 联系管理员续期或重新申请授权
机器码不匹配 授权文件绑定的机器码与当前设备不一致 重新获取机器码并生成新授权
所有接口返回空白 过滤器误吞请求 检查 LicenseFilter.doFilter 是否调用了放行逻辑
授权信息弹窗为空 后端未写入 system_info 或接口返回空 检查离线授权是否成功,查看后端日志
水印异常 目标 DOM 被删除或样式被篡改 检查水印容器是否存在,确认 MutationObserver 是否正常工作

章节来源

  • LicenseFilter.java:1-74
  • LicenseUtil.java:91-113
  • useWatermark.ts:1-200

结论

regInfo.exe 在本系统中扮演“本机授权校验器”的角色:它不直接参与 Web 请求,而是被后端以子进程方式调用,负责读取 license.xlts、输出机器码、校验授权有效性。前端通过 /sys/info、/sys/code、/sys/checkAuth、/sys/noNet 等接口完成机器码获取、离线授权和授权状态展示。

授权状态分为正式授权、试用授权和已过期三类,前端据此改变授权信息弹窗、授权页摘要、应用标题标签和水印体验。部署时应确保 regInfo.exe 和 license.xlts 位于 QingJian/license,并在非 Windows 环境下保证文件可读。