Resolução de Problemas Comuns de Configuração em Scripts Bash

Problemas de configuração em Bash geralmente se manifestam de forma vaga: um script funciona no terminal, mas falha no cron; um script de deploy não encontra kubectl; ou um caminho de arquivo de configuração com espaço quebra apenas para um cliente. O bug geralmente não está na lógica principal. Está nas suposições sobre ambiente, argumentos, citações, permissões ou o shell que realmente executou o arquivo.

Quando resolvo problemas em um script Bash, primeiro tento responder quatro perguntas: Qual shell o está executando? Qual ambiente ele recebeu? Quais entradas ele analisou? Qual comando falhou primeiro? Essa ordem evita que você corra atrás de sintomas.

Confirme o shell e o contexto de execução

Um script que começa com sintaxe Bash, mas é executado sob sh, pode falhar de maneiras estranhas. Arrays, [[ ... ]], source, substituição de processo e set -o pipefail são recursos do Bash. Se o arquivo os utiliza, o shebang deve indicar Bash:

#!/usr/bin/env bash

Em seguida, execute-o da mesma forma que sua automação o executa. Estes não são equivalentes:

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

./deploy.sh usa o shebang. bash deploy.sh força o Bash. sh deploy.sh pode usar dash, BusyBox ash ou outro shell, dependendo do sistema. Se a produção chama sh deploy.sh, um shebang Bash perfeito não ajudará.

Cron, systemd, runners de CI, comandos SSH forçados e entrypoints do Docker fornecem ambientes diferentes. Um script que funciona interativamente pode falhar porque seu shell de login definiu PATH, AWS_PROFILE, NVM_DIR ou um gerenciador de versão de linguagem antes de você executá-lo.

Adicione um bloco de diagnóstico temporário perto do topo:

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

Remova ou desative isso quando tiver a resposta. Diagnósticos são úteis, mas vazar valores de ambiente para logs pode expor segredos.

Use o modo estrito com cuidado, não cegamente

set -euo pipefail é um padrão forte para muitos scripts de automação, mas tem casos extremos. set -u captura variáveis ausentes. pipefail torna as falhas de pipeline visíveis. set -e interrompe após muitas falhas de comando, embora se comporte de forma diferente dentro de condicionais, pipelines e comandos compostos do que os novos usuários de Bash esperam.

Um ponto de partida prático é:

set -Eeuo pipefail
trap 'printf "Erro na linha %s: %s\n" "$LINENO" "$BASH_COMMAND" >&2' ERR

Use-o quando um comando com falha deve interromper o script. Não o use casualmente em scripts que intencionalmente testam comandos e continuam. Para falhas esperadas, escreva a condição explicitamente:

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

Isso é mais claro do que deixar grep falhar sob set -e e se perguntar por que o script saiu.

Valide argumentos antes de ler arquivos

Um bug de configuração comum é tratar $1 como presente quando não está. Sob set -u, referenciar um $1 ausente sai imediatamente. Sem set -u, torna-se uma string vazia.

Use um pequeno bloco de uso:

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

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

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

if [[ ! -r $config_file ]]; then
  printf 'Arquivo de configuração não legível: %s\n' "$config_file" >&2
  exit 1
fi

Observe o padrão para environment, mas não para config_file. Padrões são úteis para valores opcionais e perigosos para valores obrigatórios. Um script não deve silenciosamente recorrer a ./config.yml para uma implantação de produção, a menos que esse comportamento seja muito deliberado.

Cite caminhos e valores da configuração

A maioria dos scripts Bash eventualmente lê um caminho de um arquivo de configuração ou variável de ambiente. Se esse valor não estiver entre aspas, o Bash realiza divisão de palavras e expansão de glob.

backup_dir="/mnt/backups/May reports"

# Quebrado: torna-se múltiplos argumentos.
cp $backup_dir/latest.tar.gz /restore/

# Correto.
cp "$backup_dir/latest.tar.gz" /restore/

A mesma regra se aplica a substituições de comando:

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

Se você intencionalmente precisa de múltiplos argumentos, use um array em vez de uma string:

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

Isso evita o padrão frágil de opts="-a --delete" seguido por rsync $opts ....

Verifique PATH e dependências de comandos externos

command not found geralmente é um problema de contexto. Seu terminal pode encontrar aws em /opt/homebrew/bin/aws, enquanto o cron tem apenas /usr/bin:/bin.

