Claude Code 写 Shell 脚本翻车实录：一次“看起来很对”的自动化事故复盘

一、事故背景：一个“十分钟就能搞定”的需求

事情的起因非常简单：我需要每天凌晨把一台测试机上的日志目录打包、压缩、上传到备份机，并清理 7 天前的旧文件。需求听起来毫无技术含量，于是我打开终端，对着 Claude Code 说了一句：

帮我写一个 shell 脚本，每天凌晨 2 点把 /data/logs 打包压缩，上传到 192.168.1.20 的 /backup 目录，然后删除 7 天前的压缩包。

Claude Code 很快给出了一个结构完整、注释清晰的脚本。变量命名规范、有 set -e、有日志输出、有错误判断，第一眼看过去甚至比我自己写的还工整。

问题恰恰就出在这里：它太像一份正确答案了，以至于我跳过了逐行审查。

二、第一版脚本：看起来无懈可击

这是 Claude Code 给出的初版脚本，我几乎原样保存成了 backup.sh：

#!/bin/bash
set -e
LOG_DIR="/data/logs"
BACKUP_HOST="192.168.1.20"
BACKUP_DIR="/backup"
DATE=$(date +%Y%m%d)
ARCHIVE_NAME="logs_${DATE}.tar.gz"
echo "[$(date '+%F %T')] 开始打包 ${LOG_DIR}"
tar -czf "/tmp/${ARCHIVE_NAME}" "${LOG_DIR}"
echo "[$(date '+%F %T')] 打包完成，开始上传"
scp "/tmp/${ARCHIVE_NAME}" "${BACKUP_HOST}:${BACKUP_DIR}/"
echo "[$(date '+%F %T')] 上传完成，开始清理旧文件"
find "${BACKUP_DIR}" -name "logs_*.tar.gz" -mtime +7 -delete
echo "[$(date '+%F %T')] 全部完成"

逻辑上确实跑得通：打包、上传、清理，三步走。我手动执行了一次，成功了。于是加进 crontab，收工。

现在回头看，这个脚本里至少埋了 四个雷，而它们全都在“手动执行一次成功”的假象下被掩盖了。

三、翻车现场：凌晨两点的告警

第二天早上到公司，我发现测试机的磁盘使用率飙到了 98%，备份机上却一个文件都没有。更糟的是，/data/logs 目录下的日志文件少了一大半。

我第一反应是“脚本没跑”，但 crontab 日志显示它跑了，而且“全部完成”的日志也打出来了。

于是我开始逐条复盘，问题一个接一个浮出水面。

把整个过程按时间顺序串起来看，事故链条其实非常清晰：从写脚本到手动执行成功，再到 cron 凌晨触发，每一步都在为后面的失败埋下伏笔。下面这张时间线把关键节点和对应的雷区编号标了出来：

flowchart TD
A[写脚本] –> B[手动执行成功]
B –> C[加入 crontab]
C –> D[凌晨 2 点执行]
D –> E[打包成功]
E –> F[scp 因无免密失败<br/>雷区三]
F –> G[set -e 退出<br/>雷区一]
G –> H[本机 /backup 被误删<br/>雷区二]
H –> I[磁盘飙至 98%<br/>雷区四]
I –> J[次日发现告警]
style F fill:#ffe0e0,stroke:#d9534f
style G fill:#ffe0e0,stroke:#d9534f
style H fill:#ffe0e0,stroke:#d9534f
style I fill:#ffe0e0,stroke:#d9534f

图中标红的四个节点就是本次事故的四个雷区，它们并不是孤立出现的，而是前后串联、互相放大：免密缺失导致 scp 失败，set -e 让脚本在错误的位置退出，路径混用把删除动作落到了本机，临时文件与日志无人清理最终撑爆磁盘。

四、雷区一：set -e 并不像你以为的那样可靠

我最初以为 set -e 能保证“任何一步失败就退出”。但实际情况是，set -e 在很多场景下会失效，比如命令出现在 if 条件里、管道中间、或者被 || 连接时。

更关键的是，scp 失败时脚本确实退出了，但退出发生在打包之后、清理之前。而清理那一步用的是 find … -delete，它删除的是备份机上的路径——可脚本是在本机执行的，/backup 在本机根本不存在。

