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 的版本无法重新签名。换密钥只影响之后发布的新版本。