密钥与签名

这一页解决三件事：密钥放在哪、怎么生成与签名、换钥要同时做哪三件事。

签名回答的唯一问题是：这个包是不是我签发的、上传之后有没有被改过。 它不判断代码好坏。为什么必须有签名（以及白名单管的是另一件事）见 包安全与签名；off / warn / enforce 三种模式和「现在能不能切 enforce」见 安全校验模式。

四样东西，别混复制标题链接

一句话记住：私钥只签名、公钥只验签；-SigningKey 只是私钥路径，签名是打包时算出来的产物（包根 signature.txt），不是某个"打开签名"的开关。

密钥放在哪复制标题链接

主用位置是插件仓库的 keys/，也就是 wujies/wujies-plugins/keys/：private.pem + public.pem。该目录在 wujies/wujies-plugins/.gitignore 第 10 行（keys/）被忽略，所以它只存在于发布方本机。目录结构见 仓库结构。

不带 -SigningKey 时，package.ps1 的 Find-SigningKey 按下面的顺序找第一个存在的私钥：

# 落在插件仓库（推荐，与自动发现的第 2 顺位一致）
powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1 -Keygen -SigningKey keys\private.pem

生成密钥（keygen）复制标题链接

# 在插件仓库根 wujies/wujies-plugins/ 执行；目录不存在会自动建
powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1 -Keygen -SigningKey keys\private.pem

底层就是 PackageSignerMain keygen 这一条纯 JDK 命令（脚本只是把 keygen + 公钥比对 + 提示串起来）：

# 在平台仓库根 wujies-platform/ 执行
java -cp wujies-modules\wujies-app-market\target\classes `
    cn.wujies.appmarket.security.PackageSignerMain keygen wujies\wujies-plugins\keys

产出与格式（PackageSignerMain.keygen / writePem）：

失败: 密钥已存在，拒绝覆盖: <目录>（要轮换请先自行备份并移走旧密钥）

找不到签名工具类: <平台仓库>\wujies-modules\wujies-app-market\target\classes\cn\wujies\appmarket\security\PackageSignerMain.class
签名工具随应用市场模块一起编译，请先构建平台：
    mvn -pl wujies-admin -am -B install -DskipTests

生成成功后，keygen 会直接打印一段可以粘贴进 yml 的片段（mode 是提示文字，按你的实际模式填）：

app-market:
  security:
    mode: enforce            # 确认所有包都能通过后，从 warn 切到 enforce
    public-key: |
      -----BEGIN PUBLIC KEY-----
      <你的公钥内容>
      -----END PUBLIC KEY-----

配置项位置与生效时机见 配置参考：public-key 是启动期读入的 @Value（PackageSecurityInspector:100），改完必须重建宿主 + 重启。

给包签名（sign）复制标题链接

日常只需要一个参数。不传 -SigningKey 时脚本会自动发现本机私钥（上表 4 个候选位置），发现不了才警告：

# 在插件仓库根执行；以 wujies-hello 为例
powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1 `
    -Plugin wujies-hello -SigningKey keys\private.pem

两个自动行为要知道（都在 package.ps1）：

• 传了不存在的路径、且以 private.pem 结尾 → 自动 keygen 到该目录再接着签名（package.ps1:1058-1070）。这是"第一次用"的最短路径；
• 未传 -SigningKey 且本机没有私钥 → 不会自动生成（新钥和宿主配的公钥对不上，生成了也只会得到一堆被拒的包），而是 Write-Warning 说清「宿主 app-market.security.mode=enforce 时这个包上传/部署会被拒绝」。注意脚本在这一栏里给出的路径提示仍写着历史位置 <平台仓库>\plugins\keys\private.pem（package.ps1:1117），实际自动发现以"密钥放在哪"那节的表为准。

签名成功时会看到三行（前两行来自 PackageSignerMain.sign，第三行来自脚本的自查）。下面这段是真实的一次 gallery-1.0.5 打包输出：

  使用私钥签名: …\keys\private.pem
