企业官网建设流程全解析

简介：面向需要更新 Google Play 应用签名密钥的 Android 开发者，这份源码包完整提供了 pepk 工具在签名更新流程中的 Java 实现，可用于从源码层面理解上传密钥如何被读取、加密并生成 Play 控制台所需的格式。资源共 2000 个文件，其中 1999 个为 Java 源码、1 个为 TXT 文本，整体以密码学与证书处理类代码为主；源码模块涵盖 TLS 通信、PKIX 证书链校验、椭圆曲线点运算、AES/Threefish/DSTU 等分组加密与摘要算法，几乎覆盖密钥转换过程中的底层密码学依赖，适合排查加密失败、证书校验异常等问题。压缩包约 5.02MB，体积小巧、目录紧凑，支持本地快速下载、按需查阅或重新编译。已有 372 人浏览/学习；对处理 Play 签名更新、密钥导出与加密上架的开发者有直接参考价值，尤其适合具备 Java 基础、希望深入掌握签名机制和密码学模块用法，并打算对 pepk 做二次定制的 Android 上架工程师或工具链维护者。

1. 这个场景很痛：上传密钥丢了，Google 后台只剩一个「升级签名」按钮——pepk 是唯一通关工具

做 Android 上架的人最怕的不是代码崩，而是签名密钥出问题。某天你打开 Play Console，发现应用签名页赫然写着「需要升级签名密钥」，后台对应的上传密钥已经失效，而本地那个 .jks 文件因为换电脑、清磁盘、离职交接断档，找不到了。这个时候，Google 给你的唯一路径就是用 pepk 工具走一遍密钥升级流程：生成新的上传密钥，用 pepk 打包成 .pepk 文件传回后台，重新建立信任链。pepk 全称是 Play Encrypt Private Key，一个官方分发的命令行 jar 工具，作用是把你的上传密钥加密封装成 Google Play 能识别的格式。这篇笔记就把 pepk 的源码行为、参数含义、升级签名的完整流程和现场踩坑一次讲透，适合正在处理签名升级、或者想提前把这条路踩平的 Android 开发者。

2. 先分清两条链：上传密钥在你这，应用签名密钥在 Google——pepk 只干一件事

2.1 你在本地持有的 upload key，和 Play 托管的应用签名密钥，不是同一个东西

很多人在这个环节就晕了。Google Play 从 2018 年后全面推行「Play 应用签名」机制，结构上是两条密钥链：一条是 Google 托管的应用签名密钥，真正给 APK/AAB 落签名的那个，私钥在 Google 手里；另一条是上传密钥，也就是你本地 .jks 或者 .keystore 里存的那一对，它只用来做「上传」这个动作的签名校验。

这两条链的职责完全不同。你在本地构建产物时，Gradle 用的是上传密钥；产物传到 Play 后台后，Google 会用自己的应用签名密钥重新签一遍再分发。也就是说，玩家最终装到手机上的那个签名，跟你本地打包用的签名，指纹对不上是正常的。而 pepk 这个工具站在这两条链的中间：它读取你本地上传密钥里的私钥，用 Google 提供的公钥加密，生成 .pepk 文件交给 Play Console，后台用这个文件建立起「你的上传身份」和「应用签名密钥」的映射关系。

理解了这条链路，你就能明白为什么密钥升级必须走 pepk：因为 Google 不可能直接收你的私钥明文，你也不可能拿到它的私钥，双方交换的是一个用公钥加密的中间格式。pepk 就是这条交换通道的唯一官方入口。

2.2 用 pepk 打包 upload key 的最小命令：三行 bash 生成 .pepk 文件

最常见的需求其实不是升级，而是「我把应用转到 Play 应用签名体系时，需要先交一个 .pepk 上去」。这个操作不复杂，一条命令就能完成。先把 pepk.jar 下载到本地，然后执行下面的脚本：

#!/bin/bash # 最小可用的 pepk 打包命令 java -jar pepk.jar \ --keystore=upload_key.jks \ --alias=upload \ --keyalg=RSA \ --keysize=2048 \ --sigalg=SHA256withRSA \ --encryptionkey="-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA8QkZ... -----END PUBLIC KEY-----" \ --output=upload_key.pepk

这段命令的逻辑是：--keystore指向本地密钥库文件，--alias指定要导出的密钥条目；--keyalg、--keysize、--sigalg三个参数必须和你生成密钥库时用的算法一致，后面会展开说为什么这仨是血泪重灾区；--encryptionkey是 Google 公开的 RSA 公钥，用来加密你的私钥内容；--output指定输出文件路径。

