Como fazer self-host do SearXNG em 2026: Search API, limites de requisições e TLS

A maioria das instruções de instalação do SearXNG termina no primeiro carregamento da página. Isso é cedo demais: os engines podem bloquear o IP do servidor ou os formatos podem omitir json para clientes de API. Um teste de produção útil é mais exigente — enviar pesquisas em HTML e JSON, confirmar que vários engines contribuem com resultados e acionar o limitador configurado a partir de um cliente de teste.

O papel do SearXNG é simples: um metasearch engine focado em privacidade e uma search API. O seu limite operacional inclui mais do que o processo web, portanto a dependência, o estado armazenado e a rota pública precisam ser explicitamente identificados antes da chegada de dados reais.

Defina primeiro o que significa sucesso para o SearXNG

Não permita que a imagem do SearXNG escolha acidentalmente a arquitetura de produção. A imagem fornece um processo na porta 8080; o armazenamento, o routing e os requisitos externos ainda precisam de ciclos de vida definidos de forma deliberada. O contrato de rede do SearXNG é Redis ou Valkey quando as funcionalidades de limitação e deteção de bots estão ativadas. Mantenha os endpoints privados no DNS interno, permita apenas as chamadas de saída necessárias e forneça ao SearXNG uma credencial de serviço com escopo limitado.

A implementação está pronta para testes mais aprofundados quando consegue enviar pesquisas em HTML e JSON, confirmar que vários engines contribuem com resultados e acionar o limitador configurado a partir de um cliente de teste. Acompanhe a transação nos logs e observe a latência dos engines upstream, as queries simultâneas, o parsing dos resultados e os bloqueios aplicados ao IP do servidor. Essas observações mostram se a topologia atual isola o componente correto.

Separe os containers substituíveis dos dados duradouros

Crie um recovery manifest para o SearXNG: settings.yml, a configuração do limitador e quaisquer plugins locais. Monte /etc/searxng antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para provar que esse caminho é realmente persistente. Verifique agora as permissões e o espaço livre, porque um caminho montado, mas sem permissão de escrita, comporta-se exatamente como se não houvesse persistência.

Faça o backup para um failure domain separado do servidor em execução. Recrie o SearXNG a partir da imagem fixada e verifique se os engines personalizados, os formatos, as regras do limitador e as configurações de proxy são recuperados, e se uma query conhecida produz resultados de vários engines. O guia de volumes persistentes ajuda a transformar esse exercício numa política de snapshots e retenção.

Feche o acesso temporário de configuração

As credenciais de bootstrap são temporárias; o trust model é permanente. No SearXNG, tenha atenção para não enviar o secret_key de exemplo incluído na imagem nem desativar os controlos de rate em um endpoint público. Mantenha uma secret key não padrão, ative os controlos contra abuso e exponha JSON apenas quando um agent ou uma aplicação precisar disso.

Trate SEARXNG_SECRET de acordo com o seu papel no SearXNG: mantenha os valores sensíveis fora do Git, documente os efeitos da rotação e nunca substitua um exemplo público em produção. Execute a imagem sem capabilities Linux desnecessárias e exponha apenas a rota pública da aplicação. Mantenha a atividade administrativa visível sem registar valores secretos.

Registe uma implementação do SearXNG validada

Transforme o smoke test do SearXNG num comando de release repetível ou num runbook curto. O resultado deve demonstrar o seguinte: enviar pesquisas em HTML e JSON, confirmar que vários engines contribuem com resultados e acionar o limitador configurado a partir de um cliente de teste. Registe com o resultado a versão da aplicação, o digest do container, o hostname da rota e o identificador dos dados de teste.

Execute a mesma verificação depois de uma substituição rotineira do container e após restaurar settings.yml, a configuração do limitador e quaisquer plugins locais em outro local. A restauração foi bem-sucedida quando os engines personalizados, os formatos, as regras do limitador e as configurações de proxy são recuperados, e uma query conhecida produz resultados de vários engines. Compare o timing e o consumo relacionados com a latência dos engines upstream, as queries simultâneas, o parsing dos resultados e os bloqueios aplicados ao IP do servidor; uma alteração significativa merece investigação, mesmo quando a ação final continua a passar.

Em seguida, exercite uma falha segura: negue temporariamente ao identity de teste o acesso ao Redis ou Valkey quando as funcionalidades de limitação e deteção de bots estiverem ativadas. Confirme que o SearXNG sinaliza a falha e volta ao funcionamento normal sem edições manuais destrutivas. Preserve apenas o trecho de log necessário e com os dados sensíveis removidos. Este gate em quatro partes cobre o arranque, a persistência, a recuperação e o tratamento de falhas.

Execute a primeira instância com características de produção

Use o container como um runtime substituível, não como a fonte da verdade.

docker run -d \
  --name searxng \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v searxng-data:/etc/searxng \
  -e SEARXNG_SECRET=replace-with-a-long-random-value \
  searxng/searxng:latest