等等，那本机的日志为什么少了？这才是真正吓人的地方。

五、雷区二：路径变量写错，删掉了本机文件

仔细看清理那一行：

find "${BACKUP_DIR}" -name "logs_*.tar.gz" -mtime +7 -delete

BACKUP_DIR 的值是 /backup，这是备份机上的路径，但 find 是在本机执行的。如果本机恰好也存在 /backup 目录（我们这台测试机上确实有，是之前某个项目留下的），那么这条命令就会在本机的 /backup 里删文件。

而日志文件之所以“少了”，是因为打包时用了 tar -czf，但 LOG_DIR 后面没有加 /，导致压缩包里多了一层目录结构；同时我在排查时手动解压验证，误操作覆盖了原目录。这一条是我自己的锅，但也说明脚本缺少必要的防护。

教训：远程路径和本地路径必须用不同的变量名，并且清理操作前一定要加 echo 预览，确认无误后再执行。

六、雷区三：scp 没有免密，cron 环境下必然失败

手动执行时，scp 弹出了密码输入，我顺手输了。但在 cron 环境下，没有交互终端，scp 会直接失败。

而 set -e 让脚本在这里退出了，所以“上传完成”的日志其实从来没打印过——我看到的“全部完成”是前一天手动执行留下的日志，被 echo 追加到了同一个文件里，我根本没注意时间戳。

正确做法是提前配置 SSH 免密登录，并在脚本里显式检查：

if ! ssh -o BatchMode=yes -o ConnectTimeout=5 "${BACKUP_HOST}" "echo ok" >/dev/null 2>&1; then
echo "[ERROR] 无法免密连接 ${BACKUP_HOST}，请检查 SSH 配置" >&2
exit 1
fi

免密登录的配置本身并不复杂，但每一步都有容易忽略的细节。下面按顺序走一遍，建议在执行脚本的那台机器（也就是本机）上操作，目标是把本机的公钥装到备份机的 authorized_keys 里。

第一步：生成密钥对。如果本机还没有密钥，用 ssh-keygen 生成一对。注意 cron 场景下不要给私钥设置口令，否则同样会卡在交互输入上：

# -t 指定算法，-b 指定长度，-N "" 表示空口令（cron 场景必须），-f 指定密钥文件
ssh-keygen -t ed25519 -b 256 -N "" -f ~/.ssh/id_ed25519 -C "backup@cron"
预期输出（关键行）
Generating public/private ed25519 key pair.
Your identification has been saved in /root/.ssh/id_ed25519
Your public key has been saved in /root/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx backup@cron

如果已经有可用的密钥，这一步可以跳过，直接用 ls -l ~/.ssh/id_*.pub 确认公钥存在即可。

第二步：分发公钥。用 ssh-copy-id 把公钥追加到备份机的 ~/.ssh/authorized_keys，这一步需要输入一次备份机的密码：

# 把本机公钥写入 192.168.1.20 对应用户的 authorized_keys
ssh-copy-id -i ~/.ssh/id_ed25519.pub root@192.168.1.20
预期输出（关键行）
/usr/bin/ssh-copy-id: INFO: Source of key(s) to be installed: "/root/.ssh/id_ed25519.pub"
Number of key(s) added: 1
Now try logging into the machine, with: "ssh 'root@192.168.1.20'"
and check to make sure that only the key(s) you wanted were added.

如果目标机没有安装 ssh-copy-id，可以手动追加，效果等价：

# 手动方式：把公钥内容追加到远程 authorized_keys
cat ~/.ssh/id_ed25519.pub | ssh root@192.168.1.20 \\
'mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys'

第三步：验证 BatchMode 免密连通。这是最关键的一步，必须用 BatchMode=yes 验证，因为它会禁用一切交互式密码输入，能真实模拟 cron 的执行条件：

# BatchMode=yes 下不允许任何交互，能连通才说明免密真正生效
ssh -o BatchMode=yes -o ConnectTimeout=5 root@192.168.1.20 "echo ok"
预期输出
ok

如果输出 ok，说明免密配置成功。如果报 Permission denied (publickey,password)，说明公钥没有生效，按下面的权限要求逐项排查。