这里最容易被忽略的是--encryptionkey的格式。它是一整段 PEM 格式的公钥文本，必须包含BEGIN PUBLIC KEY和END PUBLIC KEY两行，不能只用中间那段 Base64。命令行里直接换行粘贴是可以的，但如果你把这段公钥写进 shell 变量或者 CI 平台的 secret 里，换行符会被吞掉，导致 pepk 解析失败。我一般会先把公钥写进一个 pem 文件，然后用$(cat google_play_public_key.pem)引用，避免换行问题。

2.3 换个视角看「pepk源码」：jar 包里到底做了什么

标题里带「源码」两个字，很多人以为要去看 Google 的开源实现。实际 pepk 是一个可直接执行的 jar 包，官方源码逻辑并不复杂，理解它的行为模型比读字节码更实用：输入一个标准的 Java Keystore（JKS 或 PKCS12 都支持），根据 alias 找到对应私钥条目，把私钥内容用--encryptionkey指定的公钥做 RSA 加密，再封装成一个带格式头的 .pepk 文件。整个过程是本地的、单向的，不会把任何私钥明文上传到网络。

这个行为模型解释了三个关键特征：第一，pepk 不校验你的上传密钥是否「当前有效」，它只做格式转换，所以密钥过期了也能打包；第二，pepk 生成的 .pepk 文件里，包含着你的私钥密文，但只有 Google 的私钥能解开，这个文件泄露出去的风险相对可控，但仍要当敏感文件对待；第三，整个打包是确定性的——同样的 keystore、alias、密码、公钥，输出的 .pepk 是相同的，这意味着你可以放心在 CI 里反复执行，不需要担心每次打包产生不同结果。

3. 参数不能只抄命令：pepk 的 5 个必调参数与 3 个常见误读

3.1 --keyalg / --keysize / --sigalg 必须和原 key 一致

这三个参数是 pepk 命令里最容易被「抄作业抄错」的地方。很多教程给的是 RSA + 2048 + SHA256withRSA，因为这是 Android Studio 生成密钥库的默认组合。但如果你手上的旧密钥是从早期项目带出来的，或者是某内部工具链生成的，算法可能是 DSA、EC 或者 RSA + 1024，这时候你用默认参数去跑 pepk，生成的 .pepk 文件到了后台会直接报签名不匹配。

查原密钥算法不需要回忆，一条命令就能看到：

# 查看密钥库中指定 alias 的算法信息 keytool -list -v -keystore upload_key.jks -alias upload # 输出里重点看这两行： # Algorithm: RSA 或 DSA 或 EC # Signature algorithm: SHA256withRSA

拿到算法信息后，把 pepk 的--keyalg、--keysize、--sigalg改成和输出一致即可。需要特别注意的是--sigalg不能随便填，它必须同时被你的 key 类型和 Google 后台支持。经验值是：RSA key 配 SHA256withRSA，EC key 配 SHA256withECDSA，DSA key 需要查一下后台是否还支持，建议尽早换掉 DSA。

有个容易忽略的细节：--keysize填 2048 对 RSA 有意义，但对 EC key 来说这个参数会被忽略，EC 曲线的位数是 key 本身决定的。所以如果你原 key 是 EC，这个参数不要照抄 2048，直接删掉这行就行。

3.2 --encryptionkey 是加密公钥，不是你的私钥

这是把 pepk 用翻车的最常见原因。--encryptionkey参数全称是「Google Play 的加密公钥」，用来加密你的上传私钥，它跟你的 keystore 没有任何关系。有的开发者会把自己的公钥填进去，有的会把 keystore 密码当公钥填进去，生成的 .pepk 看起来也有内容，但传到 Play Console 后后台无法解密，直接报「无法解析 pepk 文件」。

这个公钥是 Google 官方在文档里公开的固定值，不需要你生成。它的特征是那段MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...开头的长字符串。注意一点：这个公钥曾经有过一次更新，如果你的项目非常老，存的是旧版公钥，打包出的 pepk 可能无法被当前后台解析。验证方法很简单——去官方文档页面复制当前公钥，重新打包一次，对比两次 .pepk 文件内容，如果差异巨大，说明你原来用的就是旧公钥。

3.3 输出文件命名与路径规范：在 CI 脚本里如何避免写死路径

