包安全与签名

这一页解决什么问题复制标题链接

应用包（zip）的两个部分都是完全可信代码：backend/*.jar 是任意 Java 代码，跑在宿主 JVM 里； frontend/** 是跑在宿主同源上下文里的 JS，能拿用户的 token 调任何接口。 所以"能不能装"这件事要由平台回答三个问题，这一页就是这三个问题的答案：

前两个机制都在 wujies-platform/wujies-modules/wujies-app-market/src/main/java/cn/wujies/appmarket/security/， 本页每条断言都指向那里的类或 wujies/wujies-plugins/package.ps1 —— 看完可以直接去核对。

什么时候必须读：改 app-market/security/** 或打包器的签名流程；要切 app-market.security.mode； 排查"上传 / 部署被安全检查拒绝"；要给历史未签名版本补签名。

为什么必须有签名复制标题链接

所以"装一个来路不明的应用"和"让陌生人在你服务器上执行代码"是同一件事。

静态扫描（关键字黑名单、危险 API 检测）挡不住有意作恶的包，只能提高门槛。 签名是唯一真防线：它不判断代码好坏，只回答「这个包是不是我签发的、有没有被改过」。 答不上来的包就不装。这段推导写在 PackageSecurityInspector 的类注释里。

产物白名单管的是另一件事复制标题链接

白名单挡不住恶意代码，但能挡掉「往前端目录塞个 .jsp 让 Web 容器执行」这类结构性问题 —— 因为前端目录就是宿主的静态资源目录，同源。

规则由 PackageSecurityInspector 的两个常量与 checkArtifacts 决定（ALLOWED_TOP_LEVEL / HOME_LEVEL_FILES / FORBIDDEN_FRONTEND_EXT）：

frontend/ 下无论如何都拒绝的扩展名（写进配置也改不掉）：

.jsp .jspx .jspf .php .phtml .war .jar .class
.exe .dll .so .dylib .sh .bat .cmd .ps1 .vbs
.properties .xml .yml .yaml .sql

允许的扩展名由 app-market.security.allowed-frontend-extensions 配置，默认值（注解与 application.yml 里是同一串）：

.js,.mjs,.cjs,.css,.json,.svg,.png,.jpg,.jpeg,.gif,.webp,.ico,.bmp,
.woff,.woff2,.ttf,.otf,.eot,.map,.txt,.html,.wasm

分离式签名（signature.txt）复制标题链接

签名是分离式的：包根一个 signature.txt，覆盖除它自己以外的全部文件 —— app.json、backend/*.jar、frontend/**、migrations/*.sql（会真实执行的 SQL）都在内。

被签名的数据怎么算出来复制标题链接

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

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

拼出来的整段 UTF-8 字节就是要签名的数据，算法是 SHA256withRSA（PackageKeys.ALGORITHM）。 两条要点（PackageDigest 类注释）：

• 路径参与签名 —— 否则把 A 文件改名成 B 就能逃过校验；
• 只签名内容、不签名 zip 元数据（时间戳、压缩级别、外部属性）—— 否则重新打一次包签名就废了。 所以「按目录签名」与「按 zip 签名」算出来是同一份数据，这也是打包脚本能先给暂存目录签名、 再打 zip 的原因。

归一化细则（PackageDigest.normalize / canonicalText）：

signature.txt 长什么样复制标题链接

PackageSignerMain.sign 写出的就是下面四行（后两行是注释）：

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

解析侧（PackageSecurityInspector.parseSignatureFile）跳过空行与 # 开头的行； 遇到 app-market-signature/ 前缀的行必须是 app-market-signature/1，否则报「不支持的签名格式」； 第一个非注释行是算法，必须恰好是 SHA256withRSA，否则报「不支持的签名算法」； 第二个非注释行是 base64 签名，解不出来报「签名内容不是合法的 base64」。 后两行只在"手里只有一个签名文件"时用来核对覆盖范围。

四个类与「纯 JDK」这条硬约束复制标题链接

签名工具是用 -cp wujies-modules/wujies-app-market/target/classes 启动的， 这个 classpath 上没有 Spring、没有 wujies-common-*。

在哪校验：两处，缺一不可复制标题链接

AppPackageDeployService.deploy 里的顺序是刻意排的（deploy(Long, boolean)）：

requireVersion → download → verifyChecksum(MD5/SHA256) → inspectOrThrow → 解包落位

校验和的顺序也不能调：校验和只证明"没下坏"，证明不了"是不是我们签发的"。 enforce 下不通过的包连解都不会解，插件目录里不会落位任何文件 —— 这一点实测过。

失败时抛的就是这句话（inspectOrThrow）：

应用包安全检查未通过（app-market.security.mode=enforce）：应用包未签名（缺少 signature.txt）。…

结论还会落到两个地方：部署报告（POST /app/version/{versionId}/deploy 的返回）里的 security 字段，以及上传返回体 AppPackageParseVo.securityNote。 格式都是 Report.summary() 的一句话版本：模式=enforce, 签名=有效, 无问题。

三档模式（app-market.security.mode）复制标题链接

判定就一行（inspect 末尾）：accepted = !enforce || problems.isEmpty()。 PackageSecurityInspector.isEnforce() 是给调用方判断"问题是否只是提示"用的，当前没有调用方。

打包脚本帮你记住"要签名"复制标题链接

宿主是 enforce，"忘了签名"等于白打一个包，所以 wujies/wujies-plugins/package.ps1 把 keygen、签名、自查、比对公钥串成了一个入口（在插件仓库根执行）：

几条纪律：

• 私钥只留在发布方，放在插件仓库 keys/（已 gitignore）；公钥不是秘密，填进 app-market.security.public-key 即可。私钥一旦进仓库，任何人都能签出被认可的包。
• 绝不覆盖已有私钥：keygen 在目录里已存在 private.pem 或 public.pem 时直接拒绝 （覆盖等于让所有已签发的包失效，必须是显式动作）。
• 换钥要同时做三件事：① 重新生成；② 把新 public.pem 贴进 public-key （-SyncPublicKey 可代劳）；③ 重建宿主并重启。旧钥签过的包届时全部作废， 得按下面的「就地重签」重签一遍。
• -Keygen 未显式给 -SigningKey 时，默认落点仍是历史路径<平台仓库>\plugins\keys\private.pem （脚本第 697 行），而平台仓库里已经没有 plugins/ 了。所以要么显式传 -Keygen -SigningKey keys/private.pem，要么生成后自己把 keys/ 挪到插件仓库 —— 否则自动发现（Find-SigningKey 先查插件仓库 keys/）找不到它。

密钥生成、算法逐字说明与底层 PackageSignerMain 命令见 密钥与签名， 打包参数全表见 打包应用。

切换 enforce 之前先自检复制标题链接

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

实现是 SignatureReadinessService.check()：把已发布（app_version.status = '1' 且未删除） 的版本逐个下载验签，分类计数 + 阻止切换的原因 + 逐版本明细。响应字段：

分类与处置（Item.status）：

blockers 的组成只有四条：unsigned > 0、invalid > 0、unverifiable > 0、以及"未配公钥"。 failed 刻意不进去 —— 它既不算通过也不算阻止。

把历史版本「就地重签」复制标题链接

用途：把已发布但未签名的版本补齐。目标是版本号与状态都不动，只把包换成"原内容 + signature.txt"。

# 全程在**平台仓库根**执行（-cp 用相对路径）；私钥按你的实际位置替换
$base   = 'http://127.0.0.1:8080'                       # 宿主地址
$pkgUrl = '<该版本的 package_url，取自 app_version.package_url>'

# 1) 下载已发布的包，先核对 sha256 与 app_version.package_sha256 一致
curl.exe -s -o original.zip $pkgUrl

# 2) 解包 → 只加签名（内容一个字节都不动）→ 自查 → 重打包
Expand-Archive original.zip pkg
java -cp wujies-modules/wujies-app-market/target/classes `
    cn.wujies.appmarket.security.PackageSignerMain sign pkg ..\wujies\wujies-plugins\keys\private.pem
java -cp wujies-modules/wujies-app-market/target/classes `
    cn.wujies.appmarket.security.PackageSignerMain verify pkg ..\wujies\wujies-plugins\keys\public.pem
    # ↑ 必须打印「签名有效」，否则不要往下走
Compress-Archive -Path "pkg\*" -DestinationPath signed.zip -CompressionLevel Optimal

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

# 4) 用返回的 packageUrl / packageSize / packageMd5 / packageSha256 更新**那一行** app_version

注意事项：

补签完成后重新调一次 GET /app/console/signature-readiness，确认 ready=true（unsigned=0 且 invalid=0）。

怎么核对这一页复制标题链接

相关阅读复制标题链接

• 密钥与签名 —— 密钥生成、算法逐字说明、换钥
• 安全校验模式 —— off / warn / enforce 的取舍与切换步骤
• 应用市场模块 —— security/ 在这个模块里的位置
• 应用生命周期 —— 部署 / 安装 / 升级里"校验在解包之前"这一步
• 目录中心化与版本形态 —— 用户版下哪些上架端接口被挡
• 配置项索引 —— app-market.security.* 的完整条目
• 备份与安全 —— 密钥纪律与上线前脱敏
• 故障排查 —— "安装报应用包未签名"怎么定位