中国 帮助

许可证

官方 付费 插件

Wujies 无界平台(wujies.cn)的许可证应用,一个插件一个仓库。它是一个

v1.0.8

<p> <a href="https://wujies.cn" target="_blank" rel="nofollow"> <img width="100" src="https://wujies.cn/brand/logo-stacked.svg" alt="Wujies 无界 logo"> </a> </p>

<p><b>许可证</b>,签发与运营台账在插件里(运营侧),当前账号名下的许可证、兑换与凭证下载也在插件里(客户侧)。</p> <p> <a rel="nofollow"><img alt="应用版本" src="https://img.shields.io/badge/app-1.0.7-111111?style=flat-square"></a> <a rel="nofollow"><img alt="应用编码" src="https://img.shields.io/badge/code-license-0057FE?style=flat-square"></a> <a rel="nofollow"><img alt="License" src="https://img.shields.io/badge/license-commercial-orange?style=flat-square"></a> <br> <a rel="nofollow">功能特性</a> <a rel="nofollow">安装</a> <a rel="nofollow">设置</a> <a rel="nofollow">端点清单</a> <a rel="nofollow">常见问题</a> <a href="https://docs.wujies.cn/docs/wujies/5.x/platform/plugin" rel="nofollow">插件开发</a> <a href="https://gitee.com/wujies" rel="nofollow">Gitee</a> </p>


Wujies 无界平台(wujies.cn)的许可证应用,一个插件一个仓库。它是一个 闭源商业包,自带后端:签发与台账整半(AppLicenseLedgerService / LicenseIssuer 的私钥侧 / 三张表 app_license_order、app_license_activation、app_redeem_code)住在本仓库,开源平台侧 只留验证(app_license 那一行、AppLicenseService 的激活与解除、LicenseGuard.evaluate、 hiddenPrivateApps,以及 app-market.license 那四项 public-key / grace-days / mode / report-url)。

为什么签发只在一个闭源插件里(定案与全部理由见平台仓 wujies-platform/AGENTS.md §3.15 「谁是签发方」,2026-11-04):签发代码本身可以公开 —— 门槛在私钥不在代码。但「开源仓里留一份签发代码

  • 一个开关」不是安全边界:机器主人当然能把开关改成 true,开关挡的是误用与角色边界,不挡机器主人。