本地手动跑 pepk 很随意，但放到 CI 流水线里，路径问题就会放大。pepk 命令的--output参数支持相对路径，但如果你在 CI 里执行java -jar时工作目录跑到了别的地方，输出文件会落在你完全想不到的位置。我见过最典型的一次：脚本里写--output=./build/upload_key.pepk，但 CI 里前一步把工作目录切到了build/子目录，结果 pepk 在build/build/下生成了文件，上传步骤找不到产物直接失败。

#!/bin/bash # 在 CI 中推荐的处理方式：先固定工作目录 PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" KEYSTORE_PATH="${PROJECT_ROOT}/keystore/upload_key.jks" OUTPUT_PATH="${PROJECT_ROOT}/build/outputs/upload_key.pepk" mkdir -p "$(dirname "${OUTPUT_PATH}")" java -jar "${PROJECT_ROOT}/tools/pepk.jar" \ --keystore="${KEYSTORE_PATH}" \ --alias=upload \ --keyalg=RSA \ --keysize=2048 \ --sigalg=SHA256withRSA \ --encryptionkey="$(cat "${PROJECT_ROOT}/tools/google_play_public_key.pem")" \ --output="${OUTPUT_PATH}"

这段脚本做了三件事：第一，用PROJECT_ROOT显式锁定绝对路径，无论 CI 从哪个目录启动脚本，路径都不会漂移；第二，把加密公钥外置到 pem 文件里，用$(cat ...)读取，换行符处理交给 shell；第三，先mkdir -p确保输出目录存在，避免 pepk 因为目录不存在而静默失败。

另一个建议是给输出文件加上时间戳或者构建号。因为同一个 keystore 打出的 .pepk 内容是一样的，但如果换了 keystore，文件名还叫upload_key.pepk，下载下来容易搞混哪个是哪个。加个日期后缀，成本几乎为零，收益是后期排查时少掉很多「这个文件是什么时候打的」的疑问。

4. 更新 Google Play 签名的完整流程：从本地新 key 到后台生效的 6 步

4.1 生成新的上传密钥（.jks）并导出 PEM

升级签名的前提是你得有一把新的上传密钥。注意这不是「重新生成一把一样的」，而是生成一把全新的密钥对，因为它要替换掉后台已经失效的那一把。用 Android Studio 的生成向导可以，但命令行更可控：

# 生成新的 RSA 2048 上传密钥库 keytool -genkeypair \ -v \ -keystore new_upload_key.jks \ -alias upload \ -keyalg RSA \ -keysize 2048 \ -validity 10000 \ -sigalg SHA256withRSA \ -storepass your_store_password \ -keypass your_key_password \ -dname "CN=Android Debug,O=YourOrg,C=CN" # 导出证书的 PEM 格式，后续可能需要在后台比对指纹 keytool -export -rfc \ -keystore new_upload_key.jks \ -alias upload \ -file upload_cert.pem \ -storepass your_store_password

-validity 10000是给密钥定了大概 27 年的有效期，Android 密钥不设太长会埋雷，但也不要设成天荒地老，有的内部合规要求密钥必须定期轮换，10000 天是个比较平衡的取值。生成后用keytool -list -v记下 SHA-256 指纹，这个指纹后面在后台核对要用。

4.2 用 pepk 二次打包并上传到 Play Console

拿到新 keystore 后，接下来就是标准的 pepk 打包流程。这一步的命令模板和第 2 章的最小命令一致，唯一要注意的是：--keyalg、--keysize、--sigalg必须和新生成密钥库时用的参数一致。如果你照上面的命令生成，就是 RSA + 2048 + SHA256withRSA：

# 用新生成的 keystore 打包 pepk java -jar pepk.jar \ --keystore=new_upload_key.jks \ --alias=upload \ --keyalg=RSA \ --keysize=2048 \ --sigalg=SHA256withRSA \ --encryptionkey="$(cat google_play_public_key.pem)" \ --output=new_upload_key.pepk

打完包不要急着上传。用下面的命令做一次本地自检，确认 .pepk 文件头部结构完整：

# 查看 pepk 文件的头部信息（文件前面几十个字节有固定格式标识） xxd new_upload_key.pepk | head -20

正常文件的头部能看到明确的文本标识符，如果xxd输出全是随机字符没有任何可读字段，说明打包过程可能出了问题，先排查再上传。上传步骤在 Play Console 的「应用签名」页面，找到「升级签名密钥」的入口，选择这个 .pepk 文件提交。

