许可证(license)
谁能签发凭证、私钥配在哪、客户那台怎么激活,以及签发与包签名为什么必须是两把钥匙。
应用编码 license,本页对应应用版本 1.0.3(引擎要求 >=5.6.2 <6.0.0),商业授权(app.json 里写 UNLICENSED),仓库 wujies-license-plugin(闭源,公开访问取不到源码)。
这个应用把「凭证怎么产生」收在一处:签发与运营台账、兑换码、激活记录、凭证下载。平台本体只留验证那一半(app_license 那一行、激活与解除、LicenseGuard.evaluate,以及 application.yml 的 app-market.license.*)。三档授权本身的区别见 授权档位,按应用解锁的口径见 按应用授权。
两把钥匙,各管一件事
| 钥匙 | 回答的问题 | 私钥在哪 | 公钥配在哪个键 |
|---|---|---|---|
| 包签名密钥 | 这个应用包是谁打的、上传后有没有被改过 | 每个应用仓库的 keys/private.pem | app-market.security.public-key |
| 授权签发密钥 | 这台部署买了什么、这枚凭证是不是签发方给的 | 签发方那台机器的仓库外路径 | app-market.license.public-key |
两把必须是不同的钥匙。共用一把时,给某个应用重新签包会连带影响所有已发出的凭证,轮换其中一把要同时重签另一件事的全部产物。包签名那对的生成与同步在 密钥与签名,本页只管授权这一把。
装它
签发与台账这一半装在签发方自己那台(官网)。客户那台不需要装这个应用,它靠平台自带的验证代码读凭证。
装之前两件事按顺序确认,配反了签发接口只会回一句"没配私钥":
-
签发私钥落盘。绝不把私钥明文写进任何 yml、文档示例或环境变量。推荐给一个仓库外的绝对路径,权限收到运行账号:
# Linux 签发方 chmod 600 /etc/wujies/license-private.pem喂值有三条路,优先级从高到低:后台「参数设置」里
wujies.license.private-key-file那一行(运行期可改、每次签发重读文件,换钥不必重启)> JVM 参数-Dwujies.license.private-key-file=…> 环境变量WUJIES_LICENSE_PRIVATE_KEY_FILE。后两条要在起宿主之前设好,改了必须重启。 -
验签公钥配对。
WUJIES_LICENSE_PUBLIC_KEY必须与上面那把私钥同一对,否则每一枚签出来的凭证都会在客户部署被判「签名不匹配」。客户那台忘配公钥时的表现是「任何凭证都判为 invalid,并明确报本机未配置公钥」,不会静默降级成社区版,这是刻意的:买了授权却因为运维漏配而看不到功能最难查。
生成这一对(生成到仓库之外;keygen 遇到目录里已有 private.pem 或 public.pem 会直接拒绝覆盖):
cd wujies-platform
mvn -o -q -pl wujies-modules/wujies-market-core compile
# <KEY_DIR> 换成一个仓库外的目录,Windows 下形如某个非项目盘的路径
java -cp wujies-modules/wujies-market-core/target/classes ^
cn.wujies.appmarket.security.PackageSignerMain keygen <KEY_DIR>签发一枚凭证(payload 是一个 JSON 文件,档位与应用名单写在里面):
java -cp wujies-modules/wujies-market-core/target/classes ^
cn.wujies.appmarket.security.LicenseSignerMain issue payload.json <KEY_DIR>\private.pem命令行这条路适合离线补签;日常签发走后台那屏。私钥路径只写进配置项,不要出现在提交、文档示例或截图里。私钥丢了只能把每一枚已售凭证重签,所以正式对外发授权前先把它备份到仓库之外的另一处。
配它
签发方那台要动的只有两个键,都在 application.yml 的 app-market.license 段:
| 键 | 默认 | 说明 |
|---|---|---|
issuer-enabled | false | 这台是不是签发方。改成 true 的那台才允许签发、看台账、生成兑换码;false 时这些端点当场报「这台部署不是授权签发方」,读侧不受影响 |
private-key-file | 空 | 指向仓库外的私钥文件。与 private-key(直接放 PEM 文本)同时配了以前者为准 |
issuer-enabled 这道闸挡的是误用与角色边界,挡不住机器主人:那台机器上的人当然能把开关改成 true。真正决定「能不能拿到付费包」的是包下发那一条路(中心按凭证发私有包,并断掉公开直链)。把这一页当成安全边界来读会得出错误结论。
客户那台要动的也是两个键,口径与上面一致:WUJIES_LICENSE_PUBLIC_KEY(验签公钥)与 app-market.license.mode(off / warn / enforce,默认 warn 放行并记日志)。mode 的值是 @Value 注入的字符串,写成空串或拼错都不报错,一律按 warn 处理,所以别指望「改错了会当场起不来」帮你发现笔误。到期宽限天数 grace-days 默认 7。
report-url(激活回报地址)只在客户那台配:配了签发方官网地址后,本机激活成功会回报一次设备信息(设备 ID、主机名、来源 IP),客户才能在「我的许可证 → 激活信息」里看到自己跑在哪几台。留空是内网与离线部署该有的样子,那张表空着是预期结果而不是故障;回报失败只记一行日志,不回滚已经成功的本机激活。生产上必须配 https,回报原文里是授权凭据。
用它
运营侧在「许可证签发」这一组菜单里做四件事,五个权限点逐条挂在角色上(license:ledger:list / query / issue / revoke / redeem-code),不要授给客户账号:签发一枚、看台账分页、撤销、批量生成兑换码、查兑换码状态。
台账分页按 state 筛(valid / grace / expired / revoked,空为不筛),四格状态与行上那句 stateLabel 出自同一份算法(LicenseState.filterBounds(graceDays, now)),SQL 里不重算,避免出现「这行写着有效、筛『有效』查不到它」。两个边界是 now - 1 天(valid 用它做严格大于,因为剩余天数走整数除法向零截断,刚过期不足一天仍判 valid)与 now - grace-days × 1 天(grace 的下界),调用方不许自己拼 86400000 或按 graceDays 算日期,等号方向一漂开就再造一次分歧。state 传那四个码值以外的东西会直接报错并列出合法值,不静默返回空表。下拉选项由 GET /app/issuer/license/ledger/options 一次给全(含「哪些档位能签」,community 不在里面),前端因此不必自己抄一份码值到中文的映射。
签发时 tier 与 grant 必填,apps 留空会被拒签(空名单等于白送),tier=community 签不出来:社区版是一台部署没有凭证时的默认状态,不是一种凭证。userId 可以留空,线下成交先有证、客户之后才注册账号;没绑定账号的行在客户侧任何一屏都查不到,只有台账列表看得见(AppLicenseLedgerQueryBo.unbound 那一格筛的就是它)。补一个「给已签发的凭证改绑账号」的端点本轮没做:改归属是敏感操作,得和操作留痕一起做,现在只有直接改库这一条路。签发入参里没有凭证字段:凭证只能服务端签出来,收现成凭证等于允许任何人往台账里插一枚别人签的授权。subscription 最长 36 个月(兑换码上以天数表达,上限 1095 天);version_lock 必须给版本上限 versionTo,它是签发与台账口径里的约束,部署侧当前只按签名与到期判定,别把它当成已经硬性的收口。apps 选项带的 minTier 只用于让签发页算默认勾选,服务端从不按档位推导名单,解锁什么只看签进凭证的 apps。
兑换码:POST …/redeem-code 批量生成、GET …/redeem-codes 查状态。授权内容在生成时逐行定死在码上(档位、名单、期限形态、域名、有效天数、版本上限),兑换端点只收 code,接受任何授权参数等于让三十块的码兑出企业版。抢码是一条带条件的 UPDATE … WHERE code = ? AND status = 'unused' 加影响行数判定,不是先查后写,所以并发双击只有一笔生效;签发在同一事务里,私钥没配时整笔回滚、码回到 unused,没配私钥的机器不会吃掉任何一枚码。到期时刻在兑换那一刻按 durationDays 算,不是生成时算。已发出去的码改不了内容,只能整批作废(status = void)再重做一批;生成阶段一枚都不签,所以还没配密钥也能先把码备出来。一次 1–500 枚,多了分批,每批一个批次号。
撤销只作用于台账侧:收回的是「再下载一份凭证」和「把这一行当续费依据」,激活记录保留、app_license 一行都不动(那是部署侧「这台当前用哪枚凭证」的表)。已经装了这枚凭证的部署验签照旧通过,它没有任何通道知道中心撤了它。真要收回得轮换密钥对。所以 revoked 是台账专属的第五种状态,部署侧那个枚举刻意没有它。
设备回报(POST /app/issuer/license/report,匿名)不验签也不解析凭证:判据是凭证原文与 app_license_order.credential 精确匹配,签发方再验一次只是多要求一把公钥,没配公钥的开发环境反而回报不进来。同一台机器只留一行,判据 order_id + device_id,重复上报只刷 last_seen_at;被「删除此设备」解绑过的那台再回来置回 active 并清 release_at,所以删除是置 released 而非物理删(台账要能回答这台机器什么时候占过名额)。一枚许可证下最多 50 条在用设备记录。这个上限防的是有人拿自己的凭证把别人台账刷脏。已撤销的许可证照样记设备:一张撤了的证还在几台机器上跑着,正是要收集的信号。
台账三张表按账号归属,tenant_id 只作对账:所有查询都包在 TenantHelper.ignore 里,客户侧越权判据只有 user_id 一处(AppLicenseLedgerService.requireOwned),设备行自己不带归属人,所以永远先按 orderId 断言 owner 再取设备,绝不按 deviceId 直接查。运营侧那几条故意没有 user_id 谓词,闸是上面那五个权限点;两套口径分在两个控制器里,任何一条被对面复用都是跨账号泄露。「不存在」与「不是你的」共用同一句报错,兑换失败时「已被使用」「已作废」也合并成一句:分开说就是送一个探测别人台账与码有效性的 oracle。
客户侧两屏在会员中心:/member/license 一行一张证,/member/license/detail?orderId= 给明细、激活记录、兑换与凭证下载。下载的 .lic 原文只落盘,不印在页面上。这两屏的组件写在宿主路由里,不由这个包种菜单。
运营侧那几个字面量路径(…/list、…/options)与 …/{orderId} 挂在同一个前缀下,命中靠 Spring 的「字面量优先于路径变量」规则;这一段路径还没联机调过,改动时别只靠读代码判断它通了。明细里那一列 appNames 在插件侧恒为 null:应用目录住在平台那半,本包拿不到,页面上这一栏空着属正常。
客户侧这两屏的形状由平台侧的 AppLicenseOrderVo 一处定,字段名逐字对齐插件里的 frontend/src/api/license/types.ts,以插件那份为准。各种 label、剩余天数、到期状态一律服务端算完给出去,前端不做判断;时间给格式化字符串,不给 Date 或时间戳。订单号是雪花号 Long,超出 JS 安全整数时序列化器输出成字符串,前端按字符串用,别 Number() 转换再传回来,那会静默丢精度。改这个 VO 的字段名要同时改插件那份 types.ts,漏一边表现为页面上那格空白。
给某个客户账号看这些屏,需要它持有 system:console:access(后台准入闸),口径见 菜单范围与后台准入。
出问题查什么
| 现象 | 先看 |
|---|---|
| 签发收到「本机没有配置签发许可证用的 RSA 私钥」 | private-key-file 指的路径在这台机器上是否存在、进程账号能不能读。这句是"私钥没配"的证据,不是签名算法坏了 |
| 客户部署说凭证签名不匹配 | 两边的公钥与私钥是否同一对;签发方换过钥而客户那台还是旧公钥 |
/app/issuer/license/** 全部 403 | 当前角色没有那五个 license:ledger:* 权限点,或 issuer-enabled 是 false |
| 官网「激活信息」永远空 | 客户那台的 report-url 没配;配了仍空,查那条匿名回报路径是否被租户拦截器挡成 401。写入 app_license_activation 的代码在本包,平台侧那份台账服务只读不写,所以没装这个包的部署这张表必然是空的,那是预期而不是故障 |
| 装了应用却提示未解锁 | 凭证里的 apps 名单与该应用包内 licenseRequired 是否对得上,mode 是哪一档 |
查 app_license 报 near 'grant' 语法错误 | 实体属性名被改动过。AppLicense.grantType 必须与列名 grant_type 同形:叫 grant 时 MyBatis-Plus 拼出 grant_type AS grant,而 GRANT 是 MySQL 保留字。对外字段名仍叫 grant,在 service 里映射到 AppLicenseVo.grant |
| 客户「我的许可证」永远空列表,且不报错 | 宿主 application.yml 顶层 tenant.excludes 漏了台账那三张表。漏进去后框架会自动拼 tenant_id,运营租户下签出的行永远匹配不到;同一条漏在 app_redeem_code 上时兑换 CAS 永远匹配不到,客户只看见「码无效」。这是最难查的一类失败,装包先确认这三行 |
装了插件、report-url 也配了,设备表还是空 | 部署侧那条回报是 report-url 加常量拼出来的,平台开源仓的常量值是 /app/license/report,改配置改不出 /app/issuer/… 前缀。平台那三条同名控制器还在时回报仍打进平台那一条;删平台那半边时必须同时改那一侧常量或让网关改写旧路径 |
实现索引
| 项 | 值 |
|---|---|
| 数据表 | app_license_order、app_license_activation、app_redeem_code(台账三张,有 tenant_id 列但按账号归属,见 多租户下的应用);app_license(本机那一行)留在平台侧 |
| 运营侧端点 | POST /app/issuer/license/ledger/issue、GET …/list、…/options、…/{orderId}、…/{orderId}/activations、POST …/{orderId}/revoke、POST …/redeem-code、GET …/redeem-codes |
| 客户侧端点 | GET /app/issuer/license/my/orders、…/{orderId}、…/remark、…/credential、…/activations、POST /app/issuer/license/redeem |
| 部署回报 | POST /app/issuer/license/report(匿名,靠 tenant.excludes 放行) |
| 平台侧本机授权 | GET /app/license/subscription、…/subscription/apps、…/required-apps、POST /app/license/activate |
| 判据代码 | LicenseProperties.requireIssuerEnabled()、LicenseKeySource、LicenseIssuer.payload、LicenseGuard.evaluate |
| 源码 | cn/wujies/license(闭源仓库) |
截至本页写作时,这个包没打过也没装过,上面 15 条端点一条都没联机调过;客户侧两屏仍在用平台开源那半的 /app/license/**,只有台账页已指到本包的 /app/issuer/license/ledger/**。也就是说,客户侧页面上看到的一切都不证明插件端点通了。验收清单在插件仓库 README 的「本机联机验收手册」一节,做完那几条才能把本页当成实测口径。