第四步：检查 authorized_keys 权限。SSH 对权限极其敏感，权限过宽会直接拒绝使用公钥，而且报错信息往往只有一句 Permission denied，非常容易误判。备份机上的权限必须满足：

• ~/.ssh 目录权限为 700，属主是登录用户本人。
• ~/.ssh/authorized_keys 文件权限为 600，属主是登录用户本人。
• ~ 家目录不能对 group 和 other 可写，否则同样会被拒绝。

# 在备份机上执行，修正权限
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
chmod go-w ~
检查结果，预期输出
ls -ld ~ ~/.ssh ~/.ssh/authorized_keys
drwx—— 5 root root 4096 Mar 12 10:00 /root
drwx—— 2 root root 4096 Mar 12 10:00 /root/.ssh
-rw——- 1 root root 102 Mar 12 10:00 /root/.ssh/authorized_keys

提醒：如果 ssh-copy-id 之后仍然连不上，先看备份机的 /var/log/secure（Debian 系为 /var/log/auth.log），里面会明确写出是权限问题、密钥不匹配还是 StrictModes 拒绝。另外，首次连接时的 Host key verification failed 属于另一类问题，需要先把备份机指纹写入 known_hosts，否则 cron 下同样会失败。

cron 环境与手动执行的差异排查

这次事故最迷惑人的地方在于：同一个脚本，手动执行一切正常，交给 cron 就翻车。原因并不神秘——cron 启动的是一个几乎“裸奔”的 shell，它和你登录终端时的环境完全是两回事。下面把最容易出问题的五个维度列出来，对照着排查一遍，基本能覆盖绝大多数“手动能跑、cron 不跑”的场景。

实战排查示例：cron 下 tar: command not found

光看表格还不够直观，这里还原一个我实际遇到的场景。某天早上打开 cron 邮件，看到这样一行报错：

/bin/sh: tar: command not found
[2024-03-12 02:00:01] 开始打包 /data/logs

奇怪的是，同样的脚本我在终端里敲 ./backup.sh 一切正常。原因就在于：我的 tar 是后来通过源码编译安装到 /usr/local/bin/tar 的，而登录 shell 的 PATH 里包含 /usr/local/bin，cron 的默认 PATH 却只有 /usr/bin:/bin。

第一步：复现问题。不要靠猜，直接用 env -i 清空环境变量，模拟 cron 的“裸奔” shell：

# 模拟 cron 环境执行脚本，观察是否复现报错
env -i /bin/bash -c 'echo "PATH=$PATH"; command -v tar; /path/to/backup.sh'

输出会清楚地显示 PATH=/usr/bin:/bin，并且 command -v tar 没有任何返回，紧接着脚本第一行 tar 就报 command not found。问题被稳定复现，说明这不是偶发故障，而是环境差异导致的必然结果。

第二步：修复。有两种常见做法，任选其一即可。

方案一是在 crontab 里显式声明 PATH，改动最小，适合脚本本身不想动的情况：

# 修复前：crontab 里只有一行任务，PATH 完全依赖 cron 默认值
0 2 * * * /path/to/backup.sh >> /var/log/backup.log 2>&1
修复后：在 crontab 顶部显式声明 PATH，覆盖 cron 的默认值
PATH=/usr/local/bin:/usr/bin:/bin
0 2 * * * /path/to/backup.sh >> /var/log/backup.log 2>&1

方案二是在脚本内部自己兜底，把 PATH 写死，这样无论谁来调用都不会踩坑，可移植性更好：

# 修复前：脚本直接开始干活，完全依赖调用方的 PATH
#!/bin/bash
set -e
LOG_DIR="/data/logs"
tar -czf "/tmp/logs_$(date +%Y%m%d).tar.gz" "${LOG_DIR}"
修复后：脚本开头显式设置 PATH，并校验关键命令是否存在
#!/bin/bash
set -euo pipefail
export PATH="/usr/local/bin:/usr/bin:/bin"
for cmd in tar scp ssh find; do
command -v "${cmd}" >/dev/null 2>&1 || { echo "[ERROR] 缺少命令: ${cmd}" >&2; exit 1; }
done
LOG_DIR="/data/logs"
tar -czf "/tmp/logs_$(date +%Y%m%d).tar.gz" "${LOG_DIR}"

