本文说明脚本的错误处理、调试方法与工程规范。变量与展开见 变量与参数展开,流程控制与函数见 流程控制与函数,文本处理见 文本处理工具,信号与后台任务见 作业控制与信号,脚本执行与权限见 脚本执行,服务化运行见 systemd,定时任务见 计划任务与定时器,以最小权限运行的约束见 主机加固与登录安全,文件权限模型见 权限模型,变更与发布流程见 变更与发布管理,批量运维脚本的组织见 配置管理。
一、起源
1.1 失败的三种形态
| 形态 | 表现 | 危害 |
|---|---|---|
| 静默继续 | 中间步骤失败后脚本继续执行后续步骤 | 最终状态部分完成,且报错信息与实际原因无关 |
| 部分完成 | 前半段生效、后半段未生效 | 需要人工判断当前状态,恢复成本高 |
| 失败被掩盖 | 失败发生在管道中间或子 shell 中 | 退出码为成功,监控与调度无法感知 |
三种形态的共同原因是:Shell 默认不因命令失败而中止,退出码需要显式检查。
1.2 需要回答的三个问题
- 哪里失败了:定位到具体步骤与具体命令。
- 失败后发生了什么:脚本是可重入的还是会留下中间状态。
- 如何复现:是否有足够上下文(参数、环境、输入)支持重放。
脚本工程的核心就是把这三个问题在编写阶段解决,而不是留到故障现场。
1.3 取舍
| 选择 | 获得 | 付出 |
|---|---|---|
| 严格模式加显式校验 | 失败快速暴露、行为可预期 | 需要处理严格模式带来的边界情况 |
| 依赖默认行为 | 写法简洁 | 上述三种失败形态不可避免地出现 |
二、原理
2.1 退出码与失败传播
每个命令结束都会返回退出码,0 表示成功,非 0 表示失败。失败传播有三种方式:
| 方式 | 写法 | 特点 |
|---|---|---|
| 立即中止 | 严格模式或显式判断 | 失败即停,适合不允许部分完成的任务 |
| 收集失败 | 记录状态并继续 | 适合批量任务,最后统一汇总 |
| 重试后中止 | 有限次重试后退出 | 适合存在瞬时故障的外部调用 |
选择依据是任务是否可安全中断:修改配置、迁移数据这类任务应"失败即停";检查与采集类任务应"收集失败并汇总"。
2.2 严格模式的三个选项
| 选项 | 作用 | 需要注意 |
|---|---|---|
| 出错即退出 | 命令返回非 0 时立即退出 | 在多种上下文中失效,见下表 |
| 未定义变量报错 | 引用未设置的变量时中止 | 与显式默认值写法配合使用 |
| 管道整体失败 | 管道中间任一命令失败则整体失败 | 未开启时只看最后一个命令的退出码 |
出错即退出的失效场景是严格模式最需要掌握的部分:
| 场景 | 是否生效 | 说明 |
|---|---|---|
| 作为条件判断的一部分 | 不生效 | 条件中的失败由条件自己处理 |
| 作为逻辑连接的一环 | 不生效 | 左侧失败会被逻辑运算接管 |
| 命令前有取反 | 不生效 | 退出码被反转,语义已改变 |
| 管道中非最后一段 | 不生效 | 需要开启管道整体失败选项 |
| 子进程或子 shell 内部 | 不生效 | 选项不自动下传,需要在子进程内单独设置 |
| 命令替换中 | 视写法而定 | 部分实现在赋值语句中不生效,需要显式判断 |
由此产生两条实践结论:
- 严格模式是"减少遗漏"而不是"保证安全",关键步骤仍需显式判断退出码。
- 需要严格模式在子进程生效时,应在子脚本与子 shell 中重新设置。
2.3 钩子的分工
| 钩子 | 触发条件 | 用途 |
|---|---|---|
| 退出钩子 | 脚本以任何方式结束 | 清理临时资源、释放锁、输出汇总 |
| 错误钩子 | 命令失败时 | 输出失败上下文(行号、命令、参数) |
| 信号捕获 | 收到指定信号 | 优雅停止子进程后退出 |
错误钩子默认不继承到函数内部,需要开启继承选项(set -E)或在函数内另行设置。三个钩子的具体实现见 作业控制与信号。
2.4 输出规范
| 输出 | 去向 | 用途 |
|---|---|---|
| 业务数据 | 标准输出 | 供管道或调用方读取 |
| 诊断信息、日志、进度 | 标准错误 | 不污染数据通道 |
# 数据与诊断分离:数据可被管道消费,日志仍可见
list_instances() {
printf '%s\n' "${instances[@]}" # 数据走标准输出
}
log_info() { printf '[%s] [INFO] %s\n' "$(date '+%F %T')" "$*" >&2; }
log_warn() { printf '[%s] [WARN] %s\n' "$(date '+%F %T')" "$*" >&2; }
log_error() { printf '[%s] [ERROR] %s\n' "$(date '+%F %T')" "$*" >&2; }
# 用法:数据与日志互不干扰
instances=$(list_instances)
log_info "共获取 ${#instances[@]} 个实例"
日志格式应固定,包含时间、级别与关键标识(如目标、批次),便于集中检索;日志级别与集中采集的配合见 日志查询与审计 与 监控与告警。
2.5 幂等与文件锁
幂等指"重复执行结果一致"。实现手段是执行前检测当前状态:
| 场景 | 检测方式 |
|---|---|
| 创建目录 | 存在则跳过 |
| 创建用户与组 | 查询是否存在后再创建 |
| 修改配置 | 检测目标内容是否已符合预期 |
| 部署文件 | 比对校验和而非只看文件是否存在 |
需要保证同一时刻只有一个实例运行时使用文件锁:
# 基于文件描述符加锁:脚本退出时锁自动释放,避免残留
readonly LOCK_FILE="/var/lock/app-sync.lock"
exec 9>"$LOCK_FILE"
if ! flock -n 9; then
log_error "已有实例在运行,退出"
exit 1
fi
要点:使用文件描述符方式加锁时,锁随进程退出自动释放,不会因脚本异常终止而残留。若使用创建锁文件的方式,则必须在退出钩子中删除,并处理"进程已死但锁文件仍在"的残留情况。
2.6 临时文件与清理
# 安全创建临时目录:名称随机、权限受限
umask 077
tmp_dir="$(mktemp -d -t app-XXXXXX)" || exit 3
trap 'rm -rf -- "$tmp_dir"' EXIT
# 临时文件也应使用随机名称,避免被预测后抢先创建
tmp_file="$(mktemp "${tmp_dir}/result.XXXXXX")"
三条安全要求:
- 临时文件必须使用随机名称创建,固定名称存在被其他用户抢先创建并借此写入的风险。
- 权限应限制为仅属主可读写,通过设置权限掩码或使用权限受限的目录实现。
- 必须在退出钩子中清理,异常退出时也不留下残留。
2.7 安全要点
| 要点 | 风险 | 做法 |
|---|---|---|
| 命令注入 | 变量内容被当作命令执行 | 不拼接命令字符串,不将外部输入交给解释器执行 |
| 通配符误伤 | 变量中的通配字符被展开 | 引用变量,必要时临时关闭通配 |
| 选项注入 | 输入以减号开头被当作选项 | 命令中显式使用选项终止符 |
| 凭据外泄 | 口令出现在进程列表与日志中 | 通过环境变量或受限权限的文件传递,不写入日志 |
| 权限过高 | 脚本以高权限运行且可被普通用户修改 | 脚本与配置目录归属高权限用户且不可写 |
| 路径依赖 | 依赖调用时的当前目录 | 基于脚本所在目录推导资源路径 |
| 环境不可信 | 继承的路径与变量被篡改 | 使用绝对路径调用关键命令,必要时重置搜索路径 |
| 不可逆操作 | 删除与覆盖无确认 | 先打印待处理清单,确认后再执行 |
# 路径处理:基于脚本所在目录推导,避免依赖当前目录
script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
readonly script_dir
# 选项终止符:避免以减号开头的输入被当作选项
rm -f -- "$target"
grep -e "$pattern" file.txt
# 关键命令使用绝对路径,避免被篡改的搜索路径劫持
/usr/bin/install -m 0640 -- "$src" "$dst"
2.8 调试手段
| 手段 | 用法 | 用途 |
|---|---|---|
| 语法检查 | 解释器带语法检查选项执行 | 不实际运行即可发现语法错误 |
| 执行跟踪 | 开启跟踪选项 | 观察每条命令展开后的实际内容 |
| 自定义跟踪前缀 | 设置跟踪提示串包含文件与行号 | 快速定位到触发点 |
| 静态检查 | 使用专门的静态检查工具 | 发现引用与比较与未使用变量等常见缺陷 |
| 单元化的临时代码 | 把可疑片段单独放入临时脚本运行 | 排除环境影响 |
# 语法检查(重定向用于抑制纯语法检查时的语法错误提示之外的输出)
bash -n script.sh
# 执行跟踪:设置提示串包含脚本名与行号
PS4='+ ${BASH_SOURCE:-$0}:${LINENO}: '
set -x
critical_step
set +x
# 只跟踪指定区段:在函数内部单独开启与关闭
debug_run() { set -x; "$@"; set +x; }
debug_run critical_step
# 跟踪输出重定向到文件,避免与业务输出混在一起
exec 5> /tmp/trace.log
BASH_XTRACEFD=5
set -x
# 静态检查(装入后即可使用)
shellcheck -S warning script.sh
shellcheck -f gcc script.sh | head -20
2.9 可移植性
| 差异点 | 说明 | 建议 |
|---|---|---|
| 默认解释器 | 部分发行版的默认解释器是精简实现,不支持扩展语法 | 需要扩展语法时在首行显式声明 bash |
| 双方括号 | 非标准语法 | 需要兼容时改用单方括号并严格引用 |
| 数组与关联数组 | 非标准语法 | 兼容场景改用普通变量与分隔符 |
| 字符串大小写转换与替换 | 参数展开的扩展形式 | 兼容场景改用外部工具 |
| 命令选项 | 部分选项是特定实现扩展 | 脚本中避免使用平台专有选项 |
echo 行为 | 对转义字符的处理在不同实现中不同 | 输出使用格式化打印而非 echo |
判断标准是"脚本可能运行在哪些系统上":只在受控服务器上运行且明确有 bash 时,可自由使用扩展语法;需要分发给不确定环境或作为系统初始化脚本时,应限制在最小可用语法子集。
三、实现
3.1 完整脚本骨架
#!/usr/bin/env bash
# 说明:同步指定目录到备份位置
# 退出码:0 成功 2 用法错误 3 环境不满足 4 依赖执行失败
set -Eeuo pipefail
# ---------- 基础路径 ----------
script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
readonly script_dir
readonly script_name="$(basename -- "${BASH_SOURCE[0]}")"
# ---------- 常量 ----------
readonly LOCK_FILE="/var/lock/${script_name%.sh}.lock"
readonly DATE_TAG="$(date '+%F')"
readonly LOG_DIR="/var/log/app"
umask 077
mkdir -p -- "$LOG_DIR"
readonly LOG_FILE="${LOG_DIR}/${script_name%.sh}.log"
# ---------- 日志 ----------
log() {
local level="$1"; shift
printf '[%s] [%s] %s\n' "$(date '+%F %T')" "$level" "$*" | tee -a "$LOG_FILE" >&2
}
log_info() { log INFO "$@"; }
log_error() { log ERROR "$@"; }
# ---------- 错误钩子 ----------
# 取退出码必须是函数内第一条语句,之后任何命令都会覆盖它
# set -E 使该陷阱在函数内部同样生效
on_error() {
local code=$?
local line="$1" cmd="$2"
log_error "第 ${line} 行执行失败,退出码=${code},命令=${cmd}"
exit "$code"
}
trap 'on_error "$LINENO" "$BASH_COMMAND"' ERR
# ---------- 清理钩子 ----------
tmp_dir=""
cleanup() {
local code=$?
[[ -n "$tmp_dir" && -d "$tmp_dir" ]] && rm -rf -- "$tmp_dir"
exit "$code"
}
trap cleanup EXIT
# ---------- 用法 ----------
usage() {
cat >&2 <<EOF
用法:${script_name} -s <源目录> [-d <目标目录>] [-k <保留天数>]
退出码:0 成功 2 用法错误 3 环境不满足 4 依赖执行失败
EOF
}
# ---------- 参数解析 ----------
src_dir=""
dst_dir="/data/backup"
keep_days=7
while getopts ":s:d:k:h" opt; do
case "$opt" in
s) src_dir="$OPTARG" ;;
d) dst_dir="$OPTARG" ;;
k) keep_days="$OPTARG" ;;
h) usage; exit 0 ;;
:) log_error "选项 -${OPTARG} 缺少参数"; usage; exit 2 ;;
\?) log_error "未知选项 -${OPTARG}"; usage; exit 2 ;;
esac
done
[[ -n "$src_dir" ]] || { log_error "缺少必填参数 -s"; usage; exit 2; }
[[ "$keep_days" =~ ^[0-9]+$ ]] || { log_error "保留天数必须为非负整数"; exit 2; }
# ---------- 环境检查 ----------
require_cmd() {
command -v "$1" >/dev/null 2>&1 || { log_error "缺少命令:$1"; exit 3; }
}
require_cmd rsync
require_cmd find
[[ -d "$src_dir" ]] || { log_error "源目录不存在:$src_dir"; exit 3; }
# ---------- 单实例控制 ----------
exec 9>"$LOCK_FILE"
flock -n 9 || { log_error "已有实例在运行"; exit 1; }
# ---------- 主流程 ----------
main() {
tmp_dir="$(mktemp -d -t backup-XXXXXX)"
log_info "开始同步:源=${src_dir} 目标=${dst_dir}"
rsync -a --delete --exclude='*.tmp' -- "$src_dir"/ "${dst_dir}/${DATE_TAG}/" \
|| { log_error "同步失败"; exit 4; }
log_info "清理 ${keep_days} 天前的备份"
find "$dst_dir" -maxdepth 1 -type d -mtime "+${keep_days}" -print \
| while IFS= read -r old; do
log_info "删除 ${old}"
rm -rf -- "$old" || { log_error "删除失败:${old}"; exit 4; }
done
log_info "执行完成"
}
main "$@"
要点:错误钩子输出行号与失败命令,退出钩子负责清理,锁使用文件描述符方式,日志同时写入文件与标准错误,退出码按含义分层。
3.2 幂等操作示例
# 创建用户:存在则跳过,避免重复执行报错
ensure_user() {
local user="$1"
if id "$user" >/dev/null 2>&1; then
log_info "用户已存在:${user}"
return 0
fi
useradd --system --no-create-home --shell /usr/sbin/nologin "$user"
}
# 修改配置:内容已符合预期则不动,避免无意义的重启
ensure_line() {
local file="$1" line="$2"
grep -qxF -- "$line" "$file" && return 0
printf '%s\n' "$line" >> "$file"
log_info "已追加配置:${line}"
}
# 部署文件:比对校验和而非仅判断存在
deploy_if_changed() {
local src="$1" dst="$2"
if [[ -f "$dst" ]] && cmp -s -- "$src" "$dst"; then
log_info "内容一致,跳过:${dst}"
return 0
fi
install -m 0640 -- "$src" "$dst"
log_info "已更新:${dst}"
}
3.3 安全检查清单
| 核对项 | 要求 |
|---|---|
| 解释器声明 | 首行显式声明解释器,需要扩展语法时声明 bash |
| 严格模式 | 已启用三个选项,关键步骤另有显式判断 |
| 变量引用 | 除明确需要分词外均加双引号 |
| 外部输入 | 已校验类型与范围,未交给解释器执行 |
| 路径处理 | 基于脚本目录推导,关键命令使用绝对路径 |
| 选项终止 | 处理用户输入的路径时使用选项终止符 |
| 临时资源 | 随机名称创建、权限受限、退出时清理 |
| 单实例 | 使用文件锁或进程号文件保证唯一 |
| 凭据 | 不出现在命令行参数与日志中,文件权限受限 |
| 不可逆操作 | 先打印清单再执行,必要时要求确认 |
| 幂等 | 重复执行结果一致,已覆盖中断后重跑 |
| 日志 | 格式固定,含时间与级别,数据与诊断分离 |
| 退出码 | 按含义分层,调用方可区分失败类型 |
| 依赖检查 | 执行前校验必需命令与前置条件 |
3.4 常见问题对照
| 现象 | 常见原因 | 处置 |
|---|---|---|
| 中间步骤失败但脚本继续执行 | 未启用严格模式或该上下文使严格模式失效 | 启用严格模式并对关键步骤显式判断 |
| 脚本退出码为 0 但实际失败 | 失败发生在管道非最后一段 | 启用管道整体失败选项 |
| 日志中出现"命令不存在"但未中止 | 严格模式在条件上下文中失效 | 改为显式判断并处理 |
| 重复执行导致报错 | 缺少幂等判断 | 执行前检测当前状态 |
| 出现两个实例同时运行 | 无单实例控制 | 使用文件锁 |
| 脚本异常终止后无法再次运行 | 残留锁文件未清理 | 改用文件描述符方式加锁 |
| 临时文件被其他用户读取 | 权限未限制或名称可预测 | 限制权限掩码并使用随机名称 |
| 密码出现在进程列表中 | 通过命令行参数传递凭据 | 改用环境变量或权限受限的文件 |
| 从其他目录调用时找不到资源 | 路径依赖当前目录 | 基于脚本目录推导 |
| 输出被当作数据处理 | 诊断信息写入了标准输出 | 日志与诊断统一写入标准错误 |
| 语法检查通过但运行报错 | 语法检查不覆盖运行期错误 | 结合执行跟踪与静态检查 |
| 忘记开启跟踪导致难以定位 | 缺少调试手段 | 用环境变量控制跟踪开关,需要时开启 |
四、总结
- 脚本的失败往往是静默的,三种形态(静默继续、部分完成、失败被掩盖)都源于未显式检查退出码。
- 脚本工程要在编写阶段回答三个问题:失败位置可定位、失败后可重入、现场可复现。
- 严格模式的三个选项能减少遗漏但不能保证安全,出错即退出在条件上下文、逻辑连接、取反、管道非末段与子进程中均会失效。
- 退出钩子负责清理、错误钩子负责输出上下文、信号捕获负责优雅停止,三者应指向同一清理逻辑。
- 数据走标准输出、诊断走标准错误是脚本可被组合的前提,日志格式应固定并包含时间与级别。
- 幂等通过执行前检测状态实现,文件锁通过文件描述符方式实现可避免残留锁导致的无法启动。
- 临时资源必须随机命名、权限受限并在退出时清理,固定名称存在被抢先创建的安全风险。
- 安全要点集中在命令注入、通配误伤、选项注入、凭据外泄、权限过高与路径依赖六项,均在编码阶段可消除。
- 调试的三层手段是语法检查、执行跟踪与静态检查,跟踪应可开关且输出到独立通道。
- 可移植性取决于运行环境的确定性,需要分发的脚本应限制在最小语法子集内。