从 Debian 11（bullseye）升级到 Debian 12（bookworm）是一次原地大版本升级，核心流程是：完整备份 → 更新现有系统 → 切换软件源（关键变化是 non-free-firmware） → 分步升级 → 重启验证。

🛡️ 第一步：升级前强制准备

升级过程涉及大量软件包替换，没有可回滚的备份，不要开始操作。

1. 创建系统快照
如果是虚拟机或云服务器，先在控制台创建系统盘快照，并确认能够回滚。

2. 记录当前关键信息
记录当前内核、关键软件版本，以及被手动“hold”住的软件包，便于升级后核对：

cat /etc/debian_version
uname -r
apt-mark showhold

3. 检查磁盘空间
升级需要下载并安装大量软件包，根分区建议至少保留 2GB 可用空间：

df -h /

4. 备份关键配置与源列表

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak.bullseye
sudo tar czf /root/etc-backup-$(date +%F).tar.gz /etc

🔄 第二步：将 Debian 11 更新到最新状态

在切换版本代号之前，先把 bullseye 上所有已安装的软件包更新到当前源中的最终版本，减少升级时的依赖冲突。

sudo apt update
sudo apt upgrade -y
sudo apt full-upgrade -y
sudo apt autoremove -y

完成后建议重启一次，确保系统在干净、无残留进程的状态下进入下一步。

📝 第三步：切换软件源（核心变化：non-free-firmware）

Debian 12 在仓库结构上有一个必须处理的变化：非自由固件（non-free firmware）被划分到了独立的 non-free-firmware 分区。如果你的系统依赖这些固件（如无线网卡、部分显卡驱动），遗漏该组件可能导致升级后硬件无法正常工作。

同时，必须处理第三方源。 /etc/apt/sources.list.d/ 下的 Docker、NodeSource、各类 Agent 等第三方仓库如果仍指向 bullseye，升级过程中会出现 404 或依赖冲突。升级期间应先将它们全部禁用或移走，待系统升级完成后再逐一确认其是否支持 bookworm，然后恢复。

编辑 /etc/apt/sources.list，将 bullseye 相关内容整体替换为以下 bookworm 格式。如果是国内网络，可以将 deb.debian.org 和 security.debian.org 替换为清华 TUNA 或中科大 USTC 的镜像地址，但同一套源不要混用多个镜像站。

sudo nano /etc/apt/sources.list

deb https://deb.debian.org/debian bookworm main contrib non-free non-free-firmware
deb https://deb.debian.org/debian bookworm-updates main contrib non-free non-free-firmware
deb https://security.debian.org/debian-security bookworm-security main contrib non-free non-free-firmware

如果你确定不需要任何非自由固件，可以省略 non-free-firmware，但这对于大多数物理机并非明智选择，因为硬件驱动可能依赖它。

保存后刷新索引：

sudo apt update

如果此时仍然看到第三方源报错，说明 /etc/apt/sources.list.d/ 中还有未禁用的仓库，需要继续处理，不要在源混杂的状态下强行升级。

⚙️ 第四步：最小化升级（--without-new-pkgs）

先执行一次保守的升级，只升级现有软件包，不安装新包，降低一次性变更的规模。

sudo apt upgrade --without-new-pkgs -y

🚀 第五步：完整版本升级（full-upgrade）

这是真正的版本迁移步骤。full-upgrade 会安装新内核、升级核心库，并卸载或替换与新版本不兼容的旧包。

sudo apt full-upgrade -y

过程中会弹出交互式提示，处理原则如下：

如果出现依赖错误，不要强行继续，可以先尝试修复：

sudo apt --fix-broken install

修复后再重新执行 sudo apt full-upgrade -y。

🧹 第六步：清理、重启与验证

升级完成后，清理不再需要的旧包和残留配置：

sudo apt autoremove --purge -y
sudo apt clean

然后重启系统以加载新内核：

sudo reboot

重启后，依次验证：

# 1. 确认版本为 bookworm
cat /etc/debian_version
lsb_release -a

# 2. 确认运行的是 Debian 12 的内核（通常为 6.1.x 系列）
uname -r

# 3. 检查是否有服务启动失败
systemctl --failed

# 4. 检查包管理状态是否干净
dpkg --audit

以上命令均无异常输出，即表示升级完成。

⚠️ 升级后必须处理的遗留事项

1. 逐一恢复第三方源
之前禁用的第三方仓库，只有在官方明确声明支持 bookworm 后，才应恢复启用。不要一次性全部打开，恢复一个就执行一次 apt update，确认无报错后再继续。

2. 关注关键应用的大版本跳变
Debian 12 带来的不只是系统本身的变化，默认软件栈也发生了显著升级。如果你的服务器运行着 Web 应用或数据库，需要特别留意：

• PHP：Debian 11 默认为 7.4，Debian 12 默认为 8.2。旧代码中的废弃语法、扩展兼容性需要在升级后重点测试。

• MariaDB：软件包名和版本均有变化，涉及数据库的生产环境应提前确认应用兼容性。

• 其他：youtube-dl 已被 yt-dlp 取代，Puppet 从 5 跳至 7 等，可参考 Debian 官方发布说明第 5 章逐项核对。

3. 旧内核处理
Debian 12 不会自动删除 bullseye 时期的旧内核。确认新系统稳定运行后，可以手动清理以释放 /boot 空间，但至少保留当前内核和一个上一个版本的内核作为回退保障。

升级到 Debian 12 后，系统将重新获得安全更新支持，之前因 bullseye EOL 导致的 404 问题也会随之消失。如果你的应用栈比较复杂（如涉及 PHP、MariaDB、Docker 等），建议先在快照或克隆机上完整演练一遍，再对生产环境执行正式升级。