Na inicialização, verifique as ferramentas necessárias:

require_cmd() {
  command -v "$1" >/dev/null 2>&1 || {
    printf 'Comando necessário não encontrado: %s\n' "$1" >&2
    exit 127
  }
}

require_cmd docker
require_cmd jq
require_cmd aws

Para utilitários críticos do sistema, caminhos absolutos podem ser bons. Para ferramentas de desenvolvedor instaladas em lugares diferentes, uma verificação de dependência com um erro claro geralmente é mais fácil de manter.

Se um script for iniciado pelo systemd, defina o ambiente na unidade ou em um arquivo de ambiente, em vez de confiar no .bashrc do usuário. Shells não interativos não leem necessariamente os mesmos arquivos de inicialização que seu terminal.

Analise variáveis de ambiente explicitamente

A configuração orientada por ambiente é conveniente, mas vazio e não definido nem sempre são a mesma coisa. A expansão de parâmetros do Bash permite que você seja preciso:

: "${APP_ENV:?APP_ENV deve ser definido}"
log_level=${LOG_LEVEL:-INFO}

${APP_ENV:?mensagem} falha se a variável não estiver definida ou vazia. ${LOG_LEVEL:-INFO} usa um padrão se não estiver definido ou vazio. Se uma string vazia for significativa em seu script, use os formulários sem os dois pontos, como ${VAR-default}.

Evite despejar todo o ambiente nos logs durante a solução de problemas. É muito fácil imprimir tokens, senhas de banco de dados ou credenciais de nuvem.

Cuidado com terminações de linha CRLF e caracteres invisíveis

Um script editado no Windows pode conter terminações CRLF. O sintoma clássico é um erro contendo ^M, ou uma falha de shebang que parece que o interpretador não existe.

Verifique com:

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

Corrija com um destes:

dos2unix deploy.sh
# ou, se dos2unix não estiver disponível:
sed -i 's/\r$//' deploy.sh

Verifique também os valores de configuração copiados quanto a espaços à direita. Uma variável que parece prod mas é na verdade prod pode perder um ramo case e fazer você andar em círculos.

Depure o primeiro comando com falha

set -x mostra comandos após a expansão. Isso é exatamente o que você precisa para bugs de citação e configuração:

PS4='+ ${BASH_SOURCE}:${LINENO}: '
set -x
# seção com falha aqui
set +x

Não habilite xtrace em torno de segredos. Se seu script lida com senhas, tokens, URLs assinados ou chaves privadas, rastreie apenas a seção estreita que você precisa.

Para arquivos de configuração, imprima o valor resolvido e o teste que você está prestes a aplicar:

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

%q é útil para depuração porque torna os espaços em branco visíveis de uma forma amigável ao shell.

Trate permissões também como configuração

Às vezes, o script está correto, mas a conta que o executa não pode ler a configuração, executar o auxiliar ou escrever o diretório de saída.

Verifique o usuário real:

id
namei -l "$config_file"

namei -l é especialmente útil porque cada diretório no caminho precisa de permissão de execução. Um arquivo legível dentro de um diretório pai inacessível ainda é inacessível.

Para scripts executáveis, defina permissões e terminações de linha juntos durante a embalagem ou construção da imagem:

chmod 0755 /usr/local/bin/deploy

Se um script só funciona com sudo, identifique qual arquivo ou comando precisa de privilégio. Não execute todo o script como root apenas para encobrir uma configuração de propriedade incorreta.

Uma passagem confiável de solução de problemas

Quando um problema de configuração do Bash não está claro, execute esta passagem em ordem:

1. Confirme que o script está sendo executado sob Bash se ele usa recursos do Bash.
2. Imprima o diretório de trabalho, usuário e PATH para o contexto com falha.
3. Valide argumentos e arquivos de configuração necessários antes da lógica principal.
4. Cite toda expansão, a menos que você intencionalmente queira divisão.
5. Verifique comandos externos necessários com command -v.
6. Use set -x apenas em torno da seção com falha, com segredos protegidos.
7. Verifique permissões e terminações de linha antes de alterar a lógica de negócios.

Essa sequência captura a maioria das falhas do mundo real sem transformar o script em um romance de mistério. Bash é pequeno, mas seu contexto de execução é grande; solucione o contexto primeiro.

Separe o carregamento da configuração da execução

