精通 DevOps 工具与最佳实践 - DevOps 知识中心 精通 DevOps 工具与最佳实践 - DevOps 知识中心

排查常见 Bash 脚本配置问题

掌握排查 Bash 脚本配置问题的技巧。本指南详细介绍了关键的调试技术，重点关注环境依赖、常见语法陷阱（如不正确的引号和单词分割）以及严重的执行失败。学习如何使用稳健的标志（`set -euo pipefail`）、处理参数解析错误，并解决常见问题，如 DOS 换行符和错误的 PATH 变量，确保您的自动化脚本在任何环境中都能可靠运行。

排查常见 Bash 脚本配置问题

Bash 配置问题通常表现为一些模糊的现象：脚本在终端中正常工作，但在 cron 中失败；部署脚本找不到 kubectl；或者包含空格的配置文件路径仅对某个客户造成问题。错误通常不在主要逻辑中，而是在关于环境、参数、引号、权限或实际运行文件的 shell 的假设中。

当我排查 Bash 脚本时，我首先尝试回答四个问题：哪个 shell 在运行它？它接收到了什么环境？它解析了什么输入？哪个命令首先失败了？这个顺序可以防止你追逐症状。

确认 shell 和执行上下文

一个以 Bash 语法开头但在 sh 下运行的脚本可能会以奇怪的方式失败。数组、[[ ... ]]、source、进程替换和 set -o pipefail 是 Bash 特性。如果文件使用了这些特性，shebang 应该指明 Bash：

#!/usr/bin/env bash

然后以与自动化运行相同的方式运行它。以下方式并不等价：

./deploy.sh
bash deploy.sh
sh deploy.sh

./deploy.sh 使用 shebang。bash deploy.sh 强制使用 Bash。sh deploy.sh 可能使用 dash、BusyBox ash 或系统上的其他 shell。如果生产环境调用 sh deploy.sh，那么完美的 Bash shebang 也无济于事。

Cron、systemd、CI 运行器、SSH 强制命令和 Docker 入口点都提供不同的环境。一个在交互式环境中正常工作的脚本可能会失败，因为您的登录 shell 在您运行它之前设置了 PATH、AWS_PROFILE、NVM_DIR 或语言版本管理器。

在顶部附近添加一个临时的诊断块：

printf 'shell=%s\n' "$BASH_VERSION" >&2
printf 'user=%s pwd=%s\n' "$(id -un)" "$PWD" >&2
printf 'PATH=%s\n' "$PATH" >&2

一旦得到答案，就删除或关闭它。诊断很有用，但将环境值泄露到日志中可能会暴露秘密。

谨慎使用严格模式，不要盲目

set -euo pipefail 对于许多自动化脚本来说是一个强大的默认设置，但它有边界情况。set -u 捕获缺失的变量。pipefail 使管道失败可见。set -e 在许多命令失败后停止，但在条件、管道和复合命令中的行为与 Bash 新手期望的不同。

一个实用的起点是：

set -Eeuo pipefail
trap 'printf "Error on line %s: %s\n" "$LINENO" "$BASH_COMMAND" >&2' ERR

当失败的命令应该停止脚本时使用它。不要随意在有意探测命令并继续的脚本中使用它。对于预期的失败，显式地编写条件：

if ! grep -q '^enabled=true$' "$config_file"; then
  printf 'Feature is disabled.\n'
fi

这比让 grep 在 set -e 下失败并想知道脚本为何退出要清晰得多。

在读取文件之前验证参数

一个常见的配置错误是将 $1 视为存在，但实际上它并不存在。在 set -u 下，引用缺失的 $1 会立即退出。没有 set -u，它变成一个空字符串。

使用一个小的用法块：

usage() {
  printf 'Usage: %s <config-file> [environment]\n' "${0##*/}" >&2
}

