Como rodar Qdrant com Docker em VPS: backup, SSL e custo

Para rodar Qdrant com Docker em uma VPS, crie um volume persistente, mantenha as portas 6333 e 6334 na rede interna, configure API key e HTTPS no proxy, e copie snapshots para fora do servidor. O processo não foi cronometrado pelo Runzos. O custo depende da VPS, do backup externo e da operação. Você precisa de VPS Linux, Docker Compose, domínio e acesso ao proxy.

Seu agente não ganha memória confiável só porque você subiu um container. Ele ganha outro sistema para operar. Isso inclui dados persistentes, controle de acesso, cópias recuperáveis e uma decisão honesta sobre quando um banco vetorial separado vale a complexidade.

Este guia organiza uma arquitetura inicial documentada para Qdrant em Docker. O Compose foi conferido contra a documentação oficial, mas não foi executado em uma VPS pelo Runzos. Portanto, trate cada validação abaixo como etapa a rodar no seu ambiente, não como teste já realizado.

Passo 1: confirme os pré-requisitos e a fronteira do serviço

💡 Vai rodar Qdrant numa VPS? A gente comparou o preço real em cada provedor — com renovação e requisitos — em VPS para Qdrant.

Antes de criar o arquivo, tenha uma VPS Linux com Docker e o plugin Docker Compose disponíveis. Você também precisa de um domínio apontado para o reverse proxy, acesso para criar uma API key e um destino externo para os snapshots.

Defina qual serviço pode falar com o Qdrant. No desenho deste artigo, apenas o reverse proxy e os serviços autorizados participam da rede interna. A internet acessa HTTPS na porta 443. O banco não publica 6333 nem 6334 diretamente.

O quickstart oficial do Qdrant documenta REST na porta 6333, dashboard em /dashboard e gRPC na porta 6334. A configuração padrão inicia sem autenticação nem criptografia. Por isso, expor essas portas publicamente não é o ponto de partida recomendado.

Passo 2: crie o Compose com armazenamento persistente

Crie um diretório do projeto e salve o arquivo abaixo como compose.yaml. Antes de subir o serviço, defina QDRANT_API_KEY no ambiente do seu shell ou em um mecanismo de segredos. Não versiona o valor real junto do Compose.

services:
qdrant:
image: qdrant/qdrant:latest
restart: unless-stopped
environment:
QDRANT__SERVICE__API_KEY: ${QDRANT_API_KEY:?defina QDRANT_API_KEY antes de continuar}
volumes:
- qdrant_storage:/qdrant/storage
- qdrant_snapshots:/qdrant/snapshots
networks:
- qdrant_internal
expose:
- "6333"
- "6334"

volumes:
qdrant_storage:
qdrant_snapshots:

networks:
qdrant_internal:
internal: true

O volume em /qdrant/storage mantém os dados quando o container é recriado. Já o volume de snapshots dá um local explícito para os arquivos antes da cópia externa. Nenhum dos dois, sozinho, substitui backup fora da VPS.

Valide a sintaxe e as variáveis resolvidas antes de iniciar. A expansão obrigatória abaixo interrompe o Compose se QDRANT_API_KEY não estiver definida:

docker compose config
docker compose up -d
docker compose ps

O primeiro comando deve renderizar a configuração sem deixar uma variável obrigatória vazia. Sem QDRANT_API_KEY, ele falha com a mensagem definida no Compose. O último deve mostrar o serviço qdrant em execução. Defina a variável e execute a validação novamente antes de seguir.

Passo 3: ligue proxy, HTTPS e autenticação

Coloque o reverse proxy na mesma rede Docker do Qdrant. O proxy publica 443 e encaminha internamente para a porta REST 6333. Assim, o app ou usuário não precisa alcançar o banco pelo IP público da VPS.

A documentação de segurança do Qdrant aceita a chave por service.api_key ou por QDRANT__SERVICE__API_KEY. Ela também recomenda TLS quando a chave é usada, para impedir que trafegue sem criptografia.

