Scripts operacionais¶
Esta página documenta os scripts administrativos instalados em:
Eles controlam ferramentas auxiliares e atualizam serviços Docker da VPS.
Inventário¶
| Script | Finalidade |
|---|---|
quiet_mode.sh |
Desliga ferramentas administrativas não essenciais |
tools_mode.sh |
Religa ferramentas administrativas |
update_n8n.sh |
Atualiza somente o serviço n8n |
update_portainer.sh |
Atualiza o Portainer |
update_kuma.sh |
Atualiza o Uptime Kuma |
update_dozzle.sh |
Atualiza o Dozzle |
update_pgadmin.sh |
Atualiza o pgAdmin |
update_traefik.sh |
Atualiza o Traefik principal |
update_traefik_dashboard.sh |
Atualiza o container do dashboard do Traefik |
Todos estão marcados como executáveis e pertencem ao usuário root.
Verificar os scripts¶
Validar sintaxe¶
Essa validação não executa atualizações nem altera containers:
for script in \
/usr/local/bin/quiet_mode.sh \
/usr/local/bin/tools_mode.sh \
/usr/local/bin/update_n8n.sh \
/usr/local/bin/update_portainer.sh \
/usr/local/bin/update_kuma.sh \
/usr/local/bin/update_dozzle.sh \
/usr/local/bin/update_pgadmin.sh \
/usr/local/bin/update_traefik.sh \
/usr/local/bin/update_traefik_dashboard.sh
do
if bash -n "$script"; then
echo "OK $script"
else
echo "ERRO $script"
fi
done
Resultado registrado:
Modos operacionais¶
Modo silencioso¶
Script:
Finalidade:
- Reduzir consumo de CPU e memória.
- Desligar interfaces administrativas.
- Manter os serviços principais de automação funcionando.
Executar¶
Serviços afetados¶
| Serviço | Ação |
|---|---|
| Portainer | stop |
| Traefik Dashboard | stop |
| Uptime Kuma | stop |
| Dozzle | stop |
| pgAdmin | down |
Serviços que continuam ativos¶
Normalmente permanecem ativos:
- n8n
- PostgreSQL
- Redis
- Traefik principal
- MkDocs
- Docker
Mensagem do script
A mensagem antiga dizia que apenas o n8n permaneceria ativo. Isso não era literalmente correto, pois banco, cache, proxy e documentação também continuam funcionando.
Comandos usados¶
docker compose -f /opt/stacks/infra/compose.yml stop portainer
docker compose -f /opt/stacks/reverse-proxy/compose.yml stop traefik-dashboard
docker compose -f /opt/stacks/infra/compose.yml stop uptime-kuma
docker compose -f /opt/stacks/infra/compose.yml stop dozzle
docker compose -f /opt/stacks/pgadmin/compose.yml down
Impacto do down no pgAdmin¶
O comando:
remove o container e a rede criada pela stack, mas preserva o volume nomeado:
Ele não deve ser executado com -v, pois isso removeria o volume persistente.
Modo ferramentas¶
Script:
Finalidade:
- Religar as interfaces administrativas.
- Disponibilizar ferramentas de monitoramento e manutenção.
Executar¶
Serviços iniciados¶
| Serviço | Stack |
|---|---|
| Traefik Dashboard | reverse-proxy |
| Portainer | infra |
| Uptime Kuma | infra |
| Dozzle | infra |
| pgAdmin | pgadmin |
Correção realizada¶
O script usava anteriormente:
O nome correto do serviço é:
O comando foi corrigido para:
Confirmar os serviços¶
Estado das versões¶
Verificação realizada em julho de 2026.
| Serviço | Instalada | Versão estável consultada | Tag no Compose |
|---|---|---|---|
| n8n | 1.121.3 |
2.31.7 |
latest |
| Portainer CE | 2.33.5 |
2.39.5 LTS |
latest |
| Uptime Kuma | 1.23.17 |
2.3.2 |
latest |
| Dozzle | 8.14.6 |
10.6.13 |
latest |
| pgAdmin | 9.9 |
9.16 |
latest |
| Traefik principal | 3.7.1 |
3.7.9 |
v3.7.1 |
| Traefik Dashboard | 3.7.1 |
3.7.9 |
v3.7.1 |
Fontes oficiais consultadas:
https://github.com/n8n-io/n8n/releases
https://docs.portainer.io/release-notes
https://github.com/louislam/uptime-kuma/releases
https://github.com/amir20/dozzle/releases
https://www.pgadmin.org/news/
https://github.com/traefik/traefik/releases
Informação temporal
Versões mais recentes mudam com frequência. Consulte as fontes oficiais novamente antes de atualizar.
Funcionamento comum dos atualizadores¶
Os scripts de atualização seguem aproximadamente este fluxo:
- Recebem uma tag opcional.
- Criam backup do arquivo
compose.yml. - Alteram a tag da imagem.
- Executam
docker compose pull. - Recriam somente o serviço selecionado.
- Testam uma URL pública.
- Restauram o Compose anterior se o teste falhar.
Exemplo:
Sem argumento, a maioria usa:
Latest
A tag latest pode atravessar versões principais e introduzir mudanças incompatíveis. Para produção, use uma versão explícita.
Backup criado pelos scripts¶
Os scripts copiam o Compose para arquivos no mesmo diretório da stack.
Formato:
Exemplo:
Localizar backups¶
find /opt/stacks \
-type f \
-name 'compose.yml.bak.*' \
-printf '%TY-%Tm-%Td %TH:%TM %p\n' \
| sort
Limitação¶
O backup automático inclui apenas o compose.yml.
Ele não inclui:
- Bancos de dados
- Volumes Docker
- Arquivos
.env - Credenciais
- Configurações persistentes
- Estado interno das aplicações
Rollback não é máquina do tempo
Restaurar a imagem anterior não desfaz migrações realizadas dentro de PostgreSQL, SQLite ou outros volumes persistentes.
Atualizador do n8n¶
Script:
Versão atual¶
Verificar¶
Executar com tag explícita¶
Executar com latest¶
Não usar latest neste momento
A versão instalada está na linha 1.x, enquanto latest atualmente aponta para a linha 2.x. Essa atualização contém mudanças incompatíveis e deve seguir o guia oficial de migração.
Fluxo do script¶
- Backup de
/opt/stacks/n8n/compose.yml - Alteração da imagem
n8nio/n8n - Pull da imagem
- Recriação apenas do serviço
n8n - Teste em
/rest/settings - Até 15 tentativas
- Intervalo de 6 segundos
- HTTP
200considerado saudável - Restauração do Compose em caso de falha
Healthcheck externo¶
Riscos¶
- O script não faz backup do PostgreSQL.
- O script não faz backup dos dados persistentes do n8n.
- Migrações de banco podem impedir downgrade.
- A tag
latestpode instalar uma versão principal diferente. - O rollback restaura o Compose, mas não o banco.
Procedimento mínimo antes de atualizar¶
docker exec n8n-postgres-1 \
pg_dump -U n8n -d n8n -Fc \
> "/opt/backups/n8n/n8n-pre-update-$(date +%Y%m%d-%H%M%S).dump"
Validar o arquivo:
Atualizador do Portainer¶
Script:
Versão atual¶
Healthcheck¶
Resposta esperada:
Executar com versão explícita¶
Fluxo¶
- Backup do Compose da stack
infra - Alteração de
portainer/portainer-ce - Pull da imagem
- Recriação apenas do Portainer
- Até 20 tentativas
- Intervalo de 5 segundos
- Rollback do Compose em caso de falha
Backup adicional recomendado¶
O Portainer usa:
Antes da atualização:
docker run --rm \
-v infra_portainer-data:/source:ro \
-v /opt/backups/portainer:/backup \
alpine \
tar -czf "/backup/portainer-pre-update-$(date +%Y%m%d-%H%M%S).tar.gz" \
-C /source .
Atualizador do Uptime Kuma¶
Script:
Versão atual¶
Versão estável consultada¶
Migração principal
A atualização da linha 1.x para 2.x contém mudanças importantes. Leia o guia oficial antes de executá-la.
Guia:
Healthcheck atual do script¶
O script aceita somente:
Limitação do teste¶
Uma versão pode responder 200 na página inicial e estar saudável. Nesse caso, o script declararia falha indevidamente.
Uma condição mais tolerante seria:
Melhoria ainda não aplicada
Essa alteração deve ser feita e validada separadamente.
Executar¶
Não executar antes de:
- Criar backup do volume
- Ler o guia de migração
- Testar restauração
- Confirmar compatibilidade dos monitores
Volume¶
Atualizador do Dozzle¶
Script:
Versão atual¶
Versão estável consultada¶
Executar¶
Healthcheck¶
Resposta esperada:
Observação¶
O Dozzle não possui volume persistente na configuração atual.
O risco de perda de dados é menor, pois ele atua como visualizador de logs em tempo real. Mesmo assim, alterações entre versões principais podem modificar opções e comportamento.
Atualizador do pgAdmin¶
Script:
Versão atual¶
Versão estável consultada¶
Executar¶
Healthchecks¶
Primeira tentativa:
Alternativa:
Resposta esperada:
Volume¶
Backup recomendado¶
docker run --rm \
-v pgadmin_pgadmin-data:/source:ro \
-v /opt/backups/pgadmin:/backup \
alpine \
tar -czf "/backup/pgadmin-pre-update-$(date +%Y%m%d-%H%M%S).tar.gz" \
-C /source .
Atualizador do Traefik principal¶
Script:
Versão atual¶
Versão estável consultada¶
Tag padrão do script¶
Tag padrão desatualizada
O script usa v3.1 quando nenhum argumento é informado. Isso poderia substituir a versão atual 3.7.1 por uma versão da linha 3.1.
Sempre informe a versão explicitamente:
Healthcheck¶
O script usa o domínio do n8n para confirmar que o roteamento continua funcionando.
Aceita:
Impacto¶
A atualização do Traefik pode afetar simultaneamente:
- n8n
- MkDocs
- Portainer
- Uptime Kuma
- Dozzle
- pgAdmin
- Dashboard do Traefik
- Certificados TLS
- Roteamento HTTPS
Serviço crítico
Uma falha no Traefik pode tornar todos os domínios externos inacessíveis, mesmo que os containers internos continuem funcionando.
Arquivos importantes¶
/opt/stacks/reverse-proxy/compose.yml
/opt/stacks/reverse-proxy/.env
/opt/stacks/reverse-proxy/letsencrypt/acme.json
Atualizador do Traefik Dashboard¶
Script:
Versão atual¶
Executar¶
Comportamento¶
- Altera apenas o serviço
traefik-dashboard - Aceita HTTP
200–399 - Aceita HTTP
401quando há autenticação - Encerra sem erro se o serviço não existir
- Preserva o Traefik principal
Observação arquitetural¶
Existem dois containers Traefik:
Eles usam atualmente a mesma versão:
Para evitar incompatibilidades, mantenha os dois na mesma versão.
Melhorias recomendadas¶
Instalar ShellCheck¶
O ShellCheck encontra problemas que o bash -n não detecta.
Executar:
Corrigir o healthcheck do Kuma¶
Aceitar qualquer resposta entre 200 e 399, em vez de apenas 302.
Alterar a tag padrão do Traefik¶
No update_traefik.sh:
Ou, mais seguro, exigir argumento:
Exigir versão explícita¶
Para evitar atualizações acidentais para versões principais diferentes, os scripts podem rejeitar execução sem argumento.
Exemplo:
Criar backups de dados¶
Cada script deveria criar ou exigir backup do volume antes da atualização.
Validar o Compose antes do pull¶
Adicionar:
Verificar versão após atualização¶
Cada script deveria imprimir:
- versão anterior
- versão solicitada
- versão instalada
- imagem usada
- ID da imagem
Preservar modo silencioso¶
Um atualizador pode iniciar um serviço que estava parado intencionalmente.
O script ideal deve:
- Registrar se o serviço estava ativo.
- Atualizar.
- Retornar ao estado original.
Consultar conteúdo dos scripts¶
Ordem segura de atualização¶
Uma ordem conservadora é:
- Criar backups.
- Validar os scripts.
- Atualizar ferramentas auxiliares.
- Testar cada domínio.
- Atualizar pgAdmin.
- Planejar migração do Kuma.
- Planejar migração do n8n.
- Atualizar Traefik por último.
Não atualize vários serviços simultaneamente. Quando tudo quebra junto, cada log aponta para outro log e nasce o polvo do caos.
Checklist antes de executar¶
[ ] Versão atual confirmada
[ ] Versão de destino confirmada
[ ] Release notes lidas
[ ] Mudanças incompatíveis verificadas
[ ] Compose validado
[ ] Backup do Compose criado
[ ] Backup do .env criado
[ ] Backup do volume criado
[ ] Espaço em disco verificado
[ ] Procedimento de rollback definido
[ ] Janela de manutenção disponível
Ver espaço em disco¶
Ver espaço usado pelo Docker¶
Ver estado geral¶
Validar todas as stacks¶
docker compose -f /opt/stacks/n8n/compose.yml config >/dev/null &&
docker compose -f /opt/stacks/infra/compose.yml config >/dev/null &&
docker compose -f /opt/stacks/pgadmin/compose.yml config >/dev/null &&
docker compose -f /opt/stacks/reverse-proxy/compose.yml config >/dev/null &&
echo "Todas as stacks: OK"