> For the complete documentation index, see [llms.txt](https://ajuda.zdg.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.zdg.com.br/configuracao-superadmin/tenants-e-licenca/gerenciar-licenca-z-pro/agente-de-infra-painel-licenciado.md).

# Agente de Infra - Painel licenciado

Instale o Z-PRO numa VPS limpa, atualize, volte versão, crie instâncias, verifique a saúde do servidor e veja logs pelo Painel do Licenciado, sem   abrir o terminal. Recurso em beta.

O **Agente de Infra** liga a sua VPS ao Painel do Licenciado. Ao cadastrar o servidor, o painel instala nele um pequeno serviço, o **agente**, que roda dentro da sua infraestrutura e executa as tarefas que você pedir pelo painel.

Com o agente instalado, o que antes exigia terminal e SSH passa a ser feito com alguns cliques: **instalar o sistema numa VPS limpa**, **atualizar**, **voltar para a versão anterior**, **criar uma nova instância**, **verificar a saúde do servidor**, **ver logs**, **consultar credenciais**, **emitir certificado SSL** e, quando houver backup disponível, **restaurar o banco de dados**.

{% hint style="warning" %}
**Recurso novo, em beta.** O Agente de Infra está sendo melhorado continuamente: as funções podem mudar e novas ações serão incluídas aos poucos. Por isso, a janela de instalação recomenda testar primeiro em ambiente de laboratório ou desenvolvimento. Antes de qualquer instalação, atualização ou restauração, **crie um snapshot da VPS no provedor**.
{% endhint %}

{% hint style="info" %}
**O terminal continua funcionando normalmente.** O Agente de Infra é uma opção a mais, não uma substituição. A instalação e a atualização pelo terminal (instalador automático e Procedimento Padrão de Atualização) seguem disponíveis e suportadas. Usar o painel ou o terminal é decisão sua.
{% endhint %}

{% hint style="info" %}
**Pré-requisitos:**

* Acesso ao [Painel do Licenciado](https://painel.zdg.com.br/) com o **e-mail da licença**
* A **pesquisa do licenciado** respondida (é ela que libera o Agente de Infra, ver Etapa 1)
* VPS com acesso SSH liberado e usuário **root** (ou um usuário com **sudo sem senha**), com a senha ou a chave privada desse usuário
* Acesso ao painel do provedor da VPS, para conferir a impressão digital do servidor e criar snapshots
* **Para instalar o sistema do zero:** VPS limpa, sem painel, dentro dos Pré-requisitos de instalação; dois subdomínios (interface e API) com registro do tipo **A** apontando para o IP da VPS; e o domínio raiz liberado na aba **Domínios** do painel
  {% endhint %}

***

#### Como funciona

1. Você informa o endereço da VPS e o acesso SSH **uma única vez**.
2. O painel conecta, instala o agente e **descarta o acesso na hora**. A senha ou a chave privada não ficam guardadas.
3. A partir daí, quem conversa com o painel é o agente. Ele busca as tarefas que você pede, executa dentro da VPS e devolve o andamento na tela, atualizado a cada poucos segundos.
4. **Toda ação crítica pede um código de 6 dígitos**, enviado para o e-mail da licença: cadastrar a VPS, instalar, atualizar, liberar domínio.

Cada servidor cadastrado aparece como um cartão com:

| Campo               | O que mostra                                                                        |
| ------------------- | ----------------------------------------------------------------------------------- |
| **Nome e status**   | O nome que você deu ao servidor e a situação do agente (veja a tabela abaixo)       |
| **Instâncias**      | As instalações do Z-PRO na VPS e a versão de cada uma, ou **sem sistema instalado** |
| **Sinal do agente** | Quando o agente deu o último sinal ao painel                                        |
| **Agente**          | A versão do agente instalada                                                        |
| **Última tarefa**   | A última ação executada nesse servidor e o resultado                                |

| Selo                      | O que significa                                                                                     |
| ------------------------- | --------------------------------------------------------------------------------------------------- |
| **Conectado**             | O agente está ativo e recebendo tarefas                                                             |
| **Sem sinal**             | O agente não se comunica com o painel há algum tempo (VPS desligada, sem internet ou agente parado) |
| **Instalação incompleta** | Uma instalação está em andamento ou não terminou                                                    |
| **Banco sem pasta fixa**  | O banco de uma instância secundária antiga está num volume sem pasta fixa (veja Possíveis Erros)    |

{% hint style="info" %}
Uma VPS pode ter mais de uma instância do Z-PRO (por exemplo, a **principal** e outras criadas depois). O painel reconhece todas e mostra cada uma separadamente.
{% endhint %}

***

#### Etapa 1: Liberar o Agente de Infra (pesquisa do licenciado)

O Agente de Infra é liberado depois que você responde a **pesquisa do licenciado**: são 22 perguntas sobre você e o seu uso do Z-PRO, quase todas de um clique, em cerca de 5 minutos.

1. No Painel do Licenciado, abra **Onboarding**.
2. Expanda o **Passo 2: Responda a pesquisa do licenciado**.
3. Responda as perguntas na própria tela ou clique em **Abrir a pesquisa em nova aba**.

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2FhEWzeQt3nOgQxuIwfbHV%2F01-pesquisa-do-licenciado.png?alt=media&amp;token=ff3420ab-9fe8-4f50-a5c3-cf9d009ed9cd" alt="" width="375"><figcaption></figcaption></figure>

Ao concluir, o passo fica marcado sozinho e aparece o botão **Abrir o Agente de Infra**.

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2FGZ9Nv6L9oSeVWSpSnku6%2F02-pesquisa-concluida.png?alt=media&amp;token=45be75af-f74c-4e69-b798-21ff168e6ec5" alt="" width="375"><figcaption></figcaption></figure>

{% hint style="info" %}
Se fechar a pesquisa no meio, ela volta de onde você parou **no mesmo navegador**. As perguntas abertas são opcionais: a liberação acontece quando todas as perguntas de escolha estão respondidas.
{% endhint %}

Enquanto a pesquisa não é concluída, a tela do agente mostra o aviso **Agente de Infra (beta) travado**. Os servidores já cadastrados continuam vinculados, e você ainda consegue acompanhar uma tarefa em andamento e desvincular um servidor, mas as demais ações ficam bloqueadas.

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2FvhnuoVlsdqVqFAqX7VIv%2F03-agente-travado.png?alt=media&amp;token=d4d11fee-7026-42b5-bc20-6da176eddf80" alt="" width="375"><figcaption></figcaption></figure>

***

#### Etapa 2: Abrir o Agente de Infra e cadastrar a VPS

1. No menu lateral, em **Infraestrutura**, clique em **Agente de Infra**.
2. Clique em **Cadastrar VPS**.

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2FtFJJurTbWzvsc5JrnoWj%2F04-agente-de-infra-lista.png?alt=media&amp;token=08a26198-1500-468b-86d1-81a9a316bb1d" alt="" width="375"><figcaption></figcaption></figure>

***

#### Etapa 3: Informar onde está o servidor (passo 1 de 3)

Preencha os campos:

| Campo              | O que informar                                                   |
| ------------------ | ---------------------------------------------------------------- |
| **Nome**           | Como o servidor vai aparecer na lista (ex: VPS principal)        |
| **IP ou hostname** | Só o endereço, sem usuário, porta ou barras (ex: `203.0.113.10`) |
| **Porta SSH**      | `22`, a menos que o seu provedor use outra porta                 |

Clique em **Conectar e conferir**.

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2FdtRcY3JnoneepqkCcZVK%2F04a-cadastrar-vps-onde-esta.png?alt=media&amp;token=353efc0c-1cce-40d7-8a40-4650731530ff" alt="" width="219"><figcaption></figcaption></figure>

***

#### Etapa 4: Conferir a impressão digital do servidor (passo 2 de 3)

Antes de você enviar qualquer senha, o painel mostra como o servidor se apresentou: **IP ou hostname**, **tipo da chave** e **impressão digital** (fingerprint SSH).

1. Se quiser conferir, abra o painel do seu provedor de VPS (ou o console da VPS) e, logado como root, rode o comando abaixo:

```
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
```

2. Se for a mesma, clique em **A impressão confere**.

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2FJWYbSkA6s5or2tiRZBkc%2F04b-impressao-digital.png?alt=media&amp;token=3eeaf18c-a1c5-4162-88a9-6af09ce54dec" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
**Se a impressão digital não conferir, não envie o acesso.** Clique em **Cancelar**. Uma impressão diferente pode indicar que outro servidor está no meio do caminho entre o painel e a sua VPS.
{% endhint %}

***

#### Etapa 5: Informar o acesso e instalar o agente (passo 3 de 3)

1. Em **Usuário SSH**, informe `root` (ou um usuário com sudo sem senha).
2. Em **Como entrar**, escolha:
   * **Senha:** a senha do usuário na VPS; ou
   * **Chave privada:** o conteúdo completo do arquivo da chave (começa com `-----BEGIN`).
3. Cole a senha ou a chave no campo **Senha ou chave privada**.
4. Clique em **Instalar o agente** e confirme com o código enviado ao e-mail da licença.

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2FBUq1Ilpep0nwvWtf9OV9%2F04c-acesso-ssh.png?alt=media&amp;token=6f8bba74-e169-44a0-855f-e0febd20f4a0" alt="" width="223"><figcaption></figcaption></figure>

A instalação do agente leva **de um a três minutos**. Você pode sair da tela: o andamento continua aparecendo no cartão **Instalando o agente**, com o registro de cada etapa.

Ao final, o cartão mostra **Concluído** e a mensagem **Agente instalado**. O servidor passa a aparecer na lista com o status **Conectado**. Numa VPS limpa, o campo **Instâncias** mostra **sem sistema instalado**.

{% hint style="info" %}
Mensagens de aviso do sistema operacional no registro (linhas que começam com `[stderr] W:`) são normais e não impedem a instalação. O que vale é a última linha, que confirma o agente instalado e ativo.
{% endhint %}

***

#### Etapa 6: Instalar o Z-PRO numa VPS limpa

Pule esta etapa se a VPS já tem o Z-PRO instalado: o agente reconhece as instâncias existentes, e você segue para a Etapa 8.

{% hint style="danger" %}
**Antes de instalar:**

* **Crie um snapshot da VPS** no painel do provedor. A partir de certo ponto a instalação não tem volta pelo painel (veja abaixo), e o snapshot é o seu ponto de restauração.
* **Libere o domínio raiz** (ex: `suaempresa.com.br`) na aba **Domínios** do Painel do Licenciado. O endereço da API precisa ser de um domínio liberado na licença; sem isso, a instalação não segue e o sistema mostra erro de domínio não liberado.
  {% endhint %}

1. No cartão do servidor, clique nos **três pontos (⋮)** e escolha **Instalar o sistema**. A opção só aparece em servidores sem sistema instalado.
2. Leia o aviso no topo da janela. Ele lembra que a função está em beta, que a instalação leva alguns minutos e pode reiniciar a VPS uma vez, e qual é a **senha padrão** do administrador, que você troca no primeiro acesso.
3. Preencha os campos:

| Campo                     | O que informar                                                                                                                                                                         |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Versão a instalar**     | **Hotfix** (a mais recente, com as últimas correções) ou **Homolog** (a versão oficial). O número de cada uma aparece na opção. A diferença está no Procedimento Padrão de Atualização |
| **Endereço da interface** | O endereço em que as pessoas vão entrar no sistema (ex: `https://app.suaempresa.com.br`)                                                                                               |
| **Endereço da API**       | O endereço do servidor de aplicação (ex: `https://api.suaempresa.com.br`). Precisa ser de um domínio liberado na licença                                                               |
| **E-mail do responsável** | Recebe os avisos do certificado SSL                                                                                                                                                    |

4. Em **DNS**, escolha:
   * **Ainda não apontei o DNS:** a instalação confere os dois endereços antes de começar e **para** se eles não apontarem para esta VPS;
   * **Já apontei os dois endereços para esta VPS:** a instalação continua mesmo que a conferência ainda não os veja (útil quando o apontamento é recente e ainda está propagando).
5. Digite o **nome do servidor** para confirmar e clique em **Instalar**. **\[IMAGEM: 09-instalar-o-sistema-dns.png]**
6. Informe o **código de 6 dígitos** enviado para o e-mail da licença e clique em **Confirmar e continuar**.

**Acompanhar a instalação**

O cartão **Instalação** mostra a barra de progresso, a etapa atual e o registro de cada comando. Você pode navegar por outras telas do painel e voltar: a instalação continua rodando na VPS. Leva **cerca de 15 minutos**, dependendo do servidor.

A instalação passa, em ordem, por:

1. **Download** do pacote da versão escolhida;
2. **Preparação do servidor:** atualização do sistema operacional e dos pacotes;
3. **Servidor web (Nginx)** e certificados;
4. **Serviços de apoio:** banco de dados (PostgreSQL), Portainer e Redis;
5. **Backend:** instalação, criação do banco e dos dados iniciais, e início do serviço;
6. **Frontend:** instalação, build e início do serviço;
7. **Certificado SSL** para os dois endereços;
8. **Verificação de saúde:** o painel confere o backend, o frontend, o Nginx e o banco, e acompanha os processos em três amostras antes de dar a instalação como concluída.

{% hint style="warning" %}
**"Sem volta a partir daqui".** Quando esse selo aparece, a instalação já está alterando o servidor e não pode ser desfeita pelo painel. Se algo der errado depois desse ponto, o caminho de volta é o **snapshot** feito no provedor.
{% endhint %}

{% hint style="info" %}
Se a VPS precisar reiniciar durante a instalação, a instalação continua sozinha depois do reinício.
{% endhint %}

**Instalação concluída**

Ao final, o cartão da instalação mostra **Tarefa concluída sem erros** e o aviso **Sistema instalado**, que lembra a senha padrão do administrador.

O servidor passa a mostrar a instância **principal** com a versão instalada e a última tarefa **Instalação: Concluída**.

***

#### Etapa 7: Primeiro acesso depois da instalação

1. Acesse o **endereço da interface** que você definiu na Etapa 6.
2. Entre com o usuário **Super Admin** e a senha padrão informada no aviso da janela de instalação.
3. Aceite os termos de serviço.
4. **Troque a senha imediatamente.** Veja as demais ações obrigatórias em Manutenção e Segurança.
5. Siga para a ativação da licença, conforme o passo **Ativar a licença** do Onboarding.

A partir daqui, a configuração do sistema é a mesma de qualquer instalação: Customizar (White Label) para aplicar a sua marca, criar as empresas (tenants) e conectar os canais.

***

#### Etapa 8: Usar as ações do servidor

No cartão do servidor, clique nos **três pontos (⋮)** à direita para abrir o menu de ações.

| Ação                   | O que faz                                                                                       |
| ---------------------- | ----------------------------------------------------------------------------------------------- |
| **Instalar o sistema** | Instala o Z-PRO numa VPS sem sistema (só aparece nesse caso, ver Etapa 6)                       |
| **Atualizar**          | Atualiza todas as instâncias da VPS para a versão Hotfix ou Homolog                             |
| **Voltar versão**      | Retorna o sistema para a versão anterior                                                        |
| **Nova instância**     | Cria mais uma instância do Z-PRO na mesma VPS                                                   |
| **Verificar saúde**    | Confere processos, respostas na web, licença, banco, disco e certificado SSL                    |
| **Ver logs**           | Mostra as últimas linhas de log de uma instância                                                |
| **Credenciais**        | Exibe as variáveis de configuração da instância, como a senha do banco de dados                 |
| **Restaurar banco**    | Restaura o banco de dados a partir de um backup do painel (só fica ativa com backup disponível) |
| **Emitir SSL**         | Emite um novo certificado SSL para a instalação                                                 |
| **Atualizar agente**   | Atualiza o agente instalado na VPS para a versão mais recente                                   |
| **Ver última tarefa**  | Reabre o registro da última tarefa executada no servidor                                        |
| **Desvincular**        | Remove o servidor do painel                                                                     |

As seções abaixo detalham as ações mais usadas.

**Atualizar o sistema**

1. No menu do servidor, clique em **Atualizar**.
2. Confira a **versão atual** de cada instância.
3. Em **Versão a instalar**, escolha **Hotfix** ou **Homolog**.
4. Em **Snapshot da VPS**, crie o snapshot no painel do seu provedor e marque **Criei o snapshot da VPS no provedor**.
5. Clique em **Atualizar** e confirme com o código enviado ao e-mail da licença.

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2FQpCaTWgNXZCZoespP4sb%2F13-atualizar.png?alt=media&amp;token=fe97a768-eaef-4f01-884e-c0dedd87762a" alt="" width="197"><figcaption></figcaption></figure>

O painel atualiza **todas as instâncias da VPS** de uma vez: faz um backup de segurança, pausa o sistema por alguns minutos e roda uma verificação de saúde no fim. **Se a verificação reprovar, o servidor volta sozinho à versão anterior, código e banco.**

{% hint style="warning" %}
**Programe a atualização para um horário de pouco movimento.** Durante a pausa, o sistema fica indisponível para os atendentes. O snapshot no provedor é o caminho de volta caso algo dê errado além do que o painel consegue desfazer.
{% endhint %}

**Verificar a saúde do servidor**

Clique em **Verificar saúde** para o agente conferir a VPS. O resultado aparece em três blocos:

* **Verificações:** cada item com **OK** ou **Falhou**, por instância (processos do backend e do frontend no PM2, respostas HTTP, licença e banco), mais o servidor web, o espaço em disco e o certificado SSL.
* **Instâncias:** o resumo de cada instância (servidor de aplicação, interface, resposta na web e banco de dados).
* **Servidor:** espaço livre, validade do certificado SSL, backups disponíveis e o horário da verificação.

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2FSXcTF4i5rLB3EK5SLgq1%2F14-verificar-saude.png?alt=media&amp;token=86cb460c-c292-46f1-a1a5-6ade8a04ff93" alt="" width="375"><figcaption></figcaption></figure>

Se algum item **falhar**, a verificação aparece como reprovada e o motivo fica ao lado do item. No exemplo acima, `missing` indica que o processo da instância `appzpro` não foi encontrado no PM2.

**Ver logs**

1. Clique em **Ver logs**.
2. Escolha a **instância**.
3. Escolha o **serviço**: **Servidor de aplicação** (backend) ou **Interface** (frontend).
4. Informe a **quantidade de linhas** (de 1 a 500, contadas do fim).
5. Clique em **Buscar logs**.

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2Fktrs6VB4DoQtSREC3iDO%2F15-ver-logs.png?alt=media&amp;token=4968a6e4-c85e-4617-9e13-7ea790b560f3" alt=""><figcaption></figcaption></figure>

É o mesmo conteúdo que você veria no terminal com o PM2, útil para investigar um erro ou enviar ao suporte junto com o chamado.

**Consultar credenciais**

Clique em **Credenciais** para ver as variáveis de configuração da instância, como usuário e senha do banco de dados (PostgreSQL), segredos do JWT e dados do Redis. Use quando precisar, por exemplo, da senha do banco para uma integração ou um backup feito por fora.

<figure><img src="https://3541975055-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FM5B652UsmGn3Q7h9Du1t%2Fuploads%2FesVSxu7seDAskibyEb24%2F16-credenciais.png?alt=media&amp;token=6320aeb1-a0d4-4ca1-bf6b-1a78db07677e" alt="" width="215"><figcaption></figcaption></figure>

{% hint style="danger" %}
**Trate essas informações como senhas.** Não envie prints dessa tela sem ocultar os valores e não compartilhe as credenciais com clientes ou terceiros.
{% endhint %}

***

#### Segurança do acesso

* **O acesso SSH é usado uma vez só.** O painel conecta, instala o agente e descarta a senha ou a chave na hora. Nada disso fica guardado.
* **Impressão digital antes da senha.** Você confere a identidade do servidor antes de enviar qualquer credencial.
* **Confirmação por e-mail.** Toda ação crítica pede um código enviado ao e-mail da licença. Mantenha esse e-mail acessível e seguro.
* **Tarefas assinadas.** Cada tarefa sai do painel com uma assinatura, e o agente só executa o que foi realmente enviado pelo painel oficial e está disponível no menu de ações.
* **Nenhuma porta extra.** O agente roda na sua VPS como um serviço do sistema (`zpro-agent`) e é ele quem busca as tarefas no painel, então você não precisa abrir portas novas no firewall.
* **Para tirar o servidor do painel**, use **Desvincular** no menu de ações.

***

#### Perguntas frequentes

**Posso usar uma porta SSH diferente da 22?**

Sim. Informe a porta no campo **Porta SSH** ao cadastrar a VPS. Ela só é usada nesse primeiro acesso, para instalar o agente.

**Posso usar chave privada em vez de senha?**

Sim. No passo 3 do cadastro, em **Como entrar**, escolha **Chave privada** e cole o conteúdo completo do arquivo.

**Um técnico ou parceiro pode cuidar do servidor por mim?**

O Painel do Licenciado é acessado pelo **e-mail da licença**, e os códigos de confirmação chegam só nesse e-mail. Não é possível cadastrar outro e-mail para receber os códigos. Se outra pessoa administra o servidor, ela vai precisar do código enviado ao titular a cada ação crítica.

**Consigo trocar o domínio de uma instalação pelo agente?**

Ainda não. A troca de domínio de uma instalação existente continua sendo feita na VPS. Se precisar de ajuda, [abra um chamado](https://suporte.zdg.com.br/).

**Ainda posso instalar e atualizar pelo terminal?**

Sim. Os processos pelo terminal continuam funcionando normalmente e seguem suportados: o instalador automático para a primeira instalação e o Procedimento Padrão de Atualização para as atualizações. O Agente de Infra é uma função nova e opcional, e a escolha entre ele e o terminal é sua. Você também pode combinar os dois, por exemplo instalar pelo terminal e usar o painel para verificar a saúde e ver logs.

**Prefiro não instalar sozinho. Tem outra opção?**

Sim. Você pode **agendar a instalação com a equipe da ZDG** abrindo um chamado em [suporte.zdg.com.br](https://suporte.zdg.com.br/). Veja o Onboarding.

***

#### Resumo das Funcionalidades

| Funcionalidade                                | Onde acessar                                                |
| --------------------------------------------- | ----------------------------------------------------------- |
| Liberar o Agente de Infra                     | **Onboarding > Passo 2: Responda a pesquisa do licenciado** |
| Cadastrar uma VPS e instalar o agente         | **Infraestrutura > Agente de Infra > Cadastrar VPS**        |
| Instalar o Z-PRO numa VPS limpa               | **Agente de Infra > ⋮ > Instalar o sistema**                |
| Atualizar todas as instâncias da VPS          | **Agente de Infra > ⋮ > Atualizar**                         |
| Voltar para a versão anterior                 | **Agente de Infra > ⋮ > Voltar versão**                     |
| Criar uma nova instância                      | **Agente de Infra > ⋮ > Nova instância**                    |
| Conferir a saúde do servidor                  | **Agente de Infra > ⋮ > Verificar saúde**                   |
| Ver logs do backend ou do frontend            | **Agente de Infra > ⋮ > Ver logs**                          |
| Consultar a senha do banco e outras variáveis | **Agente de Infra > ⋮ > Credenciais**                       |
| Restaurar o banco a partir de backup          | **Agente de Infra > ⋮ > Restaurar banco**                   |
| Emitir certificado SSL                        | **Agente de Infra > ⋮ > Emitir SSL**                        |
| Atualizar o agente                            | **Agente de Infra > ⋮ > Atualizar agente**                  |
| Rever a última tarefa                         | **Agente de Infra > ⋮ > Ver última tarefa**                 |
| Remover o servidor do painel                  | **Agente de Infra > ⋮ > Desvincular**                       |

***

#### Encerramento

Com o Agente de Infra, instalar o Z-PRO, atualizar, subir uma nova instância ou conferir se está tudo no ar deixa de exigir terminal. O agente faz o trabalho dentro do seu servidor e o painel mostra cada etapa e o resultado. Comece respondendo a pesquisa do licenciado, cadastre a VPS e rode uma **Verificação de saúde** para conhecer o estado atual da sua instalação.

***

#### Possíveis Erros e Soluções

**O Agente de Infra aparece como "travado"**

**Causa:** a pesquisa do licenciado ainda não foi concluída.

**Solução:** clique em **Responder a pesquisa** (ou vá em **Onboarding > Passo 2**) e responda até o fim. A liberação é imediata.

**Não recebi o código de confirmação**

**Causa:** o código vai sempre para o **e-mail da licença**, não para o e-mail de quem está operando o painel.

**Solução:** confira a caixa de entrada e o spam do e-mail da licença. O código vale para uma única ação; se expirar, peça outro repetindo a ação.

**A impressão digital mostrada não confere com a do provedor**

**Causa:** o endereço informado aponta para outro servidor, ou há algo interceptando a conexão.

**Solução:** clique em **Cancelar** e não envie o acesso. Confira o IP no painel do provedor e tente de novo. Se a impressão continuar diferente, [abra um chamado](https://suporte.zdg.com.br/).

**A instalação do agente falha logo no início**

**Causa:** IP ou porta SSH incorretos, porta bloqueada no firewall, ou usuário sem permissão de root.

**Solução:** confira o IP (sem usuário, porta ou barras), a porta SSH e se o usuário é `root` ou tem sudo sem senha. Libere a porta SSH no firewall do provedor e tente novamente.

**A instalação do sistema parou na conferência do DNS**

**Causa:** você marcou **Ainda não apontei o DNS** e os dois endereços ainda não apontam para o IP da VPS.

**Solução:** confira os registros do tipo **A** dos dois subdomínios no seu provedor de domínio. Se o apontamento for recente e estiver certo, aguarde a propagação ou rode a instalação de novo marcando **Já apontei os dois endereços para esta VPS**.

**Erro de domínio não liberado**

**Causa:** o domínio raiz dos endereços informados não está cadastrado na licença.

**Solução:** no Painel do Licenciado, abra **Domínios > Adicionar domínio**, informe o domínio raiz (ex: `suaempresa.com.br`) e confirme com o código. Depois, tente de novo.

**O servidor aparece como "Instalação incompleta"**

**Causa:** a instalação ainda está em andamento ou foi interrompida antes de terminar.

**Solução:** se a tarefa estiver **Em andamento**, aguarde. Se não estiver, use **Ver última tarefa** para ver onde parou e **Ver logs** para o motivo, e [abra um chamado](https://suporte.zdg.com.br/) com essas informações. Se a falha foi depois do selo **Sem volta a partir daqui**, restaure o snapshot da VPS antes de tentar de novo.

**O servidor aparece como "Sem sinal" ou não recebe tarefas**

**Causa:** o agente não está se comunicando com o painel: a VPS está desligada ou sem internet, ou o agente parou.

**Solução:** confira se a VPS está ligada e com internet e aguarde alguns minutos, acompanhando o campo **Sinal do agente**. Se o sinal não voltar, [abra um chamado](https://suporte.zdg.com.br/).

**A verificação de saúde reprovou com "missing"**

**Causa:** o processo daquela instância (backend ou frontend) não está rodando no PM2.

**Solução:** use **Ver logs** na instância para identificar o motivo. Se a instância não estiver mais em uso, ignore o aviso; se estiver, [abra um chamado](https://suporte.zdg.com.br/) com o resultado da verificação.

**Aparece o aviso "Banco sem pasta fixa"**

**Causa:** o banco de uma instância secundária antiga está em um volume sem pasta fixa no servidor.

**Solução:** o painel não recria esse banco. **Faça um backup por fora** antes de mexer nessa instância.

**"Restaurar banco" aparece desabilitado**

**Causa:** ainda não existe backup do painel disponível para restaurar.

**Solução:** a opção é liberada quando houver backup. Confira em **Verificar saúde**, no campo **Backups**.

**A atualização terminou, mas o sistema voltou para a versão anterior**

**Causa:** a verificação de saúde no fim da atualização reprovou, e o servidor voltou sozinho à versão anterior (código e banco).

**Solução:** rode **Verificar saúde** e **Ver logs** para ver o que falhou e [abra um chamado](https://suporte.zdg.com.br/) com essas informações.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://ajuda.zdg.com.br/configuracao-superadmin/tenants-e-licenca/gerenciar-licenca-z-pro/agente-de-infra-painel-licenciado.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