Depois de configurar o certificado no proxy, teste pelo domínio. Substitua o domínio pelo seu e use a chave que você definiu:

curl -i -H 'api-key: QDRANT_API_KEY_AQUI' https://qdrant.seu-dominio.example/collections

Uma resposta HTTP de sucesso confirma que o proxy consegue chegar ao serviço e que a requisição autenticada foi aceita. Faça também uma requisição sem o cabeçalho em um ambiente controlado. Ela não deve receber o mesmo acesso. Não exponha a chave no histórico do terminal, em logs ou em capturas de tela.

Passo 4: crie snapshots e copie-os para fora da VPS

Snapshot local não é sinônimo de backup. Por padrão, snapshots ficam em ./snapshots ou em /qdrant/snapshots na imagem Docker. Se o arquivo continua no mesmo disco da VPS, a perda do host ainda pode levar dados e cópia juntos.

A documentação de snapshots cobre criação, download e restauração. Desde o Qdrant 1.10, ela também permite configurar armazenamento compatível com S3.

Sua rotina precisa ter quatro partes curtas e verificáveis:

1. Crie o snapshot da coleção ou do storage conforme a documentação oficial.
2. Copie o arquivo para um destino fora da VPS, como armazenamento compatível com S3.
3. Registre o nome do arquivo, a data e a versão do Qdrant usada na origem.
4. Alerte quando a cópia externa falhar ou quando a retenção ameaçar lotar o disco.

Para uma instância única, existe snapshot de storage completo. Esse formato serve apenas para single-node. Ele não transforma um container em alta disponibilidade. Para essa arquitetura, a documentação de capacidade recomenda ao menos três nós e replication factor de dois ou mais.

Passo 5: teste a recuperação antes de chamar de backup

Restaure uma cópia em coleção ou ambiente descartável. O objetivo é confirmar que você consegue localizar o arquivo externo, baixá-lo e recuperar os dados esperados. Não basta conferir que um arquivo foi criado.

Antes de atualizar o Qdrant, preserve um snapshot externo e anote a versão de origem. Snapshot de coleção só é restaurável na mesma minor version ou na minor seguinte. Um snapshot 1.18.1, por exemplo, cabe em uma 1.18.x posterior ou 1.19.x.

Esse limite transforma atualização em procedimento. Primeiro você preserva e testa a cópia. Depois atualiza. Por fim, refaz a verificação de conectividade e restauração.

Como saber se funcionou

Você terminou a instalação inicial quando consegue confirmar todos estes resultados no seu ambiente:

• docker compose config renderiza o Compose sem variável crítica ausente.
• docker compose ps mostra o Qdrant em execução.
• O domínio HTTPS responde à requisição autenticada para a API.
• A porta 443 está no proxy, enquanto 6333 e 6334 não estão expostas à internet pública nesse desenho.
• O volume qdrant_storage continua associado ao serviço após recriar o container.
• Um snapshot foi copiado para fora da VPS e pode ser localizado no destino externo.
• Um restore em ambiente ou coleção descartável recupera os dados que você esperava.

Não marque a etapa como concluída só porque o dashboard abre. A validação completa inclui autenticação, persistência e recuperação.

Problemas comuns

A autenticação falha

Confira se QDRANT_API_KEY está definida antes de executar docker compose config e se o proxy encaminha o cabeçalho api-key. Não publique o segredo ao depurar. Teste primeiro a variável e a configuração renderizada, depois o pedido HTTPS autenticado.

As portas 6333 ou 6334 ficaram públicas

Remova a publicação direta de portas do serviço e mantenha expose para a comunicação interna. O acesso externo deve terminar no proxy em 443. Qdrant inicia sem autenticação nem criptografia na configuração padrão.

Os dados sumiram após recriar o container

Confira se /qdrant/storage está montado em qdrant_storage e se o Compose usado na recriação declara o mesmo volume. Container é descartável; o volume persistente é o que preserva os dados.

