apt 升级整批中断?第三方源 TLS 握手失败的完整排查与修复(附全部命令与截图)

一条 apt-get upgrade 因为 Docker 官方源 TLS 握手失败而整批中断,一个包都没装上。本文把这次排查拆成 8 个可复制的步骤:逐源测连通性、看清源配置两种格式、备份改写源地址、重导 GPG 密钥、读懂 Hit/Ign/Err、预演再升级、内核三件套单独补装、重启后逐项验证,每一步都配真实命令输出截图。

一条 apt-get upgrade 挂掉,报了一行 Could not handshake with download.docker.com:443,结果一个包都没装上——很多人在这一步就卡住了:明明是系统更新,怎么会被一个 Docker 源拖死?这篇文章用一台真实 Ubuntu 24.04 服务器的完整排查过程,把这件事从”看懂报错”到”修好并验证”一步步走通:先定位是哪个源坏了 → 看清源配置长什么样 → 备份并改写源地址 → 重新导入 GPG 密钥 → 读懂 Hit/Ign/Err → 预演再升级 → 内核单独补装 → 重启后逐项验证,每一步都配真实命令输出截图。

文中所有 IP、路径、账号都已脱敏,命令可直接复制到自己的 Ubuntu/Debian 上对照执行。

目录

  • 一、先看懂 apt 升级的执行路径(它到底经过哪几环)
  • 二、第 1 步:先测连通性,找出到底是哪个源坏了
  • 三、第 2 步:看清源配置放在哪、长什么样
  • 四、第 3 步:备份 + 改写源地址
  • 五、第 4 步:GPG 签名密钥也要从新源重新导入
  • 六、第 5 步:刷新索引,读懂 Hit / Ign / Err
  • 七、第 6 步:先预演,再真升级
  • 八、第 7 步:内核三件套单独点名安装
  • 九、第 8 步:重启后逐项验证
  • 十、错误速查表
  • 十一、安全与隐私经验
  • 十二、命令速查表

一、先看懂 apt 升级的执行路径

为什么要先看路径:报错只说”握手失败”,不告诉你是哪个环节、哪个源。知道整条链路,才知道该从哪一环下手,也才明白为什么”一个第三方源坏了”会让”整批升级失败”。