已签名: …\.plugin-dist\gallery\1.0.5\gallery-1.0.5\signature.txt
  覆盖 5 个文件（不含 signature.txt）
  签名自查通过

自查用的是同一份规范化实现（PackageDigest）+ verify，所以它能提前发现「签出来的东西后端不认」，而不是等安装时才炸。

签名后脚本还会顺手比对宿主的 public-key：一致打 ✓ 公钥与宿主 …application.yml:NNN 一致，不一致或为空就警告并说清改法。比对用的是 PackageKeys 同一套规范化（去掉 PEM 标记 + 所有空白），刻意不自己写一份"公钥相等"的判定。

三个子命令复制标题链接

工具是 cn.wujies.appmarket.security.PackageSignerMain，退出码 0 成功 / 1 失败：

verify 目录与 zip 都支持（目录走 fileDigestsOfDir，zip 走 fileDigestsOfZip），这正是下面「只签内容、不签 zip 元数据」换来的性质。

$classes = "wujies-modules\wujies-app-market\target\classes"   # 相对平台仓库根
$keys    = "keys"                                              # 相对插件仓库根

# 生成
java -cp $classes cn.wujies.appmarket.security.PackageSignerMain keygen $keys

# 签名（package.ps1 会自动调用，一般不用手敲）
java -cp $classes cn.wujies.appmarket.security.PackageSignerMain sign ..\.plugin-dist\hello\1.0.0\hello-1.0.0 $keys\private.pem

# 校验（目录或 zip 都行）
java -cp $classes cn.wujies.appmarket.security.PackageSignerMain verify ..\.plugin-dist\hello\1.0.0\hello-1.0.0.zip $keys\public.pem

签名工具只依赖纯 JDK复制标题链接

这是硬约束，不是风格偏好：签名工具是用 -cp wujies-modules/wujies-app-market/target/classes 启动的，这个 classpath 上没有 Spring、没有 wujies-common-*。

NoClassDefFoundError: cn/wujies/common/core/exception/ServiceException

签名算的是什么复制标题链接

规范化由 PackageDigest 实现，签名方与校验方共用同一份。两边各写一遍实现是这类系统最常见的自伤方式 —— 差一个字节就永远验不过。

对包内每个文件（排除 signature.txt 自己），按路径字符串升序依次拼：

<相对路径>\n<内容 SHA-256 十六进制小写>\n

即先写路径、一个换行符，再写该文件内容的 SHA-256（64 位小写十六进制）、一个换行符。全部片段连起来的整段 UTF-8 字节就是要签名/校验的数据（下称规范化文本）。

签名本身：算法 SHA256withRSA，签的是规范化文本的 UTF-8 字节，签名编码是单行 Standard Base64。

signature.txt 的格式复制标题链接

位置在包根。下面这个样本取自历史目录里的 wujies/wujies-plugins/dist-packages/gallery-1.0.5/signature.txt（那是产物默认落点还在仓库内时打的包；现在的默认落点已改到仓库外的 <插件仓库的上一级>\.plugin-dist\<code>\<version>\<code>-<version>\，见打包应用）：

app-market-signature/1
SHA256withRSA
<base64 签名>
# 覆盖文件数: 5
# 内容摘要: <规范化文本的 SHA-256 十六进制小写>

校验侧的解析规则（PackageSecurityInspector.parseSignatureFile）：跳过空行与 # 开头的注释行；app-market-signature/ 前缀的行必须是 app-market-signature/1，否则报「不支持的签名格式」；第一个非注释行是算法，必须恰好是 SHA256withRSA（否则「不支持的签名算法」）；第二个非注释行是 base64 签名，解不出报「签名内容不是合法的 base64」；缺签名内容报「签名文件格式不正确（缺少签名内容）」。

两条设计要点复制标题链接

为什么不把签名塞进 app.json复制标题链接

因为 JSON 的键序在不同语言/库之间不保证一致。把签名放进被签名的 JSON 里，就得先做一套"规范化 JSON"（排序键、固定分隔符、统一转义），跨语言极易出错；独立文件完全没有这个问题。