O snapshot está apenas no disco da VPS

Trate esse arquivo como cópia local, não como recuperação de desastre. Configure uma transferência para destino externo e acompanhe se ela terminou. Sem essa cópia, a falha do host pode remover o banco e o snapshot.

O restore falha depois de uma atualização

Compare a minor version de origem com a versão de destino. Snapshot de coleção só é compatível com a mesma minor version ou a seguinte. Preserve a cópia externa e teste o restore antes de promover uma atualização.

Antes do Docker: quando Qdrant vale mais que pgvector

A pergunta certa não é “Qdrant é melhor?”. A pergunta é qual componente reduz mais risco no seu produto agora. Um banco vetorial dedicado cria uma fronteira operacional nova. Ele pede monitoramento, backup, atualização e decisões de capacidade próprias.

Chamamos essa conta de Custo de Recuperação: o custo real de um banco vetorial é o que você paga para recuperar dados e serviço depois de uma falha, não só a mensalidade da VPS. Um servidor barato sem cópia externa e sem restore testado apenas adia a conta para o incidente.

Use Qdrant se a busca vetorial virou componente dedicado

Qdrant faz sentido quando embeddings, filtros por payload e busca vetorial já merecem uma camada própria. Esse cenário aparece quando seu RAG ou agente deixa de ser experimento e passa a atender fluxos relevantes do produto.

O ganho não é “memória de IA” por si só. É ter um banco projetado para esse tipo de consulta. A troca é clara: você passa a administrar mais uma superfície de produção.

Fique em PostgreSQL com pgvector se isso simplifica o produto

Se o micro-SaaS já usa PostgreSQL e a busca vetorial ainda é pequena, manter vetores no mesmo banco pode reduzir uma operação inteira. O pgvector oferece busca exata e aproximada, incluindo HNSW e IVFFlat. Como fica no PostgreSQL, também se beneficia de ACID, PITR e JOINs.

Isso não torna pgvector universalmente superior. Só evita criar um segundo banco antes de haver uma razão arquitetural concreta. Para muitos MVPs, menos serviços significa menos backup para conferir e menos caminhos de falha.

Quando um serviço gerenciado compra tempo

Um serviço gerenciado pode comprar tempo operacional. Ele não compra desempenho mágico. A escolha pode valer se sua prioridade for lançar e você aceitar depender da plataforma para parte da operação.

O Supabase AI & Vectors, por exemplo, reúne armazenamento, índices e consultas de embeddings sobre Postgres e pgvector. Compare o preço atual, os limites e a reversibilidade antes de assumir que ele será mais barato ou mais simples para sempre.

Arquitetura mínima segura para uma VPS

O app fala com um reverse proxy por HTTPS. O proxy encaminha internamente ao Qdrant. O banco grava em volume persistente. Uma tarefa cria snapshots e manda cópias para fora da VPS.

Usuário ou app
|
HTTPS :443
|
Reverse proxy
|
Rede Docker interna -> Qdrant REST :6333 -> /qdrant/storage
|
snapshots -> armazenamento externo compatível com S3

Não publique 6333 e 6334 diretamente na internet nesse desenho. O Qdrant inicia sem autenticação nem criptografia na configuração padrão. Qualquer parte com acesso de rede poderia alcançar a instância se você a expuser sem proteção.

Quanto custa de verdade hospedar Qdrant

Sem tabela oficial de preços coletada nesta pesquisa, não seria honesto fixar um valor em reais ou dólares. Qdrant OSS não cria uma mensalidade própria por existir no container. Seu custo é a soma de infraestrutura, cópia recuperável e tempo de operação.

Fórmula de RAM e disco pelos seus vetores

Para vetores densos, a fórmula da Qdrant é pontos × réplicas × dimensões × bytes por dimensão. Float32 usa 4 bytes, float16 usa 2 e uint8 usa 1. O cálculo é base, não capacidade final. Payload, índices, WAL e o modo de armazenamento também entram na conta.