所以「这台能不能签发」的判据只能是这个 jar 在不在:签发代码与签发配置只在本插件里,开源平台不含 签发端点(/app/license/ledger/**、/app/license/my/**、/app/license/redeem、/app/license/report 都不在里面),app-market.license 里也没有 issuer-enabled 这一项 —— 装了本包就是签发方,没装就没有, 配置怎么写都换不来签发能力。⚠️ 反过来也别指望在一台没装本包的部署上「补个配置」来签发或补台账: 那台上连接收端点都没有,只会得到 404。真正决定「能不能拿到付费包」的是包下发 那一条路(中心按凭证发私有包 + 断掉公开直链),所以签发与台账这一半要搬到闭源件里来,和另外 8 个付费件走同一道墙。光把代码搬过去而不把这个仓转成闭源商业包 = 换个地方开源。

  • 运营侧:一组「许可证签发」菜单 + 签发台账页 + 配置页,权限点 license:ledger: 下九项(list / query / issue / revoke / redeem-code / void / delete / assign / reveal-code,授权由运营在角色上勾,不给客户)。后端端点全部挂在 /app/issuer/license/** 前缀,共 25 条,逐条列在「端点清单」一节。
  • 客户侧:列表(视图键 license/license)一行一张许可证,详情(license/detail,?orderId=) 给明细、激活记录、兑换与凭证下载(凭证原文只落盘成 .lic,不印在页面上)。文本一律取服务端 VO (productName / source / stateLabel / hasActivation),前端不参与判断。
  • 入口:运营侧两屏由本包 app.json 的 menus 种进 sys_menu(见「菜单入口」); 客户侧两屏仍是会员中心里的两条路由,组件写在宿主 wujies-admin/src/router/index.ts (/member/license、/member/license/detail),不由本包种。远程清单的 routes 一律不声明 (既有决定:清单里的绝对路径会被 loader 注册成没有 Layout 的顶级路由,页面会裸奔)。
  • 前台:没有公开直出页(src/main/resources/site-templates/ 不存在)。

应用编码 license | 应用版本 1.0.7 | 清单 type = plugin | 引擎 &gt;=5.6.2 &lt;6.0.0 | 后端构件 wujies-license-plugin | 签发私钥配置键 wujies.license.private-key-file

✨ 功能特性

  • 🧾 签发台账 — 一行一张许可证(lic、客户名、商品名、档位、期限形态、解锁应用、绑定域名、 版本区间、到期时间、备注),按状态四格筛选(有效 / 宽限期 / 已过期 / 已撤销)。
  • ✍️ 签发 — 13 个字段的 BO,判据全在服务端(LicenseIssuer.payload):apps 不能空、 tier=community 拒签、永久不填到期与版本上限、订阅最远 36 个月、版本买断必须给 versionTo。
  • 🎫 兑换码全生命周期 — 批量生成(档位 / 名单 / 天数 / 域名定死在每一行码上)、台账分页(码文只回末四位)、 按批次回看明文(独立权限)、作废、删除、发放给指定站点账号、撤回发放、发放选人搜索。
  • 👤 我的许可证 — 列表 / 详情 / 改自己的备注 / 激活记录 / 删除此设备 / 下载凭证 .lic (凭证原文只做下载,页面上不印)。
  • 🔑 兑换与按编号领取 — 手输兑换码兑换;「发放给我、还没领」的码可按 codeId 一键领取, 响应就是那张新许可证。
  • 📡 设备回报接收端 — POST /app/issuer/license/report,装机侧激活成功后把设备登记进台账 (匿名可达,靠平台 security.excludes;这个字符串与平台侧常量必须逐字一致)。
  • ⚙️ 许可配置页 — 「许可证签发 → 配置」读写宿主 sys_config 的 wujies.license.private-key-file (只填路径、不填私钥文本),保存即生效、不用重启。
  • 🔐 两套口径互不复用 — 客户侧每条都做 requireOwned 归属断言、不加权限串; 运营侧每条都挂自己的权限串、不做归属断言。少一边就是越权或签发裸奔。
  • 📦 闭源商业包 — license: UNLICENSED + licenseRequired: true,与另外 8 个付费件同口径。

🚀 安装

环境要求

| 项 | 要求 | |---|---| | 平台版本 | &gt;=5.6.2 &lt;6.0.0(app.json 的 engine) | | 后端构建 | JDK 17+(父 POM 的 java.version 为 17) | | 前端构建 | Node.js 18+(建议 20 LTS 及以上),npm | | 授权 | 一枚覆盖本应用的有效凭证;平台 app-market.license.mode 默认 warn,要真拦得改 enforce | | 安装方式 | 开发台「插件开发 → 本地安装」(POST /app/dev/install);正式分发经上架中心(wujies-market)发布后由平台拉取 |

安装入口(本机走开发台,不是「应用市场」)

POST /app/dev/install,请求体 {"code":"license","zipPath":"&lt;磁盘上 zip 的绝对路径&gt;","watch":false}, 权限 app:dev:install,靠平台 application.yml 的 app-market.plugin-runtime.dev-mode: true(276 行) 开着才允许(关着时端点 404)。

  • ⚠️ 它吃的是磁盘路径,不是上传文件:POST /app/install 那一条只收 appCode(走目录), 全仓没有「浏览器上传 zip」的端点;正式分发仍经上架中心发布后由平台拉取。
  • zipPath 有目录约束:必须是已存在的 .zip,且落在「插件工程搜索根」或其兄弟目录 \.plugin-dist 之内;留空则服务侧现场打一个开发包。
  • 包里两个产物的路径由 app.json 的 assets 决定:frontend → frontend/index.js | backend → backend/wujies-license-plugin-1.0.7.jar(jar 名 = -&lt;应用版本&gt;.jar, 改 version 必须同步改这一行,脚本会按同一条规则 WARN)。
  • 另一道开关 app-market.dev.enabled 是生产锁;yml 里没有这一项时走 @Value 默认 true。

安装成功后逐项核对响应(键名取自 PluginDevInstallService):

| 字段 | 期望 | |---|---| | migrations.applied | 首次装含三个脚本名;⚠️ 重装时 applied 为空数组、脚本落在 skipped 里,那时要核 skipped 与 app_schema_history | | menus.created / menus.total | 菜单节点 1 个 M + 2 个 C + 8 个 F;升级装按 menu_key 幂等 upsert,只补新增的 F 行,别按上一次的数字判失败 | | menus.granted | 给当前租户角色授权的条数 | | hotLoaded | 必须是 true;false 时 hotLoadNote 会说清缺哪一步(jar 找不到 / 热加载抛异常) | | signed | 开发路固定 false(不验签),是预期值 | | artifact.artifactPath | 优先工程的 target/classes,没有才用 jar(本仓 target/wujies-license-plugin-1.0.6.jar) |

日志两行(格式逐字来自代码):

[plugin-dev] 本地安装完成: app=license, devVersion=…, installId=…, hotLoaded=true, watching=false
插件 license 已加载(classes):组件 N 个,接口 25 个,Mapper 3 个,启动类 LicensePluginApplication,类加载器 …

第二行是 PluginRuntimeManager 拼出来的原样格式(没有 [plugin-runtime] 前缀,旧读法会搜不到)。 其中「接口 25」与「Mapper 3」是按代码数出来的(3 个 controller 共 25 条映射、3 个 Mapper), 数字对不上说明有 controller / Mapper 没被扫到,先翻加载日志的异常尾巴。

从源码构建

在本仓库根打包(三条命令各管一段,都在本仓库根执行):

powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1 -CheckOnly   # ① 打包前检查:清单/产物/迁移/菜单/密钥,几秒返回
powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1 -Dev         # ② 开发包:不签名,落 ..\.plugin-dist\license\dev
powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1              # ③ 正式包:构建前后端 + 用 keys\private.pem 签名

zip 名固定是 -&lt;应用版本&gt;.zip,默认落点 &lt;插件仓上一级&gt;\.plugin-dist\\&lt;版本&gt;\, 即 ..\.plugin-dist\license\1.0.7\license-1.0.7.zip(在仓库之外,git 看不到它)。 -Dev 只把版本目录换成 dev(zip 名仍带版本号,不签名)。

关于上面三条命令的取值口径:

  • 判据是「脚本所在仓库根有没有 app.json」,所以在本仓库里不要传 -Plugin(它按子目录找清单, 会报「找不到插件目录」);-FrontendProject / -FrontendDist 也不用传 —— 独立布局的前端工程固定就是 本仓库 frontend/、产物 frontend/dist,脚本自己跑 npm run build(首次先 cd frontend &amp;&amp; npm install, 缺依赖时脚本会把这条命令直接报给你)。只想复用现成产物就加 -SkipBuild。
  • -SkipFrontend 只用于没有前端的纯后端应用:带前端时它会连「复制前端产物」一起跳过, 出的包只有 app.json,装上去没有界面。本应用前后端都有,任何时候都别加它。
  • 本脚本的构建命令是 mvn -B package -DskipTests(不带 -o)。本机要走离线仓库时, 先手工构建一次再让脚本装包:
  $env:JAVA_HOME="C:/Users/TX/.jdks/ms-17.0.16"
  &amp; "C:/Program Files/JetBrains/IntelliJ IDEA 2024.3.3/plugins/maven/lib/maven3/bin/mvn.cmd" -o -B package -DskipTests
  powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1 -SkipBuild
  • 签名密钥在本仓库 keys/(private.pem + public.pem,.gitignore 已忽略)。⚠️ 这对密钥是 包签名用的(PackageDigest / PackageSignerMain),与签发许可证那把 RSA 私钥是两把不同的 密钥,别混用、也别把后者放进仓库(许可证私钥在本机仓库外路径,见「签发私钥」)。
  • ⚠️ 平台 app-market.security.mode 切到 enforce 那一档管的是走市场上架链路的上传与加载: 没签名(或签名对不上)的包会被拒。开发台本地安装是开发路,它没有目录版本、对象存储与签名校验, 响应里固定 signed: false —— -Dev 出的不签名包在这条路上照样能装。落位那一步仍走 AppPackageDeployService.deployLocal(jar 会进 plugins-dist、active-plugins.txt 会加一行)。 「正式分发必须签名」这条要靠走中心下发来保证。对照:开发台的「热加载」POST /app/dev/reload 更彻底, 连 AppPackageDeployService 都不过、也不写 active-plugins.txt,所以靠 reload 挂上的插件重启就掉。

手工构建(不用打包脚本时,本机 2026-11-05 跑过 exit=0):

mvn -B -o package -DskipTests                 # 后端,产物 target/wujies-license-plugin-1.0.6.jar
cd frontend &amp;&amp; npm install &amp;&amp; npm run build   # 前端,产物 dist/index.js + assets/license-app.css

最快的开发路子不用打包、不用重启宿主:启动平台宿主,打开管理端「开发工具 → 插件开发」, 找到 license 这一行,「启动后端」(编译并加载 target/classes,带监听)与「启动前端」 (常驻 vite build --watch,保存即重建、刷新生效,没有 HMR)两颗都要点。全流程见 文档站「插件开发」。

升级与卸载

  • 升级:换 app.json 的 version 后重新打包上传;已执行过的迁移脚本不可改内容, 新增表结构一律加新编号脚本(02-redeem-code-assign.sql、03-license-config.sql 就是这种加法)。
  • 卸载:管理端「应用市场」里卸载,平台按 migrations/ 记录的建表脚本清理;台账三张表的事实源 只有本仓 migrations/,所以「彻底删除」删的正是那三张表 + 配置行。
  • ⚠️ 迁移脚本是目录扫描执行的(按文件名排序),app.json 的 migrations 数组留空是正确写法, 不是漏写(见「迁移脚本」)。

⚙️ 设置

签发私钥(wujies.license.private-key-file)

后端读配置键 wujies.license.private-key-file,判据与取值顺序写在 src/main/java/cn/wujies/license/sign/LicenseKeySource.java:

环境变量 WUJIES_LICENSE_PRIVATE_KEY_FILE
  → 系统属性 -Dwujies.license.private-key-file
  → @Value 注入值 / Spring Environment(application.yml 里那一段)
  → sys_config 同名项(后台「许可证签发 → 配置」,运行期可改)
  • 只写路径。填一段 PEM 进去当场被拒;私钥文件本身放仓库之外 (Linux 例如 /etc/wujies/license-private.pem,chmod 600)。
  • 平台 application.yml 里此刻并没有 wujies.license.* 那一段(顶层 wujies: 下只有 rabbitmq), 所以本机只有三条可走:环境变量、JVM 参数、后台配置页(推荐最后一条:运行期可改、不用重建宿主, 而且每次签发都会重读路径与文件)。
  • ⚠️ 绝不在任何配置或文档里内联私钥明文(平台仓有过库口令进公开 git 历史的事故)。
  • ⚠️ 私钥必须与部署侧那把验签公钥是同一对,否则每一枚签出来的凭证都会在客户部署被判「签名不匹配」。 公钥不在平台仓的 yml 里:app-market.license.public-key 只是 ${WUJIES_LICENSE_PUBLIC_KEY:} 这个占位, 真身走环境变量或 1Panel 的 data/keys/license-public.pem。别和 app-market.security.public-key (那是签包用的)混 —— 两把不同的钥匙,动手对拍前先确认自己抄的是哪一段。
  • 配对自查(只导出公钥做比对,绝不把私钥内容打到屏幕或文件里,只输出 MATCH / NOMATCH):
  openssl rsa -in &lt;私钥路径&gt; -pubout -out /tmp/derived_pub.pem
  norm(){ tr -d '\r\n' | sed 's/-----BEGIN PUBLIC KEY-----//;s/-----END PUBLIC KEY-----//'; }
  [ "$(norm &lt; /tmp/derived_pub.pem)" = "$(norm &lt; &lt;生效的授权公钥&gt;)" ] &amp;&amp; echo MATCH || echo NOMATCH

⚠️ 别省掉 tr -d '\r' 那一步:Windows 上 openssl 写出的 PEM 是 CRLF,只 tr -d '\n' 会假报 NOMATCH。

平台本体的两处配置依赖

本包的后端半要能跑,平台仓 wujies-platform/wujies-admin/src/main/resources/application.yml 里有两处必须跟着改 —— 插件自包含是假象,这两处不在插件里:

| 配置 | 必须包含 | 缺了会怎样 | |---|---|---| | 顶层 tenant: excludes: | app_license_order、app_license_activation、app_redeem_code | 自动拼上 tenant_id 后,客户查自己名下的许可证永远返回空行(症状是「我的许可证永远空」);兑换码那句 code = ? AND status = 'unused' 也永远匹配不到 | | security.excludes | /app/issuer/license/report | 装机的服务器没有本机会话,回报请求会被拦成 401,官网「我的许可证 → 激活信息」永远是空的 |

三张表的建表语句只有本仓 migrations/ 一份;这两行都在平台仓,本 README 只说明要配什么,不做重复改动。

第三条配置由本仓自己的 migrations/03-license-config.sql 种进 sys_config: wujies.license.private-key-file(config_value 与 default_value 都是空串)+ 配置类别 license。 宿主 updateConfig 只按 config_key 改已存在的行、不插入,所以这一行必须先落库,配置页才有得读写。 ⚠️ 只写默认租户 000000:要让所有租户共用同一把签发私钥,请配环境变量。

授权档位与 LicenseGuard

licenseRequired 是商业包闸门,判据只有清单那一个布尔:LicenseGuard.evaluate(appCode, licenseRequired) 在部署链路与运行时装载器各判一次,值本身被 PackageDigest 的摘要覆盖(改它就等于改包签名)。 执行强度由平台侧 app-market.license.mode 决定,默认 warn(只记日志不拦),生产要真拦得改成 enforce(off 完全不判)。三档口径(社区版 / 专业版 / 企业版)见官网文档「授权与版本」。

菜单入口

| 菜单 | 路径 | 组件键 | 权限前缀 | |---|---|---|---| | 许可证签发(目录) | licenseIssuer | — | — | | 签发台账 | licenseIssuer/ledger | remote:license/license/ledger | license:ledger:list | | 配置 | licenseIssuer/config | remote:license/license/config | system:config:list |

按钮(type=F)8 个,逐字取自 app.json:license:ledger:query / :issue / :revoke / :redeem-code / :void / :delete / :assign / :reveal-code。合计 1 个 M + 2 个 C + 8 个 F。

&gt; 「配置」那一屏复用平台的 system:config:list(它读写的就是宿主 sys_config), &gt; 所以能进系统配置的角色天然能进这一页 —— 这与「运营才该看到台账」是两回事,别把它们并成一个权限。

前端注册的视图键四个:license/license(客户侧列表,宿主 /member/license)、license/detail (宿主 /member/license/detail,orderId 走 query)、license/ledger、license/config。 后两个由本包 app.json 的 C 菜单指过来;远程清单的 routes 仍然不声明。

🧩 依赖与插件支持

| 项 | 说明 | |---|---| | 依赖插件 | 无(app.json 的 dependencies 为空数组);但签发要平台侧的验证半(LicenseGuard / app-market.license 四项)与部署侧注入的验签公钥 | | 平台存储 | 包与私有应用落中心的本地磁盘(私有应用必须 local,OSS 直链等于没私有);本插件不存任何密钥 | | 公共 API | 前端走打进包内的 @wujies/api-client,运行期由宿主 import map 提供 vue / element-plus / @wujies/ui-shared 单例;发放选人走插件 SDK 的 PlatformUserApi.searchEnabledUserIds | | 平台用户接口 | 不开宿主 GET /system/user/list:那条要 system:user:list,等于把「能给一张码指定领取人」放大成「能翻整库用户的手机号、邮箱、部门」 | | 启动类 | LicensePluginApplication(插件启动类,start() 每次热重载都会跑,必须幂等) |

端点清单(25 条映射,逐字读自三个 controller)

&gt; 计数口径:@GetMapping/@PostMapping/@PutMapping/@DeleteMapping 实数 —— &gt; AppLicenseLedgerController 15、AppLicensePortalController 9、AppLicenseReportController 1。 &gt; ⚠️ 包内 route-index.json 会比源码少一条:report 那条的路径写成了常量 &gt; (AppLicenseReportBo.REPORT_PATH),package.ps1 扫的是源码、读不出常量值(脚本自己声明了这个盲区); &gt; 服务端上传那一路会退回扫 jar 字节码,javac 已内联常量,所以清单里不会真少一条。别拿「少一条」当端点总数。

运营侧,基路径 /app/issuer/license/ledger(AppLicenseLedgerController),每条都挂自己的权限串:

| 方法 + 路径 | 权限串 | 做什么 | |---|---|---| | POST /issue | license:ledger:issue | 签发一枚(13 个字段的 BO,判据全在服务端) | | GET /list | license:ledger:list | 台账分页。状态按 state 筛(valid/grace/expired/revoked 四选一,空为不筛);这三格背后的日期边界取 LicenseState.filterBounds(graceDays, now),与行上那句 stateLabel 同一份算法 —— SQL 里不重算,否则会出现「这行写着有效、筛『有效』查不到它」。不在那四个码值里直接报错,不静默返回空表 | | GET /options | license:ledger:list | 七族下拉:tiers(筛选用的档位,含 community)/issuableTiers(能签的档位,不含)/grants/ledgerStates(台账页那排状态胶囊的四格)/redeemStatuses(未兑换/已发放/已兑换/已作废)/issueSources/apps(付费应用名单,每项 {code,label,minTier})。label 与台账行上那几族 label 出自同一批方法,前端不必抄「码值 → 中文」映射 | | GET /{orderId} | license:ledger:query | 单行明细 | | GET /{orderId}/activations | license:ledger:query | 运营侧设备表(撤销前要看这台许可证在几台机器上跑着) | | GET /{orderId}/credential | license:ledger:query | 运营侧下载凭证原文(对账 / 补发用)。与客户侧同一个 requireOwned 之外的口径:只认权限串,不落到页面上显示 | | PUT /{orderId}/revoke | license:ledger:revoke | 吊销 | | POST /redeem-code | license:ledger:redeem-code | 批量生成兑换码(档位/名单/天数/域名定死在每一行码上);响应是这批码的原文,只在这一刻给一次 | | GET /redeem-codes | license:ledger:redeem-code | 兑换码台账分页(批次/档位/期限/status+statusLabel/发放对象 ownerName/兑换人/兑出的 lic)。⚠️ 码本体只回末四位:能反复读取的列表里回显原文等于让这个端点把别人买走的东西再抄一遍 | | GET /redeem-code/batch/{batchNo}/codes | license:ledger:reveal-code | 按批次回看明文(batchNo 精确匹配,不是模糊)。生成那一次没抄下来就只能整批作废重做,对运营是二次事故。权限串刻意不与生成共用 —— 能造码不等于能把码反复捞出来。@Log 上 isSaveResponseData = false 是这条的关键:默认 true 就是整批明文进 sys_oper_log,而操作日志的读口比这条端点宽得多 | | PUT /redeem-code/void | license:ledger:void | 作废(unused/assigned → void),一枚与一批同一条(body {codeIds})。已兑换的挡在服务层 —— 收回一张已发出去的授权是台账 revoke 那件事,不是改码的状态 | | DELETE /redeem-code/{codeIds} | license:ledger:delete | 删除(逗号分隔的路径参数),只允许 unused/void:used 那一行是唯一能对账「这枚码换走了哪张许可证」的地方,删掉等于替客户改账 | | POST /redeem-code/assign | license:ledger:assign | 发放给指定站点账号(body {codeIds, userId} → assigned + owner_user_id)。不改变这枚码值多少钱,只改变谁能领;userId 必填且必须是存在且启用的账号,留空当场报错而不是当成「取消发放」 | | PUT /redeem-code/unassign | license:ledger:assign | 撤回发放(assigned → unused,清空归属)。⚠️ 撤回后这枚码回到公共池,任何登录用户手输都能兑 —— 不是收回运营口袋 | | GET /redeem-code/assign-users | license:ledger:assign | 发放选人搜索(keyword ≥2 字,只回启用中的账号,上限 20 条,只有 userId/userName/displayName 三样) |

客户侧,基路径 /app/issuer/license(AppLicensePortalController),只要登录、刻意不加权限串, 每条都带 orderId / activationId 归属断言(AppLicenseLedgerService.requireOwned 那一个私有谓词):

| 方法 + 路径 | 做什么 | |---|---| | GET /my/orders | 我名下的许可证列表 | | GET /my/orders/{orderId} | 详情 | | PUT /my/orders/{orderId}/remark | 改自己的备注 | | GET /my/orders/{orderId}/credential | 客户侧凭证原文出口(下载成 .lic,页面上不印) | | GET /my/orders/{orderId}/activations | 我的激活记录 | | DELETE /my/activations/{activationId} | 删除此设备 | | POST /redeem | 兑换码兑换(不接受任何授权参数)。手输这一条同时认 unused 和发给我的 assigned(CAS 里那半个 or),别人的 assigned 码手输兑不走 | | GET /my/codes | 发放给我、还没领的兑换码(谓词 owner_user_id = 我 AND status = assigned)。⚠️ 不回码文,连末四位都不必回 —— 领取按 codeId,回显码文只会把「按编号领取」重新变成「互相抄码」 | | POST /my/codes/{codeId}/claim | 按编号领取,响应就是那张新许可证(AppLicenseOrderVo,形状与 /redeem 一致)。⚠️ 雪花 codeId 是可猜的,所以服务端自己先断言 assigned + owner_user_id = 我,不能只靠 CAS;三种失败(行不存在、不是发给我的、状态已不是 assigned)共用「许可证不存在或不属于当前账号」那一句,不给探测留缝 |

部署回报:POST /app/issuer/license/report(常量 AppLicenseReportBo.REPORT_PATH,controller 类上 无 @SaIgnore,匿名性靠平台 excludes 里那一条)。⚠️ 这个字符串与平台部署侧同名常量必须逐字一致 (开源平台激活成功后拼的就是 report-url + 这一个常量),两边只改一边 = 设备表永远为空。

⚠️ 两套口径分在两个类里,不许互相复用端点:客户侧少了 requireOwned 就是跨账号读别人的凭证, 运营侧少了权限串就是任何登录用户能签发。

与开源平台的分工(读这段再动手)

  • 平台只剩 AppLicenseController(GET /app/license、/subscription、/subscription/apps、 /required-apps、POST /app/license/activate、DELETE /app/license)与 LicenseGuard 那一族判据, 配置侧只剩 app-market.license 那四项(public-key / grace-days / mode / report-url)。 平台没有 AppLicenseLedgerController/AppLicensePortalController/AppLicenseReportController, 也没有 issuer-enabled 这一项:一台部署是不是签发方,只看它装没装本包那个 jar。 ⚠️ 别在平台 yml 里补 issuer-enabled 或私钥项 —— 那些键没有读取方,写进去只会让人以为这台能签发。
  • 本包的后端半统一挂 /app/issuer/license/** 前缀(签发方的命名空间)。加端点时前缀照抄、 绝不允许与平台的映射重名:同一个路径两处 @RequestMapping 会让宿主起不来 (Spring 启动期报重复映射,不是运行期才炸)。
  • ⚠️⚠️ 红线(回报路径):AppLicenseReportBo.REPORT_PATH 这一串在本包与平台部署侧是同一个值 /app/issuer/license/report(平台那段调用是 report-url + 同名常量 的拼接), 平台 security.excludes 放行的也正是这一条。任何一边单独改动都算走偏:只改一边 = 客户的部署报不上来, 表现是「设备列表永远是空」,而空列表看起来完全像「还没人激活过」,等于静默丢掉已有的激活记录。 真要一起改,还得同时看 excludes 那一条 —— 路径变了放行没跟上就是匿名 401,症状同上。
  • ⚠️ frontend/ 两屏与台账页都指在本包端点上(frontend/src/api/license/** 一律 /app/issuer/license/**): 平台侧不再有任何一份同名实现兜着,没装本包的部署上这两屏就是 404,而 404 在页面上显示成 「这个账号还没有许可证」—— 判据请回到本包这一侧查,别去客户账号上找原因。
  • 签发内核在 src/main/java/cn/wujies/license/sign/ 下自己一份,刻意不依赖 wujies-market-core —— 那份开源构件里只有验证侧,签发逻辑挂在它身上就等于让公开仓来决定闭源包能不能签。
  • .gitignore 已加 target/(后端插件构建产物)。

迁移脚本:migrations 字段为什么留空(实测结论)

结论:**脚本必须放进仓库根的 migrations/ 目录(平铺 .sql,文件名带 01- / 02- 序号), app.json 的 migrations 数组留空 [] 是正确写法,不是漏写。** 图床那种「migrations: [] 但仓库里有 migrations/ 目录」的看似矛盾,是同一条设计,不是 bug。

依据(读的是运行期那两处代码,不是文档):

  • AppMigrationService 类注释明写:本类扫描该目录按文件名顺序执行,不去解析 app.json 的 migrations 数组;该字段(含 down)保留为文档与回滚预留,当前不参与执行,回滚未实现 —— 只做 up。
  • listScripts(appCode) / migrationRoot(appCode) 给出实际目录与排序规则: /migrations//*.sql,Files.list + 按文件名 (大小写不敏感)排序 —— 目录里有什么就跑什么。
  • AppPackageDeployService 说明包内 migrations/** 在部署时原子复制到 /migrations//, 所以仓库里平铺、包根里平铺、落位后按 appCode 归目录。
  • 全仓 grep getMigrations() 在平台与中心两侧零调用点,字段确实没有消费者。

本仓三个脚本(按文件名顺序执行):

| 脚本 | 内容 | |---|---| | 01-create-license-ledger.sql | 三条 CREATE TABLE IF NOT EXISTS:app_license_order / app_license_activation / app_redeem_code | | 02-redeem-code-assign.sql | app_redeem_code.owner_user_id(发放给谁)+ 第四个状态 assigned。升级前提,不是可选优化:实体多了这个字段,SELECT/UPDATE 会带上它,存量库没这列就是 Unknown column 'owner_user_id',兑换码台账直接 500 | | 03-license-config.sql | sys_config 的 wujies.license.private-key-file(空值)+ 配置类别字典 license;幂等(MAX+1 主键、按业务键判重、只写 000000) |

⚠️ 目录层级写错会被打包脚本当场指出:package.ps1 对子目录里的 .sql 报 WARN|迁移脚本|子目录里的 .sql 后端扫不到,不会执行,正文里有裸 CREATE TABLE 报 WARN|迁移幂等|…老机重装会炸,请写成 CREATE TABLE IF NOT EXISTS。 ⚠️ 账本判据是 (app_code, script) 且比对 checksum:同名脚本改了内容会直接拒绝执行, 要改就换文件名;换行差异(Windows CRLF / Linux LF)已豁免,不算改动。

上架前的两个外部前提(都不在本仓库里,人工执行)

这两条没做完之前,本包不能当成商业件上架 —— 少任何一条,付费墙都不成立:

  1. Gitee 仓转私有:wujies/wujies-license-plugin 目前是公开仓,必须在 Gitee 网页端把仓库可见性 改为私有(只有人工能在网页里做,本 README 不声称已做 —— 未执行;具体入口以 Gitee「仓库 → 管理」页 实际显示为准,未验证)。另外 8 个付费件已经是私有仓,本包要和它们同一口径。
  2. 私有包必须按凭证下发:目录条目的 visibility 要标成 private(在中心控制台改,别直接改库), 且存储必须是本地磁盘(local)—— 对象存储桶必须公开读,公开直链等于没私有。 逐条步骤与验证 curl 见中心仓 wujies/wujies-market README 的 「断掉公开直链(付费墙成立的前提,运维执行)」一节。中心侧写入还有一道一致性检查 (LicenseVisibilityRule.assertAgrees):licenseRequired: true 的版本不允许挂在 public 条目上。

本机联机验收清单(待执行清单,不是已完成记录)

⚠️ 这一节是「照着做就能跑」的清单,不是验收记录。 本仓没有「已联机验收」的记录:三张表没有任何 库建过的记录、包没有装过的记录、端点没有逐条 curl 过的记录。构建全绿只代表编译与对拍成立,不代表功能验证过。

⚠️ 本机宿主跑在 8086 且 profile=prod ⇒ 下面每一步都在写线上库。 签发、生成兑换码、兑换、 激活、回报、删除设备全都落库;这是这台机器的既定事实,不是本包的特殊性。要拿它当验收环境, 就先接受「验收数据会进线上库、要自己清」。

⚠️ 客户侧两屏与台账页打的是同一批端点:一台没装本包的部署上,客户侧那两屏是 404, 页面看起来完全像「这个账号还没有许可证」,不像「这台没装插件」。

0. 取一个 token(后面每条 curl 都要)

登录体三个字段缺一不可:clientId + grantType(两个 @NotBlank)、以及 tenant.enable: true 时不能留空的 tenantId(留空直接被 TenantException 拒)。 口令走 PasswordLoginBody(username / password)。

curl -s -o login.json -w "%{http_code}\n" -X POST http://127.0.0.1:8086/auth/login \
  -H 'Content-Type: application/json' -H "clientid: &lt;宿主前端的 VITE_APP_CLIENT_ID&gt;" \
  -d '{"tenantId":"000000","username":"&lt;账号&gt;","password":"&lt;口令&gt;","grantType":"password","clientId":"&lt;同上&gt;"}'
TOKEN=$(sed -n 's/.*"access_token":"\([^"]*\)".*/\1/p' login.json)   # 键是 data.access_token,不是 data.token

后续每条 curl 都带两个头:Authorization: Bearer $TOKEN 与 clientid: &lt;同上&gt;(`sa-token.token-name: Authorization + token-prefix: Bearer)。clientid` 的值实读到三处且彼此一致:宿主前端的 VITE_APP_CLIENT_ID、平台 application.yml 的 qrcode.pc-client-id、种子数据 sys_client 那行 —— 文档里不抄这个值,按本机实际配置取。

三条环境前提(都读自代码,不是猜):明文 JSON 能进是因为平台 api-decrypt.enabled: false (@ApiEncrypt 过滤器没注册;哪天真开了,这条 curl 会变 403,那时就改从浏览器 DevTools 抄 token); 验证码 PasswordAuthStrategy 读 captcha.enabled,种子值是 false(当前库里的实际值未验证, 真被拒就去后台「参数设置 → 登录配置」看);本节整条链路都没在本机跑过。

1. 配签发私钥(先配再装,否则签发当场报错)

没配到私钥时签发收到的是:本机没有配置签发许可证用的 RSA 私钥,签发不了许可证。… —— 这一句就是「私钥没配」的证据,不是签名算法坏了。私钥放仓库之外的独立目录(绝不入库、绝不内联), 三条配法见「签发私钥」;前两条(环境变量 / JVM 参数)都要在起宿主之前设好,改了必须重启才生效。

2. 打包

powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1 -CheckOnly   # 非 0 就别往下走
powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1              # 正式包(keys\private.pem 签的是「包」)

产物是 ..\.plugin-dist\license\1.0.7\license-1.0.7.zip(在仓库之外)。⚠️ 打包前先看磁盘: .plugin-dist\license\ 下有哪些版本目录,决定这一步是「首装」还是「重装」—— 上一版 README 记录时 那里只有 1.0.0 / 1.0.1 / dev 三个目录、清单里那个版本从没打过,别把「首装」当「重装修复」。

3. 安装(这一步会建表、种菜单、把后端装进宿主 JVM)

入口是开发台那条(POST /app/dev/install,权限 app:dev:install),不是「应用市场上传 zip」。 admin 是超管(*:*:* 通配命中 app:dev:install 与后面九个 license:ledger:*),所以第 0 步那个 token 直接能用。两道开关都得开着:app-market.plugin-runtime.dev-mode(否则端点 404)与 app-market.dev.enabled (yml 里没有 ⇒ 默认 true)。

curl -s -o install.json -w "%{http_code}\n" -X POST http://127.0.0.1:8086/app/dev/install \
  -H "Authorization: Bearer $TOKEN" -H "clientid: &lt;同上&gt;" -H 'Content-Type: application/json' \
  -d '{"code":"license","zipPath":"&lt;上面那个 zip 的绝对路径&gt;","watch":false}'

⚠️ 这一步是写库动作,且不止台账三张表:app_info / app_version(登记 -dev 版本)/ app_install / sys_menu(种菜单)/ 角色授权 / app_schema_history / app_route_index 都会被动,jar 与 migrations/ 会落位到 plugins-dist,active-plugins.txt 增加一行 —— 验收完要按第 7 步一起收。

再核三件事:三张表在不在(SHOW TABLES LIKE 'app_license%'、SHOW TABLES LIKE 'app_redeem_code'、 SELECT script, success, execution_ms FROM app_schema_history WHERE app_code='license'); plugins-dist\migrations\license 与 active-plugins.txt 是否落位;后台是否出现「许可证签发」菜单。 ⚠️ fixed-plugin-path: [] 意味着启动期不自动加载任何插件工程:热加载只活在当前进程里, 宿主一重启就得重装(或把这一项指到本仓)—— 这是既有的开发模式语义。

4. 运营签发 → 台账

POST /app/issuer/license/ledger/issue,13 个字段逐字取自 AppLicenseIssueBo (lic/userId/customerName/productName/source/tier/grant/apps/bindDomain/versionFrom/ versionTo/expireAt/remark),没有 credential 字段 —— 凭证是服务端签出来的,收现成凭证等于让任何人 往台账里插别人签的授权。

  • tier 与 grant 是仅有的两个 @NotBlank;apps 留空会被 LicenseIssuer.payload 拒签(空名单=白送)。
  • tier=community 签不出来:社区版是一台部署没有凭证时的默认状态;签发页的下拉取 /options 的 issuableTiers(只有 pro / enterprise),不是自己筛档位码。
  • 期限形态与字段的搭调(判据全在 LicenseIssuer.payload):perpetual 的 expireAt 与 versionTo 都必须留空(填 1970-01-01 那种「默认值」会把永久伪装成日期);subscription 的 expireAt 必填、 晚于当前时间、且最远 36 个月后(MAX_SUBSCRIPTION_MONTHS,与官网定价三档一致)、不给 versionTo; version_lock 的 versionTo 必填、expireAt 可空。⚠️ 部署侧还没有比较 to 的代码, 所以一枚不带 exp 的买断当前效果等于永久。
  • source 只认 purchase / manual(留空按 manual);填 redeem 报「来源不能填 redeem」。
  • lic 撞号报「授权编号已存在」(唯一索引 uk_license_order_lic 在拦,不是静默覆盖)。
  • 越权别拿 admin 测:超管 *:*:* 永远 200;要用没勾这九个权限点的普通后台账号才回 403。
  • 台账列表 / 明细返回的 grantLabel / statusLabel / tierLabel / sourceLabel / stateLabel 必须都是中文且不为空 —— 页面只显示服务端给的词,出现 perpetual 这种原值就说明话术漏了。

5. 兑换码 → 兑换 → 下载凭证

  • 生成:POST /ledger/redeem-code,body 含 count / tier / grant / apps / bindDomain / durationDays / versionTo / remark。count 超出 1–500 回「一次生成 1–500 枚兑换码,请分批生成」。
  • 形态与天数:tier=community 直接回「档位 community(社区版)不做兑换码」;subscription 不给正数天数回 「必须给出正数有效天数」,超过 1095 天回「订阅兑换码最长 1095 天(三年)」;perpetual / version_lock 填了天数回「不要填有效天数」;version_lock 不给 versionTo 由内核报「必须给版本上限」。
  • 回读:GET /ledger/redeem-codes?pageNum=1&amp;pageSize=10(statusLabel = 未兑换、codeMasked 只有末四位); ⚠️ statusLabel 已兑换而 lic 为空 = 「码被吃掉但台账没生成」那种事故行,对账就查这一条。
  • 状态筛选:两排胶囊各绑一个参数 —— state(有效/宽限期/已过期/已撤销)与 status (未兑换/已发放/已兑换/已作废),文案读 options 那两族。同一参数只留一个入口(搜索栏里的状态下拉 与「只看未兑换」开关已删);传四个码值以外的东西必须报错,静默返回空表会让人以为「这批发出去没人兑」。 另一条更值钱的:筛「有效」筛不出来的行若 stateLabel 写着「有效」,就是筛选项与行上话术分家了 —— 边界只允许取自 LicenseState.filterBounds,SQL 里出现 86400000 这类自己拼的毫秒数即为走偏。
  • 兑换:POST /app/issuer/license/redeem(客户 token,只要登录)。同一枚码第二次兑换必须失败 (CAS 抢码 WHERE code=? AND status='unused');码为空回「兑换码不能为空」,状态不是 unused 回 「兑换码状态异常,请联系平台客服」。
  • 领取:GET /my/codes 只回编号与元数据,POST /my/codes/{codeId}/claim 按编号领。
  • 越权:GET /my/orders 里能看见自己那枚、看不见别人的;拿 A 的 orderId 用 B 的 token 调详情必须报错 —— 这是这一族唯一没有框架兜底的判据,requireOwned 少一处就是跨账号读凭证。
  • 凭证:GET /app/issuer/license/my/orders/{orderId}/credential 只读、不落库,下载成 .lic。

6. 激活与设备回报(端到端回报这一步现在一定不通,只能手工)

激活走的是平台侧那半(POST /app/license/activate,body {"credential":"…","remark":"…"}, 权限 app:license:edit;本包不提供)。本机这台激活不会产生任何回报记录,拦住的只有一道: app-market.license.report-url 是空串,AppLicenseService.reportActivation 第一行判空就 return。

配上 report-url 之后这条路就该通:那一行拼的是 report-url + AppLicenseReportBo.REPORT_PATH (平台侧那个常量与本包端点逐字一致),匿名可达靠平台 security.excludes 里那一条。 ⚠️ 这条路断掉的症状两边都一样 —— 台账的「激活信息」永远为空,而客户那边看不出任何故障, 因为回报方把所有异常吞成一行 log.warn:接收的那台没装本包就是 404,客户部署还跑着没升级的平台构建 也打不到这里(它手里那份常量还是老路径)。

⇒ 这一步只能带 token 手工 curl(body 三个字段逐字取自 AppLicenseReportBo:credential @NotBlank、 deviceId @NotBlank + @Size(max=128)、hostname @Size(max=255) 可空)。凭证原文要和台账里那一行 完全一致(签发方按原文精确匹配、不解析不验签),对不上回「这枚凭证不在本台账的签发记录里,未登记激活设备」; 同一张许可证下在用设备到 50 台就拒新设备(MAX_ACTIVE_DEVICES)⇒「超过 50 台被拒」这条要 51 台机器才验得了, 本轮没验。

成功后的样子:运营侧设备表出现这一条(deviceId、ip 是服务端看到的来源地址、status=active / statusLabel=在用);删除走 DELETE /my/activations/{activationId},删后那条变 status=released / statusLabel=已解除(不是消失,撤销留痕),同一 activationId 再删一次回 「该设备记录已被删除或状态已变化,请刷新后重试」。

端到端自动回报要先满足三件事:① 平台 security.excludes 里有插件那条路径;② 装机侧把 report-url 配成签发方地址;③ 接收的那台装了本包,且客户部署跑的是常量已对齐的平台构建。

7. 收尾

PUT /app/issuer/license/ledger/{orderId}/revoke → 页面「状态」列与 statusLabel 都是 已撤销 (同一个词,别一个是「吊销」一个是「撤销」);再撤一次回「该许可证已经是撤销状态」; 撤销后下载凭证回「该许可证已被撤销,无法再下载凭证;已经激活的部署不受影响。」

再把验收产生的行从线上库清掉:三张台账表里 remark 标了验收的那几条,加上第 3 步顺手动的那些 (app_info / app_version 的 -dev 行 / app_install / sys_menu 里 license-issuer 那棵子树与角色授权 / app_schema_history / app_route_index),磁盘上还有 plugins-dist 落位的 jar、migrations/license/ 与 active-plugins.txt 里那一行。⚠️ 清到什么程度算干净要你拍板(「整包卸载」走的是平台卸载链路, 它删不删台账三张表没查、也没跑)—— 拍不了就先把这几行留着,别在验收当晚做删除实验。

验收之前先跑的离线门禁

export JAVA_HOME="C:/Users/TX/.jdks/ms-17.0.16"
MVN="C:/Program Files/JetBrains/IntelliJ IDEA 2024.3.3/plugins/maven/lib/maven3/bin/mvn.cmd"
"$MVN" -o -B package                &gt; /tmp/pkg.log   2&gt;&amp;1 ; echo "pkg_exit=$?"
"$MVN" -o -B test -DskipTests=false &gt; /tmp/test.log  2&gt;&amp;1 ; echo "test_exit=$?"   # 3 个测试类、20 条 @Test
cd frontend
npm run typecheck                   &gt; /tmp/tc.log    2&gt;&amp;1 ; echo "tc_exit=$?"
npm run build                       &gt; /tmp/build.log 2&gt;&amp;1 ; echo "build_exit=$?"

⚠️ 每条命令单独取退出码,别 | tail(那会把失败码吞成 0)。 ⚠️ package 不跑测试(父 POM skipTests=true),只有第二条算真跑过测试。 ⚠️ npm run build(vite)不查类型,所以 typecheck 必须单独跑;本仓 frontend 没装 @iconify, 写 ~icons/... 只在 vite 构建期报 not found。

开发环境

git clone git@gitee.com:wujies/wujies-license-plugin.git
cd wujies-license-plugin

启动平台宿主后,管理端「开发工具 → 插件开发」里找到 license 这一行, 「启动后端」(编译并加载 target/classes,带监听)与「启动前端」(常驻 vite build --watch, 保存即重建、刷新生效,没有 HMR)两颗都要点。

要直接落位到本机宿主调试,前端构建前设 WUJIES_FRONTEND_DIST=/app-market-dist/remote-apps (宿主 dev 从 app-market-dist/remote-apps/<code>/ 提供 /remote-apps/**)。

仓库布局

| 位置 | 内容 | |---|---| | app.json | 应用清单,打包器读的唯一事实来源:code / version / license / licenseRequired / assets(frontend + backend)/ menus / dependencies / migrations(留空,原因见「迁移脚本」;routes 不声明) | | menus 树 | license-issuer(M,path=licenseIssuer,order=22)→ license-ledger(C,component=remote:license/license/ledger,perms=license:ledger:list)+ license-config(C,component=remote:license/license/config,perms=system:config:list)→ 台账下 8 个 F。键、type、C 必须有 component、F 必须有 perms、深度 ≤5 都是 AppMenuPlanner 的校验项(同步按 menu_key 幂等 upsert) | | pom.xml、src/ | 后端半:pom.xml(artifactId=wujies-license-plugin、version=1.0.6、packaging=jar)|LicensePluginApplication + controller/{Ledger,Portal,Report} + service/AppLicenseLedgerService + mapper/{Order,Activation,RedeemCode} + domain/{,bo,vo} + sign/{LicenseCredential,LicenseIssuer,LicenseKeySource,LicenseKeys,LicensePayload,LicenseState,LicenseTier,LicenseCatalogApp}|src/test/java/ 三个测试类(对拍 7 条 + 环境探针 5 条 + 签发判据 LicenseIssuerRulesTest 8 条,共 20 条) | | migrations/ | 3 个脚本:台账三表、兑换码发放列、许可配置行(见「迁移脚本」);这三张表只有这里一份事实源,脚本平铺、不要开子目录 | | frontend/ | 远程应用源码,入口 frontend/src/index.ts(manifest.version = 1.0.5;注册 license/license、license/detail、license/ledger、license/config 四个视图键),四屏在 src/views/license/(index.vue / detail.vue / ledger.vue / config.vue,共用 license.scss),接口在 src/api/license/(index.ts 客户侧与 ledger.ts 运营侧都指本包 /app/issuer/license/**) | | src/main/resources/ | 不存在(本包不需要资源配置,签发私钥走宿主配置键) | | package.ps1、package.cmd | 打包脚本(与其余插件仓库逐字同一份母本) | | keys/ | 包签名密钥对 private.pem + public.pem,.gitignore 已忽略;与许可证签发私钥无关 | | docs/screenshots/ | 不存在 —— 本仓没有截图,README 也就不放「预览」一节 |

❓ 常见问题

Q:版本号到底以哪个为准?app.json 是 1.0.7,pom.xml 是 1.0.6,前端 manifest.version 是 1.0.5。 以 app.json 为准(它是清单与包名的唯一事实来源,assets.backend 写的是 …-1.0.7.jar);打包脚本会把 target 里现成的 jar 按清单名复制进包,所以 pom 的真实构件版本不必等于应用版本。前端那个 manifest.version 只影响装载日志里那一行显示,不是判据。⚠️ 但三处该一起改,脚本不会替你对账(历史上就出现过只改清单)。

Q:migrations 数组是空的,是不是漏写了? 不是,正确写法。迁移执行是目录驱动的(扫 /migrations//*.sql),清单那个字段 含 down 只是回滚预留、当前零消费者。详见「迁移脚本」。

Q:签发出错「本机没有配置签发许可证用的 RSA 私钥」? 私钥没配到:按 WUJIES_LICENSE_PRIVATE_KEY_FILE → JVM 参数 → yml → sys_config 四级找一遍。 推荐后台「许可证签发 → 配置」填路径(运行期可改、不用重启),别把 PEM 文本填进去(会被拒)。

Q:客户侧那两屏打开是空的 / 看起来像「这个账号还没有许可证」? 两种可能都长得一样:这台没装本包(端点 404),或者平台 tenant.excludes 少了那三张表 (查询永远返回空行)。判据回到本包这一侧查,别去客户账号上找原因。

Q:「我的许可证」永远为空、兑换码 CAS 永远匹配不到? 平台 application.yml 顶层 tenant: excludes: 少了 app_license_order / app_license_activation / app_redeem_code 之一 —— 自动拼上的 tenant_id 把行过滤掉了,而且不报错。

Q:设备表永远是空? 先看三件事:平台 security.excludes 有没有 /app/issuer/license/report(缺了 401,回报方吞成一行 log.warn); 装机侧 app-market.license.report-url 配没配(本机是空串,第一行就 return);接收的那台装没装本包。 三处任一不满足,症状都是安静地空着。

Q:装完点「配置」页报「操作失败」? sys_config 里没有 wujies.license.private-key-file 那一行 —— 宿主 updateConfig 只改已存在行、不插入。 跑 migrations/03-license-config.sql(幂等)即可。

Q:装完只有管理员能进台账,运营账号 403? 安装只把菜单授给安装者所属角色;其余角色要在「系统管理 → 角色管理」里勾 license:ledger:* 那九个。 ⚠️ 别用超管验越权(*:*:* 永远 200)。

Q:兑换码列表只看到末四位,明文去哪了? 只能按批次回看(GET /redeem-code/batch/{batchNo}/codes,权限 license:ledger:reveal-code), 生成那一刻的响应是唯一一次「整批原文」。⚠️ 明文进不进操作日志由 @Log(isSaveResponseData = false) 决定, 别把它改回 true。

Q:打包时提示「找不到插件目录」? 在本仓库根不要传 -Plugin —— 脚本按「仓库根有没有 app.json」判定布局,传了它就去找子目录清单。

Q:route-index.json 只有 24 条,控制器却有 25 条映射? report 那条路径是常量(AppLicenseReportBo.REPORT_PATH),package.ps1 扫源码读不出常量值。 服务端上传那一路会退回扫 jar 字节码补齐,不是真少一条。

Q:宿主起不来,报重复映射(Ambiguous mapping)? 本包端点前缀是 /app/issuer/license/**,与平台 /app/license/** 刻意分开;往平台或本包任一侧加同名路径 都会在启动期炸。别为了「看起来统一」把前缀改回 /app/license/**。

Q:热加载装上的插件,宿主一重启就没了? 开发台 POST /app/dev/reload 不过 AppPackageDeployService、也不写 active-plugins.txt; 本地安装(/app/dev/install)会落位并写清单,但 fixed-plugin-path: [] 时启动期不自动加载任何工程 —— 要常驻就把这一项指到本仓,或走正式安装链路。

Q:前端构建产物里有裸 vue 之类的 import,会不会找不到? 正常。vue / element-plus / @wujies/ui-shared 由宿主 import map 提供单例,属于刻意 external。

🔒 隐私与外部资源

  • 不收集、不上报任何遥测;台账、激活与兑换码都存本平台数据库,不往外发。
  • 仓库与 README 里不包含任何真实口令、token、私钥或凭证原文:私钥只以文件路径形式出现 (配置键 + 环境变量名),凭证只以「下载成 .lic」这一形态描述。
  • 凭证原文是敏感材料:客户侧只做下载、不打印;运营侧下载走独立权限;生成兑换码的响应只给一次; 兑换码列表只回末四位。这三条都是刻意的口径,不是漏做。
  • 包签名密钥在本机 keys/(已 gitignore),与签发许可证那把 RSA 私钥是两把不同的钥匙, 两把都不入库。

📄 许可证与致谢

商业授权:需要一枚覆盖本应用的有效授权凭证才允许安装与加载(条文见仓库根目录 LICENSE)。 清单 app.json 里 license 为 UNLICENSED、licenseRequired: true —— 与那 8 个付费件 (cms / enterprise / exam / finance / im / mall / member / pay)逐字同口径 (都是 UNLICENSED + licenseRequired: true + backend/-&lt;版本&gt;.jar)。 gallery / hello / quote / social 仍是 MIT 且不带 licenseRequired,本包不跟它们对齐 (只在 menus 的形状上参照 gallery)。三档口径(社区版 / 专业版 / 企业版)见官网文档「授权与版本」。

💬 反馈与建议

参考

平台仓 AGENTS.md §3.15「本机授权:社区版 / 专业版 / 企业版」 与其中「谁是签发方」一节(本包为什么长这样的权威叙述)、 wujies-mall-plugin(带后端 + 商业件的清单与 LICENSE 样板)、 wujies-gallery-plugin(menus 树与 migrations/ 布局样板)、 wujies-market(中心:目录可见性与「断掉公开直链」那节)、 wujies-ui(@wujies/* 四件套源码仓)、 文档站「插件开发」与 「打包应用」。 </code>

v1.0.8 2026-11-15 平台 >=5.6.2 <6.0.0 211 KB

其他

  • chore(release): license 1.0.8 —— 版本号与包内 jar 名同步 (e2220fa)
  • docs: 注释与前端说明去掉第三方产品名指代 (f2ba6a8)
  • docs: README 改为 Halo/NexT 版式并更新品牌 logo 地址 (7183216)
v1.0.7 2026-11-08 平台 >=5.6.2 <6.0.0 211 KB

新增

  • 新增授权配置页与 03-license-config 迁移;订单列表接口对齐

修复

  • 宿主公钥体检改成占位符感知,不再把 ${WUJIES_PACKAGE_PUBLIC_KEY:} 当一把钥

其他

  • license 1.0.7 —— 版本号与包内 jar 名同步
  • 1.0.6 —— 许可证一码一机,换机先解绑
  • 1.0.5 —— 兑换码运营侧补齐 + 对齐主线删除签发后的口径
  • 1.0.4 —— 客户侧端点也切到 /app/issuer 前缀

评论区需要浏览器启用 JavaScript 才能加载。