当前位置：首页 > news >正文

Gitea GPG密钥过期问题：诊断、修复与预防全攻略

news 2026/6/18 10:02:09

1. 项目概述：当Gitea的“数字身份证”失效时

如果你正在使用Gitea搭建自己的代码仓库，并且启用了GPG签名来验证提交的真实性，那么迟早会遇到一个让人头疼的提示：“GPG密钥已过期”。这感觉就像你的数字身份证突然失效了，导致所有需要身份验证的操作都卡了壳。最近在社区里，关于w: 校验数字签名时出错。此仓库未被更新...这类错误的讨论又多了起来，很多朋友在安装依赖或者配置CI/CD时，因为一个过期的GPG密钥，整个流程就中断了。

这个问题看似简单，但背后牵扯到Gitea的提交签名机制、GPG密钥的生命周期管理，以及如何在不影响历史提交记录和团队协作的前提下，安全地完成密钥轮换。我管理过几个基于Gitea的中型项目，都经历过密钥过期的阵痛期。今天，我就结合自己的踩坑经验，把Gitea项目GPG密钥过期问题的来龙去脉、影响范围，以及一套从诊断到彻底解决的实操方案，完整地梳理出来。无论你是个人开发者，还是团队的基础设施维护者，这篇文章都能帮你从容应对这个“定时炸弹”。

2. 核心问题拆解：为什么GPG密钥会过期？

在深入解决方案之前，我们必须先搞清楚问题是怎么来的。GPG密钥过期不是一个Bug，而是一个设计上的安全特性。

2.1 GPG密钥过期的设计初衷

GPG（GNU Privacy Guard）密钥对包含一个公钥和一个私钥。在创建密钥时，你可以为其设置一个有效期（Expiration Date）。这个设计主要有两个目的：

风险控制：即使私钥不幸泄露，攻击者也只能在密钥有效期内冒用你的身份。过期后，该密钥自动失效，限制了损失范围。
促进密钥更新：强制使用者定期审查和更新密钥，采用更强的新算法或更大的密钥长度，跟上安全发展的步伐。

在Gitea的语境下，当你用这个GPG密钥对Git提交进行签名时，签名信息里就包含了签名时间和所用密钥的ID。如果验证签名时发现当前时间已经超过了该密钥的有效期，验证就会失败。

2.2 过期对Gitea项目的具体影响

密钥过期的影响是逐步显现的，并非所有操作立刻瘫痪：

新提交无法验证（最直接影响）：这是最直观的问题。当你推送一个用过期密钥签名的提交到Gitea仓库时，Gitea的UI上该提交可能会显示为“未验证”或“无效签名”。这会严重影响代码审查流程，因为无法确认提交者身份。
自动化流程中断：这是最容易引发故障的环节。许多CI/CD流水线（如使用Gitea Actions、Drone、Woodpecker）或自动化脚本，会配置为只接受经过有效GPG签名的提交或标签。一旦密钥过期，这些流程会因签名验证失败而拒绝执行，导致部署阻塞。搜索热词中提到的“woodpecker连接gitea一直授权失败”，有时根源就在于CI服务验证提交签名时遇到了过期密钥。
依赖安装与系统更新失败：这个问题有点间接，但非常常见。很多Linux发行版或软件仓库（如Docker、Kubernetes）使用GPG密钥来验证软件包的完整性。如果你在服务器上通过脚本安装或更新Gitea，而脚本中引用的某个上游仓库的GPG密钥过期了（例如热词中提到的curl -fssl https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor这个命令所获取的密钥），就会导致apt update或yum update失败，报错类似于W: GPG error: ... NO_PUBKEY ...或校验数字签名时出错，进而影响Gitea服务本身的维护。
历史提交的“污点”：虽然历史提交在当初被签名时是有效的，但密钥过期后，在Gitea界面上重新查看这些旧提交时，其验证状态也可能变为“警告”或“过期”，影响项目历史的“整洁度”。

注意：密钥过期和密钥被吊销（Revoke）不同。过期是自动的、时间触发的；吊销是密钥所有者主动宣布该密钥作废。两者都会导致验证失败，但处理方式略有不同。

3. 诊断与影响评估：你的项目“病”到哪一步了？

遇到问题不要慌，先做一次全面的诊断，确定影响范围。

3.1 本地诊断：检查你的个人密钥

首先，在本地开发环境检查你的GPG密钥状态。

# 列出你的所有私钥，查看密钥ID和过期时间 gpg --list-secret-keys --keyid-format=long # 列出你的所有公钥 gpg --list-keys --keyid-format=long

输出会类似于：