A documentação de capacity planning recomenda cerca de 20% de folga de RAM e disco para page cache, overhead, WAL, snapshots e segmentos temporários. Faça o sizing com uma amostra representativa do seu dataset. Não transforme “2 GB bastam” em regra para qualquer RAG.

Folga troca custo por latência

Qdrant documenta tiers pinned, cached e cold. Vetores cold ficam em disco. Porém, reduzir aproximadamente pela metade os vetores em RAM pode aproximadamente dobrar a latência de busca. Menos RAM não cria desempenho gratuito; troca custo de infraestrutura por tempo de resposta.

A conta que falta: manutenção e recuperação

Uma VPS pode parecer a alternativa mais barata no checkout. Ela deixa de ser a mais barata quando exige horas de depuração após uma atualização, um disco cheio ou uma restauração que nunca foi ensaiada. Inclua esse trabalho na decisão, especialmente se você é o único operador do produto.

Se decidiu pela infraestrutura própria, compare a oferta atual de VPS Servla pelo Runzos com suas necessidades de RAM, armazenamento e rotina de backup. Confira os detalhes atuais antes de contratar; este guia não fixa preço nem plano.

Checklist final: escolha Qdrant, pgvector ou gerenciado

• Escolha Qdrant se busca vetorial, filtros e escala justificam um serviço separado.
• Fique com pgvector se seu PostgreSQL atual resolve o caso e reduzir serviços vale mais.
• Considere gerenciado se sua prioridade é tempo de entrega e você aceita a dependência da plataforma.
• Mantenha /qdrant/storage em volume persistente.
• Configure API key e TLS antes de conectar o app público.
• Copie snapshots para fora da VPS.
• Teste restore em ambiente ou coleção descartável.
• Dimensione por vetores, dimensões, tipo de dado, payload e folga.
• Registre versões antes de atualizar e valide a compatibilidade do snapshot.

FAQ

Qdrant precisa de Docker?

Não. Docker é uma forma prática de empacotar e operar o serviço. O ponto importante deste tutorial é persistência, segurança e backup, independentemente da forma de instalação.

Posso expor a porta 6333 na internet?

O recomendado aqui é não expor. Publique 443 no reverse proxy e mantenha o acesso ao Qdrant na rede interna, com API key e TLS no caminho público.

Snapshot local é backup?

Não sozinho. Snapshot no mesmo disco da VPS ajuda em algumas operações, mas não protege contra perda do host. Backup exige cópia externa e teste de restauração.

Quanta RAM preciso para Qdrant?

Depende do número de pontos, dimensões, tipo dos vetores, payload, índices, réplicas e latência esperada. Use a fórmula de capacidade e acrescente folga. Uma resposta fixa sem conhecer o dataset seria chute.

Qdrant ou pgvector para um RAG pequeno?

Comece por pgvector se seu produto já opera PostgreSQL e a busca vetorial não exige uma camada dedicada. Migre para Qdrant quando o volume, os recursos e a evolução do produto justificarem essa fronteira operacional.

Conclusão: Docker resolve o deploy, não a operação

Rodar Qdrant com Docker em VPS é viável para um MVP ou micro-SaaS. Mas o container é apenas a embalagem. O desenho responsável inclui volume persistente, API key, HTTPS, portas internas, snapshot externo e restore testado.

Antes de escolher a VPS, some infraestrutura, armazenamento de backup e o seu tempo de operação. Esse é o Custo de Recuperação. Quando a busca vetorial realmente precisa de um serviço dedicado, esse custo é uma escolha consciente. Quando não precisa, pgvector ou uma plataforma gerenciada podem manter o produto mais simples.

Para montar uma base de VPS voltada a Docker e serviços self-hosted, veja a oferta de VPS Servla no Runzos. Escolha o plano depois de estimar seus vetores, sua retenção e sua rotina de recuperação.

Leia também: Como instalar Node-RED com Docker em VPS: SSL, domínio e backup