Configurar o qBittorrent WebUI em uma VPS (2026): Docker, HTTPS, diretórios de download e configuração de segurança

O qBittorrent pode ser executado sem ambiente gráfico e gerenciar tarefas pelo navegador, sendo adequado para:

• Distribuição de longo prazo dos seus próprios espelhos de código aberto, conjuntos de dados ou vídeos públicos;
• Download de ISOs Linux, dados públicos e materiais com licença legal;
• Fornecer um nó online estável para distribuição de arquivos grandes dentro de uma equipe;
• Transferência legal de arquivos ponto a ponto entre seus próprios dispositivos;
• Ambientes de teste que precisam de IP público fixo e capacidade de upload contínua.

Os casos inadequados incluem:

• Planos que proíbem explicitamente BitTorrent, P2P ou tráfego elevado sustentado;
• Uma VPS com apenas algumas dezenas de GB de disco de sistema, mas com planos de armazenar grandes quantidades de arquivos;
• Tráfego mensal muito pequeno que gera altas cobranças por excesso ou suspensão direta quando ultrapassado;
• Necessidade de armazenar dados privados, mas com a intenção de expor o WebUI diretamente à internet;
• Supor que uma "porta de 1Gbps" significa que você pode saturá-la a longo prazo sem limite de tráfego.

O qBittorrent em si é gratuito, mas isso não significa que largura de banda, armazenamento, backup e risco de direitos autorais também sejam gratuitos. Antes de comprar uma VPS, leia a Política de Uso Aceitável, o processo de reclamação de direitos autorais, as restrições de portas e as condições de cobrança de tráfego.

O qBittorrent consome poucos recursos em repouso, mas verificar arquivos grandes, conectar-se a muitos peers ao mesmo tempo e gravar em disco em alta velocidade consome significativamente CPU, memória e E/S.

O uso sustentado de 10Mbps durante um mês civil resulta em um volume teórico de transferência de aproximadamente 3.24TB; o uso sustentado de 100Mbps resulta em aproximadamente 32.4TB. O BitTorrent tem tanto download quanto upload, e os provedores podem contar apenas a saída ou contar ambas as direções, então você não pode confiar apenas nas estatísticas de download do qBittorrent.

A escolha do disco é igualmente importante:

• NVMe/SSD é adequado para muitos arquivos pequenos, verificação frequente e várias tarefas simultâneas;
• HDD é barato por capacidade, mas leituras/gravações aleatórias e o upload simultâneo de vários arquivos são mais propensos a esperas de E/S;
• O armazenamento em bloco é usado como um disco local e é adequado como disco de dados independente, mas confirme os preços de IOPS, throughput e snapshots;
• O armazenamento de objetos não tem a semântica de gravação de um sistema de arquivos comum e não é adequado diretamente como diretório de download ativo do qBittorrent;
• A desconexão de um disco de rede pode fazer os arquivos desaparecerem temporariamente, e configurações incorretas de gerenciamento automático podem trazer riscos aos dados.

Após a entrada em produção, recomenda-se usar nosso tutorial de monitoramento de tráfego e alertas de excesso de VPS e também configurar alertas de cobrança do provedor.

Este artigo usa a seguinte estrutura:

浏览器 -> HTTPS 443 -> Caddy -> 127.0.0.1:8080 -> qBittorrent WebUI
Peer    -> TCP/UDP 6881 -> Docker -> qBittorrent 下载监听端口

Planejamento de portas:

O WebUI e a porta de peer não são a mesma coisa. O WebUI é apenas para administradores, enquanto a porta de peer é usada para conexões de dados BitTorrent. Abrir 8080 para toda a internet é desnecessário e aumenta o risco de força bruta de senhas e vulnerabilidades web.

Primeiro atualize o Ubuntu:

sudo apt update
sudo apt upgrade -y
sudo apt install -y ca-certificates curl gnupg ufw

Em produção, recomenda-se instalar o Docker Engine e o plugin Compose a partir do repositório oficial do Docker. Após a instalação, verifique:

docker version
docker compose version
sudo systemctl enable --now docker
sudo systemctl status docker --no-pager

Se você ainda não estabeleceu hábitos para verificações de integridade do Compose, rotação de logs, segredos e reversão, pode ler primeiro a lista de verificação de configuração de produção do VPS Docker Compose.

Os comandos deste artigo assumem que o usuário atual pode executar o Docker. Adicionar um usuário ao grupo docker concede controle do host quase como root e não deve ser dado a contas não confiáveis.

Crie o diretório do projeto e um diretório de download independente:

sudo install -d -m 750 /opt/qbittorrent
sudo install -d -m 750 /srv/qbittorrent/downloads
sudo install -d -m 750 /srv/qbittorrent/downloads/incomplete
sudo install -d -m 750 /srv/qbittorrent/downloads/complete
sudo chown -R "$(id -u):$(id -g)" /opt/qbittorrent /srv/qbittorrent
cd /opt/qbittorrent

Confirme o UID, GID e fuso horário reais:

id -u
id -g
timedatectl show --property=Timezone --value

Crie /opt/qbittorrent/.env e substitua o UID, GID e fuso horário do exemplo pela saída real do comando anterior:

PUID=1000
PGID=1000
TZ=Asia/Shanghai
WEBUI_PORT=8080
TORRENTING_PORT=6881

Proteja o arquivo de ambiente:

chmod 600 /opt/qbittorrent/.env

.env não armazena a senha do WebUI, mas ainda faz parte da configuração da implantação. Não faça commit de todo o diretório do projeto diretamente em um repositório Git público.

Crie /opt/qbittorrent/compose.yaml:

services:
  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      PUID: "${PUID}"
      PGID: "${PGID}"
      TZ: "${TZ}"
      WEBUI_PORT: "${WEBUI_PORT}"
      TORRENTING_PORT: "${TORRENTING_PORT}"
    volumes:
      - ./config:/config
      - /srv/qbittorrent/downloads:/downloads
    ports:
      - "127.0.0.1:${WEBUI_PORT}:${WEBUI_PORT}/tcp"
      - "${TORRENTING_PORT}:${TORRENTING_PORT}/tcp"
      - "${TORRENTING_PORT}:${TORRENTING_PORT}/udp"
    restart: unless-stopped
    stop_grace_period: 30s
    security_opt:
      - no-new-privileges:true
    logging:
      driver: json-file
      options:
        max-size: 10m
        max-file: "3"

Esta configuração tem vários pontos-chave:

1. 8080 é mapeado apenas para o 127.0.0.1 do host, portanto não pode ser acessado diretamente pela internet;
2. 6881 mapeia tanto TCP quanto UDP, e corresponde a TORRENTING_PORT;
3. A configuração e os dados de download ficam em diretórios do host, então excluir o contêiner não exclui os arquivos;
4. São definidos limites de tamanho e quantidade de logs do Docker para evitar crescimento ilimitado;
5. no-new-privileges impede que processos do contêiner obtenham novos privilégios por meio de mecanismos como setuid.

A documentação oficial da imagem LinuxServer enfatiza especialmente: ao alterar a porta do WebUI, você deve alterar tanto o mapeamento de portas quanto WEBUI_PORT; ao alterar a porta de peer, também deve alterar os mapeamentos TCP e UDP e TORRENTING_PORT. Alterar apenas um lugar causará problemas no WebUI, na verificação CSRF ou nas conexões de entrada.

Primeiro valide o Compose:

cd /opt/qbittorrent
docker compose config
docker compose pull
docker compose up -d
docker compose ps

Na primeira inicialização, a imagem atual do LinuxServer exibe nos logs do contêiner uma senha temporária para o usuário admin:

docker compose logs --tail=200 qbittorrent

Você também pode filtrar apenas os logs relevantes:

docker compose logs qbittorrent | grep -i -E 'password|webui'

A partir do qBittorrent 4.6.1, você não deve mais copiar a senha padrão fixa adminadmin de tutoriais antigos. A senha temporária aparece nos logs de inicialização; após fazer login, você deve alterar imediatamente o nome de usuário e definir uma senha aleatória forte, caso contrário o contêiner pode gerar uma nova senha temporária após reiniciar.

Neste ponto, teste na própria VPS:

curl -I http://127.0.0.1:8080
docker compose logs --tail=100 qbittorrent

Uma resposta HTTP indica que o WebUI foi iniciado. Como a porta escuta apenas no endereço de loopback, acessar http://VPS-IP:8080 diretamente do seu computador pessoal deve falhar; este é o resultado de segurança esperado.

No seu próprio computador, execute:

ssh -L 8080:127.0.0.1:8080 [email protected]

203.0.113.10 é um endereço de exemplo da documentação; substitua pelo IP real da VPS. Mantenha a sessão SSH aberta e então acesse no navegador:

http://127.0.0.1:8080

Após fazer login com a senha temporária dos logs, entre nas configurações do WebUI e conclua:

• Alterar o nome de usuário e a senha de administrador padrão;
• Manter ativadas a proteção CSRF e contra clickjacking;
• Não habilitar "ignorar autenticação para rede local" nem a dispensa de autenticação para sub-redes amplas;
• Definir o caminho de salvamento padrão como /downloads/complete;
• Definir o caminho de tarefas incompletas como /downloads/incomplete;
• Confirmar que a porta de escuta é 6881 e desativar a porta de inicialização aleatória;
• Definir velocidades globais de upload e download e números de tarefas simultâneas razoáveis;
• Salvar e sair, e então fazer login novamente com a nova conta.

Em agosto de 2026, a versão estável atual do qBittorrent é 5.2.1. As versões continuarão sendo atualizadas; antes de implantar, consulte a página oficial de releases do qBittorrent e a página oficial de notícias, e não confie apenas no número de versão antigo do cache da imagem.

Primeiro aponte o registro A/AAAA de downloads.example.com para a VPS. Este domínio é apenas um exemplo e deve ser substituído pelo seu próprio domínio.

Adicione ao Caddyfile:

downloads.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:8080
}

Valide e recarregue:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
sudo systemctl status caddy --no-pager
sudo journalctl -u caddy -n 100 --no-pager

Abra HTTP e HTTPS:

sudo ufw allow 80/tcp comment 'Caddy HTTP'
sudo ufw allow 443/tcp comment 'Caddy HTTPS'

Para o processo completo de instalação do Caddy, DNS, certificados automáticos e logs, consulte o guia completo de Caddy como proxy reverso em VPS.

Após fazer login no WebUI do qBittorrent, defina a lista de domínios permitidos do WebUI para o domínio real e ative cookies seguros. Não desative a Validação de Host Header apenas para lidar com Unauthorized ou erros de Host header; em vez disso, verifique se o domínio, o Host header do proxy reverso e a configuração de porta estão consistentes.

O HTTPS protege apenas a conexão de gerenciamento do navegador até a VPS; o tráfego de peers continua funcionando conforme o protocolo BitTorrent. Não faça proxy de 6881/TCP/UDP no Caddy ou Cloudflare; um proxy reverso web comum não pode substituir a porta de escuta de peers.

Primeiro confirme que o SSH não ficará bloqueado:

sudo ufw allow OpenSSH
sudo ufw allow 6881/tcp comment 'qBittorrent peer TCP'
sudo ufw allow 6881/udp comment 'qBittorrent peer UDP'
sudo ufw enable
sudo ufw status numbered

O grupo de segurança da plataforma de nuvem também deve permitir a mesma porta de peer TCP/UDP. Não adicione uma regra pública para 8080/tcp.

Verifique a escuta do host:

sudo ss -lntup | grep -E ':8080|:6881'
docker compose ps

Os resultados esperados são:

• 8080 aparece apenas em 127.0.0.1;
• 6881 tem mapeamentos tanto TCP quanto UDP;
• O Caddy escuta no 80/443 público;
• A porta de escuta nas configurações do WebUI corresponde ao Compose.

Com a porta de peer de entrada aberta, o qBittorrent tem mais chances de se tornar um nó ativo e aceitar conexões, mas a velocidade ainda depende da disponibilidade de recursos, do número de peers, da rota, do disco e da política de limites de velocidade. Uma porta aberta não significa que qualquer tarefa atingirá a velocidade máxima.

No WebUI, use caminhos do contêiner:

/downloads/incomplete
/downloads/complete

Não insira o caminho /srv/qbittorrent/... do host, porque dentro do contêiner apenas o /downloads montado é visível.

Verifique as permissões:

cd /opt/qbittorrent
docker compose exec qbittorrent id
stat -c '%u:%g %a %n' config /srv/qbittorrent/downloads
touch /srv/qbittorrent/downloads/.write-test
rm /srv/qbittorrent/downloads/.write-test

Se Permission denied aparecer nos logs do contêiner, primeiro compare o UID/GID do contêiner, o PUID/PGID em .env e o proprietário do diretório do host; não use chmod -R 777 diretamente.

Mantenha pelo menos 10%–20% de espaço livre e defina limites de monitoramento:

df -h /srv/qbittorrent/downloads
df -i /srv/qbittorrent/downloads
du -xhd1 /srv/qbittorrent/downloads | sort -h

Tarefas incompletas podem ocupar tanto espaço pré-alocado quanto arquivos temporários. As regras de exclusão automática também devem ser usadas com cuidado: excluir uma tarefa do qBittorrent e excluir arquivos do disco são duas ações diferentes, então leia bem as opções antes de confirmar.

Não deixe o qBittorrent saturar a porta da VPS a longo prazo. Saturar o upload aumenta a latência interativa e pode acionar a limitação por uso justo do provedor.