Adicione as configurações de conexão revistas para Redis ou Valkey quando as funcionalidades de limitação e deteção de bots estiverem ativadas; use nomes privados para serviços privados. Inspecione o utilizador do container, os caminhos com permissão de escrita e o listener associado antes de o expor. Execute a ação completa — enviar pesquisas em HTML e JSON, confirmar que vários engines contribuem com resultados e acionar o limitador configurado a partir de um cliente de teste — e guarde a referência exata da imagem que produziu o resultado.

Evite que o sucesso do proxy mascare uma falha da aplicação

Exponha um hostname HTTPS para o SearXNG; mantenha a porta 8080 privada. Defina server base_url e os trusted proxy headers para HTTPS. Isso impede que browsers e clientes de API descubram dois endereços concorrentes.

A partir de um cliente limpo, execute a transação validada e inspecione o primeiro request que falhar. Use o guia de domínio personalizado quando houver problemas de DNS ou TLS. Trate “os engines bloqueiam o IP do servidor ou os formatos omitem json para clientes de API” como um diagnóstico separado da aplicação depois de a rota estar comprovada.

Logs que respondem à próxima pergunta

A primeira métrica operacional útil para o SearXNG é saber se consegue enviar pesquisas em HTML e JSON, confirmar que vários engines contribuem com resultados e acionar o limitador configurado a partir de um cliente de teste. Combine-a com sinais de saturação relativos à latência dos engines upstream, às queries simultâneas, ao parsing dos resultados e aos bloqueios aplicados ao IP do servidor. Um probe limitado ao processo não deve chamar dependências dispendiosas nem reiniciar o container porque um upstream está temporariamente indisponível.

Trate os upgrades como alterações de dados, porque a sintaxe das configurações, as definições dos engines e o comportamento do limitador podem mudar. Por isso, faça o deploy das alterações de configuração e de imagem como parte da mesma revisão. Fixe as versões, ensaie com o estado restaurado e mantenha a imagem anterior disponível até que um rollback continue a ser válido. Quando os engines bloquearem o IP do servidor ou os formatos omitirem json para clientes de API, preserve os logs anteriores ao restart; normalmente contêm a mensagem causal.

Ligue o SearXNG ao ciclo de vida da Dockup

A camada de plataforma do SearXNG é composta pela porta 8080, ingress, TLS, configuração de runtime, armazenamento e acessibilidade da dependência. A Dockup pode reproduzir esses elementos na sua própria infraestrutura ou num servidor ligado pelo cliente.

Depois, o operador conclui a camada do produto: definir server base_url e os trusted proxy headers para HTTPS; aplicar esta regra de acesso — manter uma secret key não padrão, ativar os controlos contra abuso e expor JSON apenas quando um agent ou uma aplicação precisar disso; e executar “enviar pesquisas em HTML e JSON, confirmar que vários engines contribuem com resultados e acionar o limitador configurado a partir de um cliente de teste”. Registar esse teste juntamente com a implementação evita confundir o provisionamento automatizado com a prontidão da aplicação.

Perguntas frequentes

Do que o SearXNG precisa para uma implementação de produção?

Encaminhe o container do SearXNG na porta 8080 através de uma única origem HTTPS. O requisito de rede de suporte é Redis ou Valkey quando as funcionalidades de limitação e deteção de bots estão ativadas. Não considere o SearXNG pronto até conseguir enviar pesquisas em HTML e JSON, confirmar que vários engines contribuem com resultados e acionar o limitador configurado a partir de um cliente de teste.

Que dados do SearXNG devem fazer parte de um backup?

Persista /etc/searxng e inclua settings.yml, a configuração do limitador e quaisquer plugins locais no mesmo recovery manifest. Uma restauração limpa do SearXNG só é bem-sucedida quando os engines personalizados, os formatos, as regras do limitador e as configurações de proxy são recuperados, e uma query conhecida produz resultados de vários engines.

O SearXNG precisa de HTTPS por trás de um reverse proxy?

Use HTTPS para a origem pública do SearXNG e mantenha a porta 8080 na rota interna. Aplique corretamente a configuração do SearXNG: defina server base_url e os trusted proxy headers para HTTPS. No SearXNG, o HTTPS protege credenciais ou conteúdos do utilizador durante o trânsito e mantém consistente o comportamento do cliente sensível à origem.

Como deve ser testado um upgrade do SearXNG?

Restaure o estado atual do SearXNG numa implementação isolada, aplique a versão candidata e repita a sua transação de aceitação. Preste especial atenção porque a sintaxe das configurações, as definições dos engines e o comportamento do limitador podem mudar. Por isso, faça o deploy das alterações de configuração e de imagem como parte da mesma revisão. Mantenha a imagem anterior do SearXNG até compreender os limites da migração de dados e do rollback.