GPG 密钥与 Maven Central 发布签名
Maven Central 要求每个上传的制品都附带 GPG 签名(.asc 文件),否则拒绝接收。签名需要两样东西:一把私钥,以及私钥的口令。本文按顺序列出查询、创建、上传、配置的命令。
每条命令单独执行,不要合并成一行,也不要放进 for 循环。gh secret set 每条都会开启一次终端提示等待输入,循环会导致值写入错误的 secret。
一、查询本机已有密钥
gpg --list-secret-keys --keyid-format LONG
列出本机所有私钥。输出形如:
sec rsa4096/0B4189D9794C625F 2026-11-02 [SC]
301B6185F94AA2CC125A82AA0B4189D9794C625F
uid [ultimate] crowf <you@example.com>
第一行的 0B4189D9794C625F 是 16 位短 ID,下一行缩进的 301B6185F94AA2CC125A82AA0B4189D9794C625F 是完整指纹。后续命令使用完整指纹。
若需要列出公钥,用:
gpg --list-keys --keyid-format LONG
二、检查密钥是否有口令
gpg --list-packets <(gpg --armor --export-secret-keys 你的指纹)
在输出的 :secret key packet: 之后,如果出现 iter+salt S2K 这一行,说明私钥有口令保护;没有这一行说明口令为空。
有口令的密钥在 CI 中必须同时提供口令,否则签名失败,报错为 PGPException: checksum mismatch in checksum of 20 bytes。这个报错读起来像密钥损坏,实际原因是口令缺失。
三、创建发布专用密钥
若还没有密钥,或想为发布单独使用一把,执行:
gpg --quick-generate-key '你的名字 <你的邮箱>' rsa4096 sign 0
参数逐项说明:
| 部分 | 含义 |
|---|---|
--quick-generate-key |
跳过交互菜单,按参数直接生成 |
'你的名字 <你的邮箱>' |
用户 ID,会写入密钥并上传到 keyserver 公开 |
rsa4096 |
RSA 算法,4096 位 |
sign |
用途仅为签名 |
0 |
永不过期 |
有效期写法
| 写法 | 含义 |
|---|---|
1d |
1 天 |
2w |
2 周 |
3m |
3 个月 |
1y |
1 年 |
5y |
5 年 |
0 |
永不过期 |
单位是 d 天、w 周、m 月、y 年。永不过期写 0,不能写 n 或 never,否则报 Key generation failed: Invalid value。
密钥过期只影响能否继续用它签新内容,已发布到 Central 的签名文件不受影响。过期后可续期,指纹不变:
gpg --quick-set-expire 你的指纹 5y
算法与用途
rsa2048、rsa4096、ed25519 可用于 sign。cv25519 是加密算法,用作 sign 会报 Wrong key usage。
用途可选 sign、cert、auth、encr,留空默认为 cert,sign。Maven Central 只需要签名能力。
输入口令
执行时会弹出窗口要求输入 Passphrase 和 Repeat,两栏填同一个值。这个口令是你自己设定的字符串,不是任何平台下发的值。记下来,配置 MAVEN_CENTRAL_SIGNING_KEY_PASSWORD 时要用。
若两栏都留空,密钥不带口令保护,CI 就不需要配置口令那条 secret,但拿到私钥文件的人可直接使用。
创建后查询指纹:
gpg --list-secret-keys --keyid-format LONG
删除已有密钥
同一个 uid 重复执行 --quick-generate-key 会报 一个 "..." 的密钥已经存在。此时密钥不会被覆盖,需要先删除。
先确认要删哪一把:
gpg --list-secret-keys --keyid-format LONG
删除私钥和公钥:
gpg --batch --yes --delete-secret-and-public-key 你的指纹
必须加 --batch --yes。不加时 gpg 会尝试打开 /dev/tty 请求确认,在非交互环境报 cannot open '/dev/tty': No such device or address。
也可以分两步执行,顺序不能颠倒:
gpg --batch --yes --delete-secret-keys 你的指纹
gpg --batch --yes --delete-keys 你的指纹
删除后确认:
gpg --list-secret-keys --keyid-format LONG
若私钥已上传到 keyserver,删除本地密钥不会移除服务器上的公钥。公钥一旦上传就无法撤回,只能吊销。因此发布密钥泄露时,正确做法是生成吊销证书并上传,而不是只删本地。
四、上传公钥到 keyserver
gpg --keyserver keyserver.ubuntu.com --send-keys 你的指纹
Maven Central 在验证签名时需要能取到公钥,所以必须上传。上传后可用浏览器访问 https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x你的指纹 确认已存在。
五、配置 GitHub Actions Secret
1. 写入私钥
gpg --armor --export-secret-keys 你的指纹 | gh secret set MAVEN_CENTRAL_SIGNING_KEY --repo 你的用户名/仓库名
--armor 把私钥输出为 -----BEGIN PGP PRIVATE KEY BLOCK----- 开头的文本格式,| 把它直接传给 gh。私钥不显示在屏幕上,也不存成文件。
2. 写入口令
gh secret set MAVEN_CENTRAL_SIGNING_KEY_PASSWORD --repo 你的用户名/仓库名
这条命令执行后会停在提示符等待输入。粘贴口令后按回车。输入过程中屏幕不显示任何字符,没有星号或圆点,这是正常行为。
3. 确认
gh secret list --repo 你的用户名/仓库名
应看到包含 MAVEN_CENTRAL_SIGNING_KEY 和 MAVEN_CENTRAL_SIGNING_KEY_PASSWORD 的条目。
六、Gradle 中的对应配置
gh secret set 写入的 secret 在 workflow 中通过环境变量传给 Gradle:
env:
ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.MAVEN_CENTRAL_SIGNING_KEY }}
ORG_GRADLE_PROJECT_signingInMemoryKeyPassword: ${{ secrets.MAVEN_CENTRAL_SIGNING_KEY_PASSWORD }}
变量名中的 ORG_GRADLE_PROJECT_ 前缀会让 Gradle 把后面的部分当作项目属性读取。因此构建脚本里可以用 providers.gradleProperty("signingInMemoryKey") 判断是否配置了签名,只有存在时才启用 signAllPublications()。
这样本地的 publishToMavenLocal 不需要 GPG 密钥,CI 才执行签名。
七、常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
checksum mismatch in checksum of 20 bytes |
私钥有口令,但 MAVEN_CENTRAL_SIGNING_KEY_PASSWORD 未配置,或值与私钥不匹配 |
重新设置 MAVEN_CENTRAL_SIGNING_KEY_PASSWORD |
gpg: directory '/tmp/xxx' does not exist |
环境变量 GNUPGHOME 指向不存在的目录 |
命令前加 GNUPGHOME=$HOME/.gnupg,或 unset GNUPGHOME |
gpg: no valid OpenPGP data found |
管道传给 gh 的内容为空,通常是导出命令本身失败 |
先单独执行 gpg --armor --export-secret-keys 指纹 确认有输出 |
| 上传后 Central 报签名无法验证 | 公钥未上传到 keyserver | 执行第四步重新上传 |
八、验证密钥与口令是否配对
在本地确认口令正确,避免等到 CI 才失败。把 你的口令 换成真实值:
gpg --batch --pinentry-mode loopback --passphrase '你的口令' --armor --export-secret-keys 你的指纹 > /dev/null; echo "退出码=$?"
退出码=0 表示口令正确。出现 Bad passphrase 且退出码为 2 表示口令错误。
用 --export-secret-keys 而不是 --import 做判断,因为导入私钥不校验口令,只有真正解密时才校验。
九、一个密钥可以服务多个仓库
同一把私钥可以配置到多个仓库的 secret 中,各仓库独立发布、各自签名。更换密钥时,每个正在发布 Maven 制品到 Central 的仓库都要更新 MAVEN_CENTRAL_SIGNING_KEY 与 MAVEN_CENTRAL_SIGNING_KEY_PASSWORD。
MAVEN_CENTRAL_USERNAME 和 MAVEN_CENTRAL_PASSWORD 是 Central Portal 的账号 token,与签名密钥无关,不需要随密钥更换。
已发布到 Central 的版本无法重新签名。换密钥只影响之后发布的新版本。