① 读源列表        /etc/apt/sources.list + /etc/apt/sources.list.d/*.list
                            ↓
② 取索引文件      每个源都要下载 InRelease / Release.gpg(验证签名用)
                            ↓              ↑ 卡死在这里 = "Could not handshake"
③ 汇总版本表      所有源的包版本合并成一张表(apt-cache policy 能看到)
                            ↓
④ 算升级计划      比对已装版本和候选版本(apt-get -s upgrade 可预演,不实际执行)
                            ↓
⑤ 下载 .deb 包    按计划逐个下载
                            ↓
⑥ 校验并解包      验签名、dpkg 解包安装
                            ↓
⑦ 触发钩子        更新 initramfs、刷新 ldconfig、重启服务等

这次卡在第 ② 环:apt 要去 download.docker.com 下载索引文件,这一步的 TLS 握手被重置了。后面 ③④⑤⑥⑦ 一个都没开始,所以一个包都没装上——这就是”整批中断”的字面含义。

为什么一个第三方源的故障能连累整批?因为 apt-get upgrade 要求所有源的索引都拿全才敢开始升级(万一索引不全,会算错依赖关系,装出一个坏掉的组合)。它宁可什么都不做,也不愿装到一半出错的状态。

当时的原始报错,整条命令只输出了这一行就退出了:

apt 升级因 TLS 握手失败整批中断
图1:原始现场——apt-get upgrade 在取索引阶段就断了,输出里只有一行握手失败

二、第 1 步:先测连通性,找出到底是哪个源坏了

为什么要先做这步:报错信息不告诉你是哪个源。挨个源测一遍,几十秒就能锁定目标,避免瞎改一通配置。

# 挨个源测 InRelease(索引文件)能不能取到
# 只测一个文件就够,因为它在每个源里都在固定位置
for u in download.docker.com mirrors.aliyun.com mirrors.tuna.tsinghua.edu.cn; do
  echo -n "$u : "
  curl -sS -o /dev/null -w '%{http_code} time=%{time_total}s
' \
    --max-time 20 https://$u/linux/ubuntu/dists/noble/InRelease
done

命令白话拆解:-o /dev/null = 下载但不要正文(我们只想看通不通);-w '%{http_code}' = 结束时打印状态码(200 通、000 失败);--max-time 20 = 最多等 20 秒,免得它在那儿干等把整条命令拖死。

逐个源测试连通性
图2:只有 download.docker.com 连不上(TLS 被重置),阿里云和清华都通 —— 目标锁定

怎么确认成功:输出里应该看到只有一个源是 000/失败,其余全是 200。如果多个源都不通,那就是本地网络或 DNS 的问题,换源救不了,得先解决网络。

三、第 2 步:看清源配置放在哪、长什么样

为什么要做:源配置不一定都在一个文件里。新版 Debian/Ubuntu 是”一个目录、一个源一个文件”,你改错文件等于没改。

# 所有第三方源都在这个目录里,一个源一个文件
ls -l /etc/apt/sources.list.d/
源配置文件清单与内容
图3:源配置目录——docker.list(官方源)和 docker-ce.list(镜像源)并存,ubuntu.sources 是另一种格式

顺便认识两种写法,新手最容易在这里看晕:

  • 单行格式(老式,.list 文件):一整行写完。deb [架构=amd64 签名密钥路径] 仓库地址 发行代号 组件。改它就是改这一行的域名。
  • 多行格式(Deb822,新版 .sources 文件):拆成 Types: / URIs: / Suites: / Components: / Signed-By: 五个字段,一个源可以有多段。

两种格式的关键区别是 Signed-By 指向的密钥文件不同——这正是下一步要动的地方。

怎么确认成功:你能找到坏掉那个源对应哪个文件,并看清它用的是哪个密钥路径。后面两步都要改这两处。

四、第 3 步:备份 + 改写源地址

为什么要备份:改坏了能一条命令还原。没有备份,改一次就是一次赌博。

# ① 备份原文件(带时间戳,每次互不覆盖)
cp /etc/apt/sources.list.d/docker-ce.list \
   /etc/apt/sources.list.d/docker-ce.list.bak-$(date +%Y%m%d-%H%M%S)

# ② 改写仓库地址:域名换成镜像,其余字段一字不动
#    signed-by 必须指向你自己的密钥文件(下一步会重新导入)
cat > /etc/apt/sources.list.d/docker-ce.list <<'L'
deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.asc] https://mirrors.aliyun.com/docker-ce/linux/ubuntu noble stable
L

# ③ 改完立刻看一眼,确认没写错
cat /etc/apt/sources.list.d/docker-ce.list

白话说明这段:<<'L' 表示"把后面这行 L 结束之前的内容原样写进文件"(引号是关键,不加引号 shell 会先展开里面的变量,写出来就变形了)。deb 是"这是个二进制包源",arch=amd64 是只取 x86_64 的包,noble 是 Ubuntu 24.04 的代号,stable 是这个源的分支名。除了域名,其余字段照抄原来的——写错了发行代号,apt 会告诉你找不到那个包。

怎么确认成功:cat 出来的那一行,和你原来那行只有域名不同,别的字符一个没变。

五、第 4 步:GPG 签名密钥也要从新源重新导入

这一步最容易被漏掉。换源只改地址不改密钥,会得到一个更难懂的报错:NO_PUBKEY 或 The following signatures couldn't be verified——因为新地址的索引文件是用另一把密钥签的。密钥下不到,apt 一样不认这个源。

# ① 确认密钥目录存在(apt 8+ 的规范做法,密钥单独放一个目录)
install -m 0755 -d /etc/apt/keyrings

# ② 从镜像源下载公钥(注意是镜像源的 gpg 路径,不是官方站的)
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc && echo key_ok

# ③ 让所有用户都能读(644 即可,密钥是公开的,不需要 600)
chmod a+r /etc/apt/keyrings/docker.asc

# ④ 核对一下:这确实是一把公钥,不是空文件或错误页
head -1 /etc/apt/keyrings/docker.asc
# 期望:-----BEGIN PGP PUBLIC KEY BLOCK-----
stat -c '%n perms=%a size=%s' /etc/apt/keyrings/docker.asc

第 ④ 步的检查别省:如果镜像返回的是一张 404 图片或一段 HTML,head -1 一看就知道,而不是等到 apt 报错才发现。

怎么确认成功:第一行是 -----BEGIN PGP PUBLIC KEY BLOCK-----,文件大小是几 KB(不是 0 也不是几百字节的 HTML)。

六、第 5 步:刷新索引,读懂 Hit / Ign / Err

为什么要做:改完源必须刷新索引,否则 apt 还拿着旧的清单去找包。而且这一步的输出里,藏着"到底哪个源还没搞定"的关键信息。

# 刷新索引(只更新"包清单",不装任何东西,安全)
apt-get update
apt-get update 输出
图4:刷新索引——阿里云 Hit、官方源 Ign,其余 Ubuntu 源全部 Hit,索引读取完成

这三个词必须分清,含义完全不同:

输出含义要不要管
Hit这个源正常取到了索引不用管
Ign这个源被跳过了(取不到、校验不通过或被忽略),但 apt 会继续用其它源看情况:会导致每个源都白等一次超时
Err这个源真的出错了必须处理:apt-get upgrade 会被它整批中断

这次 apt-get update 之所以能过,是因为官方源被标成了 Ign(跳过)而不是 Err(错误)——索引阶段容错,升级阶段不容错。这就是为什么"update 看着没事,upgrade 却整批挂"。

顺带一个真实发现:这次换源是新增了一个镜像源文件,没有删掉原来的官方源文件。所以现在 apt 会同时问两个源同一个仓库——看 apt-cache policy 就能发现同一个包在版本表里出现了两份:

apt-cache policy 显示两个源并存
图5:同一个 docker-ce 包在阿里云和官方源各有一份记录——官方源虽然被跳过,但它还在列表里

后果是每次 apt-get update 都要在坏源上浪费一次连接超时。这台机器实测官方源是"时好时坏"(第一次探测 Connection reset by peer,重试时又能 Hit),属于典型的间歇性抽风。更干净的做法是把官方源文件移走,只留镜像源:

# 想彻底只用镜像源:把官方源文件移出 sources.list.d(移走而不是删,随时能放回)
mv /etc/apt/sources.list.d/docker.list /root/docker.list.disabled

# 然后再刷一次,应该只剩镜像源被问
apt-get update

怎么确认成功:apt-get update 输出里没有 Err;并且 apt-cache policy 某个包 的版本表里不再出现重复来源。

七、第 6 步:先预演,再真升级

为什么要先预演:-s(--simulate)只算不装,能让你提前看到"会升级哪几个、会装哪几个、有没有要删的",避免在正式升级时才发现计划有问题。

# ① 预演:只看计划,不做任何改动
apt-get -s upgrade
# 输出末尾那行是汇总,例如:
#   2 upgraded, 0 newly installed, 0 to remove and 3 not upgraded
# "not upgraded" 是被 hold 住或依赖冲突的包,会被跳过而不是失败

# ② 看看有没有被 hold 住的包(held back 的常见原因)
apt-mark showhold

# ③ 确认没问题再真升级
apt-get upgrade -y

这次正式升级时,18 个包装好,但内核那三个包没装上。原因不复杂:内核包体积大、依赖特殊,apt 在批量升级时经常把它单独留着,需要你点名才装。

怎么确认成功:预演输出的汇总行里,没有 "The following packages have been kept back" 之类需要你决策的提示;有的话先查清楚再往下走。

八、第 7 步:内核三件套单独点名安装

# 内核三件套:内核本体 + 内核头文件 + 元包
apt-get install -y linux-image-generic linux-headers-generic linux-generic

# 装完必须重启,内核只有重启才切换
reboot

白话解释三个包:linux-image-generic 是"内核本体"(真正跑的内核文件),linux-headers-generic 是"内核头文件"(编译驱动模块要用,缺了以后装 nvidia、virtualbox 会失败),linux-generic 是"元包"(一个指向当前最新内核的快捷方式,以后再升级它就带上新内核)。三个一起装最省事,少一个都可能留下隐患。

内核包安装结果与重启记录
图6:装完的状态——新旧两个内核同时在(旧的留着可回退),重启记录显示已运行在 6.8.0-149

看到旧内核还在,别急着删。内核包默认不会自动清理,新旧并存是好事:新内核万一有问题(比如装完网卡驱动不上、界面起不来),重启时选旧内核就能立刻回退,不用重装。等新内核跑稳了几个月再清理不迟。

怎么确认成功:dpkg -l | grep linux-image 能看到新旧两个版本号都在,并且 uname -r(重启后)显示的是新版本。

九、第 8 步:重启后逐项验证

为什么要逐项验证:重启完最容易犯的错是看一眼"回来了"就收工。有些问题重启前存在、重启后自愈(这台机器的 CIFS 挂载失败就是),也有些重启后才会暴露。

# ① 内核是不是真的换了
uname -r
# 期望:6.8.0-149-generic(不再是旧的 147)

# ② 待升级包是否清零
apt list --upgradable 2>/dev/null | tail -n +2 | wc -l
# 期望:0

# ③ 容器是不是都活着、是不是健康
docker ps --format '{{.Names}} | {{.Status}}'
# 期望:都是 Up ... (healthy)

# ④ 自动更新定时器还在不在
systemctl list-timers --all --no-pager | grep apt-daily
# 期望:能看到 NEXT 时间

# ⑤ 之前 failed 的挂载单元是不是自愈了
systemctl --failed --no-pager
# 期望:只剩 systemd-networkd-wait-online(无害)
重启后逐项验证结果
图7:重启后逐项验证——新内核生效、待升级包清零、容器全部 healthy

这次验证有两个意外收获:CIFS 挂载失败在重启后自己好了(说明它只是启动时序问题,不是配置错);Docker 也跟着从 29.9.2 升到了 29.9.3,3 个容器全部 healthy。

一个诚实的补充:图里"待升级包清零"是升级刚做完那一刻的状态。过了几天上游又发新版本,这个数字会自己涨回来——写这篇时实测又是 5 个可升级包(其中 libmysqlclient21 来自 noble-security,属于安全更新)。所以"清零"不是终点,是快照。真正要盯的是定时更新有没有在跑、以及安全源上的包有没有被卡住。

十、错误速查表

报错真因怎么办
Could not handshake with ...: tls: handshake failure该源的 TLS 握手被阻断(国内访问第三方源常见)逐源测连通性 → 换国内镜像源 + 重导 GPG key
NO_PUBKEY / signatures couldn't be verified换源后没换密钥,或密钥没下载成功从新源重新导入 gpg 到 /etc/apt/keyrings/
Connection reset by peer源不可达(网络或被限流)同上换源;注意它可能间歇性抽风,重试一次能通不代表稳定
升级整批中断、装了一半某个源 Err,apt 要求索引齐全才敢动手先 apt-get update 看清有没有 Err
普通包装上了、内核没装内核包被 apt 单独跳过(体积大/依赖特殊)单独 apt-get install linux-image-generic linux-headers-generic linux-generic
N packages not upgraded这些包被 hold 住或依赖冲突apt-mark showhold 查;必要时 apt-mark unhold 包名

十一、安全与隐私经验

  • 改配置前先备份:cp 原文件 原文件.bak-$(date +%Y%m%d-%H%M%S),改坏了 1 分钟回滚,没有备份就是事故。
  • 换源不换密钥是最常见的坑:地址改了、密钥没改,得到的是 NO_PUBKEY 这种比原报错更难懂的错误。
  • 密钥文件用 644 就够:GPG 公钥本来就是公开的,chmod 600 反而可能让 apt 读不到。真正需要 600 的是私钥。
  • 坏源要移走而不是无视:留着它,apt 每次都要浪费一次连接超时,版本表还会出现同包两份的混乱。
  • 不要在聊天和文档里贴完整的源配置:虽然源地址本身不算秘密,但它会暴露你的服务器用了哪些第三方源。文中所有地址均已脱敏。
  • "待升级包清零"是快照不是终点:盯住定时更新和安全源,比盯这个瞬时数字有意义得多。

十二、命令速查表

场景命令
看待升级包apt list --upgradable | tail -n +2 | wc -l
测某个源通不通curl -sS -o /dev/null -w '%{http_code} ' --max-time 20 https://源地址/dists/代号/InRelease
看源配置ls -l /etc/apt/sources.list.d/
改源(备份+写回)cp 文件 文件.bak-$(date +%Y%m%d-%H%M%S) && cat > 文件 <<'L' ... L
导 GPG 密钥curl -fsSL https://镜像/gpg -o /etc/apt/keyrings/xxx.asc && chmod a+r /etc/apt/keyrings/xxx.asc
刷新索引apt-get update
预演升级apt-get -s upgrade
查被 hold 的包apt-mark showhold
解除 holdapt-mark unhold 包名
单独装内核apt-get install -y linux-image-generic linux-headers-generic linux-generic && reboot
看某个包的来源apt-cache policy 包名
移走坏源mv /etc/apt/sources.list.d/源.list /root/源.list.disabled
看内核版本uname -r
自动更新定时器systemctl list-timers --all | grep apt-daily

整套流程再强调一遍:逐源测连通性 → 备份并改写源 → 重导密钥 → 刷新索引看清 Hit/Ign/Err → 预演 → 正式升级 → 内核单独补装 → 重启 → 逐项验证。每一步都有对应的"怎么确认成功",做到最后那条命令之前,你已经知道每一步有没有生效。

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注