校验发生在哪两个点复制标题链接

下载后的那次校验在校验和之后、解包之前（AppPackageDeployService:188）：enforce 下不通过的包不会落位任何文件。

失败时的两句话（inspectOrThrow 抛的 ServiceException，前缀固定是 应用包安全检查未通过（app-market.security.mode=enforce）：）：

应用包未签名（缺少 signature.txt）。签名是识别「包是否被改过」的唯一手段，开放第三方上架前必须开启强制校验。
应用包签名校验失败: 签名与包内容不匹配。包内容可能被篡改，或不是用对应私钥签发的。
应用包带签名，但服务端未配置 app-market.security.public-key，无法校验。      ← 公钥没配时是这一句

部署报告的 security 字段就是同一份结论的一句话版本（AppPackageDeployService:311 的 security.summary()），形如 模式=enforce, 签名=有效, 无问题。上架时同一句话由 AppPackageParseVo.securityNote 返回。

签名就绪度自检复制标题链接

GET /app/console/signature-readiness      # 权限 app:console:list

SignatureReadinessService.check() 把 app_version 里已发布（status = 1，见 AppMarketConstants.VERSION_STATUS_RELEASED）的版本逐个下载验签，直接回答「现在能不能切 enforce」。它属于上架端（控制台就是目录的所有者，直接用 Mapper 是正常的），所以用户版下不可用：/app/console/** 被形态闸门挡住，而它不在例外清单里（MarketEdition.java:62-69）。

换钥要同时做三件事复制标题链接

1. 重新生成密钥对（旧私钥丢了就只能重来，没有找回的办法）。先备份并移走旧钥，keygen 拒绝覆盖。
2. 把新的 public.pem 整段贴进 app-market.security.public-key —— package.ps1 -SyncPublicKey 可以代劳（写成 public-key: | 块，并吞掉旧的 PEM 行）。
3. 重建宿主并重启：mvn -pl wujies-admin -am -B install -DskipTests。

换钥的代价取决于已经签过多少包：旧钥签过的包全部作废，得逐个重新签一遍，最后再调一次 GET /app/console/signature-readiness 确认 ready=true。所以正式对外发布前，私钥就该备份好、尽量别换（密钥纪律见 备份与安全）。

把历史未签名的包「就地重签」复制标题链接

用于把已发布但未签名的版本补齐 —— 版本号与状态都不动，只把包换成「原内容 + signature.txt」。

# 1) 下载已发布的包，先核对 sha256 与 app_version.package_sha256 一致
curl.exe -s -o original.zip <该版本的 package_url>

# 2) 解包 → 只加签名（内容一个字节都不动）→ 自查 → 按同样的方式重打包
Expand-Archive original.zip pkg
java -cp wujies-modules\wujies-app-market\target\classes `
    cn.wujies.appmarket.security.PackageSignerMain sign pkg <插件仓库>\keys\private.pem
java -cp wujies-modules\wujies-app-market\target\classes `
    cn.wujies.appmarket.security.PackageSignerMain verify pkg <插件仓库>\keys\public.pem   # 必须打印"签名有效"
Compress-Archive -Path "pkg\*" -DestinationPath signed.zip -CompressionLevel Optimal

# 3) 走上传接口（服务端落对象存储并回填校验和）
curl.exe -X POST http://<host>/app/package/parse -F "file=@signed.zip" -F "appId=<appId>"

# 4) 用返回的 package_url / package_size / package_md5 / package_sha256 更新**那一行** app_version
#    （版本号 version 与状态 status 都不动）

注意事项：

相关阅读复制标题链接

• 打包与上架 —— 整条发布链路与三个动作的区别
• 打包应用 —— package.ps1 参数表、-Keygen / -NoSign 的交互
• 上架与发布 —— 上传时的那次校验与端点
• 安全校验模式 —— off / warn / enforce 与切换步骤
• 包安全与签名 —— 白名单规则与签名的定位
• 配置参考 —— public-key 的生效时机与容器化覆盖
• 备份与安全 —— 密钥纪律与私钥归档