Como instalar o Dify num VPS com Docker Compose

O que é o Dify e o que está a preparar-se para executar

O Dify é uma plataforma que pode alojar para criar aplicações sobre modelos de linguagem de grande escala. Inclui uma interface Web para conceber aplicações de chat, agentes e pipelines de retrieval, uma API para os chamar a partir do seu próprio código e um local central para gerir prompts, conjuntos de dados e chaves de modelos. É o tipo de ferramenta que uma equipa pequena instala para que todos trabalhem sobre uma base privada partilhada, em vez de espalharem chaves de API por scripts. Se termos como agent, tool call e retrieval pipeline ainda não forem claros, rever esses conceitos desde o princípio primeiro fará com que os ecrãs do builder do Dify pareçam controlos conhecidos, e não um conjunto de opções sem identificação.

Executá-lo por conta própria significa executar muitos componentes. Em outubro de 2026, a stack predefinida documentada do Dify inicia 15 containers de execução contínua, além de uma tarefa única que define permissões de ficheiros e termina. Sete são serviços próprios do Dify: o servidor de API, um servidor websocket, um worker em segundo plano, um scheduler, o frontend Web, um daemon de plugins e um backend de agentes. Os outros oito são dependências: uma base de dados Postgres, uma cache Redis, uma base de dados vetorial Weaviate, uma entrada nginx, dois sandboxes de código e dois proxies SSRF. O Docker Compose liga todos estes componentes, mas trata-se de uma stack real, e o mínimo documentado pelo Dify é 4 GiB de RAM e dois núcleos de CPU. Se esse VPS também for executar outros serviços, dimensione-o com base em valores medidos, e não nos valores anunciados, porque os limites reais de RAM do PhotoPrism e do Immich ficam bem acima dos mínimos publicados, e um servidor de fotografias partilhado nesse host esgotará primeiro os recursos da base de dados e do armazenamento vetorial do Dify. A contenção de CPU causa o mesmo problema: uma biblioteca Jellyfin apresentada como uma videoteca dos anos 90 quase não consome recursos enquanto apenas navega pelas capas, mas, assim que alguém inicia uma transcodificação, as filas de workers do Dify ficam atrás dela. A vantagem é que o número de containers do Dify permanece fixo, independentemente do número de aplicações criadas, o que produz um custo mais previsível do que o OpenBot, em que cada colega de trabalho de IA recebe o seu próprio container e o seu próprio browser e cada nova instalação aumenta novamente o limite mínimo de memória.

Como o Dify armazena as suas chaves de API dos modelos e, muitas vezes, documentos privados carregados para retrieval, trate o host onde é executado como um sistema sensível desde o primeiro minuto. Este guia instala-o e depois reforça a segurança da mesma forma que reforçaria a de qualquer serviço que armazene segredos.

Pré-requisitos

É necessário ter um VPS a executar Ubuntu 24.04, com pelo menos 4 GiB de RAM e 2 núcleos de CPU, Docker com o plugin Docker Compose instalado (o Dify requer o Compose 2.24.0 ou posterior) e um utilizador com sudo ou que pertença ao grupo docker. O comando de clonagem abaixo também usa git, curl e jq. Se o Docker for uma novidade, os fundamentos do Docker Compose num VPS explicam a instalação e os comandos principais utilizados neste guia. É recomendável ter um nome de domínio apontado para o servidor, porque deverá configurar TLS à frente do Dify em vez de expor um endereço IP simples.

Etapa 1: Obter o Dify e os seus ficheiros Compose

O Dify mantém a configuração do Docker no repositório principal. Clone a versão mais recente, não o branch de desenvolvimento, e entre no diretório docker:

git clone --branch "$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | jq -r .tag_name)" https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env

Se o clone falhar com o erro "Remote branch null", a consulta à API do GitHub não devolveu resultados. Escolha uma versão na página de releases e passe-a manualmente para --branch.

O ficheiro .env contém a configuração principal. Leia-o antes de iniciar qualquer operação. Os primeiros valores a verificar são os que definem palavras-passe e segredos: SECRET_KEY, a palavra-passe do Postgres e a palavra-passe do Redis. O valor de SECRET_KEY vem vazio. Se o deixar assim, o Dify gera uma chave e guarda-a no seu diretório de armazenamento. As palavras-passe são diferentes: o ficheiro de exemplo define o mesmo difyai123456 para o Postgres e o Redis, além de chaves fixas e publicamente conhecidas para o sandbox de código, o daemon de plugins e o Weaviate. Deixar estes valores inalterados é a forma mais comum de um Dify autoalojado acabar comprometido. Se preferir definir a sua própria chave secreta, gere uma:

openssl rand -base64 42

Cole-a em SECRET_KEY e defina um valor forte e exclusivo para cada campo de palavra-passe e chave no ficheiro. A palavra-passe do Redis também aparece em CELERY_BROKER_URL. Altere-a nesse ficheiro também, caso contrário o worker não conseguirá ligar-se ao Redis.

Passo 2: Inicie-o

Inicie a stack:

docker compose up -d

A primeira execução descarrega várias imagens e inicializa a base de dados, por isso aguarde um minuto. Confirme que os contentores estão saudáveis:

docker compose ps

Cada serviço de execução contínua deve ler running; a tarefa de permissões executada uma única vez termina depois de concluir o seu trabalho. Por predefinição, o Dify disponibiliza a interface web através de um contentor nginx incluído, na porta 80. Na primeira visita a http://YOUR_SERVER/install, crie a conta de administrador. Faça isso imediatamente, antes que qualquer outra coisa possa aceder à porta, porque, enquanto essa conta não existir, qualquer pessoa que carregue a página poderá registá-la e assumir o controlo da sua instância.

Etapa 3: Não o exponha diretamente. Coloque TLS e uma firewall à frente

É aqui que a maioria das instalações rápidas termina e onde começam a maioria dos incidentes. O nginx do Dify escuta na porta 80, sem encriptação, em todas as interfaces, e também publica a porta 443. Não quer que o seu login de administração e as suas chaves de modelos circulem por HTTP simples, nem que os serviços internos fiquem acessíveis a partir do exterior.

Proteja o servidor com uma firewall com política padrão de negar tudo, permitindo apenas SSH e tráfego web:

sudo ufw default deny incoming
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Lembre-se de que uma firewall que cobre apenas IPv4 pode deixar as mesmas portas abertas em IPv6, a falha da firewall IPv6 que apanha tantos utilizadores de servidores self-hosted. Confirme que ambas as pilhas estão filtradas. Tenha também em conta que as portas publicadas pelo Docker são tratadas pelas próprias regras de firewall do Docker, não pelas regras do ufw, e que a pilha predefinida publica a porta de depuração do daemon de plugins, 5003, em todas as interfaces. Defina EXPOSE_PLUGIN_DEBUGGING_PORT em .env como 127.0.0.1:5003, a menos que queira realmente depurar plugins a partir de outra máquina.

Para TLS, a opção mais simples é associar a porta web do Dify à interface de loopback e executar à frente um reverse proxy com um certificado Let's Encrypt. Assim, o único componente exposto à Internet pública é o proxy, que comunica por HTTPS. O .env do Dify permite alterar a porta exposta; defina-o para fazer o bind em 127.0.0.1 e aponte o proxy para essa porta. Faça o mesmo com EXPOSE_NGINX_SSL_PORT, porque o nginx do Dify reivindica a porta 443 do host por predefinição e o seu proxy precisa dela. As práticas de proteção de agentes descritas em executar um agente de IA em segurança num VPS também se aplicam aqui: mantenha os componentes em loopback, exponha apenas o que tem de ser público e deixe uma única porta de entrada protegida tratar do TLS. Quando a interface de uma ferramenta se destina apenas a si e não precisa de certificado, não use um proxy. Aceda-lhe através de um túnel SSH, tal como alojar o scanner de segurança open-kritt mantém o dashboard associado a loopback e encaminha-o para o seu portátil, em vez de o publicar. Se uma equipa inteira precisar do Dify, mas a Internet pública não, uma rede overlay permite aplicar esta ideia a mais do que um portátil: anunciar a sub-rede privada do servidor à sua tailnet permite que todos os dispositivos aprovados acedam ao builder através de um endereço privado, enquanto a firewall continua a bloquear tudo exceto SSH. Se administrar este servidor através de um agente de programação, em vez de manualmente, defina previamente até que ponto ele pode agir sem supervisão antes de lhe entregar as chaves, porque o modo de permissões em que deixa o Claude Code determina se ele para para pedir confirmação antes de reescrever .env ou reiniciar a pilha. Se acabar com uma sessão a monitorizar os logs dos contentores enquanto outra edita a configuração do proxy, essas duas sessões podem trocar texto entre si no mesmo servidor, o que é melhor do que copiar a saída entre terminais sempre que reinicia a pilha.

