Como hospedar o Dify em um VPS com Docker Compose

O que é o Dify e o que você está se preparando para executar

O Dify é uma plataforma que você pode hospedar para criar aplicações baseadas em modelos de linguagem de grande porte. Você obtém uma interface web para criar aplicações de chat, agentes e pipelines de recuperação, uma API para chamá-los 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 única base privada partilhada, em vez de espalharem chaves de API por scripts. Se termos como agente, chamada de ferramenta e pipeline de recuperação ainda não estiverem claros, começar por esses conceitos ajudará a interpretar os ecrãs de criação do Dify como controlos familiares, em vez de um painel cheio de opções sem identificação.

Executá-lo por conta própria significa executar vários componentes. O Dify é distribuído como um conjunto de contentores Docker: um servidor de API, um worker em segundo plano, um frontend web, uma base de dados Postgres, uma cache Redis e uma base de dados vetorial, todos ligados pelo Docker Compose. Isso é mais do que um único binário, mas o Compose trata das ligações, e um VPS com alguns gigabytes de RAM disponíveis executa-o confortavelmente. Se esse VPS também for executar outro serviço, 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 partilhando a máquina consumirá primeiro os recursos da base de dados e do armazenamento vetorial do Dify. A contenção de CPU tem o mesmo efeito: uma biblioteca Jellyfin apresentada como uma videolocadora dos anos 90 quase não custa recursos enquanto alguém 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 a quantidade de contentores do Dify permanece fixa, independentemente do número de aplicações que você criar, o que gera um custo mais previsível do que o OpenBot, em que cada colega de trabalho de IA recebe o seu próprio contentor e o seu próprio navegador 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, frequentemente, documentos privados carregados para recuperação, trate a máquina onde ele é executado como sensível desde o primeiro minuto. Este guia instala o Dify e depois reforça a segurança da máquina como você faria com qualquer serviço que armazene segredos.

Pré-requisitos

É necessário ter um VPS com Ubuntu 24.04, Docker e o plugin Docker Compose instalados, além de um utilizador com sudo ou que pertença ao grupo docker. Se o Docker for uma novidade, os conceitos básicos do Docker Compose num VPS explicam a instalação e os comandos principais usados neste guia. Também é recomendável ter um nome de domínio apontado para o servidor, porque deverá colocar TLS à frente do Dify em vez de usar um endereço IP direto.

Etapa 1: Obter o Dify e os respetivos ficheiros Compose

O Dify mantém a configuração do Docker no repositório principal. Clone o repositório e entre no diretório docker:

git clone https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env

O ficheiro .env contém toda a configuração. 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 ficheiro de exemplo inclui valores de marcador de posição. Manter esses valores é a forma mais comum de deixar uma instalação self-hosted do Dify comprometida. Gere uma chave secreta real:

openssl rand -base64 42

Cole-a em SECRET_KEY e defina um valor forte e exclusivo para cada campo de palavra-passe do ficheiro.

Etapa 2: Inicie-o

Inicie a stack:

docker compose up -d

Na primeira execução, várias imagens são descarregadas e a base de dados é inicializada. Aguarde um minuto. Confirme se os contentores estão saudáveis:

docker compose ps

Todos os serviços devem ler running. 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 de qualquer outra origem conseguir aceder à porta, porque, enquanto essa conta não existir, qualquer pessoa que carregue a página pode 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ça a maioria dos incidentes. O nginx do Dify escuta na porta 80, sem encriptação, em todas as interfaces. Não quer que o login de administrador e as chaves dos modelos sejam transmitidos por HTTP simples, nem que os serviços internos possam ser acedidos a partir do exterior.

Proteja o sistema 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 abrange apenas IPv4 pode deixar as mesmas portas abertas em IPv6, a falha da firewall IPv6 que apanha tantos administradores de sistemas domésticos. Confirme que ambas as pilhas estão filtradas.

Para TLS, a abordagem mais simples é associar a porta web do Dify ao loopback e executar um reverse proxy com um certificado Let's Encrypt à frente. Assim, o único componente exposto na Internet pública é o proxy, que comunica por HTTPS. O .env do Dify permite alterar a porta exposta. Configure-o para associar-se a 127.0.0.1 e aponte o proxy para esse endereço. As práticas de proteção de agentes descritas em executar um agente de IA com segurança num VPS também se aplicam aqui: mantenha os componentes variáveis no loopback, exponha apenas o que tem de ser público e permita que uma única entrada protegida comunique por TLS. Quando a interface de uma ferramenta é apenas para si e não precisa de certificado, ignore o proxy e aceda a ela através de um túnel SSH, como em alojar o scanner de segurança open-kritt, que mantém o dashboard associado ao loopback e o encaminha para o seu portátil em vez de o publicar. Se uma equipa inteira precisar do Dify, mas a Internet pública não dever ter acesso, uma rede sobreposta amplia essa abordagem para além de um único portátil: anunciar a sub-rede privada do servidor à sua tailnet permite que cada dispositivo autorizado aceda ao builder através de um endereço privado, enquanto a firewall continua fechada a tudo, exceto SSH. Se administrar este servidor através de um agente de programação, em vez de manualmente, defina primeiro o que ele pode fazer 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 stack. Se acabar com uma sessão a acompanhar 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 stack.

Passo 4: Mantenha o sistema atualizado

O Dify evolui rapidamente, e as atualizações incluem correções de segurança. Para atualizar, faça um pull e reinicie a partir do diretório docker:

git pull
docker compose pull
docker compose up -d

Leia as notas de lançamento antes de avançar para uma versão principal, porque o Dify altera ocasionalmente o esquema .env entre versões, e 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?

O Dify é executado como uma stack Docker Compose com cerca de meia dúzia de contentores. Por isso, planeie usar uma VPS com pelo menos 2 GB de RAM livres, idealmente 4 GB, além de alguns núcleos de CPU e espaço em disco suficiente para os documentos carregados e o índice vetorial. A pressão sobre a memória vem da base de dados e do armazenamento vetorial, não do próprio Dify.

É 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 administração e das suas chaves da API de modelos. Coloque um reverse proxy com um certificado Let's Encrypt à frente, faça o bind da própria porta do Dify ao loopback e permita que apenas o proxy HTTPS fique exposto à Internet. Combine isto com uma firewall com política default-deny que cubra IPv4 e IPv6.

Como atualizo uma instalação self-hosted do Dify?

A partir do diretório docker, execute git pull e, em seguida, docker compose pull e docker compose up -d para obter as novas imagens e reiniciar. Leia primeiro as notas da versão, porque o Dify por vezes adiciona novas variáveis .env entre versões, e a ausência de uma delas pode impedir o arranque de um contentor.

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

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