这里有个容易急躁的点：上传后后台会显示「处理中」，有的开发者以为失败了就重新传一遍，结果多次提交导致后台排队变长。实际耐心等几分钟刷新页面就好，后台解密和更新映射是异步的，不需要重复操作。

4.3 切换签名密钥后的验证与灰度策略

密钥提交生效后，你的应用签名密钥本身没有变，变的是「上传密钥 → 应用签名密钥」的映射关系。所以从用户视角看，App 的安装包签名指纹没有变化，不会触发用户卸载重装。但 Google Play 内部对这个切换有一个生效周期，通常几分钟到几小时不等。

这期间如果你在本地重新打包 AAB 并上传，用的必须是你新提交的这把 upload key，不能再碰旧钥匙。我见过一个翻车现场：开发者上传新 pepk 后，本地的 Gradle 配置还指着旧 keystore 路径，结果构建产物签名用的是旧 key，上传时后台校验失败，提示「签名证书与上传密钥不匹配」，整个人直接懵了。

# 在 Gradle 里检查当前使用的 keystore 配置（以签名配置为例） # 确认 storeFile 指向的是新 keystore 文件 ./gradlew signingReport

signingReport会输出每个变体的签名证书指纹，重点检查SHA-256那一行是否和新生成的new_upload_key.jks的指纹一致。这一步在切换密钥后必做，别省。

灰度策略上，建议在密钥切换生效后，先通过 Play Console 的「内部测试」渠道发一版给测试组，确认 AAB 上传、下载、安装、内购流程全通，再推生产。密钥切换本身不改变应用签名，所以内购和云测试的数据理论上不受影响，但保险起见走一遍全流程心里才踏实——签名问题一旦出错会直接影响用户安装，没后悔药可吃。

5. 避坑清单：pepk 使用中最常见的 5 个现场翻车与排查

5.1 报错「Keystore was tampered with」：文件没坏，是密码或算法不匹配

现象：执行 pepk 打包命令，程序直接抛出java.security.UnrecoverableKeyException: Keystore was tampered with, or password was incorrect。

原因：这个报错信息很有迷惑性，绝大多数情况根本不是文件被篡改，而是密码错误或 alias 不存在。还有一个隐蔽场景——keystore 文件本身是 PKCS12 格式但命令里用了 JKS 的读取逻辑，或者文件在传输过程中从 LF 变成 CRLF 导致二进制变化。

解决：先确认密码，keytool -list -v -keystore xxx -alias xxx，如果 keytool 自己能读，说明文件和密码都没问题，问题出在 pepk 命令的参数上。再看--alias是否和 keystore 里的条目完全一致，包括大小写。PKCS12 格式的 keystore 在 pepk 命令里不需要特殊声明，会自动识别。

5.2 上传后提示 key 不匹配：--keyalg 与原有 key 的算法不一致

现象：pepk 打包成功，.pepk 文件也上传了，但 Play Console 提示「上传的密钥无法用于此应用」或者「签名证书指纹不匹配」。

原因：这条要分两种情况。第一种是你按教程默认 RSA + 2048 打包，但原 key 是 EC 或 DSA，后台拿你的加密私钥和原上传证书比对时算法对不上；第二种是你提交了新的 .pepk，但后台记录的还是旧 key 的指纹，而你生成新 key 时没有走「升级」入口，而是在别的页面直接上传，导致后台认为你在用一把从未注册过的 key。

解决：回到后台确认当前需要的到底是「替换上传密钥」还是「更新应用签名密钥」。如果是前者，只能走升级流程生成新 key；如果是后者，需要填入后台给的特定信息。先用keytool -list -v明确原 key 算法，再匹配 pepk 参数。别在一个页面上反复试，先在本地弄清楚自己手里这把 key 的身份。

5.3 密码含特殊字符：脚本变量导致 pepk 静默生成空文件

现象：命令执行完没有任何报错，但生成的 .pepk 文件只有几字节，上传后被后台拒绝。

原因：keystore 密码里如果带了$、!、&这类特殊字符，在 bash 脚本里直接写在--storepass参数中会被 shell 解析，导致实际传给 pepk 的密码是截断后的内容。pepk 读取失败时不会报错，而是生成一个空壳文件。

解决：密码不要直接写在命令行里，用环境变量传递：

