Pular para o conteúdo principal

Instalação de Módulos

Como instalar, desinstalar e gerenciar módulos na plataforma ION Guard em ambiente de produção.

Visão geral​

Módulos são distribuídos como pacotes encriptados (.enc) que contêm o código-fonte, migrations, frontend compilado e configurações. A instalação é feita pela interface web ou via linha de comando.

Instalação via interface web​

Perfil necessário

Requer Platform Admin.

  1. Acesse Módulos (/modules) no menu lateral
  2. Clique em "Instalar Módulo"
  3. Selecione o arquivo .enc do módulo (máximo 100 MB)
  4. Aguarde o processamento

O que acontece internamente​

  1. Descriptografia — O pacote .enc é desempacotado com a chave de release do módulo (MODULE_RELEASE_KEY), via ModuleReleaseEncryption. Essa chave é fixa e compartilhada entre instalações (serve apenas para embrulhar/desembrulhar o arquivo de distribuição). Não confunda com a MODULE_ENCRYPTION_KEY, que é gerada por instalação e cifra dados sensíveis de runtime (credenciais de gateway, tokens em banco)
  2. Validação — Verifica a estrutura do ZIP: exige {Módulo}/{Módulo}ServiceProvider.php, todos os arquivos sob o diretório {Módulo}/ e nenhum path traversal (.. ou caminho absoluto)
  3. Staging — Extrai para um diretório temporário com nome aleatório (.{módulo}.staging-{rand}) no mesmo filesystem do destino, para que a troca seja atômica
  4. Swap atômico — Renomeia o módulo existente para .bak-{timestamp} (se houver) e move o staging para a posição final em app/Modules/
  5. Migrations — Executa php artisan migrate --force e reotimiza o cache (optimize + opcache_reset)
  6. Assets — Publica assets do frontend
  7. Docker Compose — Regenera modules_runtime.yml com os workers declarados pelo novo módulo
  8. Restart — Agenda o restart do PHP-FPM (via watcher inotify, sem acesso ao socket do Docker) para registrar o ServiceProvider

A instalação e a desinstalação são registradas na trilha de auditoria (module_installed / module_uninstalled).

Em caso de falha​

Se qualquer etapa falhar após a extração:

  • O diretório staging é removido
  • O backup da versão anterior (se existia) é restaurado
  • Assets são despublicados
  • Uma mensagem de erro é exibida na interface
Migrations não são revertidas automaticamente

Se a falha ocorrer após as migrations, elas não são revertidas automaticamente. Será necessário executar rollback manual se necessário:

./scripts/comp.sh exec -T ionguard_php php artisan migrate:rollback

Atualização de módulo​

Para atualizar um módulo já instalado, basta instalar a nova versão sobre a existente. O sistema:

  1. Faz backup da versão atual
  2. Instala a nova versão
  3. Executa novas migrations
  4. Mantém a versão anterior como backup até confirmar sucesso

Desinstalação​

Pré-requisitos​

Antes de desinstalar, resolva todos os alertas ativos do módulo. A desinstalação é bloqueada se existirem alertas não resolvidos.

Via interface​

  1. No card do módulo em Módulos (/modules), clique em "Desinstalar"
  2. Confirme no diálogo

O que é removido​

  • Registros de habilitação por site (site_modules)
  • Arquivos do módulo em app/Modules/
  • Assets publicados
  • Workers no Docker Compose

O que é preservado​

  • Tabelas no banco de dados — Dados criados pelo módulo permanecem
  • Registros de auditoria — Log de ações do módulo
  • Backups — Backups existentes não são afetados

Logs de instalação​

Todas as operações de módulos são registradas em um log dedicado:

storage/logs/modules.log

Cada operação inclui um request_id para rastreabilidade. O log é rotacionado diariamente com retenção padrão de 14 dias.

Verificação pós-instalação​

Após instalar um módulo:

# Verificar se o módulo está registrado
./scripts/comp.sh exec -T ionguard_php php artisan tinker --execute="
    app(\App\Modules\ModuleRegistry::class)->all()
"

# Verificar se workers foram criados (se o módulo declara workers)
./scripts/comp.sh ps

# Health check
./scripts/healthcheck.sh

Habilitação por site​

Após a instalação, o módulo precisa ser habilitado para cada site onde será usado. Veja Módulos — Guia do Usuário para instruções.