if (( $# < 1 )); then
  usage
  exit 2
fi

config_file=$1
environment=${2:-dev}

if [[ ! -r $config_file ]]; then
  printf 'Config file is not readable: %s\n' "$config_file" >&2
  exit 1
fi

注意 environment 有默认值，但 config_file 没有。默认值对于可选值很有用，但对于必需值则很危险。脚本不应该在生产部署中静默地回退到 ./config.yml，除非这种行为是经过深思熟虑的。

引用配置中的路径和值

大多数 Bash 脚本最终会从配置文件或环境变量中读取路径。如果该值没有加引号，Bash 会执行单词分割和通配符扩展。

backup_dir="/mnt/backups/May reports"

# 错误：变成多个参数。
cp $backup_dir/latest.tar.gz /restore/

# 正确。
cp "$backup_dir/latest.tar.gz" /restore/

同样的规则适用于命令替换：

release_name=$(git describe --tags --always)
printf 'Deploying %s\n' "$release_name"

如果你有意需要多个参数，使用数组而不是字符串：

rsync_opts=(-a --delete --exclude '.git')
rsync "${rsync_opts[@]}" "$src/" "$dest/"

这避免了脆弱的模式 opts="-a --delete" 后跟 rsync $opts ...。

检查 PATH 和外部命令依赖

command not found 通常是一个上下文问题。你的终端可能在 /opt/homebrew/bin/aws 找到 aws，而 cron 只有 /usr/bin:/bin。

在启动时，检查所需的工具：

require_cmd() {
  command -v "$1" >/dev/null 2>&1 || {
    printf 'Required command not found: %s\n' "$1" >&2
    exit 127
  }
}

require_cmd docker
require_cmd jq
require_cmd aws

对于关键的系统工具，绝对路径可能没问题。对于安装在不同位置的开发者工具，带有清晰错误的依赖检查通常更容易维护。

如果脚本由 systemd 启动，在单元或环境文件中设置环境，而不是依赖用户的 .bashrc。非交互式 shell 不一定读取与终端相同的启动文件。

显式解析环境变量

环境驱动的配置很方便，但空和未设置并不总是一回事。Bash 参数扩展允许你精确处理：

: "${APP_ENV:?APP_ENV must be set}"
log_level=${LOG_LEVEL:-INFO}

${APP_ENV:?message} 在变量未设置或为空时失败。${LOG_LEVEL:-INFO} 在未设置或为空时使用默认值。如果空字符串在你的脚本中有意义，使用不带冒号的形式，例如 ${VAR-default}。

避免在故障排除时将整个环境转储到日志中。很容易打印出令牌、数据库密码或云凭证。

注意 CRLF 换行符和不可见字符

在 Windows 上编辑的脚本可能包含 CRLF 换行符。典型的症状是包含 ^M 的错误，或者看起来解释器不存在的 shebang 失败。

使用以下命令检查：

file deploy.sh
sed -n 'l' deploy.sh | head

使用以下命令之一修复：

dos2unix deploy.sh
# 或者，如果 dos2unix 不可用：
sed -i 's/\r$//' deploy.sh

还要检查复制的配置值中是否有尾随空格。一个看起来像 prod 但实际上是 prod 的变量可能会错过 case 分支，让你白费力气。

调试第一个失败的命令

set -x 显示扩展后的命令。这正是你处理引号和配置错误所需要的：

PS4='+ ${BASH_SOURCE}:${LINENO}: '
set -x
# 失败的部分在这里
set +x

不要在秘密周围启用 xtrace。如果你的脚本处理密码、令牌、签名 URL 或私钥，只跟踪你需要的那一小部分。

对于配置文件，打印解析后的值和你即将应用的测试：

printf 'Using config_file=%q\n' "$config_file" >&2
[[ -r $config_file ]] || exit 1

%q 对于调试很有用，因为它以 shell 友好的方式使空白可见。

也将权限视为配置

有时脚本是正确的，但运行它的帐户无法读取配置、执行辅助程序或写入输出目录。

检查实际用户：

id
namei -l "$config_file"

namei -l 特别有用，因为路径中的每个目录都需要执行权限。一个可读的文件在不可访问的父目录中仍然是不可访问的。

对于可执行脚本，在打包或镜像构建期间同时设置权限和换行符：

chmod 0755 /usr/local/bin/deploy

如果脚本只能通过 sudo 工作，确定哪个文件或命令需要特权。不要仅仅为了掩盖一个错误的权限设置而将整个脚本作为 root 运行。

可靠的故障排除流程

当 Bash 配置问题不清楚时，按顺序执行以下流程：

  1. 如果脚本使用 Bash 特性，确认它在 Bash 下运行。
  2. 打印失败上下文的工作目录、用户和 PATH。
  3. 在主逻辑之前验证必需的参数和配置文件。
  4. 引用每个扩展，除非你故意想要分割。
  5. 使用 command -v 检查必需的外部命令。
  6. 仅在失败部分周围使用 set -x，并保护秘密。
  7. 在更改业务逻辑之前检查权限和换行符。

这个序列捕获了大多数现实世界中的失败，而不会把脚本变成一部悬疑小说。Bash 很小，但它的执行上下文很大；先排查上下文。

将配置加载与执行分离

当加载配置是其自己的步骤时，脚本更容易排查。不要在一个长块中读取文件、导出变量、创建目录和重启服务。首先解析值。然后验证它们。然后执行工作。

load_config() {
  local file=$1
  [[ -r $file ]] || {
    printf 'Cannot read config: %s\n' "$file" >&2
    return 1
  }

  # 示例用于一个故意简单的 KEY=VALUE 文件。
  # 不要 source 你不完全信任的文件。
  while IFS='=' read -r key value; do
    [[ -z $key || $key == \#* ]] && continue
    case $key in
      APP_PORT) APP_PORT=$value ;;
      APP_ENV) APP_ENV=$value ;;
      *) printf 'Ignoring unknown config key: %s\n' "$key" >&2 ;;
    esac
  done < "$file"
}

使用 . config.env source 配置文件很常见，但它会执行 shell 代码。只有当文件受信任且像代码一样被拥有时，这才可以接受。对于用户可编辑的配置，只解析你支持的键。

使失败对下一个操作者有用

一个好的错误消息会说明什么失败了以及什么值导致了它。比较以下两种：

printf 'Error\n' >&2

和：

printf 'Cannot write backup directory: %s\n' "$backup_dir" >&2

第二条消息给下一个人提供了可以检查的内容。这在 DevOps 脚本中很重要，因为看到失败的人可能不是作者。他们可能正在值班，半睡半醒，看着来自失败部署的 CI 日志。

退出代码也可以传达含义。使用 2 表示用法问题，1 表示一般运行时失败，以及当你有一个文档化的原因时使用工具特定的代码。不要花一整天时间发明分类法，但避免仅仅因为脚本打印了警告就在验证失败后返回成功。

测试失败的上下文，而不是你喜欢的上下文

如果 systemd 运行脚本，用 systemd 测试。如果 cron 运行它，用精简的环境测试。一个快速的近似方法是：

env -i HOME="$HOME" PATH=/usr/bin:/bin bash ./script.sh config.env

这去掉了交互式 shell 的舒适区。缺失的导出和 PATH 假设会很快显现。

对于 Docker 入口点脚本，尽可能接近生产环境地运行镜像，使用相同的环境和挂载：

docker run --rm --env-file app.env -v "$PWD/config:/config:ro" my-image:tag

如果它只在 CI 中失败，打印 CI 运行器的工作目录和确切的命令行。许多 CI Bash 失败只是签出后的错误相对路径，而不是深层的 shell 问题。

发布前的现实世界审查流程

在将脚本或容器设置标记为完成之前，像下一个必须在凌晨 2 点调试它的人一样通读一遍。这会改变你注意到的内容。在编写脚本时合理的提示在 CI 日志中出现时可能变得模糊。一个感觉明显的 Docker 服务名称可能与应用程序中的变量名不匹配。一个 Bash 默认值可能对开发是安全的，但对生产是危险的。

我喜欢用故意别扭的值做一个简短的试运行。使用包含空格的路径。使用空的可选值。尝试一个以破折号开头的文件名。从不同的工作目录运行脚本。在没有一个预期环境变量的情况下启动容器。这些测试并不花哨，但它们捕获了通常首先破坏的假设。

还要检查失败消息。如果唯一的输出是 failed，那么文章的建议还没有在实现中得到体现。一个有用的失败会说明使用了什么值、什么检查失败以及操作者可以更改什么。这并不意味着转储每个环境变量或打印秘密。它意味着在具体有帮助的地方具体：配置路径、缺失的命令名称、网络名称、服务主机名或进程尝试绑定的端口。

最后一个习惯是让示例接近系统实际运行的方式。如果生产使用 Compose，用 Compose 测试。如果脚本由 systemd 启动，用 systemd 或类似的最小环境测试。如果一个命令应该安全地复制粘贴，在示例本身中包含引号、-- 分隔符和验证。读者复制工作模式的频率高于复制警告。

那个审查流程不是官僚主义。它是让小型自动化保持无聊的方式。无聊正是你从 shell 提示符、配置加载器、变量扩展、容器诊断和 Docker 网络中所期望的。行为越不令人惊讶，下一个操作者就越容易信任它。