第三步：验证修复效果。改完之后，仍然用同一个模拟命令再跑一遍，确认 command -v tar 能正常输出路径、脚本能完整跑通，再放心交给 cron：

env -i /bin/bash -c 'echo "PATH=$PATH"; command -v tar; /path/to/backup.sh'

经验：凡是“手动能跑、cron 不跑”的问题，先用 env -i /bin/bash -c 复现，再决定是在 crontab 里补环境，还是在脚本里自建环境。前者改动小，后者更稳妥，生产脚本建议两者都做。

排查思路也很直接：不要猜，直接用 env -i /bin/bash -c 模拟一个干净的 cron 环境，把脚本在里面跑一遍。凡是这一步暴露出来的问题，就是 cron 环境下必然会发生的问题。等它在模拟环境里跑通了，再交给 crontab，成功率会高得多。

一句话总结：手动执行验证的是“脚本逻辑对不对”，cron 执行验证的是“脚本在你的环境里能不能活下来”，这两件事必须分开测。

七、雷区四：日志没有轮转，脚本自己把磁盘写满

脚本里所有 echo 都追加到同一个日志文件，而 cron 每天跑一次，日志文件只增不减。加上打包产生的临时文件堆在 /tmp 里从不清理，磁盘就是这么被撑爆的。

修复方式很简单：临时文件用 mktemp 创建，脚本结束时用 trap 清理；日志按天切分，或者交给 logrotate 管理。

TMP_FILE=$(mktemp /tmp/logs_XXXXXX.tar.gz)
trap 'rm -f "${TMP_FILE}"' EXIT

八、修复后的脚本

经过一轮彻底重构，最终版本如下。核心改动是：区分本地与远程路径、增加连接预检、使用 trap 清理临时文件、清理操作先预览再执行。

#!/bin/bash
set -euo pipefail
LOG_DIR="/data/logs"
LOCAL_TMP_DIR="/tmp"
REMOTE_HOST="192.168.1.20"
REMOTE_BACKUP_DIR="/backup"
KEEP_DAYS=7
DATE=$(date +%Y%m%d)
ARCHIVE_NAME="logs_${DATE}.tar.gz"
log() {
echo "[$(date '+%F %T')] $*"
}
预检：确认远程可免密连接
if ! ssh -o BatchMode=yes -o ConnectTimeout=5 "${REMOTE_HOST}" "test -d ${REMOTE_BACKUP_DIR}" >/dev/null 2>&1; then
log "[ERROR] 远程目录 ${REMOTE_BACKUP_DIR} 不可用或无法免密连接" >&2
exit 1
fi
TMP_FILE="${LOCAL_TMP_DIR}/${ARCHIVE_NAME}"
trap 'rm -f "${TMP_FILE}"' EXIT
log "开始打包 ${LOG_DIR}"
tar -czf "${TMP_FILE}" -C "$(dirname "${LOG_DIR}")" "$(basename "${LOG_DIR}")"
log "开始上传到 ${REMOTE_HOST}:${REMOTE_BACKUP_DIR}"
scp "${TMP_FILE}" "${REMOTE_HOST}:${REMOTE_BACKUP_DIR}/"
log "开始清理远程 ${KEEP_DAYS} 天前的备份"
ssh "${REMOTE_HOST}" "find ${REMOTE_BACKUP_DIR} -name 'logs_*.tar.gz' -mtime +${KEEP_DAYS} -print -delete"
log "全部完成"

注意清理那一步：find 通过 ssh 在远程主机上执行，并且加了 -print，删除前会先打印出被删的文件名，方便事后审计。

脚本改好了，最后一步是把它交给 cron。修复版的 backup.sh 对应的 crontab 写法如下，建议用 crontab -e 编辑，把每一行都看明白再保存：

