简介围绕 Google Play 应用签名更新场景整理的 pepk 源码材料面向 Android 开发者、应用发布维护人员以及需要研究签名迁移与密钥处理流程的技术人员用于理解签名更新过程中密钥导出、加密传输及相关校验逻辑的实现方式。压缩包共 2000 个文件包含 1999 个 Java 源码文件和 1 个 txt 文件整体约 5.02MBJava 文件承载核心实现txt 可用于辅助查阅目录便于按类定位关键代码。已有 372 人学习或下载适合作为源码级参考资料。读者可结合代码梳理 pepk 在签名更新中的调用关系观察证书路径校验、摘要算法、分组加密等底层组件的组织方式并据此开展流程对照、问题排查、二次开发或教学研究提升对 Android 应用签名迁移机制的整体理解。1. 更新 Google Play 签名从一次密钥覆盖事故说起上个月接了个收尾的活某应用要更新 Google Play 签名交接的人翻到一份 pepk 源码直接建了个 keystore 把旧文件覆盖了接着用 JDK 17 跑 jar抛出一行 NoClassDefFoundErrorPlay Console 那边又提示上传密钥与已注册证书不匹配发布链路停了三天。pepk 这套工具不复杂一个 jar、一个公钥、一条命令但它夹在密钥生命周期的中间前面连着 keytool 生成的密钥库后面连着控制台的应用签名配置任何一处版本或参数错报错都不给因果只给一行堆栈。下面按我实际装过一遍的顺序写环境怎么列、密钥怎么生成、源码怎么构建、加密导出怎么跑、上传后怎么验证。适合手里有一个要更新签名的应用、并且还拿得到密钥库密码的人。2. 环境清单JDK、keytool 与 pepk 三件套的版本取舍pepk 是纯 Java 程序整个环境其实只有三样东西一个能跑起来的 JDK、JDK 自带的 keytool、以及 pepk 本身。真正容易出问题的不是“装没装”而是“装了三个版本命令行调用的是哪个”。我见过机器上同时存在系统自带的 OpenJDK、某个 IDE 捆绑的 JDK、以及手动解压的一份 JDK 8java -version显示 8但JAVA_HOME指向 17构建脚本和 jar 各跑各的排查时非常容易出现难以定位的怪问题。2.1 JDK 选 8 还是 11先让 pepk 跑起来我的取舍标准很简单能稳定跑通 pepk 的 JDK 就是好 JDK。实际装下来JDK 8 和 JDK 11 最省事JDK 17 及以上经常会遇到类找不到的问题——较新的 JDK 移除了若干老模块很多老 jar 在启动阶段就会失败此时你甚至还没走到加密那一步。所以别一上来就追求最新 LTS先在 8 和 11 里选一个能跑通的。第一步不是装 JDK而是确认当前 shell 真正调用的 java 是哪一个# 列出 PATH 里所有 java按优先级排序第一条就是实际生效的 which -a java # java -version 默认输出到 stderr必须重定向才能管道处理 java -version 21 # JAVA_HOME 如果指向 JRE后面的 keytool 和构建都可能出问题 echo $JAVA_HOME ls -l $JAVA_HOME/bin/javac判断依据是javac存不存在只有 JRE 没有 javac 的环境构建 pepk 源码这一步直接走不通keytool 也未必在预期位置。多版本共存时Debian/Ubuntu 系用update-alternatives --config java和--config keytool一起切两个要切到同一个 JDK否则会出现 keytool 生成 PKCS12、pepk 用另一个 JDK 读、报密码错误这种看着像“密码错了”实际是“工具版本不一致”的问题。macOS 上习惯用/usr/libexec/java_home -v 1.8拿路径再export JAVA_HOME重点是每次开新终端都确认一遍别依赖上一次会话的环境变量。提示切换 JDK 后一定要重开终端或重新 export很多“切了版本还是报错”的情况是当前 shell 里还残留着旧的 JAVA_HOME。2.2 三样前置产物缺一样后面全白跑在敲任何命令之前先把下面这些凑齐缺一样后面的流程都会卡在半路目标密钥库及其密码。要更新的是哪个密钥库、alias 叫什么、storepass 和 keypass 分别是什么这四样必须提前确认。别名写错一个字母pepk 会直接告诉你找不到。Play Console 下载的加密公钥。文件名通常是encryption_public_key.pem它和具体应用绑定拿别的应用的公钥来加密导出能成功上传必失败。pepk 本体。要么是已经拿到的可执行 jar要么是从源码构建出来的产物。源码包给的是构建脚本不是现成的 jar这一步后面单独说。还有一项容易被忽略的前置条件执行上传的账号必须有该应用的应用签名配置权限。这不是技术问题但权限不够时控制台连上传入口都不显示很多人会误以为是浏览器或网络问题白白排查半小时。2.3 目录怎么摆一份可以直接抄的文件清单pepk 的命令里路径参数很多路径写错是最廉价的失败原因。我习惯先固定一个工作目录把所有材料按用途分开放命令里统一用相对路径# 建三个子目录密钥、工具、输出 mkdir -p ~/playsign/{keystore,pepk,out} # 密钥库默认权限偏宽先收紧避免被同机其他账号读到 chmod 700 ~/playsign/keystore ls -R ~/playsign对应的文件放置方式如下路径放什么注意点keystore/upload-2025.jks新生成的上传密钥库权限 600单独备份keystore/legacy-release.jks老签名密钥的只读备份只复制不覆盖别在这里做实验pepk/pepk.jar构建产物或现成 jar版本与 JDK 要匹配out/encryption_public_key.pem从控制台下载的公钥与目标应用一一对应out/upload-encrypted.zippepk 输出的加密包不要解压后重新打包目录定好之后后面所有命令都基于~/playsign执行不用来回cd也不用在命令里塞一长串绝对路径。这个习惯看着琐碎但排查时能把“路径问题”和“参数问题”彻底分开。3. 生成新签名密钥keytool 参数与 pepk 的首次运行环境确认完接下来要造出两样东西一把新的上传密钥和一个能执行的 pepk。顺序上我建议先生成密钥再构建工具因为生成密钥的过程本身就能验证 JDK 和 keytool 是否配套如果 keytool 都跑不干净构建 pepk 只会把问题叠加。3.1 keytool 生成密钥库五个参数别用默认值下面这条命令是我常用的模板参数不多但每一个都有取舍keytool -genkeypair -v \ -keystore ~/playsign/keystore/upload-2025.jks \ -alias upload \ -keyalg RSA \ -keysize 2048 \ -validity 10000 \ -storetype PKCS12 \ -dname CNUpload Key, OUMobile, ODemo Studio, LCity, STState, CCN逐项说明-keyalg RSA -keysize 2048RSA 2048 是当前的下限别为了兼容老设备降到 1024Play 侧对新密钥的强度有要求弱密钥会在上传阶段被拒绝。-validity 10000单位是天约 27 年。新上传密钥的有效期必须覆盖到 2033 年之后手算容易出错直接给一个大值最省事。-storetype PKCS12JKS 已经是过时格式新建一律用 PKCS12。代价是 PKCS12 里 storepass 和 keypass 必须一致这一点后面避坑章节会专门讲。-dname全部写在一行避免交互式提问。字段内容本身不影响签名但要写得能认出是哪把钥匙别用一串乱码日后翻记录会后悔。-alias upload别名后面 pepk 要用建议固定成有意义的名字比如upload或upload-2025别用默认的mykey。生成完立刻做两件事收紧权限、立即备份。密钥库丢了上传密钥还能向平台申请重置但如果这是首次启用应用签名时导出的那把原始签名密钥丢了就是真的丢了。chmod 600 ~/playsign/keystore/upload-2025.jks # 备份到工作目录之外并且把密码单独记录不要和文件放一起 cp ~/playsign/keystore/upload-2025.jks ~/playsign/keystore/upload-2025.jks.bak # 立刻打印一次指纹记下来后面控制台比对要用 keytool -list -v -keystore ~/playsign/keystore/upload-2025.jks -alias uploadkeytool -list -v的输出里包含 Owner、有效期和 SHA1/SHA256 指纹把 SHA256 那行抄到记录里。这个指纹是后面所有验证的基准早记晚记都一样但早记能省一次回头找文件。3.2 从源码构建 pepk什么情况下必须自己编手里只有源码时先看目录里带的是哪种构建脚本别凭印象敲命令cd ~/playsign/pepk ls -la # 目录里带 gradlew 就走 Gradle带 pom.xml 就走 Maven ./gradlew clean build --no-daemon如果源码里是pom.xml对应命令是mvn clean package -DskipTests。构建产物一般落在build/libs/或target/下把打出来的 jar 复制成pepk.jar放到工作目录根下后面的命令就统一了。构建阶段最常见的失败是 JDK 与构建工具版本不匹配报错关键字通常是Unsupported class file major version。这类报错和 pepk 本身没关系纯粹是 Gradle 或 Maven 跑不动当前 JDK。我的处理方式很直接把JAVA_HOME切到 JDK 8 或 11 再构建不要在构建脚本上改版本号硬扛。源码构建的另一个价值是能确认依赖是否完整如果构建过程里出现依赖下载失败至少你知道问题在构建期而不是运行期。注意如果只是要用工具而不打算改代码拿到现成 jar 完全可以跳过构建。构建的意义在于版本可控和问题可定位不在于“必须编译一遍才算装好”。3.3 首次运行确认 jar、JDK、密钥库三者对得上jar 拿到手之后先别急着拼完整命令空跑一次看它能不能起来cd ~/playsign java -jar pepk/pepk.jar # 正常情况会打印 usage 和必填参数列表说明 jar 与 JDK 匹配这一步的判定标准很朴素能打印出参数说明说明类加载没问题如果抛NoClassDefFoundError或ClassNotFoundException先换 JDK而不是去改命令。跑通之后再顺手看一眼 jar 的主类信息确认拿到的不是同名但内容不对的包unzip -p pepk/pepk.jar META-INF/MANIFEST.MF输出里能看到Main-Class一行。到这里三件套的匹配关系就算确认完毕JDK 能启动 jarkeytool 能读密钥库jar 能打印参数。接下来才是真正碰签名的步骤。4. pepk 加密导出一条命令把私钥交给 Playpepk 干的事只有一件用平台下发的公钥把密钥库里的私钥加密成一个 zip让你能安全地把私钥交给平台而不是明文传输。命令本身很短但参数之间的关系比看上去紧尤其是公钥来源和输出包的处理方式错一步就得重来。4.1 先拿到 encryption_public_key.pem公钥在控制台的应用签名配置页里下载入口名称各版本略有差异认准“加密公钥”这个说法即可。下载后放到out/目录先做两步校验别拿到什么文件都直接喂给 pepkcd ~/playsign head -1 out/encryption_public_key.pem # 期望看到 -----BEGIN PUBLIC KEY----- openssl pkey -pubin -in out/encryption_public_key.pem -noout -text | head -5 # 能解出 Public-Key 位数说明文件没被编辑器改坏常见错误是下载下来的文件被浏览器或编辑器转成了别的编码或者复制粘贴时丢了首尾标记pepk 会在解析阶段报密钥格式错误。用head -1和openssl各看一眼能省掉一轮上传失败。4.2 七个参数逐个拆命令与执行时的交互完整命令如下在工作目录下执行cd ~/playsign java -jar pepk/pepk.jar \ --keystorekeystore/upload-2025.jks \ --aliasupload \ --outputout/upload-encrypted.zip \ --include-signing-key \ --rsa-aes-encryption \ --encryption-key-pathout/encryption_public_key.pem执行后会交互式要求输入密钥库密码输入时屏幕不回显输完回车即可。参数含义与常见写错方式对照如下参数作用常见写错--keystore指定要导出的密钥库用相对路径但不在工作目录执行报文件不存在--alias指定密钥库里的条目大小写或后缀与 keytool 生成时不一致--output加密包输出路径目录不存在时不会自动创建--include-signing-key把私钥一起打包漏掉后只导出证书上传时提示缺少密钥--rsa-aes-encryption用 RSA/AES 方式加密不加则生成明文包平台侧不接受--encryption-key-path指定平台公钥用了别的应用下载的公钥导出成功但上传失败两个细节值得单独说。第一--include-signing-key和--rsa-aes-encryption是配套出现的前者决定包里有什么后者决定包怎么加密少一个都会在上传环节被拒绝。第二密码不要写在命令行参数里。有些版本支持直接传密码参数但命令会进 shell 历史密钥库密码落到历史文件里等于把钥匙挂门上。4.3 输出 zip 的自检别解压、别重打包导出成功后先看包里的结构确认内容对unzip -l out/upload-encrypted.zip # 正常情况下能看到加密后的私钥文件和证书文件这里有一条来自实际教训的建议这个 zip 不要解压后重新压缩。加密包有固定结构解压再打包会改变压缩方式和条目顺序上传时平台解析失败报错信息通常只有“无法解析”四个字。要检查内容用unzip -l列出条目就够了不要去动文件本身。自检通过的标志有三个zip 能正常列出条目、条目里包含密钥与证书、文件大小不是 0 字节。如果 zip 只有几百字节多半是导出时参数不对重新跑一遍命令比研究这个包更快。4.4 上传到 Play Console启用签名与更换上传密钥是两条路这一步最容易混。pepk 导出的加密包和“更换上传密钥”要上传的证书是两种完全不同的东西用错了会在控制台卡住场景上传物生成方式用途首次启用应用签名把已有签名密钥交给平台pepk 输出的加密 zippepk.jar加密导出平台托管签名密钥更换上传密钥上传密钥的证书 PEMkeytool -export -rfc只换上传环节的密钥更换上传密钥用的证书这样导出keytool -export -rfc \ -keystore keystore/upload-2025.jks \ -alias upload \ -file out/upload_certificate.pem # -rfc 表示输出 PEM 文本格式不带这个参数会导出二进制证书上传时注意控制台的状态提示密钥轮换有生效周期新旧密钥之间存在过渡期操作前先确认下一次可轮换的时间别在临近发版时做这件事。另外如果应用已经启用平台托管签名那么“更新签名”通常指的是换上传密钥而不是再传一次 pepk 包把这两件事分清楚能避免大量无效上传。5. 避坑与排查五条踩过的记录下面这五条都是实际装环境时撞出来的每条按现象、原因、解决写遇到同类报错可以直接对照。5.1 跑 pepk 直接抛 NoClassDefFoundError现象java -jar pepk.jar刚启动就退出堆栈第一行是java.lang.NoClassDefFoundError后面跟着某个javax开头的类。原因当前 JDK 版本较新移除了老 jar 依赖的部分模块类加载阶段就失败了。这和密钥、参数都没关系纯粹是运行时环境不匹配。解决把JAVA_HOME切到 JDK 8 或 11重开终端确认java -version已变再跑同一条命令。不要在命令行里加一堆模块参数硬凑换 JDK 是最短路径。5.2 密码明明是对的却提示密钥库密码错误现象pepk 提示Keystore was tampered with, or password was incorrect但你确定密码没错用别的工具打开也正常。原因密钥库是 PKCS12 格式而生成时 storepass 和 keypass 设成了两个不同的值。PKCS12 要求两者一致某些工具读的时候只校验其中一个表现就不一样。解决重新生成密钥库两步密码用同一个值或者确认 pepk 交互时输入的是密钥库密码而不是 key 密码。已经生成且不能重来的用keytool -importkeystore迁移成新库并统一密码。5.3 提示 alias 不存在现象pepk 报找不到指定别名但密钥库文件确实能打开。原因--alias与实际条目名不一致常见是大小写差异或者生成时用了默认别名而命令里写了自定义名。解决先列出来看清楚再改命令keytool -list -keystore keystore/upload-2025.jks # 输出的第一列就是真实别名复制粘贴进 --alias别手敲5.4 加密包上传被拒提示无法解析现象pepk 导出成功zip 也有大小上传到控制台时报解析失败或密钥不匹配。原因三种可能——导出时漏了加密参数、zip 被解压后重新压缩、或者用了别的应用下载的公钥。解决删掉输出文件重跑一次 pepk命令里确认--include-signing-key与--rsa-aes-encryption都在重新从目标应用页面下载公钥整个过程不要用解压工具碰输出包。5.5 旧密钥库被覆盖历史版本对不上现象新配置能上传但从平台下载的旧版本包校验指纹对不上或者本地再也签不出与线上一致的包。原因生成新密钥时直接用了旧文件名把原始密钥库覆盖了且没有备份。解决这类问题没有万能后悔药。能做的是立刻停止在旧文件上操作把现有密钥库全部复制一份到离线位置如果启用的是平台托管签名上传密钥可以申请重置但原始签名密钥一旦丢失无法恢复。所以我在任何一次改动前都会先复制整个keystore目录再动手。6. 装完怎么验证三条命令对齐证书指纹环境跑通、包也传上去了最后一步是确认“上传的那把钥匙”和“本地这把钥匙”确实是同一把。验证不看控制台的绿色对勾只看指纹。第一条确认本地密钥库的指纹keytool -list -v -keystore ~/playsign/keystore/upload-2025.jks -alias upload \ | grep -E Owner|Valid|SHA1|SHA256 # 记下 SHA256 那一行这是本地基准第二条确认本地打出的包用的是同一把钥匙。这一步需要有 Android SDK 的构建工具# apksigner 在 build-tools 目录下先确认能调用 apksigner verify --print-certs app-release.apk | grep -i SHA-256 # 输出应与上一步的 SHA256 完全一致第三条回到控制台的应用完整性页面对比页面上显示的上传密钥证书指纹与本地记录。三处指纹一致才说明签名配置真正对齐了。如果前两条一致、第三条不一致问题出在上传环节回头检查是不是传了旧证书或者轮换还没生效。校验位置看什么不一致时的含义本地密钥库SHA256 指纹密钥库被替换或别名选错本地 APK签名证书 SHA-256打包时用了别的签名配置控制台应用签名页上传密钥证书指纹上传的不是这把钥匙或轮换未生效指纹比对之外还有一个更接近真实链路的验证方式从平台下载一个由托管密钥重新签名的产物再对它跑一次apksigner verify --print-certs看输出里的签名证书是不是平台页面上显示的那一张。这一步能同时验证上传、托管、重新签名三个环节比单看页面状态可靠得多。从那以后我每次动密钥库之前都先把整个目录连同密码记录复制一份到离线位置再跑一遍keytool -list把别名和指纹抄进变更记录最后才执行 pepk。这套动作多花五分钟但能省掉一次发版停摆。pepk 源码和配套的参数清单我整理在同一个包里拿到之后先按第 2 章的目录摆好文件再一条条对着命令跑别跳过空跑那一步。希望帮到你。本文还有配套的精品资源点击获取