sec rsa4096/3AA5C34371567BD2 2021-01-01 [SC] [有效至：2024-01-01] 1234567890ABCDEF1234567890ABCDEF12345678 uid [ 绝对 ] Your Name <your.email@example.com> ssb rsa4096/42B317FD4BA7E9E7 2021-01-01 [E] [有效至：2024-01-01]

关键信息是[有效至：2024-01-01]。如果这个日期已经过去，那么你的密钥就过期了。

3.2 服务器诊断：检查Gitea的信任密钥库

有时问题不在个人密钥，而在Gitea服务器用于验证外部资源的密钥。例如，Gitea的包管理器（如APT）可能因为系统级GPG密钥过期而无法更新。

# 连接到你的Gitea服务器，检查APT信任的密钥（以Ubuntu/Debian为例） sudo apt-key list # 或使用新的密钥环管理方式 sudo gpg --list-keys --keyring /usr/share/keyrings/*.gpg

查找输出中是否有过期密钥，特别是与软件源（如Docker、GitHub CLI、NodeSource等）相关的。

3.3 Gitea仓库诊断：查看提交验证状态

登录Gitea网页界面，浏览你的项目仓库：

进入“提交”页面。
观察最近的提交记录。如果某个提交者旁边的验证图标是灰色的（如一个带叉的盾牌），或者鼠标悬停显示“无效签名：密钥已过期”，那么就是遇到了本文讨论的问题。
可以点击有问题的提交，在提交详情页通常会有更详细的签名验证信息。

3.4 影响范围评估清单

根据诊断结果，填写下表，明确你的修复重点：

影响项	检查方法	是否受影响
个人新提交	`git commit -S`后推送，看Gitea验证状态	高
CI/CD流水线	查看最近流水线日志，寻找GPG验证错误	高
自动化部署脚本	检查脚本中是否有`git verify-commit`或`git verify-tag`命令	中
服务器系统更新	在Gitea服务器执行`sudo apt update`，看是否有GPG错误	中
历史提交显示	在Gitea查看几个月前的已合并提交的验证状态	低

4. 解决方案一：更新现有GPG密钥的有效期（治标）

如果你的密钥刚刚过期不久，且你仍然持有该密钥的私钥和密码，那么延长其有效期是最直接的方案。这相当于给你的数字身份证办理了“延期”。

4.1 使用GPG命令延长密钥有效期

# 1. 启动GPG编辑模式，指定你要修改的密钥ID（上例中的3AA5C34371567BD2） gpg --edit-key 3AA5C34371567BD2 # 2. 在gpg>提示符下，输入`expire`来修改过期时间 gpg> expire # 3. 系统会询问你要修改主密钥（默认）还是子密钥。通常选择主密钥。 # 4. 输入新的有效期。例如，可以输入`2y`表示两年，`0`表示永不过期（不推荐）。 # 5. 确认修改。 # 6. 输入`save`保存并退出编辑模式。 gpg> save

4.2 将更新后的公钥重新发布

仅仅本地修改还不够，你需要让Gitea（以及其他所有验证你提交的地方）知道你的密钥已经延期。

导出更新后的公钥：

gpg --armor --export 3AA5C34371567BD2 > my_updated_public_key.asc

将公钥上传到你的Gitea账户：
- 登录Gitea。
- 点击右上角头像 -> “设置”。
- 选择“SSH/GPG密钥”选项卡。
- 找到你之前添加的旧公钥，删除它。
- 点击“添加GPG密钥”，将my_updated_public_key.asc文件内容粘贴进去，保存。
（可选）上传到公钥服务器：如果你也在其他平台（如GitHub、GitLab）使用此密钥，需要同步更新。
```
gpg --keyserver hkps://keys.openpgp.org --send-keys 3AA5C34371567BD2
```

4.3 验证修复效果

本地验证一个旧提交（用过期密钥签名的）：
```
git verify-commit <某个旧提交的哈希>
```
如果输出包含Good signature但附带警告：此密钥已过期，说明密钥已更新，但GPG仍认为签名时的密钥是过期的。这是正常现象，因为签名是历史记录。

进行一次新的签名提交并推送：

git commit -S -m "test: verify updated gpg key" git push

刷新Gitea的提交页面，这个新提交应该显示为“已验证”状态。

实操心得：这个方法能快速解决“新提交无法验证”的问题。但对于CI/CD流水线，如果流水线脚本里写死了要验证某个特定提交（比如打标签的发布提交），而这个提交是在密钥过期期间签名的，那么验证依然会失败。此时需要考虑方案二。

5. 解决方案二：创建并更换新的GPG密钥对（治本）

如果旧密钥丢失、密码遗忘，或者你希望遵循最佳实践定期轮换密钥，那么生成一对全新的密钥是更彻底的选择。这相当于换发一张新的数字身份证。

5.1 生成新的GPG密钥对

现代GPG推荐使用更健壮的算法。