Um script é mais fácil de solucionar quando carregar a configuração é sua própria etapa. Não leia um arquivo, exporte variáveis, crie diretórios e reinicie serviços tudo em um longo bloco. Primeiro resolva os valores. Em seguida, valide-os. Depois, execute o trabalho.

load_config() {
  local file=$1
  [[ -r $file ]] || {
    printf 'Não é possível ler a configuração: %s\n' "$file" >&2
    return 1
  }

  # Exemplo para um arquivo CHAVE=VALOR deliberadamente simples.
  # Não use source em arquivos que você não confia totalmente.
  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 'Ignorando chave de configuração desconhecida: %s\n' "$key" >&2 ;;
    esac
  done < "$file"
}

Usar source em um arquivo de configuração com . config.env é comum, mas executa código shell. Isso é aceitável apenas quando o arquivo é confiável e possui propriedade como código. Para configuração editável pelo usuário, analise apenas as chaves que você suporta.

Torne as falhas acionáveis para o próximo operador

Uma boa mensagem de erro diz o que falhou e qual valor causou isso. Compare estes:

printf 'Erro\n' >&2

e:

printf 'Não é possível escrever o diretório de backup: %s\n' "$backup_dir" >&2

A segunda mensagem dá à próxima pessoa algo para verificar. Isso importa em scripts de DevOps porque a pessoa que vê a falha pode não ser o autor. Eles podem estar de plantão, meio acordados e olhando logs de CI de uma implantação com falha.

Códigos de saída também podem ter significado. Use 2 para problemas de uso, 1 para falhas gerais de tempo de execução e códigos específicos da ferramenta quando você tiver um motivo documentado. Não passe o dia todo inventando uma taxonomia, mas evite retornar sucesso após uma validação com falha apenas porque o script imprimiu um aviso.

Teste o contexto com falha, não seu contexto favorito

Se o systemd executa o script, teste com systemd. Se o cron executa, teste com um ambiente reduzido. Uma aproximação rápida é:

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

Isso remove o cobertor de segurança do seu shell interativo. Exportações ausentes e suposições de PATH aparecem rapidamente.

Para scripts de entrypoint do Docker, execute a imagem com o mesmo ambiente e montagens da produção o mais próximo possível:

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

Se falhar apenas no CI, imprima o diretório de trabalho do runner de CI e a linha de comando exata. Muitas falhas de Bash no CI são apenas caminhos relativos errados após o checkout, não problemas profundos de shell.

Uma passagem de revisão do mundo real antes de enviar

Antes de considerar um script ou configuração de contêiner finalizado, leia-o uma vez como se você fosse a próxima pessoa que precisa depurá-lo às 2 da manhã. Isso muda o que você percebe. Um prompt que fazia sentido ao escrever o script pode ser ambíguo quando aparece em um log de CI. Um nome de serviço Docker que parecia óbvio pode não corresponder ao nome da variável no aplicativo. Um padrão Bash pode ser seguro para desenvolvimento e perigoso para produção.

Gosto de fazer um teste seco curto com valores deliberadamente estranhos. Use um caminho com espaços. Use um valor opcional vazio. Tente um nome de arquivo que comece com um traço. Execute o script de um diretório de trabalho diferente. Inicie o contêiner sem uma variável de ambiente esperada. Esses testes não são sofisticados, mas capturam as suposições que geralmente quebram primeiro.

Verifique também a mensagem de falha. Se a única saída for falhou, o conselho do artigo não chegou à implementação. Uma falha útil diz qual valor foi usado, qual verificação falhou e o que o operador pode mudar. Isso não significa despejar todas as variáveis de ambiente ou imprimir segredos. Significa ser específico onde a especificidade ajuda: o caminho da configuração, o nome do comando ausente, o nome da rede, o nome do host do serviço ou a porta que o processo tentou vincular.

O hábito final é manter exemplos próximos da forma como o sistema é realmente executado. Se a produção usa Compose, teste com Compose. Se um script é iniciado pelo systemd, teste-o com systemd ou com um ambiente igualmente mínimo. Se um comando deve ser seguro para copiar e colar, inclua as citações, separadores -- e validação no próprio exemplo. Os leitores copiam padrões de trabalho com mais frequência do que copiam avisos.

Essa passagem de revisão não é burocracia. É como a pequena automação permanece chata. Chato é o que você quer de prompts de shell, carregadores de configuração, expansão de variáveis, diagnósticos de contêiner e rede Docker. Quanto menos surpreendente for o comportamento, mais fácil será para o próximo operador confiar nele.