常见兼容问题

# 确认当前 sudo 实现
sudo --version
 
# 如果脚本依赖传统 sudo 的某些特性而报错，可临时回退
sudo apt install sudo
# 安装后会接管 /usr/bin/sudo；排查完毕后建议再切回 sudo-rs

sudo apt install gnu-coreutils

# 将密钥导出到独立 keyring
curl -fsSL https://repo.example.com/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/example.gpg
 
# 在 .sources 文件中通过 Signed-By 引用
# Signed-By: /etc/apt/keyrings/example.gpg

# 旧: sudo update-initramfs -u
# 新:
sudo dracut -f

# 查看被禁用的 PPA
ls /etc/apt/sources.list.d/*.distUpgrade
 
# 错误示例
# E: The repository 'https://ppa.launchpadcontent.net/example/ppa/ubuntu resolute Release' does not have a Release file.
 
# 检查 PPA 是否支持 26.04
sudo add-apt-repository --list
 
# 删除不兼容的 PPA
sudo add-apt-repository --remove ppa:example/ppa
 
# 或手动删除
sudo rm /etc/apt/sources.list.d/example-ppa.sources
sudo apt update

# 许多第三方源使用版本代号（如 noble、resolute）
# 升级后需要更新代号
 
# 检查当前代号
lsb_release -cs
# 输出: resolute
 
# 手动修改第三方源文件中的版本代号
sudo sed -i 's/noble/resolute/g' /etc/apt/sources.list.d/example.list
 
# 对于 DEB822 格式
sudo sed -i 's/noble/resolute/g' /etc/apt/sources.list.d/example.sources
 
# 更新索引
sudo apt update

# 错误示例
# W: GPG error: https://repo.example.com ... EXPKEYSIG
 
# 重新获取密钥
curl -fsSL https://repo.example.com/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/example.gpg
 
# 删除已过期的旧密钥
sudo rm /etc/apt/trusted.gpg.d/example.gpg

# 升级后 NVIDIA 驱动可能需要重新安装
# 检查驱动状态
nvidia-smi
 
# 如果命令不可用，重新安装驱动
sudo ubuntu-drivers devices
sudo ubuntu-drivers autoinstall
 
# 推荐让 ubuntu-drivers 自动选择匹配的驱动版本
# 具体版本号以 ubuntu-drivers devices 输出的 recommended 为准
sudo ubuntu-drivers autoinstall
 
# 如果卡在低分辨率或黑屏
# 1. 切换到 TTY: Ctrl+Alt+F2
# 2. 重新安装驱动（版本号以 ubuntu-drivers devices 为准）
sudo apt install --reinstall nvidia-driver-XXX
sudo reboot

# 检查 DKMS 状态
dkms status
 
# 如果模块未构建
sudo dkms autoinstall
 
# 手动重建指定模块
sudo dkms build module-name/version -k $(uname -r)
sudo dkms install module-name/version -k $(uname -r)
 
# 常见需要 DKMS 的模块
# - VirtualBox Guest Additions
# - NVIDIA 驱动
# - ZFS
# - WireGuard (旧版内核)

# 检查无线设备
rfkill list all
iwconfig
 
# 安装缺失的固件
sudo apt install linux-firmware -y
 
# 如果特定网卡不工作
lspci | grep -i network
lsusb | grep -i wireless
 
# 查看内核日志中的固件错误
dmesg | grep -i firmware
dmesg | grep -i wifi
 
# 重新加载无线模块
sudo modprobe -r iwlwifi && sudo modprobe iwlwifi

# 检查 PipeWire（26.04 默认）或 PulseAudio
systemctl --user status pipewire pipewire-pulse
 
# 重启音频服务
systemctl --user restart pipewire pipewire-pulse
 
# 如果从 PulseAudio 迁移到 PipeWire
sudo apt install pipewire-audio

# 检查 Python 版本
python3 --version
 
# 升级后 Python 小版本可能变化（如 3.12 -> 3.13）
# 注意：26.04 系统 Python 受 PEP 668 保护，无法用 pip 直接装包（含 --user）。
# 已安装的依赖应在虚拟环境中重新安装——小版本变化后旧 venv 通常需要重建：
rm -rf venv/
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
 
# 命令行工具类的全局应用改用 pipx 安装/重装：
# sudo apt install pipx
# pipx reinstall-all

# 检查 PHP 版本
php -v
 
# 升级后 PHP 版本可能从 8.3 变为 8.5
# 需要更新 Web 服务器配置
 
# Nginx - 更新 PHP-FPM socket 路径
# 旧: fastcgi_pass unix:/run/php/php8.3-fpm.sock;
# 新: fastcgi_pass unix:/run/php/php8.5-fpm.sock;
sudo grep -r "php8." /etc/nginx/
 
# Apache - 更新模块
sudo a2dismod php8.3
sudo a2enmod php8.5
sudo systemctl restart apache2
 
# 重新安装 PHP 扩展
sudo apt install php8.5-mysql php8.5-curl php8.5-mbstring php8.5-xml -y

# 检查版本
mysql --version
 
# 注意：MySQL 8.4 已移除 mysql_upgrade 命令，
# 数据字典升级由 mysqld 启动时自动完成，无需手动运行。
# 仅 MariaDB 仍需手动升级：
sudo mariadb-upgrade -u root -p
 
# 检查表兼容性
sudo mysqlcheck -u root -p --all-databases --check-upgrade
 
# 如果出现错误，尝试修复
sudo mysqlcheck -u root -p --all-databases --auto-repair

# PostgreSQL 升级后可能需要迁移数据目录
# 检查版本
pg_lsclusters
 
# 如果有多个集群版本（如从 24.04 的 16 升级到 26.04 的 18）
# 旧集群在升级后会保留
sudo pg_upgradecluster 16 main 18
 
# 确认新集群正常后删除旧集群
sudo pg_dropcluster 16 main

# 如果通过系统包安装
node --version
 
# 推荐使用 nvm 管理版本，不受系统升级影响
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install --lts

# 升级过程中选择了"安装维护者版本"的配置文件
# 旧版本会备份为 .dpkg-old
find /etc -name "*.dpkg-old" 2>/dev/null
find /etc -name "*.dpkg-dist" 2>/dev/null
find /etc -name "*.ucf-dist" 2>/dev/null
 
# 比较差异
diff /etc/ssh/sshd_config /etc/ssh/sshd_config.dpkg-old

# 使用 diff3 进行三方合并
# 需要原始配置、你的修改和新版本配置
 
# 对于 debconf 管理的配置
sudo dpkg-reconfigure package-name
 
# 重新配置所有使用 ucf 的配置文件
sudo ucf --purge /etc/some/config
sudo apt install --reinstall package-name

# 检查是否有需要重新加载的服务
sudo systemctl daemon-reload
 
# 查看被覆盖的服务文件
systemd-delta
 
# 检查自定义的 override 是否仍然有效
systemctl cat your-service.service

# 某些服务名称在新版本中可能更改
# 例如：
# iptables -> nftables
# isc-dhcp-server -> kea-dhcp4-server
 
# 检查服务是否存在
systemctl list-unit-files | grep service-name

# 重新安装 GRUB
sudo grub-install /dev/sda   # 或你的引导磁盘
sudo update-grub
 
# 查看 GRUB 配置
cat /boot/grub/grub.cfg | grep menuentry

# 如果 autoremove 无法删除旧内核
dpkg --list | grep linux-image
 
# 手动删除指定旧内核
sudo apt purge linux-image-5.15.0-xx-generic
sudo apt purge linux-headers-5.15.0-xx-generic
sudo update-grub

# 升级后 GNOME Shell 版本可能变化
gnome-shell --version
 
# 禁用所有扩展
gsettings set org.gnome.shell disable-user-extensions true
 
# 逐个启用测试
gnome-extensions list
gnome-extensions enable extension-name@example.com
 
# 更新扩展
# 访问 https://extensions.gnome.org 重新安装

# 检查当前显示协议
echo $XDG_SESSION_TYPE
 
# 某些应用不兼容 Wayland，可强制 X11 后端
GDK_BACKEND=x11 application-name

# 检查 Docker 服务状态
sudo systemctl status docker
 
# 如果 Docker 仓库版本代号未更新
# 重新配置 Docker 源
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
 
sudo apt update
sudo apt install --only-upgrade docker-ce docker-ce-cli -y
 
# 验证
docker run hello-world
docker compose version

# 1. 查看系统日志
sudo journalctl -b -p err
sudo journalctl -b -p warning | head -50
 
# 2. 查看特定服务日志
sudo journalctl -u service-name --since "1 hour ago"
 
# 3. 检查包完整性
sudo debsums -c  # 检查修改过的配置文件
sudo debsums -s  # 静默模式，仅显示错误
 
# 4. 重新配置包
sudo dpkg-reconfigure package-name
 
# 5. 查看升级日志
less /var/log/dist-upgrade/main.log
less /var/log/dist-upgrade/apt.log