seaworld008/centos7-lighthouse / skills/centos7-almalinux-upgrade
centos7-almalinux-upgrade
Flagged把老旧 CentOS 7 / CentOS 8(及 RHEL7/8 系)服务器原地升级到最新 AlmaLinux 10(经 ELevate/Leapp 7→8→9→10,CentOS 8 先用 almalinux-deploy 转换),并保证业务、容器、nginx、kubectl 等升级后照常工作。凡是用户提到 CentOS 7 / CentOS 停服 / EOL / 老系统升级 / 迁移到 AlmaLinux / Rocky / CentOS 继任者 / ELevate / leapp / 系统漏洞要升级系统、批量升级阿里云/华为云/AWS 上的 CentOS 服务器,都要使用本技能——即使用户没说"升级"而只说"系统太老了""换个新系统但业务不能停"。In-place upgrade CentOS 7 to AlmaLinux 10 safely, single server or whole fleet.
references/pitfalls.md
View on GitHub# 避坑手册(现象 → 原因 → 处理)
带 ★ 的是真实迁移中实际踩到的。
## 目录
1. 通用:远程操作
2. EL7 准备阶段
3. 7 → 8
4. 8 → 9
5. 9 → 10
6. 每跳重启后
7. 升级后应用层
---
## 1. 通用:远程操作
**★ SSH 会话 5 分钟左右被断,长命令执行到一半没了**
- 原因:sshd_config 里 `ClientAliveInterval 300` + `ClientAliveCountMax 0`,在 OpenSSH < 8.2 上表示"空闲就断"。换回 7.4/8.0 官方 openssh 后行为出现。
- 处理:客户端开 keepalive(remote.py 已开);leapp/dnf 这种长任务用 `systemd-run` 后台跑并写日志,再轮询(hop.sh 已这样做)。
**★ `pkill -f "xxx"` 把自己的会话杀了,返回 exit -1**
- 原因:`pkill -f` 匹配完整命令行,你远程执行的 `bash -c "...pkill -f 'leapp preupgrade'...; nohup leapp preupgrade"` 里本身就包含这个字符串。
- 处理:按 PID 杀;或用 `pgrep -f "[l]eapp preupgrade"` 这种写法(正则不匹配自身字面量,但注意同一命令行里别再出现未加括号的原文);或把命令写进脚本文件执行。
**★ Windows Git Bash 下传 `/root/xxx` 参数变成 `C:/Program Files/Git/root/xxx`**
- 原因:MSYS 路径转换。
- 处理:remote.py 已自动还原;其它工具可设 `MSYS_NO_PATHCONV=1`。
**★ 远程执行 `yum check` 等极慢命令导致本地工具超时**
- 处理:不需要的检查别跑;需要的放后台。
**★ 升级到 EL9.8/EL10 后 SSH 突然连不上,banner 只有 `Not allowed at this time`**
- 原因:OpenSSH 9.8+ 的 `PerSourcePenalties`。重启后 `wait-ssh` 反复探测端口(连上不认证就断)被记为 noauth 惩罚,同一来源 IP 被拒几分钟、反复探测还会延长;经 VPN/跳板 NAT 时所有操作都是同一个源 IP,一台机器上的探测就能把你锁在外面。
- 处理:停止探测等几分钟就会自动解除;`hop.sh prep`(目标 ≥9)会把当前 SSH 来源 IP 写进 `/etc/ssh/sshd_config.d/05-osup-penalty-exempt.conf` 的 `PerSourcePenaltyExemptList`(8→9 时 leapp 会给 sshd_config 加 Include,升级后自动生效)。
**★ 下载期间换"代理"不一定更快**
- 实测(华为云):三台机器同时从阿里云镜像下载时每台只有 250~350KB/s,同一时间单台测速却有 14~16MB/s——是镜像侧的临时限速,过一会儿就恢复;经 VPC 内另一台机器(mihomo 代理)转发反而只有约 380KB/s。先在本机 `curl -o /dev/null -w '%{speed_download}'` 对比几个镜像,再决定换不换(另一台华为云主机实测反过来:华为云镜像 20MB/s、阿里云只有 157KB/s——**每台、每次都要测,不要照搬上一台的结论**);leapp 的 dnf 下载日志按包写,大包(linux-firmware 600MB+)下载时日志会停很久,看 `/var/lib/leapp/el*userspace/var/cache/dnf` 下文件是否在变大。
## 2. EL7 准备阶段
**CentOS 7 官方源已下线 / repo 文件重复定义("Repository base is listed more than once")**
- 处理:`prep-el7.sh repos <MIRROR>` 统一成 centos-vault 7.9.2009 一个文件;不可达的第三方源自动禁用(否则 yum/leapp 卡住)。
**★ `prep-el7.sh repos` 卡住 20 分钟:卡在 `yum repolist enabled`**
- 原因:机器上有访问不了的第三方源(例如 pkgs.netbird.io),yum 对每个源都会长时间重试。
- 处理:现在改为用 `curl -m 15` 逐个探测每个启用源的 repomd.xml(或 mirrorlist),不通就 `enabled=0`。实测 33 秒完成。另外所有 `CentOS-*.repo`(Vault、Debuginfo、Media 等)都会被挪走。
**★ `yum update` 时某个 python 包 "Failed":`cpio: rename` / `unpacking of archive failed`**
- 原因:以前有人 `pip install` 到了系统 site-packages(例:pip 装的 urllib3 目录占了 rpm 要放的位置)。
- 处理:`prep-el7.sh pipfix`:挪走所有不属于 rpm 的 site-packages 文件(备份可还原),重装被覆盖的 python rpm,补装失败的包。**每一跳前都要再查一次**(hop.sh prep 会做)。
**★ openssh 是自编译 rpm(如 9.8p1,vendor 为空,SysV 启动脚本)**
- 风险:leapp 不升级非官方包;它链接的 EL7 库/SysV 脚本到新系统上失效 → sshd 起不来 → 失联。
- 处理:`swap-openssh.sh`:用官方 sshd 先 `-t` 测现有配置,备份旧二进制,systemd-run 脱离会话替换,端口没起来就用旧 sshd 兜底。替换后立即用新连接验证。
- 注意:9.x 自编译版的会话进程是 `/usr/libexec/openssh/sshd-session`,换包后旧监听进程再 fork 新会话会失败,所以换完必须立刻重启 sshd(脚本已处理)。
**★ 还在用 `network.service`(NetworkManager 没运行)**
- 风险:EL8 起以 NetworkManager 为准,EL9 起已经没有 network-scripts。
- 处理:`prep-el7.sh netmgr`:安装并启用 NM,去掉 `NM_CONTROLLED=no`,在后台切换;检查默认路由和外网访问,失败就自动回滚到 network.service。然后**在 EL7 上重启一次**,确认切换在重启后依然生效。
**★ yum update 装了新内核,但运行的还是旧内核** → leapp 要求当前运行的是最新内核,所以 7→8 之前要先在 EL7 上重启一次(可以和上面的 NM 验证一起做)。
**★ `yum update` 报 `Multilib version problems` / `Protected multilib versions: glibc-...i686 != glibc-...x86_64`,但根本没装 i686 包**
- 原因:rpm 库里有**重复包**(同名两个版本:glibc-common、nss-softokn-freebl、tzdata、grub2-*…),以前某次 yum 事务中断了(这台机器运行了 1700 多天)。
- 处理:`package-cleanup --dupes` 查看;`package-cleanup -y --cleandupes` 删旧副本;被其它包依赖而删不掉的,用 `rpm -e --justdb --nodeps <旧副本>` 只从库里去掉(先备份 /var/lib/rpm),再 `prep-el7.sh update`,最后 `yum reinstall` 这些包保证文件一致。`survey.sh` 报 HIGH。
**★ 7→8 阻断 `Multiple devel kernels installed`(明明 inhibitors 删过)**
- 原因:`inhibitors` 按"正在运行的内核"保留 kernel-devel,之后 update 又装了新内核的 kernel-devel。
- 处理:已改为保留"最新已安装内核"对应的 kernel-devel。
**★ 手工启动的宿主机程序(`nohup java -jar ... &`)重启后不会起来**
- 现象:进程挂在 SSH 的 `session-N.scope` 下,没有 systemd 服务、没有 rc.local/cron @reboot。升级要重启 3~4 次。
- 处理:`backup.sh` 记录这类正在监听端口的进程的 cmdline/cwd/exe/环境变量(`<BACKUP>/manual-procs/`);EL10 后 `finalize.sh manual-procs <dir>` 生成 systemd 服务,`systemctl enable --now`。`survey.sh` 报 HIGH。环境变量里 `LANG=zh_CN.GB18030` 之类在 EL10 需要 `glibc-langpack-zh`。
- 例外:银行前置机/证书客户端(如某银行 B2C 外联平台)启动时要输入或校验证书密码,升级后可能报"证书密码错误",这类交给业务方处理,不要尝试。
**★ Harbor 机器重启后,core/registry/nginx 等容器全部 exited:`failed to initialize logging driver: dial tcp 127.0.0.1:1514: connection refused`**
- 原因:Harbor 的容器都用 syslog 日志驱动,发到 harbor-log 容器(1514 端口)。开机时它们比 harbor-log 先启动,Docker **不会重试**这种失败。这与升级无关,任何一次重启都会发生,但升级要重启好几次。
- 处理:加一个 `harbor-autostart.service`:等 1514 端口可用后,`docker start` 该 compose 项目里已经退出的容器(见 app-compat.md 的 Harbor 一节)。
**★ 自编译 nginx 静态重编时的坑**(`nginx-static-build.sh` 已修)
- 正则误伤:`--with-openssl-opt=...` 被截成 `-opt=...`
- 老版本(如 1.16.x)的签名者公钥已不在 nginx.org/keys → 按 key ID 从 keyserver.ubuntu.com 获取
- 国内服务器下载 GitHub 上的 OpenSSL 超时 → 在本机下载后上传到 `/usr/local/src/nginx-static/`;残缺文件会被 sha256 校验发现并删除
- 运行中的二进制 `cp` 覆盖会报 `Text file busy` → 先复制再 `mv` 替换
- 原二进制已经是 OpenSSL 3.x 编译的(`nginx -V` 显示 `built with OpenSSL 3.5.9`,只有 `libpcre.so.1` 是 EL7 依赖)→ 不要降回脚本默认的 1.1.1w:`NGX_OPENSSL=openssl-3.5.9 NGX_OPENSSL_SHA256=<官方 .sha256> bash nginx-static-build.sh ...`。EL7 的 gcc 4.8.5 能编 OpenSSL 3.5(需要 perl-IPC-Cmd,脚本会装)
- 静态重编后仍依赖 `libcrypt.so.1`(auth_basic 用):EL9 起要 `libxcrypt-compat`,见 8→9 一节
**★ `yum update` 整个事务失败,系统停在 7.6:第三方源的包出问题**
- `mysql-community-client-8.0.46 ... The GPG keys listed for the "MySQL 8.0 Community Server" repository are already installed but they are not correct for this package`:MySQL 换过签名密钥,老的 mysql80-community-release 里只有旧 key。
- `file /usr/obd/plugins/oceanbase-ce-libs from install of ob-deploy-4.7.0 conflicts with file from package ob-deploy-2.10.1`:OceanBase 源的新版包自己和旧版冲突。
- 处理:mysql-community-* 先按下一条 swap 掉(客户端到 EL10 再装发行版的 `mysql8.4`);用不上的第三方源挪到 `/etc/yum.repos.d/disabled-for-upgrade/` 后重跑 `prep-el7.sh update`。看 `yum7update.log` 里 `Transaction check error` / `GPG` 附近的行。
**★ 运行了几年没重启的机器:先在 EL7 上重启一次再开始 leapp**(两台 861 / 1529 天没重启的测试机,重启后暴露的全是"升级前就存在"的问题)
- `restart=no` 的容器(node_exporter)开机不会起来 → `docker update --restart=always`(survey 报 HIGH)。
- 开机自启但早就起不来的服务:KingbaseES `License file expired`、CDM 实例服务——平时没人发现,因为一直没重启。写进报告交给业务方,不算升级引起。
- 数据库手工启动、其实有现成的 unit(达梦 `DmServiceDMTEST.service` 是 enabled,但 dmserver 是 2025 年手工起的):用官方脚本 `DmServiceXXX stop` 停掉再 `systemctl start`,确认 unit 能用,开机就会自己起来,不必生成新 unit。
- 把这些和升级问题分开,后面每一跳的 verify 才有意义。
**★ 卸载 `mysql-community-libs-compat` 会连带删掉 postfix**
- 原因:它替换了 `mariadb-libs` 提供的 libmysqlclient.so.18,postfix 依赖它。
- 处理:`yum swap -- remove mysql-community-* -- install mariadb-libs`(`prep-el7.sh inhibitors` 已做);宿主机若装了 mysql-community-server 则不要自动处理。
**★ 第三方 rpm 拥有的可执行文件被手工替换过:卸载该包时一起被删**
- 现象:`/usr/bin/php` 早就被换成"转发到 PHP 容器"的包装脚本(宿主机 PHP 改用容器后),但文件仍属于 remi 的 `php-cli`。按计划卸载 remi PHP 后 `/usr/bin/php` 消失,20 个 Jenkins 任务的 `php`/`composer` 会全部失败。leapp 删除无 EL8 包的第三方 rpm 时也一样。
- 处理:卸载前 `cp -a /usr/bin/php /usr/local/bin/php`,卸载后 `ln -sf /usr/local/bin/php /usr/bin/php`(构建任务的 PATH 可能不含 /usr/local/bin,所以 /usr/bin 下要留链接)。survey 会列出这类文件(`rpm -V` 摘要变化的第三方包可执行文件)。
**★ backup.sh 的基线里所有 HTTP 探测都是 000(EL7)**
- 原因:`state.sh` 为了让 EL8+ 不走 h2 固定了 `curl --http1.1`,而 EL7 的 curl 7.29 不认识这个参数(7.33 起才有),整条命令报错。
- 处理:已修,先探测 curl 是否支持再加。基线里 http 行全是 000 就说明探测本身坏了,不要拿它对比。
**★ backup.sh 打包 /root 花了十几分钟(构建机)**
- 原因:CI/构建机的 /root 里有 `.m2`(17G)、`.npm`(16G)等构建缓存。
- 处理:已默认排除 `.m2/repository`、`.npm`、`.pnpm-store`、`.gradle/caches`、`.yarn/cache` 等(可重新下载,快照里也有)。
**★ pipfix 之后 leapp 起不来:`ImportError: No module named urllib3.exceptions`**
- 原因:当年有人用 pip 版 urllib3 替换了 rpm(`rpm -e --nodeps python-urllib3`),`python-requests` rpm 一直靠 pip 版撑着;pipfix 把不属于 rpm 的 pip 文件挪走后依赖露出来,leapp 一启动就崩(preupgrade 直接"无报告")。
- 处理:`yum install python-urllib3 && yum reinstall python-requests`。`prep-el7.sh pipfix` 现在会跑 `yum check dependencies` 补装缺失的 rpm 依赖,并验证 `import requests`。
## 2b. 源系统是 CentOS Linux 8 / Stream 8
**★ 资产表写的是"CentOS 7",实际上是 CentOS 8.3**
- 处理:一律以 `survey.sh` 的结果为准。CentOS 8 要先 `convert-el8.sh` 转成 AlmaLinux 8,ELevate 只接受 AlmaLinux/Rocky/RHEL 8 作为 8→9 的源。
**★ `almalinux-deploy`:`Please upgrade your OS from 8.3 to … ERROR`**
- 原因:要求 ≥ 8.4。
- **不要用它的 `-f`**:`-f` 只认 `CentOS-Linux-BaseOS.repo` 这类原始文件名(否则报 `Error: No repo file found for BaseOS`),并会把源改到海外的 rackspace vault。
- 处理:`convert-el8.sh update`,用自己配好的国内 vault 源 `dnf upgrade` 到 8.5,再 `convert-el8.sh run`(默认 `-d`)。
**★ EL8 机器上配着 EPEL 7(`epel.repo` 里是 `epel/7`)**
- 风险:distro-sync / leapp 会从错误的大版本拉包。
- 处理:`convert-el8.sh prep` 会改成 EPEL 8。`survey.sh` 会对 EPEL 版本与系统不一致报 HIGH。
**★ 国内服务器访问不了 `raw.githubusercontent.com`**
- 处理:在本机下载 `almalinux-deploy.sh` 后用 `remote.py put` 上传。`-l=<MIRROR>/almalinux` 让它走国内镜像(阿里云内网 `mirrors.cloud.aliyuncs.com` 实测 66ms)。
**★ CentOS 8 的 repo 指向已下线的 `centos/8-stream`**
- 处理:改成 vault:CentOS Linux 8 用 `centos-vault/8.5.2111`,Stream 用 `centos-vault/8-stream`。
**★ almalinux-deploy 显示"Migration to AlmaLinux is completed",但 680 个包还是 CentOS 的,内核也还是 CentOS 的**
- 现象:`distro-sync OK`,但 `rpm -qa --qf '%{VENDOR}\n' | sort | uniq -c` 里几乎全是 CentOS;`dnf upgrade` 显示 Nothing to do;日志里有 `Repository baseos is listed more than once`。
- 原因:自己写的 vault 源用了 `[baseos]/[appstream]/[extras]`,与 AlmaLinux 的 repo id 冲突,dnf 选用了 CentOS 的定义,distro-sync 实际同步回了 CentOS 8.5。vault 源不属于任何 rpm,almalinux-deploy 不会删除它。
- 处理:vault 源的 repo id 用不会冲突的名字(`c8vault-*`),并在执行 deploy 前移走(`convert-el8.sh` 已修)。已经中招的话:移走 vault 源 → `dnf -y distro-sync --allowerasing` → 确认 `grubby --default-kernel` 是 AlmaLinux 内核 → 重启。
- 判断标准:转换后 CentOS 厂商的包应只剩个位数(旧内核)。AlmaLinux 8 早期的包 vendor 显示为 **CloudLinux**,这是正常的。
**★ Aliyun 镜像里的 cloud-init 是源码安装的(`rpm -q cloud-init` 显示未安装,但 unit 是启用状态)**(3 台阿里云机器都遇到了;`hop.sh post` 现在会自动禁用并挪走这些不属于 rpm 的 unit)
- 现象:升到 EL9 后,cloud-init 的 4 个 unit 都变成 failed(它依赖 EL8 的 python3.6)。
- 处理:长期运行的 ECS 上,cloud-init 只在首次开机时有用。`touch /etc/cloud/cloud-init.disabled` 后执行 `systemctl reset-failed`。如果需要,就装发行版的 cloud-init 包。
## 3. 7 → 8
| 阻断项 / 报错 | 处理 |
|---|---|
| ★ `Leapp detected loaded kernel drivers which have been removed in RHEL 8`(floppy、pata_acpi) | `rmmod` + `/etc/modprobe.d` 黑名单(prep-el7.sh inhibitors) |
| ★ `Multiple devel kernels installed` | 只保留当前内核的 kernel-devel |
| ★ `Missing required answers`:`remove_pam_pkcs11_module_check.confirm` | `leapp answer --section remove_pam_pkcs11_module_check.confirm=True`(hop.sh answer) |
| ★ `Detected customized configuration for dynamic linker`(mysql-x86_64.conf) | 随 mysql-community-libs 一起换掉即消失 |
| ★ `dnf_transaction_check` 失败:`Failed to download metadata for repo 'el8-docker-ce-nightly'` | vendors.d/docker-ce.repo 改国内镜像并关掉 test/nightly 段(hop.sh prep) |
| ★ preupgrade 卡在 dnf_transaction_check 几十分钟 | EPEL 走 metalink 国外镜像,改国内 baseurl(hop.sh prep) |
| `Packages not signed by Red Hat`(hostguard、kubectl、自编译包…) | 不是阻断;但升级后这些包保持 EL7 版本,逐个确认还能用 |
| `Difference in Python versions` / `GRUB2 core will be updated` | 提示,无需处理 |
| ★ `The pam_tally2 pam module(s) no longer available`(system-auth-ac、password-auth-ac) | 先看这两个 `-ac` 文件有没有被引用:`grep -l auth-ac /etc/pam.d/*`。实测 system-auth/password-auth 早已是独立文件、`-ac` 没人引用,注释掉其中的 `pam_tally2` 行即可,登录行为不变;真在用的要改成 `pam_faillock`(改 PAM 前留一个已登录的会话) |
| ★ `Use of NFS detected`,但不想为了几十分钟的下载停业务 | 注释 fstab 的 NFS(`k8s.sh nfs-off`,非 K8s 主机也能用)后在**宿主机**卸载:容器的 bind mount 在自己的挂载命名空间里(rprivate),宿主机卸载后容器里的 NFS 照常读写(实测 8 个容器写入正常),leapp 检查也通过。重启前 `hop.sh reboot` 会 mask docker,重启后 `k8s.sh nfs-on` 先挂 NFS 再放开 docker |
| /var 空间不足 | leapp 需要约 3~5GB;清 docker 无用镜像(先确认)、日志、yum 缓存 |
| ★ preupgrade 0 阻断,`leapp upgrade` 却在 `dnf_package_download` 失败:`Transaction test error: file /usr/lib64/libwebp.so.7 from install of libwebp-1.0.0 conflicts with file from package libwebp7-1.0.3-2.el7.remi`(还有 libzip5) | 宿主机 PHP 早已迁走(容器化),Remi 的兼容库(libwebp7/libzip5/libicu69/oniguruma5php/gd3php/ImageMagick6-libs)留着没人用,和 EL8 的同名 so 冲突。preupgrade 的事务检查查不出来,下载完才报。确认没有非 Remi 包依赖后删除(`prep-el7.sh inhibitors` 第 5 步自动做;宿主机还有 Remi 的 php 时不动) |
**★ 最严重:升级重启后进 initramfs 紧急模式,`upgrade.service failed`,日志 `dnf_upgrade_transaction ... python2-pyyaml install failed: cpio: File from package already exists as a directory`**
- 原因:pip 装的 PyYAML(`/usr/lib64/python2.7/site-packages/yaml`、`PyYAML-3.12-py2.7.egg-info`)和 rpm 冲突。只有这一个包失败,但 DNF 返回非 0 → leapp 后续阶段(清理、post 动作)全部没跑。系统其实已经大部分是 EL8 了。
- 处理:见 `recovery.md` 的"半升级"流程。预防:每跳前 pipfix。
## 4. 8 → 9
| 阻断项 / 报错 | 处理 |
|---|---|
| ★ `Cannot perform the VDO check of block devices` | `dnf install vdo`(让检查能跑),确认无 VDO 设备后 `leapp answer --section check_vdo.confirm=True`(hop.sh answer 自动) |
| ★ `Network configuration for unsupported device types detected`(ifcfg-eth0) | 老阿里云镜像的 ifcfg 没有 `TYPE=Ethernet`,且是静态 IP。EL8 的 NM(≥1.38)可以直接 `nmcli connection migrate` 转成 keyfile,`hop.sh answer` 在 8→9 遇到这个阻断项时自动处理(迁移前后对比地址和默认路由),也顺带解决了 9→10 的 ifcfg 阻断项 |
| ★ `iptables-services` 出现在 8→9 的删除列表 | EL9 改名为 `iptables-nft-services`。先看 `/etc/sysconfig/iptables`:如果只有全部 ACCEPT(常见),删了也没影响;如果有真实规则,升级后安装 iptables-nft-services 并 enable |
| ★ `Firewalld Configuration AllowZoneDrifting Is Unsupported` | `AllowZoneDrifting=no`(EL9 行为本来就等同于 no);`hop.sh answer` 自动处理。**不要 `firewall-cmd --reload`**:可能清掉 Docker 的 iptables 链,导致容器网络断开,重启时自然生效 |
| ★ 安装 el8 的 leapp 时 `filtered out by exclude filtering` | 上一跳 leapp 在 /etc/dnf/dnf.conf、/etc/yum.conf 留了 `exclude=...leapp...`,删掉(hop.sh 已处理) |
| ★ 旧 el7 leapp 包残留导致 el8 leapp 装不上 | `rpm -e --nodeps` 删旧 leapp 包 + 删 /etc/leapp/files(hop.sh prep/post 已处理) |
| `Remote root logins globally allowed using password` | 若 sshd_config 显式写了 `PermitRootLogin yes` 则只是提示;**没写的话 EL9 默认 prohibit-password,root 密码登录会失联**,先显式写上 |
| python2 | EL9 没有 python2。确认无人依赖后移除(hop.sh prep 会检查依赖);有依赖的脚本先改 python3 |
| ★ `Network configuration for unsupported device types`:`ifcfg-eth0.bak` | 手工留下的备份副本也被当成配置。`hop.sh answer` 在 migrate 前把 `ifcfg-*.bak/.orig/.old/~` 挪到工具目录 |
| ★★ 重启进升级环境几秒就 `Entering emergency mode`,VNC 里敲命令没反应 | fstab 里有 bind 到 /sys 的条目(阿里云 `set_ecs_special.sh` 的 `eth0-speed.mock`)。leapp 把 fstab 固化成升级 initramfs 的 mount unit,挂不上就进 emergency,shell 在 ttyS0。`hop.sh up` 现在自动注释(EL10 post 恢复);已经中招见 recovery.md B2 |
| ★ `Detected RPMs with RSA/SHA1 signature`(rh-ruby23-*、rh-php72-*、devtoolset-*、llvm-toolset-*) | EL7 的 SCL 包(装在 /opt/rh)7→8 时 leapp 不处理、原样留下,EL9 不接受 SHA1 签名。确认没有进程/脚本在用 /opt/rh 后删除;`hop.sh post`(到 EL8 时)自动删。第三方工具包(如 OceanBase 的 `ob-deploy`,自带 PyInstaller 二进制)想保留文件的话:`rpm -ql` 存一份文件清单、备份 /var/lib/rpm,然后 `rpm -e --justdb --nodeps <包>`(只从 rpm 库去掉,文件不动、命令照常可用)。到 EL9 后再 `rpm -e gpg-pubkey-<SHA1 key>`,否则每次 rpm 操作都报 `Signature not supported. Hash algorithm SHA1 not available` |
| ★ 自编译程序(静态重编的 nginx、源码编译的 mysqld 5.7)在 EL9 上起不来:`libcrypt.so.1: cannot open shared object file` | EL9 起 libxcrypt 只提供 libcrypt.so.2,so.1 在 `libxcrypt-compat` 里且默认不装。`hop.sh prep`(目标 ≥9)扫描运行中的非 rpm 程序,需要时把 libxcrypt-compat 写进 `/etc/leapp/transaction/to_install`,升级事务里一起装上,重启后直接能起来 |
| ★ 宿主机 docker 容器正常但 Yearning 无限重启:`open /sys/fs/cgroup/memory/memory.limit_in_bytes: no such file` | EL9 起默认 cgroup v2。见 app-compat.md "cgroup v2" |
| ★ 升级后监控一直报"目标失联"(夜莺 `target_miss` 等),但 agent 明明在跑;`hostname` 从 `app_01` 变成 `app01` | `/etc/hostname` 没变,但 EL9 起的 systemd 开机时会把不合法的主机名字符(下划线等)去掉再设给内核。监控 agent 用 `$hostname` 拼 ident(如 categraf 的 `hostname = "$ip-$hostname"`),ident 就变了:监控平台里多出一个新目标,旧目标失联。实测从 EL9 第一次开机开始变。survey 会提示。处理(二选一,由用户决定):在 agent 配置里写死升级前的 ident(categraf:`hostname = "$ip-app_01"`,然后重启 agent),再到监控平台删掉多出来的新目标;或者干脆把主机名改成合法名字,再到平台删掉旧目标。依赖主机名的其他东西也要看看(宿主机 MySQL 的 `<hostname>.err`/`.pid`、按主机名区分的日志采集等) |
| ★ `Detected RPMs with RSA/SHA1 signature`:`jenkins`(DSA/SHA1,2019 年的 2.204.x rpm) | 老 Jenkins rpm 的签名 EL9 不接受。实际运行的 war 常常早被手工替换(rpm 2.204.1、war 2.346.1),启动也已换成自己的 systemd unit(见 app-compat.md Jenkins)。此时 rpm 只是一条记录:`rpm -ql jenkins` / `rpm -q --scripts jenkins` 存档后 `rpm -e --justdb --noscripts --nodeps jenkins`——**不删文件、不跑卸载脚本**(war、JENKINS_HOME、jenkins 用户都保留)。还在用 rpm 的 SysV 脚本启动的话,先换 unit 再做 |
## 5. 9 → 10
| 阻断项 / 报错 | 处理 |
|---|---|
| ★ `Deprecated DHCP plugin configured` | NM 用的是 `dhcp=dhclient`,而 EL10 没有 dhclient。来源可能不在 /etc:实测在 `/usr/lib/NetworkManager/conf.d/10-dhcp-dhclient.conf`,是**不属于任何包的残留文件**。`hop.sh answer` 会注释掉 /etc 里的这一行,并挪走 /usr/lib 下的残留文件;用 `NetworkManager --print-config \| grep dhcp` 确认已不再生效。静态 IP 的网卡不受影响 |
| ★ `Legacy network configuration found`(每个 ifcfg 一条) | 先备份 network-scripts,`nmcli connection migrate`(不重连,地址/路由不变),确认 eth0 的 FILENAME 变成 .nmconnection |
| ★ `Berkeley DB (libdb) has been detected` | EL10 没有 libdb。postfix 的 `hash:` 表升级后改 `lmdb:`(finalize.sh postfix-lmdb);其它用 libdb 的程序要换 |
| ★ `kernel drivers which are no longer maintained`(nft_compat、ip_set) | 提示;fail2ban/docker 仍可用,升级后验证 |
| CPU 不满足 x86-64-v3 | AlmaLinux 10 标准版无法启动!survey 会报 BLOCKER;用 x86_64_v2 变体或停在 9 |
| ★ 事务里会删掉 java-1.8.0/11/17-openjdk、redis、dhcp-client 等 | 用 `hop.sh report` 看"将被删除的包":宿主机直接跑 Java 8/11/17 程序的要改用容器或自带 JDK;NetworkManager 配了 `dhcp=dhclient` 的要先改回 internal |
**★★ 华为云 c9 规格:9→10 重启后卡在升级 initramfs,`dracut-initqueue: Timed out while waiting for udev queue to empty` 无限循环**
- 现象:重启后 SSH 不回来;VNC 里约 369 秒出现 hung task,调用栈 `init_module_from_file → do_init_module → async_synchronize_cookie_domain`,之后每 2 分钟一行 udev 超时。关机时多个 udev worker(0000:00:01.1 PIIX3 IDE、virtio、VGA、cpu)都报 `is taking a long time`,SIGKILL 也杀不掉,Ctrl+Alt+Del 重启不了。
- 原因:AlmaLinux 10 内核(6.12)在 c9(擎天)虚拟硬件上早期加载驱动时,某个异步探测任务永远不结束,`modprobe`/udev worker 都卡在 `async_synchronize` 里。卡在挂载根分区之前,**系统盘上的东西一点没动**。同一晚升级的 s3、之前的 c3 规格正常,EL9 内核在 c9 上也正常。
- 对照实验(2026-11-13,两台按需 c9.xlarge.2 测试机,AlmaLinux 9.8 → 10):**只有系统盘和加了数据盘的两台都以同样方式卡死**,与数据盘无关;最初怀疑 PIIX3 IDE(ata_piix),但**把 ata_piix/ata_generic 加入黑名单**(升级启动项 `modprobe.blacklist=… rd.driver.blacklist=…` + `/etc/modprobe.d`)后,ata_piix 已不再加载,**仍然同样卡死**——它不是原因。
- 处理:leapp 把升级启动项设成了**持久默认项**(grubenv `saved_entry`),强制重启还会进去;华为云强制重启后 VNC 要几秒才重连,5 秒的 GRUB 菜单抢不到。可靠的办法是换盘改 grubenv:见 `recovery.md` F(`scripts/rescue-grubenv.sh`)。改回 EL9 后业务原样恢复。
- 预防:`survey.sh` 对华为云 c9 规格报 HIGH。**c9 只升到 AlmaLinux 9**(支持到 2032);目前没有验证过的绕过办法。以后 AlmaLinux 10 内核更新后,可用同规格按需测试机(官方 AlmaLinux 9.4 镜像 → `dnf upgrade` → hop.sh 9→10,约 30 分钟)再试。
## 6. 每跳重启后
**★ `leapp_resume.service` failed:`ModuleNotFoundError: No module named 'leapp.libraries.common.rhsm'`**
- 原因:重启后 SSH 一恢复,就马上执行了清理(删除 leapp 包和 /etc/leapp),而 leapp 的 FirstBoot 阶段(`leapp_resume.service`,含 removeleftoverpackages 等)还在跑,被删掉了自己的模块。
- 处理:`hop.sh post` 现在会先等 `leapp_resume.service` 结束(最多 30 分钟)再清理;它失败时会打印日志并继续清理残留包和内核,最后删掉这个临时 unit。
- 教训:SSH 能连上 ≠ 升级流程已经结束。
**★ 7→8 后 verify 报一批 HTTPS 站点 `200 → 000`,但 nginx 正常、浏览器也能打开**
- 原因:EL8 的 curl 默认协商 HTTP/2,nghttp2 对非法响应头直接 `PROTOCOL_ERROR`;这些站点配置里写了 `add_header 'Access-Control-Allow-Credentials:' 'true'`(头名带冒号)。EL7 的 curl 7.29 不走 h2,所以基线是 200。
- 处理:`state.sh` 的探测固定 `--http1.1`,前后可比。头名带冒号是业务配置的老问题(严格的 HTTP/2 客户端会失败),列出文件交给业务方修。
**★ 基线里一个容器都没有(Docker 19.03)**:`docker ps --format '{{.State}}'` 是 20.10 才有的字段,19.03 报模板错误、不输出 → `state.sh` 已改为失败时用 `{{.Status}}` 推出状态。旧基线要补:重新跑 state.sh,把 `ctr` 行追加进 baseline.tsv。
**dbus.service 在 EL9 上"没有运行"** → 被 `dbus-broker.service` 取代,属于预期(verify.sh 已映射)。
**sssd / smartd / vdo / rngd-wake-threshold "没有运行"** → 新版本 unit 带启动条件,没有配置就跳过(verify.sh 会识别 `ConditionResult=no`)。
**★ `Error: Cannot find a valid baseurl for repo: epel-cisco-openh264`**
- 原因:这个源只有 metalink(codecs.fedoraproject.org),镜像站没有它;改写镜像时把 metalink 注释掉了,导致没有任何可用地址。
- 处理:`hop.sh post` 改写镜像时跳过它并将其 `enabled=0`(极少需要 openh264)。
**★ 旧 repo 文件仍指向 EL7/EPEL7,`dnf distro-sync` 报一堆 "nothing provides … from epel"**
- 原因:用户改过的 repo 文件不会被覆盖,新版本放在 `*.rpmnew`;旧文件以 `*.rpmsave` 留下。
- 处理:`hop.sh post`:rpmnew 替换、rpmsave 挪走、硬编码旧版本号的源挪走、镜像改写。
**★ `dnf distro-sync` 报模块包冲突(javapackages、eclipse/maven 模块)**
- 处理:用 `dnf -y upgrade --nobest` 即可,不必强求 distro-sync。
**★ 7→8 后 EL7 内核删不掉:`%preun(kernel-3.10.0-…) scriptlet failed, exit status 127`**
- 原因:EL7 内核包的卸载脚本调用 `new-kernel-pkg`,EL8 上没有这个命令。
- 处理:`hop.sh post` 会用 `rpm -e --noscripts` 删除,再清理 `/boot` 下对应的文件、`/lib/modules/<ver>` 和 BLS 启动项。
**★ 7→8 预检又报 floppy/pata_acpi 已加载(明明已经加了黑名单)**
- 原因:黑名单只写在 /etc/modprobe.d,但开机用的是旧 initramfs(黑名单之前构建的),所以模块又被加载了。另外 `prep-el7.sh inhibitors` 曾把 "rmmod xxx" 写进了黑名单文件。
- 处理:两处都已修复:写入黑名单后用 `dracut -f` 重建 initramfs;`hop.sh answer`(7→8)会再卸载一次。
**★ 旧内核、leapp 包、/var/lib/leapp(3GB+)残留**
- 处理:`hop.sh post` 统一清理,并删失效的 BLS 启动项。
**★ 依赖 NFS 的容器在 NFS 恢复前就起来了,业务目录绑到空的本地目录(`systemctl disable docker` 没用)**
- 原因:升级事务里 docker-ce 被升级,包脚本把 docker 重新 enable,开机就启动;`restart=always` 的容器把 `/data/xxx`(此时还是 NFS 挂载点下的空目录)绑进去,期间写入的日志落在本地盘、被随后挂上的 NFS 盖住。
- 处理:重启前 `systemctl mask docker.service docker.socket`(`hop.sh reboot` 在 fstab 有 `#osup-nfs#` 时自动做);重启后 `k8s.sh nfs-on` 挂好 NFS 再 unmask/启动。已经中招:挂上 NFS 后 `docker restart` 相关容器;被盖住的本地文件可 `mount --bind / /mnt/x` 后在 `/mnt/x/<挂载点>` 看到。完成后给 docker 加 drop-in `[Unit] RequiresMountsFor=/data/xxx`,以后普通重启也不会抢跑。
**★ cloud-init 服务 failed(203/EXEC)**
- 原因:EL7 上是 pip/egg 装的 py2 cloud-init。
- 处理:长期运行的机器上 cloud-init 作用有限,可 `touch /etc/cloud/cloud-init.disabled`;AWS 等依赖它的环境改装新系统 cloud-init 包(见 cloud-providers.md)。
**云厂商 SysV 插件**(华为 hostguard/ICAgent/CloudResetPwd…):AlmaLinux 10.2 仍保留 systemd-sysv-generator,实测能正常启动;为防以后去掉,可 `finalize.sh sysv-units` 包成原生 unit。升级前就坏的插件(如 cloudResetPwdAgent)在报告里注明"非本次引起"。个别机器上 cloudResetPwdUpdateAgent restart 后不写 pid 文件、一直 failed(同版本的其它机器正常),属于插件自身问题,同样注明、交给云厂商。
**★★ GitLab(omnibus 容器)一直 502:内置 PostgreSQL 反复 `lock file "/var/opt/gitlab/postgresql/.s.PGSQL.5432.lock" already exists`**
- 现象:7→8 重启后 GitLab 正常起来,`hop.sh post` 跑完却变成 502;`gitlab-ctl status` 里 postgresql 每秒重启一次,日志提示 `Is another postmaster (PID 375) using socket file`,但 `ps -p 375` 查不到。
- 原因:`hop.sh post` 的 dnf 事务升级了 docker-ce/containerd → dockerd 重启,**容器默认只给 10 秒就 SIGKILL**,GitLab 的 PostgreSQL 没关完,锁文件留在持久化目录里。新容器里 PID 375 恰好是别的进程的**线程**(`ps -p` 不列线程,但 `kill(pid,0)` 成功),PostgreSQL 就认为还有另一个实例在跑。
- 处理:确认容器里没有 postgres 主进程后,`gitlab-ctl stop postgresql`,把 `.s.PGSQL.5432.lock` 挪走、删掉 `.s.PGSQL.5432`,`gitlab-ctl start postgresql`。PostgreSQL 会自动做崩溃恢复(实测 `redo is not required`),`/-/readiness?all=1` 全部 ok 即可。
- 预防:compose 里给 GitLab 加 `stop_grace_period: 5m`;`hop.sh reboot` 和 `hop.sh post` 现在会先优雅停止有状态容器(GitLab/Gitea/Nexus/SonarQube 等已加入名单,最长等 300s),post 结束再启动回来;survey 对没设 stop_grace_period 的 GitLab 容器报 MEDIUM。
**★ 升级后的"慢性病":`verify.sh` 全绿,过几天才暴露**(一次对约 38 台已升级/新装机器的集中体检,见 `field-reports/2026-11-19-fleet-post-upgrade-audit.md`)。`verify.sh` 只比业务基线,下面这些要靠 `post-audit.sh`(只读)找出来;能自动修的由 `hop.sh tidy` 处理(`hop.sh post` 末尾自动执行,已升级完的机器可单独跑)。
**★★ 升级完日志不再轮转:logrotate 没有任何东西在调度**
- 现象:`/var/log/messages`、nginx/应用日志从升级那天起一直变大;`systemctl list-timers` 里没有 logrotate。17 台 leapp 升级到 9/10 的机器全部中招,全新安装的机器正常。
- 原因:EL8 的 logrotate 由 `/etc/cron.daily/logrotate` 调度;EL9 起改为 `logrotate.timer`,只在全新安装时按 preset 启用,leapp 升级不会对新增的 unit 执行 preset(上游 RHEL-17361)。
- 处理:`systemctl enable --now logrotate.timer`(`hop.sh tidy` 自动做),然后 `logrotate -d /etc/logrotate.conf 2>&1 | grep ^error` 看配置本身有没有错。常见错误两类:`logrotate.d` 里有人留的 `nginx.bak` 之类副本(logrotate 会读 `.bak`,与原文件重复定义同一日志,`duplicate log entry`,出错的那份配置被跳过)→ 把副本挪出目录;日志父目录权限过宽(`parent directory has insecure permissions`)→ 配置里加 `su root root`(或对应属主)。
**★ `vi` 每次启动报 `E319: Sorry, the command is not available in this version`(`crontab -e`、`visudo` 都会弹)**
- 原因:8→9 时 leapp 往 `/etc/virc` 追加了 `let skip_defaults_vim=1`、`filetype plugin on` 等(带 `" content added by Leapp` 注释),这些只有完整 vim 才有;`vi` 是 vim-minimal。包自带的新版本在 `/etc/virc.rpmnew`。
- 处理:virc 里除了 Leapp 追加的行没有别的自定义内容时,用 `virc.rpmnew` 替换(`hop.sh tidy` 自动做,先备份;有自定义内容就只提示、不动)。
**★ 开机 `systemd-sysctl` 报 `Couldn't write '1' to 'fs/may_detach_mounts'`**
- 原因:`fs.may_detach_mounts` 只存在于 EL7 内核(Docker/K8s 的老安装文档常让加),EL8+ 内核没有这个键。
- 处理:注释掉(`hop.sh tidy` 自动做;`/etc/sysctl.d/99-sysctl.conf` 是指向 `/etc/sysctl.conf` 的链接,只改真实文件,不要把链接 `sed -i` 成普通文件)。
**★ `/etc/security/limits.conf` 写错的行:从来没生效,每次登录和每个 cron 任务都记错误**
- 现象:`/var/log/secure` 里大量 `pam_limits(crond:session): unknown limit item ...` / `invalid line`;写错的那一行从来没生效过(例如限制项拼错、列数不对)。EL7 上就是这样,只是没人看 secure 日志,升级后体检时才发现。
- 处理:`post-audit.sh` 会列出可疑行。按本意改正或注释——改正后限制会**第一次真正生效**,值偏小的话要先和业务确认;不自动改。
**★ 被删除的旧服务留下的启用链接(`vdo.service`、`rhel-*.service`、`lvm2-lvmetad`、`readahead`、`netconsole`)**
- 现象:`/etc/systemd/system/*.wants/` 里指向不存在文件的链接;不影响启动,但每次 `systemctl` 相关检查都有噪音,也会掩盖真正的问题。
- 处理:`hop.sh tidy` 删除上述已知名字的失效链接(清单备份在 `/root/os-upgrade-kit/tidy-backup/removed-links.txt`);其它名字的失效链接由 `post-audit.sh` 列出,人工确认是谁的。
**★ `docker-ce.repo` 被人手工写死 `centos/7`,升级后 docker 一直装 EL7 的包**
- 原因:同一个文件里其它段还是 `$releasever`,`hop.sh post` 的"硬编码旧版本的源挪走"规则因此跳过了它;`dnf` 不报错,只是 docker-ce/containerd 停在 el7 版本。
- 处理:把写死的版本号改回 `$releasever`(`hop.sh tidy` 自动做,post 在处理源之前也会先做)。另外 post 现在把比上一跳更旧的版本号(7…上一跳)都当作"写死旧版本",之前某跳漏掉的源也会被挪走。
**★ 云厂商的非 rpm agent 在 EL9+ 起不来:`libldap-2.4.so.2: cannot open shared object file`**
- 原因:EL9 起 openldap 是 2.6,2.4 的 so 在 `openldap-compat` 里,默认不装(与 libcrypt.so.1 / libxcrypt-compat 同类)。实测是某云数据库审计 agent。
- 处理:已升级的机器 `dnf install openldap-compat` 后重启该服务;`hop.sh prep`(目标 ≥9)发现运行中的非 rpm 程序依赖 libldap/liblber-2.4 时,把 openldap-compat 写进 leapp 的 `to_install`。`post-audit.sh` 对本地程序和 failed unit 的可执行文件做 `ldd`,缺库报 HIGH。
**★ unit 文件里 `Restart=` 等键写在了 `[Install]` 段:一直被忽略**
- 现象:`journalctl -b | grep "in section 'Install', ignoring"`;这些键从来没生效(写的若是 `Restart=`,服务挂了不会被拉起),EL7 上也一样,只是没人注意。
- 处理:把键挪到 `[Service]` 段后 `daemon-reload`。`post-audit.sh` 报 HIGH。
**★ 退回 9.8 的机器(华为云 c9)一直带着 leapp 包、ELevate 源和 `/var/lib/leapp` 的升级用户空间**:见 `recovery.md` F 第 7 步。`post-audit.sh` 会报 MEDIUM。
## 7. 升级后应用层
**★ 日志采集器(vector)升级后无限重启:`Memory cgroup out of memory: Killed process (vector)`**
- 现象:容器 `RestartCount` 几分钟涨到 200+;`docker inspect` 的 `OOMKilled` 可能显示 false,`journalctl -k` 里能看到 memcg OOM。
- 原因:停机几小时积压了日志,重启后 vector 要追赶 backlog,内存远高于平时(实测 0.58 版追赶时约 0.9GiB),而容器 `mem_limit: 512m` 是按平时用量定的;每次被杀都没来得及提交 checkpoint,于是永远追不上。
- 处理:`docker update --memory 1536m --memory-swap 1536m <容器>` 立即生效(不重建),同时改 compose 文件;追平后再按实际用量决定是否调回。同类问题适用于 filebeat/fluent-bit 等有积压的采集器。
**★ 服务被 OOM 杀掉后整个 unit 停掉、不再启动(MySQL 停了 10 小时才发现)**
- 现象:`systemctl status` 显示 `failed (Result: oom-kill)`;EL7 上同样超限时服务会自己恢复。
- 原因:unit 有 `MemoryLimit=`/`MemoryMax=` drop-in。EL7 的 systemd 只是让内核杀掉超限的那个进程,mysqld_safe 之类的守护进程会把它拉起来;EL9+ 默认 `OOMPolicy=stop`,杀掉一个进程就停掉整个 unit(守护进程一起停),SysV 生成的 unit 默认 `Restart=no`。凌晨备份(mysqldump)这类高峰最容易触发。
- 处理:drop-in 改成 `MemoryMax=`(cgroup v2 下 `MemoryLimit=` 已废弃)+ `OOMPolicy=continue` + `Restart=on-failure`,上限按实际占用(buffer pool + 连接数 × 每连接缓冲)留出余量。`survey.sh` 会提示,`finalize.sh oom-policy` 自动改。宿主机 MySQL 再加 jemalloc(见 app-compat.md 宿主机数据库)。
**★ mysqldump 备份脚本升级后连不上 / 一直在静默失败**
- 现象:备份文件是 0 字节,或者结尾没有 `-- Dump completed`;cron 里 `>/dev/null 2>&1` 所以没人知道。
- 原因:EL10 的 `/usr/bin/mysqldump` 是 MySQL 8.4(老的 mysql-community-client 没有 EL10 包),**不认 `MYSQL_PWD`**;`/etc/my.cnf` 的 `[mysqldump]` 段里的 user/password 会覆盖命令行以外的来源。另一类是和升级无关、早就存在的失败(真实案例:一个库里有大写表名、服务端 `lower_case_table_names=1`,全库备份每晚在这个库中止,后面的库从没进过全量备份)。
- 处理:用 `--defaults-file=<600 临时文件>` 传账号、用与服务端同大版本的 mysqldump、逐个检查结尾和退出码 → `scripts/mysql-backup.sh`。`survey.sh` 会列出 cron 里的 mysqldump 脚本。
**★ 自编译 nginx:`libssl.so.10: cannot open shared object file`**
- 处理:过渡期 `nginx-static-build.sh`(同版本静态 OpenSSL/PCRE,实测 EL8 上编译后在 EL9、EL10 都能跑);最终换 nginx.org 官方包。
**★ `docker-compose up -d` 报 `KeyError: 'ContainerConfig'`,而且旧容器已被改名为 `<短id>_<名字>`**
- 原因:docker-compose v1.29 与 Docker ≥ 25 不兼容,失败前已经重命名了旧容器。
- 处理:`docker compose`(v2)重建;先 `docker rm` 那个改名后的残留容器(确认它没有数据卷!);`finalize.sh compose-wrapper` 让 `docker-compose` 命令转发到 v2。
- ★ 别在 EL7 上就跑 `compose-wrapper`:Docker 19.03 没有 compose v2 插件,替换后 `docker-compose` 直接不可用(真实踩坑)。脚本现在会先确认 `docker compose version` 可用,不可用就保留原文件并退出;等 docker-ce 升级到带插件的版本再做。
- ★ 更老的 v1(≤1.23)在 Docker 29 上更早就失败:`client version 1.25 is too old. Minimum supported API version is 1.40`,连 `docker-compose ps` 都不行。真实案例:EL7 阶段 wrapper 按设计跳过了,之后没人补做,第二天 Jenkins 发布在 `ssh 目标机 docker-compose up -d` 这一步才暴露。`hop.sh post` 现在发现"仍是 v1 且 v2 插件可用"会提示补做。替换前核对容器的 `com.docker.compose.project` 标签与目录名一致(v1 ≥1.21 保留连字符,与 v2 相同;更老的 v1 会去掉 `-`/`_`,替换后 `up -d` 会撞 container_name,需要 `-p` 指定旧项目名)。
**★ 发布/备份脚本 `tar -czf x.tar.gz dir --exclude=...` 在 EL9+ 直接失败**
- 现象:升级后第一次 Jenkins 发布在"备份旧代码"一步失败:`tar: The following options were used after any non-optional arguments in archive create or update mode ... --exclude 'runtime/log' has no effect`,`Exiting with failure status due to previous errors`(退出码 2)。脚本没有 `set -e` 时不会失败,但 exclude 不生效,备份把 runtime/.git 全打进去(真实案例:本该 2.8G 的备份变成 66G)。
- 原因:EL7 的 tar 1.26 会把写在目录后面的选项挪到前面处理;EL9 的 tar 1.34、EL10 的 1.35 认为它们是位置相关的,只作用于后面的参数,并报错。
- 处理:选项写在目录前面:`tar --exclude=dir/runtime/log --exclude=dir/.git -czf $BAK/dir.$T.tar.gz dir`。`survey.sh` 会扫描 cron 引用的脚本和 `/root/script*`、`/data/script*`、`/opt/script*` 下的 .sh 并报 MEDIUM;**在 CI(Jenkins 等)里通过 ssh 执行的同类命令扫描不到,升级前要去发布平台里搜一遍**(真实案例:同一台目标机有 8 个任务都是这种写法)。
- 顺带常见的老问题:`ssh host "cd $DIR"` 和下一行 `ssh host "tar ..."` 是两个独立会话,cd 不生效,tar 实际在 `/root` 下执行,可能多年来备份的都是一份过期副本;`ssh host 'find $DIR ... -delete'` 用单引号时变量在远端为空,find 会在家目录里删文件。修的时候把 cd 和 tar 放进同一个 ssh,变量用双引号在本地展开。备份只打代码(用户上传、runtime、.git 不随发布变化),保留最近 N 份:`ls -1t $BAK/name.*.tar.gz | tail -n +$((N+1)) | xargs -r rm -f`。
**★ CI/发布机升级到 EL10 后 `ssh`/`scp`/`rsync` 报 `Host key verification failed`(之前一直免密)**
- 现象:Jenkins 发布任务里 `ssh -p 10015 目标机 'docker pull ...'` 失败;免密本身没坏(报错在主机密钥校验,不在认证)。同一个任务里有的目标机正常、有的失败。
- 原因:EL10 的 crypto-policies 在 ssh_config 里**显式**设置了 `HostKeyAlgorithms`。OpenSSH 只有在这个选项没设置时才会"优先协商 known_hosts 里已记录的密钥类型";现在直接协商 ssh-ed25519。known_hosts 里只记录了 ECDSA(老系统首次连接时记下的)的主机 → 对方出示 ed25519 → BatchMode 下直接拒绝。真实案例:发布机 known_hosts 64 条里 62 条只有 ECDSA。
- 处理:`scripts/known-hosts-fill.sh`——用已记录、已信任的类型(`-o HostKeyAlgorithms=<已记录类型>`)连上去,在这条已验证的连接里读取对方 `/etc/ssh/ssh_host_*_key.pub` 补齐缺的类型;不盲信新密钥,也不用 `StrictHostKeyChecking=no`。`UpdateHostKeys=yes` 不行:固定了 HostKeyAlgorithms 后它只接收同类型的密钥。`survey.sh` 会在 EL7-9 上提示没有 ed25519 记录的主机数,`hop.sh post` 到 10 后提醒。
- ★ 验证时加 `-o ControlPath=none`:常见的 `ControlMaster auto` + `ControlPersist 10m` 会复用排查时建立的旧连接、跳过主机密钥校验,看起来"已经好了",10 分钟后又坏。
- 不要顺手"重新做免密":密钥认证没问题,重做免密解决不了主机密钥记录的问题。另外,扫描时发现的"从来不在 known_hosts 里"的地址是升级前就连不上的(多数是任务里出现的镜像仓库/HTTP 地址,不是 ssh 目标),与升级无关。
**★ Tomcat 里的 Jenkins 升级后重启,`/` 返回 404(`/jenkins/` 却能打开)**
- 现象:`localhost.<日期>.log`:`Exception starting filter authentication-filter ... IllegalArgumentException: key cannot be empty or null`(`TokenBasedRememberMeServices2`),`catalina.log`:`Context [] startup failed due to previous errors`;同一时间 `/jenkins/` 是好的。
- 原因:server.xml 里 `<Context path="" docBase="jenkins.war">` 指向 appBase 里的 war,Host 又开着 `autoDeploy`/`deployOnStartup`——同一个 war 被部署成 `/` 和 `/jenkins` 两个实例,共用同一个 JENKINS_HOME,启动时互相抢,谁先起来不确定(之前能用只是运气;两个实例同时跑还会把定时触发跑两遍)。
- 处理:Host 上加 `autoDeploy="false" deployOnStartup="false"`,只部署显式写的 Context。**不要把 `jenkins.war` 挪走**——它就是 ROOT 的 docBase,挪走后 Tomcat 整个起不来(`The main resource set specified [.../jenkins.war] is not valid`)。`survey.sh` 会报这种配置(MEDIUM)。
**重启 Jenkins 后所有人都被登出**
- Jenkins 会话只在内存里,换 systemd unit、每跳重启都会让浏览器会话失效(catalina 里 `Exception loading sessions from persistent storage` 是同一件事,无害)。需要人登录的验证(触发真实发布)提前和用户约好;Agent 不代输密码。
**★ 删掉"没用"的 PHP 后某站点从 200 变 404**
- 教训:组件和站点的对应关系要在删之前告诉用户(nginx -T 里哪些 server 用 fastcgi_pass)。由用户决定站点去留。
**`pkill`/`docker stop` 后 VPN 断开、无法登录**:见 recovery.md "失联"。
**★ ssmtp 在 7→8 被删除(EL8 没有这个包)**:如果 `/etc/ssmtp/ssmtp.conf` 里配了 `mailhub`,说明机器用它发过邮件,升级后可以改用 EPEL 的 `msmtp`(配置格式相近),并写进报告。
**★ LNMP 一键包的 `/home/wwwlogs` 是 777**:自己加的 logrotate 会因为 "parent directory has insecure permissions" 跳过,需要在配置里加 `su root root`。
**★ 容器里的 iptables-legacy(wg-easy 等):`can't initialize iptables table 'nat': Table does not exist`**
- 原因:EL10 宿主机用 nft,legacy 的 `iptable_nat` 等模块默认不加载,容器又没有挂 /lib/modules。
- 处理:`finalize.sh iptables-legacy`(加载并写入 modules-load.d),然后 `docker restart <容器>`。
**★ redis 服务消失(EL10 没有 redis 包)**:leapp 装了 valkey 但不迁移数据、不启用。`finalize.sh redis-valkey`:迁移 dump/aof、启用 valkey、提供 redis-cli 兼容链接;旧配置有 requirepass 的要手工写进 valkey.conf。
**★ postfix 起不来:`inet_interfaces: no local interface found for ::1`**:系统禁用了 IPv6,而 `inet_protocols = all`。改 `postconf -e inet_protocols=ipv4`(`finalize.sh postfix-lmdb` 顺手检查)。
**★ 宿主机 nacos 起得慢,开机后依赖它的容器"运行中但没有端口"**
- 现象:容器 Up,但应用启动时注册 nacos 失败后退出了 Spring 上下文,进程还在,Docker 不会重启它。
- 处理:nacos 就绪后 `docker restart` 这些容器;长期方案:容器的启动脚本在注册失败时退出(让 restart 策略生效),或给容器加对 nacos 的等待。这不是升级引起的,任何一次重启都会发生。
**★ Kubernetes 节点**:见 `kubernetes.md`(pod 里老 JDK 在 cgroup v2 下 OOMKilled、Dead 容器导致 kubelet 起不来、NFS PVC 阻断 leapp、启动风暴等)。
**★ 运维脚本静默失败:首行是 `#!/usr/bin/python` / `#!/bin/python`**
- 现象:升级到 EL8 后 `jenkins-systemd-watch.service` 每分钟 203/EXEC;同目录下 GitLab 每日备份、磁盘巡检、nginx 日志轮转(logrotate postrotate)脚本用的也是不带版本的 python,cron 里不会有人看见报错——当晚的 GitLab 备份就会失败。
- 原因:EL8 起没有不带版本号的 `/usr/bin/python`,EL10 只有 python3.12。
- 处理:先 `python3 -c "import ast,sys; ast.parse(open(sys.argv[1]).read())" <脚本>` 确认语法兼容(写成 2/3 兼容的脚本一般直接能用),把首行改成 `#!/usr/bin/python3`,能 dry-run 的跑一次(如 `--check-current`)。survey 会扫描 /usr/local/{bin,sbin}、/root/script* 并报 MEDIUM。
**★ 证书即将过期**:迁移 nginx 时顺手 `openssl x509 -noout -enddate` 检查,写进报告。
**★ nginx/openresty 跑在容器里,基线漏掉了所有站点**
- 现象:宿主机 `pgrep nginx` 能看到 master 进程,但路径(如 `/usr/servers/nginx/sbin/nginx`)在宿主机上不存在;老版本 nginx(<1.9.2)也没有 `-T`。
- 处理:`state.sh` 会进入 nginx/openresty/tengine 容器读取 server_name;没有 `-T` 时读取容器挂载点和常见目录下的 `*.conf`。另外所有 TCP 端口都按 IP 探测一次,443 用 https。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |