> 本文整理自平台文档 docs/wujies/5.x/platform/package/security.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-de294274e0ec-cover.svg)
这一页解决什么问题
应用包(zip)的两个部分都是完全可信代码:backend/*.jar 是任意 Java 代码,跑在宿主 JVM 里; frontend/ 是跑在宿主同源上下文**里的 JS,能拿用户的 token 调任何接口。 所以"能不能装"这件事要由平台回答三个问题,这一页就是这三个问题的答案:
| 问题 | 管这件事的机制 | 落点 |
|---|---|---|
| 包内允许出现哪些文件? | 产物白名单 | PackageSecurityInspector.checkArtifacts |
| 这个包是不是我签发的、上传之后有没有被改过? | 分离式签名(包根 signature.txt) | PackageDigest + PackageSignerMain |
| 检查到什么程度、什么时候拒? | 三档模式 off / warn / enforce | app-market.security.mode |
前两个机制都在共用内核 wujies-platform/wujies-modules/wujies-market-core/src/main/java/cn/wujies/appmarket/security/, 中心上架服务与各平台部署跑的是同一份字节码;本页每条断言都指向那里的类或各应用仓库自带的 package.ps1(wujies-<code>-plugin/package.ps1)—— 看完可以直接去核对。
什么时候必须读:改 app-market/security/** 或打包器的签名流程;要切 app-market.security.mode; 排查"上传 / 部署被安全检查拒绝";要给历史未签名版本补签名。
为什么必须有签名
| 部分 | 它能干什么 |
|---|---|
| 后端 jar | 跑在宿主 JVM 里 —— 能读数据库、读配置、发任何网络请求 |
| 前端 JS | 跑在宿主同源上下文 —— 能拿用户 token 调任何接口 |
所以"装一个来路不明的应用"和"让陌生人在你服务器上执行代码"是同一件事。
静态扫描(关键字黑名单、危险 API 检测)挡不住有意作恶的包,只能提高门槛。 签名是唯一真防线:它不判断代码好坏,只回答「这个包是不是我签发的、有没有被改过」。 答不上来的包就不装。这段推导写在 PackageSecurityInspector 的类注释里。
产物白名单管的是另一件事
白名单挡不住恶意代码,但能挡掉「往前端目录塞个 .jsp 让 Web 容器执行」这类结构性问题 —— 因为前端目录就是宿主的静态资源目录,同源。
规则由 PackageSecurityInspector 的两个常量与 checkArtifacts 决定(ALLOWED_TOP_LEVEL / HOME_LEVEL_FILES / FORBIDDEN_FRONTEND_EXT):
| 位置 | 规则 |
|---|---|
| 包根 | 只允许 app.json、signature.txt 与包内路由清单 route-index.json(HOME_LEVEL_FILES),其它文件一律报「包根出现不允许的文件」 |
| 顶层目录 | 只允许 backend/、frontend/、migrations/ 三个 |
backend/ | 只允许 .jar;且清单 assets.backend 声明了哪个 jar 时,目录下的其它 jar 会被报成「清单未声明的产物」 |
migrations/ | 只允许 .sql |
frontend/ | 必须命中配置的白名单扩展名,且再减一层硬禁止 |
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
MAX_REPORTED = 6:问题多于 6 条时报告只保留前 6 条,避免把任务日志刷满(checkArtifacts 末尾)。 包内有重名条目时直接计为问题并跳过白名单检查(zipReadable = false)—— 解包时后者覆盖前者, 而签名只算得出一份。
分离式签名(signature.txt)
签名是分离式的:包根一个 signature.txt,覆盖除它自己以外的全部文件 —— app.json、backend/*.jar、frontend/**、migrations/*.sql(会真实执行的 SQL)、route-index.json 都在内。
JSON 的键序在不同语言 / 库之间不保证一致。把签名放进被签名的 JSON 里,就得先做一套"规范化 JSON", 跨语言极易出错;独立文件完全没有这个问题。这段理由写在 PackageDigest.SIGNATURE_FILE 的注释上。
### 被签名的数据怎么算出来
对包内每个文件(排除 signature.txt 自己),按路径字符串升序依次拼:
<相对路径>\n<内容 SHA-256 十六进制小写>\n
拼出来的整段 UTF-8 字节就是要签名的数据,算法是 SHA256withRSA(PackageKeys.ALGORITHM)。 两条要点(PackageDigest 类注释):
所以「按目录签名」与「按 zip 签名」算出来是同一份数据,这也是打包脚本能先给暂存目录签名、 再打 zip 的原因。
- 路径参与签名 —— 否则把 A 文件改名成 B 就能逃过校验;
- 只签名内容、不签名 zip 元数据(时间戳、压缩级别、外部属性)—— 否则重新打一次包签名就废了。
归一化细则(PackageDigest.normalize / canonicalText):
| 项 | 规则 |
|---|---|
| 排序 | 实现里自己 TreeMap 排序,不依赖调用方传进来的是有序 Map |
| 路径分隔符 | 条目名里的 \ 一律先换成 /(Windows 的 Compress-Archive 会写反斜杠) |
| 跳过不参与的条目 | signature.txt、目录项、__MACOSX/ 下的、绝对路径或含 : 的、含 .. 段的、空名 |
| 内容摘要 | 该文件原始字节的 SHA-256,十六进制小写 |
| 单条目上限 | 256MB(MAX_ENTRY_BYTES,与解包侧 AppPackageDeployService 一致) |
| 重名条目 | 直接拒绝:应用包内存在重名条目: <name> |
### 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」。 后两行只在"手里只有一个签名文件"时用来核对覆盖范围。
签名文件里没有 keyId:服务端只有一把 public-key,所以"换钥"天然是全局作废旧包的操作。
### 四个类与「纯 JDK」这条硬约束
| 类 | 职责 | 纯 JDK? |
|---|---|---|
PackageDigest | 规范化(签名与校验共用这一份) | 是 |
PackageSignerMain | 离线命令行 keygen / sign / verify | 是 |
PackageKeys | 密钥解析(签名侧与校验侧共用) | 是 |
PackageSecurityInspector | 白名单 + 验签 + 模式判定(inspectOrThrow 在 enforce 下抛异常) | 否 —— 带 ServiceException 与 Spring @Value |
签名工具是用 `-cp wujies-modules/wu
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-de294274e0ec-guide.svg)


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