export STORE_PASS='your$pecial!pass' export KEY_PASS='your$pecial!pass' java -jar pepk.jar \ --keystore=new_upload_key.jks \ --alias=upload \ --keyalg=RSA \ --keysize=2048 \ --sigalg=SHA256withRSA \ --encryptionkey="$(cat google_play_public_key.pem)" \ --output=new_upload_key.pepk \ --storepass="${STORE_PASS}" \ --keypass="${KEY_PASS}"

另外，生成 keystore 时尽量避开特殊字符，不是不能处理，是没必要给自己埋雷。

5.4 旧版 pepk jar 不兼容新版后台：先看版本再谈用法

现象：网上找的教程、某博客附件里下的 pepk.jar，执行命令时界面和参数跟官方文档对不上，或者打出包后台上传时提示「文件格式不支持」。

原因：pepk 工具经历过几次参数调整，早期版本用的参数名是--keystore、--encryptionkey，更早的版本签名参数还不一样。教程里贴的参数格式和实际 jar 包不匹配，就会出现「照抄命令但行为完全不同」的情况。

解决：只从官方渠道下载 pepk.jar，下载后先执行java -jar pepk.jar不带参数，看它打印的帮助信息。重点检查有没有--sigalg参数，有就是新版，没有就得按旧版语法处理。历史项目里如果已经有 .pepk 文件，可以用第 3.2 节的方式对比新旧公钥，确定当前 jar 是否适配现在的后台。

5.5 不在本地保留私钥副本：密钥升级后无处回退

现象：密钥升级完成后，某开发者把旧的 keystore 文件删了，想着「反正已经换了新的」。结果三个月后发现新 keystore 密码被某个离职交接记录搞丢了，后台应用签名密钥还是好好的，但上传密钥彻底没了，Play Console 再次变成「需要升级签名密钥」。

原因：密钥管理没有冗余意识，把唯一的私钥副本放在一个位置。后台的应用签名密钥是 Google 托管的没错，但你的上传密钥仍然是你的责任——丢了它，你就失去了对应用上传渠道的控制权。

解决：任何一把上传密钥，至少保留三份副本，放在三个不同的地方。可以是加密的云存储、离线硬盘、密码管理器三处各一份。同时把密码和密钥分开存放，并在后台的「应用签名」页面下载并保存应用签名密钥的证书备份 PDF——这份文件是 Google 给你的最后底牌，将来密钥彻底失控时，可以申请恢复。

6. 验证签名是否真的生效：从本地 APK 到 Play 后台的三层核查法

密钥切换流程跑完后，最怕的是「以为成功了」。我习惯性地做三层核查，缺一层都不敢发版。

第一层，本地验证新 keystore 是否正常工作。用keytool读出证书指纹，再构建一个临时 APK/AAB 用apksigner验证签名：

# 查看新 keystore 的证书指纹 keytool -list -v -keystore new_upload_key.jks -alias upload | grep "SHA-256" # 验证本地构建产物的签名 apksigner verify --print-certs app-release.apk

对比两者的 SHA-256 指纹，一致说明构建链路用的确实是新 key。这一步在本地就拦截掉一大半问题，不用等到上传后台才发现签名不对。

第二层，后台验证。Play Console 的「应用签名」页面会显示当前上传证书的指纹，和你本地keytool查出的指纹逐位比对。注意这里比对的是「上传证书」指纹，不是「应用签名证书」指纹——应用签名证书是 Google 的，指纹永远不会因为你的升级操作而改变。只比对上传证书那一段即可。

第三层，也是我花了两次血泪代价才养成的习惯——密钥升级后，别直接在内部测试轨道发版，先在 Play Console 用「内部应用共享」上传一个包，走一遍完整的安装流程。不是只测安装成功，要测到应用内购、登录态、云同步这三个对签名最敏感的功能。签名指纹变化如果导致某些鉴权逻辑异常，这几个功能是最先暴露问题的。

验证全部通过后，把新 keystore、密码、上传证书 PEM、pepk 文件四个东西归档到离线存储，并在项目 README 里记录本次切换的时间、新旧指纹对照表。这样下次不管是你自己还是后来接手的人，都能在十分钟内搞清楚这把钥匙的来龙去脉。做签名管理这行，最值钱的经验不是命令敲得多熟，而是每次操作都给自己留好后路——密钥这个东西，丢一次就能让人长记性，希望这篇笔记能帮你把该踩的坑提前绕开。

本文还有配套的精品资源，点击获取