# 显式声明 PATH：cron 默认只有 /usr/bin:/bin，这里补上 /usr/local/bin，
# 保证脚本里调用的 tar、scp、ssh、find 都能被找到，避免 command not found
PATH=/usr/local/bin:/usr/bin:/bin
可选：显式声明 SHELL，确保脚本按 bash 语义执行，而不是被 /bin/sh 解释
SHELL=/bin/bash
可选：指定 cron 邮件的收件人，脚本异常时能第一时间收到通知
MAILTO=ops@example.com
每天凌晨 2 点执行修复版 backup.sh
分 时 日 月 周 依次为：0 2 * * *
>> /var/log/backup.log 把标准输出追加到日志文件，便于事后审计
2>&1 把标准错误也重定向到同一个文件，避免报错信息被 cron 邮件吞掉或直接丢弃
0 2 * * * /path/to/backup.sh >> /var/log/backup.log 2>&1

几点补充说明：PATH 和 SHELL 这类变量必须写在任务行之前，cron 会按顺序解析；日志文件所在目录要提前确认存在且当前用户可写，否则重定向本身就会失败；如果希望日志按天切分，可以把重定向目标改成 /var/log/backup_$(date +\\%F).log，注意 crontab 里的 % 需要转义成 \\%。

初版 vs 修复版关键差异对照

为了更直观地看清这次重构到底改了什么，下面把初版脚本和修复后脚本在六个关键维度上逐项对照。左边是当初埋雷的写法，右边是修复后的写法，差异一目了然。

在进入复盘之前，先把四个雷区放在一起对照一遍，方便快速定位问题：

九、复盘：AI 写脚本，哪些地方必须人工把关

这次翻车让我总结出几条经验，分享给同样在用 Claude Code 写运维脚本的朋友：

• 路径类变量必须人工核对：本地路径和远程路径混用是最高频的事故来源，AI 不会知道你的机器上有没有同名目录。
• 删除类操作必须加预览：任何 rm、find -delete、rsync –delete，先 echo 或 -print 跑一遍，确认无误再真正执行。
• cron 环境要单独验证：手动执行成功不等于 cron 执行成功，环境变量、PATH、免密登录、工作目录都可能不同。
• 让 AI 解释每一行：不要只看结果，让它逐行说明“这行在什么情况下会失败”，往往能提前发现隐患。
• 先在小范围试跑：把 LOG_DIR 换成一个测试目录，完整跑一遍再上生产。

附：上线前自查命令清单

复盘归复盘，真正能救命的还是上线前那几分钟的检查。下面这几条命令建议直接复制到终端里跑一遍，确认无误再把脚本交给 cron。

# 1. 检查 cron 环境下的 PATH 与关键变量，确认脚本能找到 tar、scp、ssh 等命令
crontab -l; env -i /bin/bash -c 'echo "PATH=$PATH"; command -v tar scp ssh find'
2. 测试免密连通性，BatchMode=yes 下若仍需密码会直接失败，避免 cron 里静默卡死
ssh -o BatchMode=yes -o ConnectTimeout=5 192.168.1.20 "echo ok"
3. 用 -print 预览删除范围，确认命中的文件都在预期目录内，再决定是否加 -delete
find /backup -name "logs_*.tar.gz" -mtime +7 -print
4. 检查磁盘占用，重点看根分区和 /tmp，避免临时文件把磁盘撑满
df -h; du -sh /tmp
5. 校验压缩包目录层级，确认解压后不会多出一层嵌套目录
tar -tzf /tmp/logs_$(date +%Y%m%d).tar.gz | head -n 20
6. 确认远程备份目录存在且可写，避免上传阶段才发现路径不对
ssh -o BatchMode=yes 192.168.1.20 "test -w /backup && echo writable"

这六条命令覆盖了本次事故里踩到的全部坑：环境变量、免密登录、删除范围、磁盘占用、打包层级和远程目录权限。花两分钟跑一遍，比事后花一上午排查划算得多。

十、总结

Claude Code 写 Shell 脚本的能力确实不错，语法规范、结构清晰、注释到位，能省下大量重复劳动。但它给出的代码是“通用正确”，而不是“对你的环境正确”。

运维脚本的特点是：一旦出错，代价往往是数据丢失或服务中断。所以我的结论是——可以让 AI 写，但必须由人来审，尤其是涉及路径、删除、权限和远程调用的部分。

这次事故没有造成不可挽回的损失，算是花了一上午时间买了个教训。希望这篇实录能帮你避开同样的坑。