Processo de atualização do Sherpa Orchestrator#

⚠️ Antes de atualizar: leia as notas de todas as versões, desde a instalada até a de destino. Elas podem conter etapas obrigatórias para a atualização. Notas da última versão publicada: versão 5.9.4.

⚠️ Importante: Se o Sherpa Orchestrator estiver sendo atualizado de uma versão inferior a 5.9.1 e o banco de dados integrado do Sherpa Orchestrator estiver em uso, a migração do banco de dados deve ser realizada antes da atualização.

Para MariaDB, realize a migração conforme as instruções em "Migração do MariaDB para o contêiner orchestrator-db:v5.9.2+".

Para PostgreSQL, realize a migração conforme as instruções em "Migração do PostgreSQL para o contêiner orchestrator-pg:v5.9.2+".

Se a atualização for a partir da versão 5.9.1 ou posterior, ou se for usado um banco de dados externo, a migração não é necessária.

💡 Atualização automática Em vez das etapas manuais abaixo, é possível usar um script interativo:

Copiar

sudo ./sh_scripts/update.sh

O script faz backup, interrompe os contêineres, baixa novas imagens, atualiza o .env e inicia com verificação de disponibilidade.

1. Download dos arquivos#

Baixe todos os arquivos de atualização mais recentes do Sherpa Orchestrator pelos links na seção de preparação

2. Transferência dos arquivos para o servidor#

Após o download, transfira todos os arquivos para o servidor Linux de destino por qualquer método conveniente:

Via SCP/SFTP#

# Copie os arquivos para o servidor
scp *.tar.gz user@target-server:/path/to/installation/directory/

Via cliente SFTP#

Use qualquer cliente SFTP (FileZilla, WinSCP, Cyberduck) para copiar os arquivos para o servidor.

Via pasta de rede#

Se o servidor estiver acessível via SMB/CIFS, use o Explorador do Windows ou o comando copy.

Verificação da transferência#

# Conecte-se ao servidor
ssh user@target-server

# Vá para o diretório com os arquivos (normalmente opt/SherpaOrchestrator)
cd /path/to/installation/directory

# Verifique se todos os arquivos estão presentes
ls -la *.tar.gz

# Verifique os tamanhos dos arquivos
ls -lh *.tar.gz

3. Parada dos contêineres#

# Pare todos os serviços em execução
docker compose down

4. Carregamento das imagens Docker#

# Crie um backup do arquivo .env (se existir)
cp .env .env.backup

# Crie um backup da configuração
cp -r ./backend/config ./backend/config_backup

# Se forem usados certificados personalizados, copie-os para um local seguro
cp -r ./backend/config/certs ./certs_backup

# Descompacte os arquivos de atualização
tar -xvzf "$(ls docker_orchestrator_client_files_*.tgz | sort -V | tail -n 1)"

# Copie a configuração padrão do nginx (se ela não existir)
cp -r ./nginx/config/default ./nginx/config

# Torne os scripts executáveis
chmod +x sh_scripts/*.sh

# Se tiver sido criado um backup dos certificados, restaure-os
cp -r ./certs_backup/* ./nginx/config/certs/

# Carregue todas as imagens Docker
sudo ./sh_scripts/load_all_docker_images.sh

5. Seleção da configuração de BD e verificação das variáveis de ambiente#

# Abra o arquivo .env para revisão e atualização
nano ./.env

# Verifique a presença das variáveis obrigatórias
grep -E "(HOST_IP|MYSQL_PASSWORD|DB_PASSWORD|POSTGRES_PASSWORD|NGINX_DOMAIN_NAME|DB_ENGINE)" .env

# Verifique a correção da sintaxe
cat .env | grep -v '^#' | grep '=' | wc -l

5.1 Migração do cache.bin (somente ao atualizar a partir da versão ≤ v141856)#

⚠️ Importante: Esta etapa é necessária somente se a atualização for a partir da versão v141856 ou anterior. Se a versão atual do orchestrator for superior a v141856, pule esta seção.

Ao atualizar a partir da versão ≤ v141856, o arquivo cache.bin deve ser montado dentro do contêiner orchestrator.

Adicione a seguinte linha à seção volumes do serviço orchestrator no arquivo docker-compose.yml:

  orchestrator:
    ...
    volumes:
      - orchestrator-storage:/opt/SherpaOrchestrator/backend/Storage
      - ./backend/config:/opt/SherpaOrchestrator/backend/config:z
      - ./path/to/cache.bin:/opt/SherpaOrchestrator/backend/app/cache.bin  # adicione esta linha

Substitua ./path/to/cache.bin pelo caminho real do arquivo cache.bin no servidor.

6. Inicialização dos contêineres#

# Inicie os serviços com o perfil de BD selecionado
# Opção 1: MariaDB
docker compose --profile mariadb up -d

# Opção 2: PostgreSQL
docker compose --profile pg up -d

# Se o VNC for necessário (opcional), adicione o perfil vnc:
# Opção 1: MariaDB + VNC
docker compose --profile mariadb --profile vnc up -d

# Opção 2: PostgreSQL + VNC
docker compose --profile pg --profile vnc up -d

# Se o Vault for necessário (opcional), adicione o perfil vault:
# Opção 1: MariaDB + Vault
docker compose --profile mariadb --profile vault up -d

# Opção 2: PostgreSQL + Vault
docker compose --profile pg --profile vault up -d

# Combinação de perfis: MariaDB + VNC + Vault
docker compose --profile mariadb --profile vnc --profile vault up -d

A inicialização do Vault e a migração de segredos são tratadas em um guia separado:

Após uma atualização bem-sucedida, o sistema Sherpa Orchestrator estará pronto para uso.

Migração do indicador de captura nos logs#

Esta seção se aplica a uma versão com 20261006120000_add_log_has_file.php. Antes da atualização são necessários um backup do banco e uma janela de manutenção. A conta de migração precisa de permissões para alterar tabelas e criar gatilhos. O PostgreSQL também exige permissão para criar a função.

A migração segue esta sequência:

1. Os processos da aplicação devem ser interrompidos, mantendo o banco disponível.

2. As migrações habituais do Phinx devem ser executadas no contêiner da nova versão para o mecanismo selecionado.

3. Após a migração, esta consulta deve confirmar que nenhuma linha está sem o indicador de captura:

   Copiar

   SELECT COUNT(*) FROM orchestrator.logs WHERE has_file IS NULL;
   

4. A aplicação pode ser iniciada quando o resultado for 0.

A migração adiciona orchestrator.logs.has_file e instala gatilhos para registros novos e alterados. As linhas existentes são preenchidas em lotes de até 100. As capturas antigas são lidas uma vez, portanto a duração depende do volume de dados. A alteração do esquema pode bloquear a tabela.

Após uma interrupção, a causa deve ser corrigida e as migrações executadas novamente. Linhas já preenchidas são ignoradas. A opção --fake não deve ser usada.

O formato da resposta da API e a obtenção de capturas são mantidos. A tabela de arquivo não muda. Para reverter, primeiro é necessário parar a aplicação e restaurar o código que não usa has_file. Depois a migração pode ser revertida. As capturas não são excluídas.