Устранение распространенных проблем конфигурации Bash-скриптов

Проблемы конфигурации Bash обычно проявляются как нечто неопределенное: скрипт работает из вашего терминала, но не выполняется в cron; скрипт развертывания не может найти kubectl; путь к файлу конфигурации с пробелом ломается только у одного клиента. Ошибка часто не в основной логике. Она в предположениях об окружении, аргументах, кавычках, разрешениях или оболочке, которая фактически запустила файл.

Когда я устраняю неполадки в Bash-скрипте, я сначала пытаюсь ответить на четыре вопроса: Какая оболочка его запускает? Какое окружение он получил? Какие входные данные он разобрал? Какая команда отказала первой? Такой порядок не дает вам гоняться за симптомами.

Подтвердите оболочку и контекст выполнения

Скрипт, который начинается с синтаксиса 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 или другую оболочку в зависимости от системы. Если в продакшене вызывается sh deploy.sh, идеальный shebang Bash не поможет.

Cron, systemd, CI-раннеры, принудительные команды SSH и точки входа Docker — все предоставляют разные окружения. Скрипт, который работает в интерактивном режиме, может выйти из строя, потому что ваша оболочка входа установила 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 обычно является проблемой контекста. Ваш терминал может найти aws по пути /opt/homebrew/bin/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 пользователя. Неинтерактивные оболочки не обязательно читают те же файлы запуска, что и ваш терминал.

Анализируйте переменные окружения явно

Конфигурация, управляемая окружением, удобна, но пустое и неустановленное — не всегда одно и то же. Расширение параметров 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 полезен для отладки, поскольку делает пробелы видимыми удобным для оболочки способом.

Обрабатывайте разрешения как часть конфигурации

Иногда скрипт правильный, но учетная запись, запускающая его, не может прочитать конфигурацию, выполнить вспомогательный скрипт или записать в выходной каталог.

Проверьте фактического пользователя:

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.
  # Не подключайте файлы, которым вы не полностью доверяете.
  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 распространено, но оно выполняет код оболочки. Это приемлемо только тогда, когда файл доверенный и принадлежит коду. Для конфигурации, редактируемой пользователем, анализируйте только те ключи, которые вы поддерживаете.

Делайте сбои полезными для следующего оператора

Хорошее сообщение об ошибке говорит, что не удалось и какое значение это вызвало. Сравните:

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

Это снимает одеяло комфорта вашей интерактивной оболочки. Отсутствующие экспорты и предположения PATH быстро проявляются.

Для скриптов точек входа Docker запустите образ с тем же окружением и монтированиями, что и в продакшене, настолько близко, насколько это возможно:

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

Если он выходит из строя только в CI, выведите рабочий каталог CI-раннера и точную командную строку. Многие сбои Bash в CI — это просто неправильные относительные пути после checkout, а не глубокие проблемы с оболочкой.

Реальный обзорный проход перед отправкой

Прежде чем считать скрипт или настройку контейнера завершенными, прочитайте его один раз, как если бы вы были следующим человеком, которому придется его отлаживать в 2 часа ночи. Это меняет то, что вы замечаете. Подсказка, которая имела смысл при написании скрипта, может быть неоднозначной, когда появляется в логе CI. Имя службы Docker, которое казалось очевидным, может не соответствовать имени переменной в приложении. Значение Bash по умолчанию может быть безопасным для разработки и опасным для продакшена.

Мне нравится делать короткий пробный прогон с намеренно неудобными значениями. Используйте путь с пробелами. Используйте пустое необязательное значение. Попробуйте имя файла, начинающееся с дефиса. Запустите скрипт из другого рабочего каталога. Запустите контейнер без одной ожидаемой переменной окружения. Эти тесты не являются сложными, но они выявляют предположения, которые обычно ломаются первыми.

Также проверьте сообщение об ошибке. Если единственный вывод — failed, значит, совет из статьи не был реализован. Полезный сбой говорит, какое значение использовалось, какая проверка не удалась и что оператор может изменить. Это не означает сброс каждой переменной окружения или печать секретов. Это означает быть конкретным там, где конкретность помогает: путь к конфигурации, имя отсутствующей команды, имя сети, имя хоста службы или порт, к которому процесс пытался привязаться.

Последняя привычка — держать примеры близкими к тому, как система на самом деле запускается. Если в продакшене используется Compose, тестируйте с Compose. Если скрипт запускается systemd, тестируйте его с systemd или с аналогично минимальным окружением. Если команда должна быть безопасной для копирования и вставки, включите кавычки, разделители -- и проверку в сам пример. Читатели копируют рабочие шаблоны чаще, чем предупреждения.

Этот обзорный проход — не бюрократия. Это то, как небольшая автоматизация остается скучной. Скучное — это то, что вам нужно от подсказок оболочки, загрузчиков конфигурации, раскрытия переменных, диагностики контейнеров и сетей Docker. Чем менее удивительно поведение, тем легче следующему оператору доверять ему.