中国 帮助

密钥与签名

这一页解决三件事:密钥放在哪、怎么生成与签名、换钥要同时做哪三件事。 签名回答的唯一问题是:这个包是不是我签发的、上传之后有没有被改过。 它不判断代码好坏。为什么必须有签名(以及白名单管的是另一件事)见 [包安全与签名](/docs/wu

密钥与签名
封面

> 本文整理自平台文档 docs/wujies/1.x/package/signing.mdx,用于站点内容演示。

(https://console.wujies.cn/remote-apps/cms-assets/doc-9f62fed8781c-cover.svg)

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

签名回答的唯一问题是:这个包是不是我签发的、上传之后有没有被改过。 它不判断代码好坏。为什么必须有签名(以及白名单管的是另一件事)见 [包安全与签名](/docs/wujies/1.x/advanced/security);off / warn / enforce 三种模式和「现在能不能切 enforce」见 [安全校验模式](/docs/wujies/1.x/package/security-modes)。

---

四样东西,别混

东西位置 / 名字谁读它
私钥wujies/wujies-plugins/keys/private.pem只有打包时的 PackageSignerMain sign 读它
公钥与私钥同目录的 public.pem打包后的自查(verify);以及和宿主配置比对
宿主配置项app-market.security.public-key(wujies-platform/wujies-admin/src/main/resources/application.yml)PackageSecurityInspector(上传/下载校验)、SignatureReadinessService(自检)
包内签名文件包根 signature.txt校验侧 PackageSecurityInspector.parseSignatureFile

一句话记住:私钥只签名、公钥只验签;-SigningKey 只是私钥路径,签名是打包时算出来的产物(包根 signature.txt),不是某个"打开签名"的开关。

---

密钥放在哪

主用位置是插件仓库的 keys/,也就是 wujies/wujies-plugins/keys/:private.pem + public.pem。该目录在 wujies/wujies-plugins/.gitignore 第 10 行(keys/)被忽略,所以它只存在于发布方本机。目录结构见 [仓库结构](/docs/wujies/1.x/design/repo-layout)。

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

顺序位置
1环境变量 WUJIES_SIGNING_KEY
2<插件仓库>/keys/private.pem(即上表主用位置)
3<平台仓库>/plugins/keys/private.pem(拆仓库前的历史位置)
4<平台仓库>/keys/private.pem

package.ps1 在 -Keygen 分支里写死的默认路径是 <平台仓库>\plugins\keys\private.pem(package.ps1:697),而本仓库实际在用的私钥在插件仓库 keys/ 下。

所以要么显式指定落点,要么记住这一条:

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

(-Keygen 要求路径以 private.pem 结尾,否则直接报错 —— keygen 固定产出 private.pem / public.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):

项值
算法与长度RSA 2048(KeyPairGenerator.getInstance("RSA").initialize(2048))
私钥PEM,标签 -----BEGIN PRIVATE KEY-----(PKCS#8)
公钥PEM,标签 -----BEGIN PUBLIC KEY-----(X.509 SubjectPublicKeyInfo)
文件名写死 private.pem / public.pem,每行 64 字符

private.pem 或 public.pem 任一存在就报错:

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

覆盖密钥等于让所有已签发的包失效,所以必须是显式动作。(package.ps1 在这一步之前还会先查一次 private.pem 并报「目录里已经有 private.pem…请先手工备份并移走它」。)

签名工具随应用市场模块一起编译。target/classes 里没有那个 class 时报:

找不到签名工具类: <平台仓库>\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-----

配置项位置与生效时机见 [配置参考](/docs/wujies/1.x/reference/config):public-key 是启动期读入的 @Value(PackageSecurityInspector:100),改完必须重建宿主 + 重启。

---

给包签名(sign)

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

# 在插件仓库根执行;以 wujies-hello 为例
powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1 `
    -Plugin wujies-hello -SigningKey keys\private.pem
参数作用
-SigningKey <私钥路径>私钥。传了就在打 zip 之前给暂存目录签名,产出包根 signature.txt
-SigningPublicKey <公钥路径>自查用公钥,默认取 -SigningKey 同目录下的 public.pem;同目录没有就跳过自查(只提示)
-SyncPublicKey把公钥写进宿主 application.yml 的 public-key: 块,并提醒必须重建宿主 + 重启
-NoSign显式不签名。与 -SigningKey 互斥(同时传直接报错)
-Keygen只生成密钥,不构建不打包

两个自动行为要知道(都在 package.ps1):

  • 传了不存在的路径、且以 private.pem 结尾 → 自动 keygen 到该目录再接着签名(package.ps1:1058-1070)。这是"第一次用"的最短路径;
  • 未传 -SigningKey 且本机没有私钥 → 不会自动生成(新钥和宿主配的公钥对不上,生成了也只会得到一堆被拒的包),而是 Write-Warning 说清「宿主 app-market.security.mode=enforce 时这个

本文导览

(https://console.wujies.cn/remote-apps/cms-assets/doc-9f62fed8781c-guide.svg)

章节导览
THE END

喜欢就支持以下吧

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

回到内容