Passo 4: Mantenha o sistema atualizado

O Dify evolui rapidamente, e as atualizações incluem correções de segurança. Como clonou uma tag de release, a atualização consiste em fazer checkout da tag seguinte, e não em obter alterações de uma branch. Faça primeiro uma cópia de segurança da base de dados e, em seguida, no diretório docker:

docker compose down
git fetch --tags
git checkout NEW_VERSION
docker compose pull
docker compose up -d

As migrações da base de dados são executadas automaticamente no arranque, e algumas não podem ser revertidas. Por isso, a cópia de segurança vem primeiro. Leia as notas de release antes de cada atualização, não apenas das principais: o Dify informa que os passos de atualização variam entre releases. Por exemplo, as notas da versão 1.17.1 (setembro de 2026) indicam que quem utiliza o Weaviate incluído com dados existentes não deve atualizar diretamente para essa versão, mas deve passar por cada release minor intermédia. O Dify também altera o schema de .env entre releases. Por isso, compare .env.example com o seu .env depois de fazer checkout de uma tag nova e transfira as suas alterações, porque uma variável nova que não tenha definido pode impedir o arranque de um contentor.

Passo 5: Faça backup do que não pode ser regenerado

Duas coisas num servidor Dify são insubstituíveis: a base de dados Postgres, que contém as suas aplicações, utilizadores e definições, e o volume que armazena os documentos enviados e o índice vetorial. Ambos ficam em volumes Docker no diretório docker. Crie snapshots segundo uma agenda e copie-os para fora do servidor. Esses snapshots contêm todas as chaves de modelos e todos os documentos enviados num único ficheiro. Por isso, encripte-os antes de os retirar do servidor, pelo mesmo motivo que um backup do Vaultwarden pode revelar-se o ponto fraco de um servidor de palavras-passe sólido. Uma chave de API de um modelo pode ser emitida novamente. A aplicação que demorou uma semana a criar não pode. O mesmo raciocínio aplica-se a qualquer agente cujo estado tenha de sobreviver à máquina onde é executado: manter o KiroCrew em execução como um contentor sempre ativo significa criar snapshots da memória e das agendas que, de outro modo, desapareceriam no reboot seguinte.

Quando quiser que os agentes criados aqui acedam a dados além dos seus próprios conjuntos de dados e pesquisem a Web em tempo real, apontá-los para uma instância SearXNG alojada por si mantém o fluxo de consultas no hardware que controla. Ainda assim, vale a pena estudar a superfície de ataque de prompt injection que fica exposta antes de ativar essa configuração. Para um agente mais autónomo, capaz de executar código, consulte alojar o Agent Zero por sua conta. criar o seu próprio agente de IA num VPS aborda os fundamentos comuns a todos eles.

FAQ

Quais são os requisitos do sistema para alojar o Dify por conta própria?

O Dify documenta um mínimo de 4 GiB de RAM e dois núcleos de CPU, além do Docker Compose 2.24.0 ou posterior. Esse limite reflete o tamanho da stack predefinida: 15 contentores de execução contínua e uma tarefa de inicialização executada uma vez, em outubro de 2026. Reserve espaço em disco suficiente para os documentos carregados e o índice vetorial. Reserve também mais memória se houver outros serviços no mesmo servidor.

É seguro expor o Dify diretamente na porta 80?

Não. O servidor web incluído no Dify escuta em HTTP simples e fica à frente do início de sessão de administrador e das suas chaves da API de modelos. Coloque um reverse proxy com um certificado Let's Encrypt à frente, associe a porta do próprio Dify ao loopback e permita que apenas o proxy HTTPS fique exposto à Internet. Combine isso com uma firewall de negação por predefinição que cubra IPv4 e IPv6.

Como atualizo uma instalação própria do Dify?

Faça uma cópia de segurança da base de dados. Depois, a partir do diretório docker, execute docker compose down, git fetch --tags, git checkout a nova tag de release, docker compose pull e docker compose up -d. Leia primeiro as notas da release, porque os passos de atualização variam entre releases, as migrações podem ser irreversíveis e o Dify por vezes adiciona novas variáveis .env. Se uma variável estiver ausente, um contentor pode não iniciar.

Qual é a primeira coisa a fazer depois de instalar o Dify?

Aceda a /install e crie imediatamente a conta de administrador. Até essa conta existir, qualquer pessoa que consiga aceder à página pode reclamá-la. Configure a conta assim que os contentores estiverem saudáveis e antes de abrir a firewall para a Internet.