Você pode começar com a seguinte configuração conservadora e ajustar conforme o monitoramento:

Estes são pontos de partida para solução de problemas, não valores ótimos universais. A configuração razoável varia muito entre recursos públicos populares, trackers privados, discos mecânicos, NVMe e rotas diferentes.

Ao limitar a velocidade, preste atenção às unidades: o qBittorrent costuma exibir em KiB/s, enquanto os planos de VPS costumam usar Mbps. A conversão aproximada é:

10 Mbps ≈ 1.19 MiB/s
100 Mbps ≈ 11.92 MiB/s

O limite de upload não deve ser tão baixo que mal permita enviar dados de protocolo, caso contrário o desempenho de download também pode ser afetado. Após o ajuste, observe pelo menos um ciclo completo de negócio, não apenas alguns minutos de pico.

A tag latest facilita acompanhar as versões estáveis, mas antes de atualizar você ainda deve ler as notas de alteração, fazer backup da configuração e registrar o digest atual da imagem:

cd /opt/qbittorrent
docker compose images
docker image inspect lscr.io/linuxserver/qbittorrent:latest \
  --format '{{index .RepoDigests 0}}'
docker compose logs --tail=100 qbittorrent

Faça backup da configuração e depois atualize:

backup_stamp=$(date +%Y%m%d-%H%M%S)
docker compose stop qbittorrent
sudo tar -C /opt/qbittorrent -czf \
  "/root/qbittorrent-config-${backup_stamp}.tar.gz" \
  config compose.yaml .env
docker compose start qbittorrent

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200 qbittorrent

Após atualizar, verifique o login no WebUI, a lista de tarefas, os diretórios de download, as portas de escuta e as conexões de peers reais. Não force o encerramento do contêiner enquanto as tarefas estiverem gravando muito no disco.

Se a nova imagem apresentar problemas, você pode fixar temporariamente a imagem usando o digest registrado antes da atualização, restaurar o backup da configuração e recriar o contêiner. A reversão da imagem e a reversão da configuração de dados são duas coisas diferentes: apenas trocar para a imagem antiga pode não ler a configuração já migrada pela nova versão, portanto o backup deve ser feito antes da atualização.

Priorize o backup de /opt/qbittorrent/config, que normalmente contém configurações, estado das tarefas, categorias, tags e dados de fastresume. Se fazer backup dos arquivos baixados depende de eles poderem ser obtidos novamente e de você ter o direito de armazená-los e distribuí-los.

Camadas sugeridas:

• Diretório de configuração: backup diário, manter várias versões;
• Arquivos criados por você ou insubstituíveis: use backups independentes, não trate a cópia de semeadura como único backup;
• Imagens públicas que podem ser obtidas novamente: você pode manter apenas o estado das tarefas e as informações de verificação;
• Diretórios de download grandes: calcule primeiro o armazenamento de backup e os custos de saída antes de decidir a estratégia.

Após o backup, você deve fazer um simulado de restauração. Você pode consultar o tutorial de simulado de backup e restauração de VPS, mas não envie para armazenamento público pacotes de configuração que contenham credenciais de trackers privados ou histórico de downloads.

• Os termos de serviço da VPS permitem uso legal de BitTorrent/P2P;
• Apenas conteúdo que você tem o direito de baixar, armazenar e distribuir é tratado;
• O 8080 do WebUI está vinculado apenas a 127.0.0.1;
• A entrada de gerenciamento pública usa HTTPS de domínio;
• A senha temporária foi substituída e uma senha forte independente é usada;
• CSRF, clickjacking e Validação de Host Header permanecem ativados;
• Nenhuma sub-rede ampla de dispensa de autenticação foi configurada;
• A porta de peer abre tanto TCP quanto UDP, e a porta do WebUI não está aberta;
• PUID, PGID e as permissões do diretório de download estão consistentes, e 777 não é usado;
• Os logs do Docker têm rotação configurada, e tanto o disco quanto os inodes têm alertas;
• A velocidade de upload, as tarefas simultâneas e o número de conexões não saturam o servidor a longo prazo;
• O diretório de configuração foi copiado e a restauração foi realmente testada;
• O digest da imagem é registrado antes da atualização e as Notas de Versão oficiais são consultadas;
• Endereços de trackers privados, cookies, histórico de downloads e backups de configuração não vazaram.

• Site e notícias oficiais do qBittorrent
• qBittorrent GitHub Releases
• Instruções de recuperação de senha do WebUI do qBittorrent
• Documentação do contêiner LinuxServer qBittorrent