> For the complete documentation index, see [llms.txt](https://docs.ipcheck.ing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipcheck.ing/developer/pt-br/getting-started/maxmind-setup.md). # Configuração do MaxMind (Obrigatório) Configure os bancos de dados GeoLite2 do MaxMind necessários para geolocalização de IP e consultas de ASN. MyIP lê dois bancos de dados gratuitos da MaxMind — **GeoLite2** — `GeoLite2-City.mmdb` e `GeoLite2-ASN.mmdb` — para geolocalização local/offline de IP e consultas ASN. Eles estão **não** no repositório e **não** na imagem Docker. A licença GeoLite2 da MaxMind não permite redistribuição, então cada implantação precisa trazer sua própria cópia. ## O que quebra sem eles O servidor ainda inicia. Mas: * `/api/maxmind` retorna **503** em cada requisição, então a fonte de IP da MaxMind não produz nada. * Os recursos construídos nessa fonte — incluindo os selos de país exibidos para candidatos ICE do WebRTC — ficam vazios. * Cada inicialização registra `❌ A API do MaxMind retornará 503 até que os bancos de dados sejam carregados com sucesso`. Outras fontes de IP continuam funcionando, então o app parece parcialmente quebrado em vez de completamente quebrado. É exatamente por isso que esta página é leitura obrigatória. ## Obter credenciais {% stepper %} {% step %} #### Crie uma conta GeoLite2 gratuita Cadastre-se em [maxmind.com/en/geolite2/signup](https://www.maxmind.com/en/geolite2/signup). Nenhum dado de pagamento é necessário. {% endstep %} {% step %} #### Anote o ID da sua conta A MaxMind mostra isso no painel da sua conta. É um número, não seu endereço de e-mail. {% endstep %} {% step %} #### Gere uma chave de licença Abra **Gerenciar chaves de licença** e crie uma nova chave. Copie-a imediatamente — a MaxMind a mostra apenas uma vez. {% endstep %} {% endstepper %} ## Opção A — Download automático (recomendado) Defina três variáveis e deixe o MyIP buscar e atualizar os bancos de dados por conta própria. {% code title=".env" %} ```bash MAXMIND_ACCOUNT_ID="your-account-id" MAXMIND_LICENSE_KEY="your-license-key" MAXMIND_AUTO_UPDATE="true" ``` {% endcode %} No Docker, passe os mesmos três com `-e` — veja [Implantar com Docker](/developer/pt-br/getting-started/deploy-with-docker.md). O que acontece então: | Quando | O que acontece | | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Na inicialização, arquivos ausentes | O backend baixa os dois bancos de dados **antes de começar a escutar**, limitado a 5 minutos. Isso é executado sempre que as credenciais estão presentes, mesmo se `MAXMIND_AUTO_UPDATE` é `"false"`. | | Na inicialização, arquivos presentes | Nada é baixado; os arquivos existentes são carregados imediatamente. | | \~60 segundos após a inicialização | O atualizador executa sua primeira verificação agendada. | | A cada 24 horas depois disso | Ele verifica novamente e baixa apenas o que a MaxMind realmente atualizou. | {% hint style="success" %} **As atualizações são seguras por construção.** Os novos arquivos são baixados para um diretório temporário, abertos e validados, e então publicados atomicamente com um `.bak` de fallback. Depois disso, um observador de arquivos recarrega os leitores em memória, então uma atualização do banco de dados nunca reinicia o servidor e nunca serve um arquivo parcialmente gravado. Um arquivo de bloqueio impede que dois processos (por exemplo, duas instâncias do pm2) atualizem ao mesmo tempo. {% endhint %} {% hint style="warning" %} **Quem faz deploy no Docker deve usar a Opção A.** Um contêiner novo não tem `.mmdb` nenhum arquivo, e não há nada para copiá-los para lá, a menos que você construa sua própria imagem. {% endhint %} ## Opção B — Posicionamento manual Para hosts isolados da rede, ou se você preferir não dar ao app acesso de saída à MaxMind. Isso só funciona quando você [faz deploy a partir do código-fonte](/developer/pt-br/getting-started/deploy-with-nodejs.md). {% stepper %} {% step %} #### Baixe os bancos de dados Da sua conta MaxMind, baixe os **GeoLite2 City** e **GeoLite2 ASN** arquivos em `.mmdb` formato (binário) e extraia-os. {% endstep %} {% step %} #### Coloque-os no lugar Copie ambos os arquivos para `common/maxmind-db/`mantendo exatamente estes nomes: ``` common/maxmind-db/GeoLite2-City.mmdb common/maxmind-db/GeoLite2-ASN.mmdb ``` {% endstep %} {% step %} #### Deixe a atualização automática desativada ```bash MAXMIND_AUTO_UPDATE="false" ``` Depois, inicie o backend. Ele encontra os arquivos e os carrega. {% endstep %} {% endstepper %} {% hint style="info" %} Com a Opção B, você atualiza os arquivos manualmente conforme a MaxMind publica novas versões. Você não precisa reiniciar o servidor depois de substituí-los — o observador de arquivos detecta a mudança e recarrega os leitores em alguns segundos. {% endhint %} ## Verificação Uma inicialização saudável registra: ``` 📦 Bancos de dados MaxMind carregados (inicialização) ``` Com a atualização automática ativada, você também recebe o cronograma: ``` 🗓️ Plano de atualização automática da MaxMind: próxima verificação em ..., depois a cada 24 horas ``` ## Solução de problemas
❌ A API do MaxMind retornará 503 até que os bancos de dados sejam carregados com sucesso O backend não conseguiu abrir ambos os `.mmdb` arquivos. Role para cima no log — sempre há uma linha mais específica acima desta dizendo o motivo. Causas comuns: * As credenciais estão ausentes, então nada foi baixado. * O download falhou (veja as entradas abaixo). * Apenas um dos dois arquivos está presente. O MyIP precisa de **ambos** City e ASN.
⚠️ Os bancos de dados da MaxMind estão ausentes e MAXMIND_ACCOUNT_ID / MAXMIND_LICENSE_KEY não estão configurados As variáveis nunca chegaram ao processo. Verifique se: * Seu `.env` fica na raiz do projeto e você reiniciou depois de editá-lo. * No Docker, as `-e` flags estão no `docker run` comando (ou no `environment:` bloco) — não no `docker exec`. * Os nomes das variáveis estão escritos exatamente como acima.
Falha ao verificar GeoLite2-City: HTTP 401 A MaxMind rejeitou as credenciais. O ID da conta e a chave de licença são usados como autenticação HTTP Basic contra `download.maxmind.com`, então um 401 significa que um deles está incorreto. * Confirme que o ID da conta é o ID numérico, não seu e-mail. * Gere novamente a chave de licença — as chaves podem ser revogadas, e um copiar/colar que tenha perdido um caractere parece idêntico a uma chave válida. * Certifique-se de que a chave foi criada para **GeoLite2**, na mesma conta.
Falha no download inicial da MaxMind: o download não foi concluído dentro de 5 min O download na inicialização atingiu o limite de tempo. Isso é um problema de rede, não de credenciais — verifique se o host consegue acessar `download.maxmind.com` (firewall, regras de saída, proxy). O servidor inicia mesmo assim e o atualizador agendado tentará novamente.
Plano de atualização automática da MaxMind: desativado `MAXMIND_AUTO_UPDATE` não é exatamente `"true"`. Somente esse valor literal habilita a atualização periódica. Observe que isso afeta apenas a **atualização a cada 24 horas** . O download na inicialização ainda é executado quando os arquivos estão ausentes e as credenciais estão presentes.
Atualização automática da MaxMind ignorada: MAXMIND_ACCOUNT_ID ou MAXMIND_LICENSE_KEY está ausente A atualização automática foi solicitada, mas uma das duas credenciais está vazia. Ambas são obrigatórias.
Atualização da MaxMind ignorada: outro processo está atualizando os bancos de dados Esperado quando você executa várias instâncias do backend — uma mantém o bloqueio de atualização, as outras saem da frente. Sem problema. Se você o vir em todas as tentativas, provavelmente uma execução anterior travou e deixou o bloqueio para trás. Ele é limpo automaticamente quando completa 2 horas; para limpá-lo agora, exclua `.maxmind-update.lock` de `common/maxmind-db/`.
## Próximos passos * [Implantar com Docker](/developer/pt-br/getting-started/deploy-with-docker.md) — onde os bancos de dados ficam dentro do contêiner * [Chaves de API opcionais](/developer/pt-br/configuration/optional-api-keys.md) — fontes adicionais de dados de IP além da MaxMind * [Fontes de dados de IP](/developer/pt-br/architecture/ip-data-sources.md) — como o MyIP combina suas fontes --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.ipcheck.ing/developer/pt-br/getting-started/maxmind-setup.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.