# 使用交互式命令生成密钥，推荐使用 ed25519/cv25519 椭圆曲线算法，更快更安全 gpg --full-generate-key

在交互过程中：

密钥类型选择：(1) RSA and RSA（默认）或(9) ECC and ECC。对于ECC，后续可以选择(1) Curve 25519。
密钥长度：RSA建议4096位；ECC的Curve 25519长度是固定的。
有效期：建议设置一个合理的期限，如2年（2y）。不要设置为永不过期。
输入你的姓名和邮箱（务必与你在Gitea和Git配置中使用的邮箱一致）。
设置一个强密码来保护你的私钥。

5.2 配置Git使用新密钥

获取新密钥ID：
```
gpg --list-secret-keys --keyid-format=long
```
记下新密钥的长ID（如ABCD1234EFGH5678）或指纹。

告诉Git使用这个新密钥进行签名：

# 全局设置 git config --global user.signingkey ABCD1234EFGH5678 # 或者针对单个仓库设置 git config user.signingkey ABCD1234EFGH5678

（可选）设置Git默认签名提交：
```
git config --global commit.gpgsign true
```

5.3 在Gitea中无缝切换密钥

这是关键步骤，目标是让旧提交的历史验证状态不受影响，同时让新提交正确验证。

导出并添加新公钥到Gitea：
```
gpg --armor --export ABCD1234EFGH5678 > new_public_key.asc
```
按照4.2节的步骤，将new_public_key.asc的内容添加到你的Gitea账户的GPG密钥列表中。注意：不要删除旧的公钥！让新旧公钥并存。这样Gitea才能用旧公钥验证历史提交，用新公钥验证未来提交。
处理CI/CD流水线的验证：
- 更新你的CI/CD配置（如.gitea/workflows/*.yml、.drone.yml或woodpecker.yml），确保其中验证签名所用的公钥列表包含了你的新旧两个密钥的指纹或ID。
- 对于Woodpecker授权失败的问题，检查Woodpecker服务器的配置，确保它拉取的Gitea仓库的部署密钥或访问令牌具有足够的权限，并且其内部用于验证的GPG密钥环也包含了你的新公钥。

5.4 撤销旧密钥（可选但推荐）

如果你确定不再使用旧密钥，并且已经成功切换到新密钥，应该撤销旧密钥，以防止他人误用。

# 生成吊销证书（如果当初生成密钥时没生成） gpg --output revoke.asc --gen-revoke 3AA5C34371567BD2 # 导入吊销证书，使本地密钥库知道该密钥已撤销 gpg --import revoke.asc # 将吊销信息发布到公钥服务器 gpg --keyserver hkps://keys.openpgp.org --send-keys 3AA5C34371567BD2

在Gitea中：你仍然可以保留旧公钥，Gitea会将其标记为“已吊销”，用于验证历史提交时给出相应提示，这是正确的安全状态。

6. 解决方案三：处理系统级GPG密钥过期问题

有时问题不出在个人密钥，而是Gitea服务器系统本身依赖的GPG密钥过期了，导致无法更新软件包，影响Gitea升级或系统安全更新。热词中提到的bcompare密钥过期删哪个文件和Docker仓库密钥错误就是这类问题。

6.1 定位过期的系统密钥

以Ubuntu/Debian系统上Docker仓库密钥过期为例：

执行sudo apt update，错误信息会明确指出是哪个源的GPG密钥出了问题。
例如错误：W: GPG error: https://download.docker.com/linux/ubuntu focal InRelease: The following signatures were invalid: KEYEXPIRED 1622437315

6.2 更新特定软件源的GPG密钥

方法不是“删哪个文件”，而是重新获取并添加正确的密钥。

# 1. 删除旧的、过期的密钥文件（如果知道具体位置） # 通常位于 /usr/share/keyrings/ 或 /etc/apt/trusted.gpg.d/ # 例如：sudo rm /usr/share/keyrings/docker-archive-keyring.gpg # 2. 重新从官方渠道下载并添加新密钥（以Docker为例） # 这是热词中命令的完整版 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg # 3. 再次更新软件包列表 sudo apt update

关键点：gpg --dearmor命令是将ASCII格式的密钥转换为GPG二进制格式，-o指定输出文件。确保下载链接和输出路径与你系统的软件源配置一致。

6.3 通用排查步骤

对于其他软件源（如Kubernetes, Node.js等），步骤类似：

访问该软件源的官方文档，找到其提供的当前有效的GPG密钥添加命令。
在服务器上执行该命令。
运行sudo apt update或sudo yum makecache验证错误是否消失。

注意事项：切勿从非官方渠道获取GPG密钥，这有严重的安全风险。始终使用项目官网或官方仓库提供的指令。

7. 预防措施与最佳实践

亡羊补牢不如未雨绸缪。建立良好的GPG密钥管理习惯，可以避免未来再次陷入被动。

7.1 个人密钥管理清单

设置日历提醒：在密钥过期前1-3个月，在日历中设置提醒，以便有充足时间处理。
备份私钥和吊销证书：将你的私钥（~/.gnupg/private-keys-v1.d/）和吊销证书安全备份到离线存储中。
使用智能卡或YubiKey：对于高安全需求，考虑将GPG私钥存储在硬件安全模块中，避免私钥在电脑上留存。
为不同用途使用不同子密钥：GPG主密钥可以离线保存，用于签发（Certify）子密钥。日常签名（Sign）和加密（Encrypt）使用子密钥。这样即使日常使用的子密钥泄露，可以用主密钥吊销它，而无需更换整个身份。

7.2 团队与项目级规范

文档化密钥轮换流程：在团队内部Wiki或README中，记录清晰的GPG密钥生成、添加、过期处理和轮换步骤。
在CONTRIBUTING.md中说明：对于开源项目，明确要求贡献者使用GPG签名，并提供密钥添加指南和过期问题处理链接。
CI/CD流水线弹性设计：
- 在验证签名时，不要只验证单个密钥，而是验证一个“信任密钥库”，包含所有活跃贡献者的当前有效公钥。
- 考虑在流水线中增加一个步骤，定期检查项目中使用的GPG密钥列表，并对即将过期（如90天内）的密钥发出警告通知。

7.3 服务器维护建议

监控系统更新错误：使用监控工具（如Prometheus + Alertmanager）监控apt update或yum check-update命令的退出状态，及时发现GPG密钥错误。
使用配置管理工具：使用Ansible、SaltStack或Puppet管理服务器上的软件源GPG密钥，确保其来源和内容符合预期，并能自动更新。

8. 常见问题与排查技巧实录

在实际操作中，你可能会遇到一些意料之外的情况。这里记录了几个我遇到过的典型问题及其解决方法。

问题1：更新密钥有效期后，Gitea上旧的签名提交状态还是“过期”，怎么办？

原因：Gitea在验证提交签名时，会检查签名时刻的密钥状态。如果签名时密钥有效，即使后来密钥过期，Gitea通常仍会显示“已验证但密钥已过期”之类的警告状态。这是正常且正确的行为，它忠实地记录了历史。你无法也不应该去“修复”历史提交的签名状态。
处理：接受这个状态。重点是确保新提交使用新密钥或已延期的密钥后能正确显示“已验证”。你可以考虑在项目README中加一个说明，解释某时间段前的提交因密钥过期而显示警告属正常情况。

问题2：执行git commit -S时，弹出图形界面让我输入密码，但我是在无图形界面的服务器上操作。

解决：这是因为GPG的pinentry程序默认尝试启动图形界面。将其设置为curses（文本）模式即可。

# 在~/.gnupg/gpg-agent.conf中添加（如没有则创建） echo “pinentry-program /usr/bin/pinentry-curses” >> ~/.gnupg/gpg-agent.conf # 重启gpg-agent gpg-connect-agent reloadagent /bye

或者，在命令行中通过GPG_TTY环境变量指定：

export GPG_TTY=$(tty)

问题3：团队中有多人密钥过期，如何批量验证仓库历史提交的签名状态？

解决：可以使用git log结合脚本进行批量检查。

# 查看所有提交的签名状态 git log --oneline --show-signature # 使用git verify-commit和shell脚本遍历所有提交 for commit in $(git rev-list --all); do if ! git verify-commit $commit 2>/dev/null; then echo “Bad signature in commit: $commit” git show --oneline -s $commit fi done

这能帮你快速定位哪些提交的签名有问题，便于通知相应的贡献者。

问题4：Gitea Actions Runner 因为GPG验证失败而跳过任务？

排查：检查你的Gitea Actions工作流文件（.gitea/workflows/*.yml），看是否在on:触发器条件中使用了gpg_signature过滤，例如on: push: tags: gpg_signature: ...。如果标签是用过期密钥签名的，工作流就不会触发。
解决：更新工作流触发条件，或者使用新密钥重新打标签。同时，确保Runner所在环境信任了所有必要的公钥。

GPG密钥管理是开源协作和软件供应链安全中细微但重要的一环。处理过期问题虽然繁琐，但每一步都加深了对“信任链”如何运作的理解。我的经验是，把密钥的有效期设置成一个容易记住的日期（比如两年后的今天），并在那天设置一个年度提醒，花半小时做一次密钥健康检查。这远比在某个深夜被CI/CD流水线报警吵醒，然后手忙脚乱地排查要从容得多。

查看全文

http://www.gsyq.cn/news/1547025.html