Tutoriais de VPS
Implantação do LobeHub (LobeChat) 2.x em VPS (2026): tutorial completo de Docker, PostgreSQL, armazenamento de objetos, login e HTTPS
Este tutorial segue a arquitetura atual do LobeHub 2.x e explica com clareza a configuração da VPS, o Docker Compose, o banco de dados, o armazenamento de objetos, o login, o HTTPS, as atualizações e os backups.

Se você quer reunir OpenAI, Claude, Gemini, OpenRouter e modelos locais em uma única interface de chat, o LobeHub é hoje uma das opções mais populares. Antes ele se chamava LobeChat e, a partir da versão 2.x, o nome do projeto, as imagens, o sistema de login e a estrutura de implantação mudaram. Muitos tutoriais antigos que circulam na internet ainda usam lobehub/lobe-chat, NextAuth ou comandos de contêiner único, e copiá-los diretamente costuma travar você no login, no banco de dados e no upload de arquivos.
Este guia implanta a versão estável v2.2.12 de julho de 2026. O Docker Compose oficial não é apenas um contêiner web; ele também inclui PostgreSQL, Redis, RustFS e SearxNG. O objetivo também não é "a página abre e pronto", mas sim deixar completos ao mesmo tempo o domínio, o HTTPS, a persistência de dados, as restrições de cadastro, as atualizações e os backups.
Primeiro, as conclusões:
- Se você só se conecta a APIs de modelos externos, uma VPS de 2 núcleos e 4 GB pode servir como ponto de partida para uso pessoal;
- Para vários usuários, ou se você envia muitos documentos ou bases de conhecimento, recomenda-se 4 núcleos, 8 GB e mais de 80 GB de disco;
- Uma VPS de CPU comum serve para rodar a interface do LobeHub, mas não para rodar diretamente modelos locais grandes de 7B ou 14B;
- Se você não quer manter o banco de dados, o armazenamento de objetos, o login e os backups, usar o LobeHub Cloud diretamente vai economizar muito tempo.
Em julho de 2026, o repositório oficial já migrou para lobehub/lobehub, e a imagem Docker é lobehub/lobehub. A versão estável atual é a v2.2.12.
Os componentes principais de uma implantação em servidor incluem:
| Componente | Função | Precisa de persistência |
|---|---|---|
| LobeHub | Interface web, API, Agents e lógica da base de conhecimento | Configuração gerenciada por variáveis de ambiente |
| PostgreSQL | Usuários, sessões, Agents, metadados de arquivos | Obrigatório |
| Redis | Armazenamento de sessões e cache | Recomendado |
| RustFS | Armazenamento de objetos compatível com S3 para arquivos enviados | Obrigatório |
| SearXNG | Busca na web | Manter conforme a necessidade |
O que mais gera mal-entendidos aqui é o "auto-hospedagem". O que você auto-hospeda é o aplicativo LobeHub e a camada de dados. Se você se conectar à OpenAI, Anthropic, Google ou OpenRouter, os prompts e as requisições ainda serão enviados ao provedor correspondente. Somente quando os modelos também rodarem em serviços de inferência que você controla, como Ollama ou vLLM, as requisições dos modelos não sairão do seu ambiente.
O que segue são pontos de partida para a implantação, não promessas de concorrência. O uso real será afetado pelo número de usuários, volume de documentos, busca na web, crescimento do banco de dados e onde os modelos rodam.
| Cenário | Ponto de partida recomendado | Observações |
|---|---|---|
| Um único usuário, apenas APIs externas | 2 núcleos, 4 GB, SSD de 40 GB | O Compose completo roda, mas não adicione outros serviços pesados |
| 3–10 usuários, uploads ocasionais de documentos | 4 núcleos, 8 GB, SSD de 80 GB | Deixa margem para PostgreSQL, Redis e RustFS |
| Muitas bases de conhecimento e arquivos | 4 núcleos, 8 GB ou mais, armazenamento de objetos separado | Arquivos, índices e backups consomem disco continuamente |
| Rodar modelos grandes localmente | Servidor GPU separado | Mesmo que uma VPS de CPU consiga carregá-los, a velocidade geralmente é impraticável |
Se você ainda não decidiu a configuração, pode começar por Como escolher a configuração de uma VPS. Este guia implanta uma pilha de serviços completa, então 1 núcleo e 1 GB fica fora da faixa recomendada.
Ter a topologia clara vai facilitar muito a solução de problemas depois:
浏览器
├─ https://ai.example.com -> Caddy -> LobeHub:3210
└─ https://s3.example.com -> Caddy -> RustFS:9000
LobeHub
├─ PostgreSQL:5432
├─ Redis:6379
├─ RustFS:9000
├─ SearXNG:8080
└─ OpenAI / Anthropic / Gemini / OpenRouter / 自建模型 API
PostgreSQL e Redis não devem ser expostos à internet. A API S3 do RustFS precisa ser acessível pelo navegador, então um subdomínio dedicado é o mais claro; a porta de administração 9001 deve ser vinculada apenas ao localhost e acessada por túnel SSH quando necessário.
Este artigo usa Ubuntu 24.04, Docker Engine, Compose v2 e Caddy. Primeiro prepare dois registros DNS, ambos apontando para o IP público da VPS:
ai.example.com
s3.example.com
Atualize o sistema e instale as ferramentas básicas:
sudo apt update
sudo apt install -y ca-certificates curl git openssl ufw
Instale o Docker a partir do repositório oficial:
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
-o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" |
sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker version
sudo docker compose version
Abra apenas SSH, HTTP e HTTPS no firewall:
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status
Se você estiver operando por uma sessão SSH remota, permita o OpenSSH antes de ativar o UFW; depois que a conexão atual estiver estável, ative as demais regras do firewall.
O branch padrão do repositório oficial é atualizado muito rápido, então não rode uma instância de produção diretamente no canary. Primeiro baixe a versão estável v2.2.12 localmente:
cd /tmp
git clone --depth 1 --branch v2.2.12 \
https://github.com/lobehub/lobehub.git lobehub-v2.2.12
sudo mkdir -p /opt/lobehub
sudo chown "$USER":"$USER" /opt/lobehub
cd /opt/lobehub
Execute o script de inicialização oficial que você baixou localmente e diga explicitamente para ele ler a configuração da v2.2.12:
bash /tmp/lobehub-v2.2.12/docker-compose/setup.sh \
-l zh_CN \
--url https://raw.githubusercontent.com/lobehub/lobehub/v2.2.12
Escolha a implantação com domínio e informe ai.example.com e s3.example.com. O script baixará docker-compose.yml, .env, a configuração do bucket do RustFS e a configuração do SearXNG, e preparará KEY_VAULTS_SECRET, AUTH_SECRET, a senha do banco de dados e a senha do RustFS.
Não cole as senhas exibidas no terminal em chats, tickets ou repositórios Git. Após a inicialização, faça primeiro um backup de .env e restrinja as permissões:
chmod 600 .env
cp .env ".env.initial-$(date +%F-%H%M%S)"
chmod 600 .env.initial-*
O JWKS_KEY do exemplo oficial é apenas um valor de amostra. Seguindo as instruções do script de inicialização, crie um novo conjunto de chaves na página oficial de geração de JWKS e depois substitua JWKS_KEY em .env. Não pule esta etapa.
Por conveniência de depuração, o exemplo oficial declara portas do host para PostgreSQL, Redis e RustFS. Em uma VPS pública, convém restringir:
- LobeHub:
127.0.0.1:3210:3210 - PostgreSQL: remova
5432:5432 - Redis: remova
6379:6379 - API do RustFS:
127.0.0.1:9000:9000 - Administração do RustFS:
127.0.0.1:9001:9001
Ao mesmo tempo, fixe a imagem do LobeHub na versão estável verificada neste guia:
services:
lobe:
image: lobehub/lobehub:v2.2.12
ports:
- "127.0.0.1:3210:3210"
postgresql:
# 删除 ports,数据库只走 lobe-network
redis:
# 删除 ports,Redis 只走 lobe-network
rustfs:
ports:
- "127.0.0.1:9000:9000"
- "127.0.0.1:9001:9001"
Verifique os endereços externos em .env:
APP_URL=https://ai.example.com
INTERNAL_APP_URL=http://localhost:3210
S3_ENDPOINT=https://s3.example.com
Em uma implantação com Compose, INTERNAL_APP_URL deve manter o endereço interno do contêiner. S3_ENDPOINT não pode incluir o caminho do bucket nem qualquer outro sufixo, caso contrário os arquivos enviados não abrirão. O RustFS usa path-style e o Compose oficial já define S3_ENABLE_PATH_STYLE=1.
Após modificar, valide primeiro, não inicie diretamente:
sudo docker compose config >/tmp/lobehub-compose-rendered.yml
grep -nE "image:|published:|DATABASE_URL|S3_ENDPOINT" \
/tmp/lobehub-compose-rendered.yml
Confirme que o resultado renderizado não grava segredos por acidente em logs públicos e que não há 0.0.0.0:5432 nem 0.0.0.0:6379.
Baixe a imagem e inicie:
cd /opt/lobehub
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
A primeira inicialização precisa aguardar a verificação de integridade do PostgreSQL, a inicialização do RustFS e as migrações do banco de dados. Verifique os logs:
sudo docker compose logs --tail=200 lobe postgresql rustfs rustfs-init
Teste o LobeHub primeiro localmente:
curl -I http://127.0.0.1:3210
sudo ss -lntp | grep -E ":3210|:5432|:6379|:9000|:9001"
Normalmente apenas 3210, 9000 e 9001 estão vinculados a 127.0.0.1, e 5432 e 6379 não devem aparecer na lista de portas públicas em escuta.
Instale o Caddy:
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf https://dl.cloudsmith.io/public/caddy/stable/gpg.key |
sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt |
sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddy
Edite /etc/caddy/Caddyfile:
ai.example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:3210
}
s3.example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:9000
}
Valide e recarregue:
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -I https://ai.example.com
curl -I https://s3.example.com
O Caddy solicitará os certificados automaticamente. Se falhar, verifique primeiro se o DNS já aponta para a VPS atual e depois confira journalctl -u caddy -n 100. Para uma configuração e solução de problemas mais completas, consulte Guia completo para usar o Caddy como proxy reverso em uma VPS.
O LobeHub 2.x usa o Better Auth. O login com e-mail e senha vem ativado por padrão e, se você não mudar nada, uma instância pública pode permitir que estranhos se cadastrem.
A forma mais simples de restringir uma instância pessoal é permitir apenas o seu próprio e-mail em .env:
[email protected]
Essa variável apenas restringe quais endereços podem fazer login ou se cadastrar; ela não verifica a propriedade do e-mail. Redefinição de senha, links mágicos ou verificação por e-mail também exigem configuração de SMTP.
Se sua equipe usa GitHub, Google, Keycloak ou outro SSO de forma uniforme, você pode desativar e-mail e senha:
AUTH_DISABLE_EMAIL_PASSWORD=1
AUTH_SSO_PROVIDERS=github
AUTH_GITHUB_ID=your-github-oauth-client-id
AUTH_GITHUB_SECRET=your-github-oauth-client-secret
Se os callbacks do OAuth falharem, verifique primeiro se APP_URL corresponde exatamente ao domínio acessado no navegador, incluindo https://. O NEXT_PUBLIC_AUTH_URL dos tutoriais antigos está obsoleto, e continuar definindo-o causará falhas na implantação.
Após modificar .env, reconstrua o contêiner da aplicação:
sudo docker compose up -d --force-recreate lobe
sudo docker compose logs --tail=100 lobe
As chaves de API dos modelos podem ser gravadas em .env ou configuradas nas opções do LobeHub após o login. Em instâncias de equipe, é melhor que um administrador as gerencie de forma centralizada, para evitar que cada pessoa as cole repetidamente.
Por exemplo, para conectar a OpenAI:
OPENAI_API_KEY=your-openai-api-key
Se você usar OpenRouter, LiteLLM ou outro serviço compatível com OpenAI, configure a Base URL e a Key conforme as variáveis oficiais do provedor, e não reutilize nomes de variáveis antigos por intuição. Se quiser primeiro unificar vários upstreams em um único ponto de entrada, você pode combinar com Montando um gateway de API LLM unificado com LiteLLM em uma VPS.
Após as alterações, reconstrua o LobeHub e verifique três coisas na web:
- A lista de modelos carrega;
- Uma nova conversa recebe respostas completas;
- Após atualizar a página ou fazer login novamente, a conversa ainda existe.
"A lista de modelos está vazia" normalmente não é um defeito do frontend, mas sim uma API Key, Base URL, lista de modelos permitidos ou configuração de proxy de rede incorretas. Verifique diretamente os logs da aplicação:
sudo docker compose logs -f --tail=200 lobe
Envie uma imagem pequena e um documento de teste e confirme que os arquivos continuam acessíveis após atualizar a página. Se falhar, verifique na ordem:
curl -I https://s3.example.com
sudo docker compose ps rustfs rustfs-init
sudo docker compose logs --tail=200 rustfs rustfs-init lobe
grep -E "S3_ENDPOINT|RUSTFS_|S3_ENABLE_PATH_STYLE" .env
Os problemas comuns são:
S3_ENDPOINTainda éhttp://localhost:9000, então o navegador não consegue acessar de jeito nenhum;- O caminho do bucket foi adicionado por engano ao Endpoint;
- O subdomínio do RustFS não tem HTTPS;
- A porta 9000 está bloqueada pelo firewall ou pelo proxy reverso;
- O Access Key e o Secret Key em
.envnão correspondem aos valores no Compose.
Não exponha a 9000 diretamente à internet só para economizar esforço. Passar por um subdomínio HTTPS dedicado é mais fácil de controlar e não causa erros de conteúdo misto no navegador.
Não configure a produção para baixar automaticamente latest a cada poucos minutos. O LobeHub é atualizado rapidamente e as migrações do banco de dados também mudam. O processo seguro é:
cd /opt/lobehub
# 1. 记录当前镜像
sudo docker compose images
# 2. 完成下一节的备份
# 3. 把 docker-compose.yml 中的镜像改成已确认的新版本
sudo docker compose pull lobe
sudo docker compose up -d lobe
# 4. 查看迁移和启动日志
sudo docker compose logs --tail=300 lobe postgresql
Se após a atualização aparecer um erro de migração do banco de dados, não reinicie repetidamente sobrescrevendo a situação. Salve os logs e confirme as notas de migração das versões antiga e nova; quando precisar reverter, restaure a imagem antiga e o backup do banco de dados anterior à atualização. Apenas mudar a tag da imagem de volta e continuar usando um banco de dados já migrado pela nova versão pode não funcionar corretamente.
Uma restauração completa exige pelo menos:
- Dados do PostgreSQL;
- Arquivos de objetos do RustFS;
- Dados do Redis (se você quiser preservar o estado do cache de sessões);
.env, JWKS, Caddyfile e configuração do Compose;- A versão da imagem em uso.
Crie um diretório de backup e exporte o banco de dados:
cd /opt/lobehub
mkdir -p "backups/$(date +%F)"
sudo docker compose exec -T postgresql \
pg_dump -U postgres -d lobechat -Fc \
>"backups/$(date +%F)/lobehub-postgres.dump"
cp .env docker-compose.yml bucket.config.json searxng-settings.yml \
"backups/$(date +%F)/"
sudo cp /etc/caddy/Caddyfile "backups/$(date +%F)/Caddyfile"
sudo chown -R "$USER":"$USER" backups
chmod 600 "backups/$(date +%F)/.env"
O nome padrão do banco de dados é lobechat; se você alterou LOBE_DB_NAME, o comando de exportação também deve mudar.
RustFS e Redis usam volumes do Docker. Primeiro verifique os nomes reais dos volumes:
sudo docker volume ls | grep lobehub
Em uma breve janela de inatividade, interrompa as gravações e depois empacote os volumes:
sudo docker compose stop lobe
sudo docker run --rm \
-v lobehub_rustfs-data:/source:ro \
-v "$PWD/backups/$(date +%F)":/backup \
alpine tar -czf /backup/rustfs-data.tar.gz -C /source .
sudo docker run --rm \
-v lobehub_redis_data:/source:ro \
-v "$PWD/backups/$(date +%F)":/backup \
alpine tar -czf /backup/redis-data.tar.gz -C /source .
sudo docker compose up -d
Se docker volume ls mostrar nomes diferentes, substitua o comando pelos resultados reais. Após o backup, sincronize o diretório para outra máquina ou para o armazenamento de objetos; se os backups ficarem no mesmo disco da VPS que os dados de produção, eles desaparecerão junto com a máquina se ela falhar.
Antes de restaurar, ensaie primeiro em uma VPS de teste. Exemplo de restauração do banco de dados:
cat lobehub-postgres.dump |
sudo docker compose exec -T postgresql \
pg_restore -U postgres -d lobechat --clean --if-exists
Restaure primeiro .env e as chaves, depois o PostgreSQL e os arquivos de objetos, e por fim inicie o LobeHub. Se as chaves mudarem, mesmo com o banco de dados e os arquivos presentes, o login pode falhar ou as credenciais salvas podem não ser descriptografadas.
Para um processo de backup externo mais completo, continue com Simulação de backup e restauração em VPS.
sudo docker compose ps
curl -I http://127.0.0.1:3210
sudo systemctl status caddy --no-pager
sudo journalctl -u caddy -n 100 --no-pager
Se a 3210 é acessível localmente mas o domínio não, o problema provavelmente está no DNS, no Caddy ou no firewall. Se a 3210 também não é acessível localmente, verifique os logs do LobeHub.
sudo docker compose ps postgresql
sudo docker compose logs --tail=200 postgresql lobe
sudo docker compose exec postgresql \
pg_isready -U postgres -d lobechat
Concentre-se em verificar POSTGRES_PASSWORD, LOBE_DB_NAME e o DATABASE_URL renderizado. Não abra a 5432 para toda a internet só para depurar.
Verifique APP_URL, AUTH_SECRET, a hora do sistema e os cookies do navegador. Após mudar o domínio de HTTP para HTTPS, reconstrua o contêiner do LobeHub para que as variáveis de ambiente realmente entrem em vigor:
timedatectl status
grep "^APP_URL=" .env
grep -q "^AUTH_SECRET=." .env && echo "AUTH_SECRET 已设置"
sudo docker compose up -d --force-recreate lobe
Não publique o valor de AUTH_SECRET em logs públicos.
sudo docker compose logs --tail=400 lobe postgresql
sudo docker compose images
Confirme se você cruzou uma versão principal, se a migração do banco de dados falhou ou se a nova imagem exige novas variáveis de ambiente. Preserve primeiro os logs e os dados existentes e depois decida se continua a migração ou reverte a partir do backup.
- Tanto
ai.example.comquantos3.example.comsão HTTPS; - PostgreSQL e Redis não estão escutando na rede pública;
-
.envtem permissões 600 e as chaves não foram enviadas ao Git; -
AUTH_ALLOWED_EMAILSou o SSO já restringem o cadastro de estranhos; - A lista de modelos, a persistência das conversas e o upload de imagens e documentos foram verificados;
- A imagem do LobeHub está fixada em uma versão confirmada;
- PostgreSQL, RustFS, configuração e chaves têm backups externos;
- Pelo menos uma restauração em ambiente de teste foi concluída.
O valor da auto-hospedagem do LobeHub é colocar o chat, os Agents, os arquivos e o ponto de entrada multimodelo em uma pilha de serviços que você controla. O custo também é direto: você é responsável pelo banco de dados, pelo armazenamento de objetos, pelo login e pelas atualizações. Para uso pessoal, começar com 2 núcleos e 4 GB está tudo bem; para uso formal em equipe, conclua primeiro as restrições de cadastro, o backup e a restauração, e a reversão de atualizações, e só depois convide outras pessoas.