Ir para o conteúdo
Promovaweb

Ambientes e agentes do Portainer

Um ambiente é um servidor ou cluster cadastrado no Portainer para gerenciamento. A conexão por socket ou agente permite que você consulte os recursos desse ambiente no mesmo painel usado para os outros servidores.

Ficha e sumário da página

Referência técnica
Portainer 2.45.3
Revisão
13 de novembro de 2026
Conteúdo
Documentação oficial consultada
  1. Um Server para vários servidores
  2. O ambiente local, pelo socket
  3. O Portainer Agent, na porta 9001
  4. O Edge Agent, pelo túnel
  5. Grupos, tags e acesso
  6. Limites dos agentes

Um Server para vários servidores

O Portainer Server guarda o cadastro de todos os ambientes no próprio banco, no volume montado em /data. A tela de ambientes lista cada um com o nome, o endereço que o Server usa para se conectar, o IP público opcional onde as portas publicadas ficam acessíveis, o grupo e as tags. A tela inicial do painel mostra esses ambientes lado a lado. O menu de recursos troca de servidor quando você escolhe outro ambiente.

A documentação da versão 2.45 recomenda um único Server por conjunto de ambientes. Rodar duas instâncias do Server para administrar os mesmos clusters não tem suporte oficial. O Server fica num servidor de gerência, com os agentes nos demais. Os agentes não guardam estado próprio, porque tudo o que eles leem volta ao Server. Por isso a cópia de segurança do Portainer é a cópia do volume /data do Server.

O ambiente local, pelo socket

Na instalação, o Server recebe o socket /var/run/docker.sock montado no container. O assistente da configuração inicial detecta esse socket e cadastra o Docker do próprio servidor como o primeiro ambiente. Numa VPS única, esse é o único ambiente necessário. O Server fala com o Docker local pelo arquivo do socket, sem porta aberta na rede.

O cadastro manual de um Docker Standalone também aceita a conexão direta à API do Docker por TCP. Essa forma exige que o Docker do servidor remoto escute numa porta de rede protegida por TLS. Qualquer máquina que alcance essa porta com um certificado válido controla o Docker inteiro. Os agentes existem para evitar essa exposição.

O Portainer Agent, na porta 9001

O Portainer Agent é um container que roda no servidor remoto, com acesso ao socket do Docker daquela máquina. O Server abre a conexão até o agente na porta 9001, em HTTPS, com certificados gerados pelo próprio agente na instalação. O cadastro do ambiente recebe o endereço e a porta do agente sem protocolo, porque a conexão usa o HTTPS do próprio agente.

A documentação classifica o Agent clássico como opção de legado, mantida para redes locais. A conexão parte do Server, então o servidor remoto precisa deixar a porta 9001 acessível para o Server. Recursos mais novos, como as políticas de governança de frota, não funcionam com o Agent clássico.

Num Docker Swarm, o agente roda em modo global, uma réplica por nó do cluster. Assim o Server enxerga os containers e os volumes de todos os nós pela mesma conexão. A stack de Swarm publicada pela Portainer, o arquivo portainer-agent-stack.yml, segue esse desenho, com o Server falando com o endereço tasks.agent:9001.

O Edge Agent, pelo túnel

O Edge Agent inverte a direção da conexão. Em vez de o Server procurar o agente, o agente consulta o Server em intervalos regulares para saber se existe alguma tarefa pendente. O intervalo padrão é de 5 segundos e muda nas configurações do ambiente. O servidor remoto não abre porta nenhuma para a internet, porque toda conexão sai dele em direção ao Server:

  1. Cadastro

    Edge Agent Standard

    O Server gera o comando de instalação com o token do ambiente.

  2. Consulta

    https://portainer:9443

    O agente pergunta ao Server, a cada 5 segundos, se há tarefa.

  3. Túnel

    portainer:8000

    Com tarefa pendente, o agente abre o túnel TLS até a porta 8000.

  4. Ação

    /var/run/docker.sock

    O agente executa a ação no Docker do servidor remoto.

O ciclo do Edge Agent Standard, segundo a documentação 2.45 LTS. O servidor remoto não recebe conexão de entrada, todas saem do agente.

Por isso o Server precisa expor a interface e o túnel aos servidores remotos. A interface usa normalmente a porta 9443, enquanto o túnel usa a 8000. O exemplo oficial com Traefik publica cada serviço num domínio pela porta 443, como mostra a página O Portainer atrás do Traefik. O endereço de túnel personalizado tem campo próprio apenas na Business Edition. Na Community Edition, a documentação remete ao ajuste descrito na issue 6251 do projeto. Quando o Server usa um certificado autoassinado, EDGE_INSECURE_POLL=1 permite a consulta sem verificar a confiança desse certificado.

A documentação recomenda o Edge Agent na maior parte dos cenários. Ele atende servidores fora da rede do Server, como uma VPS em outro provedor, porque só o Server precisa estar acessível. No modo Async, exclusivo da Business Edition, não existe túnel. O agente envia capturas periódicas do estado do ambiente, com pouco tráfego, para conexões instáveis ou redes móveis com franquia.

No cadastro, você lista as variáveis do host que o Edge Agent recebe. Por segurança, esse repasse aceita apenas variáveis com o prefixo PORTAINER_. Isso não limita as variáveis usadas para configurar o próprio agente, como AGENT_SECRET. As opções estão na referência oficial de configuração.

Grupos, tags e acesso

Os ambientes se organizam em grupos e recebem tags. Um grupo define o acesso de vários ambientes de uma vez. Um usuário ou um team liberado no grupo herda o acesso a todos os ambientes dele, com a marca de herdado na tela de acesso. Um acesso definido direto no ambiente prevalece sobre o do grupo naquele ambiente, com a marca de substituição.

Ao remover um ambiente, as stacks criadas nele perdem o vínculo e ficam órfãs na lista de stacks. Elas continuam visíveis pela opção de mostrar stacks órfãs, à espera de uma nova associação. A remoção não apaga os containers no servidor, porque o Portainer só deixa de administrar aquele Docker.

Limites dos agentes

Os webhooks de stack da Business Edition funcionam só em ambientes com Server ou Agent clássico. Num ambiente Edge, o túnel abre sob demanda, sem endereço permanente para receber a chamada. Os servidores administrados também entram no cálculo de nós da Business Edition. Um servidor exclusivo de gerência fica fora desse cálculo quando não é administrado pelo Portainer, como explica a página Community e Business Edition.

O ambiente define onde a stack roda. O próxima página, Stacks pelo painel, mostra como o Portainer guarda o arquivo Compose de cada app e as variáveis dele.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.