> 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/ru/getting-started/maxmind-setup.md). # Настройка MaxMind (обязательно) MyIP использует две бесплатные **GeoLite2** базы данных от MaxMind — `GeoLite2-City.mmdb` и `GeoLite2-ASN.mmdb` — для локального, автономного определения геолокации IP и поиска ASN. Они **не** в репозитории и **не** в Docker-образе. Лицензия GeoLite2 от MaxMind не разрешает распространение, поэтому каждое развёртывание должно иметь свою копию. ## Что ломается без них Сервер всё равно запускается. Но: * `/api/maxmind` возвращает **503** в каждом запросе, поэтому источник IP MaxMind ничего не выдаёт. * Функции, построенные на этом источнике, — включая значки стран, показываемые для кандидатов WebRTC ICE, — остаются пустыми. * При каждом запуске в логах появляется `❌ MaxMind API будет возвращать 503, пока базы данных не будут успешно загружены`. Другие источники IP продолжают работать, поэтому приложение выглядит наполовину сломанным, а не полностью сломанным. Именно поэтому эту страницу обязательно нужно прочитать. ## Получите учётные данные {% stepper %} {% step %} #### Создайте бесплатную учётную запись GeoLite2 Зарегистрируйтесь на [maxmind.com/en/geolite2/signup](https://www.maxmind.com/en/geolite2/signup). Платёжные данные не требуются. {% endstep %} {% step %} #### Запишите идентификатор своей учётной записи MaxMind показывает его в панели управления вашей учётной записью. Это число, а не ваш адрес электронной почты. {% endstep %} {% step %} #### Сгенерируйте лицензионный ключ Откройте **Управление лицензионными ключами** и создайте новый ключ. Скопируйте его сразу — MaxMind показывает его только один раз. {% endstep %} {% endstepper %} ## Вариант A — автоматическая загрузка (рекомендуется) Установите три переменные и позвольте MyIP самостоятельно загружать и обновлять базы данных. {% code title=".env" %} ```bash MAXMIND_ACCOUNT_ID="your-account-id" MAXMIND_LICENSE_KEY="your-license-key" MAXMIND_AUTO_UPDATE="true" ``` {% endcode %} В Docker передайте те же три с `-e` — см. [Развёртывание с Docker](/developer/ru/getting-started/deploy-with-docker.md). Что происходит дальше: | Когда | Что происходит | | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | При запуске, файлы отсутствуют | Бэкенд загружает обе базы данных **до начала прослушивания**, максимум 5 минут. Это выполняется всякий раз, когда учётные данные присутствуют, даже если `MAXMIND_AUTO_UPDATE` равно `"false"`. | | При запуске, файлы присутствуют | Ничего не загружается; существующие файлы подгружаются сразу. | | Примерно через 60 секунд после запуска | Обновлятор выполняет первую запланированную проверку. | | После этого каждые 24 часа | Он проверяет снова и загружает только то, что MaxMind действительно обновил. | {% hint style="success" %} **Обновления изначально безопасны.** Новые файлы загружаются во временный каталог, открываются и проверяются, а затем атомарно публикуются с `.bak` резервным вариантом. Наблюдатель за файлами затем перезагружает читатели в памяти, поэтому обновление базы данных никогда не перезапускает сервер и никогда не отдаёт наполовину записанный файл. Файл блокировки не позволяет двум процессам (например, двум экземплярам pm2) обновляться одновременно. {% endhint %} {% hint style="warning" %} **Те, кто развёртывает через Docker, должны использовать вариант A.** Новый контейнер не имеет `.mmdb` файлов вообще, и копировать их некуда, если только вы не собираете собственный образ. {% endhint %} ## Вариант B — ручное размещение Для изолированных хостов или если вы не хотите давать приложению исходящий доступ к MaxMind. Это работает только если вы [развёртываете из исходников](/developer/ru/getting-started/deploy-with-nodejs.md). {% stepper %} {% step %} #### Скачайте базы данных Из своей учётной записи MaxMind скачайте **GeoLite2 City** и **GeoLite2 ASN** архивы в `.mmdb` (двоичном) формате и распакуйте их. {% endstep %} {% step %} #### Разместите их Скопируйте оба файла в `common/maxmind-db/`, сохранив их точные имена: ``` common/maxmind-db/GeoLite2-City.mmdb common/maxmind-db/GeoLite2-ASN.mmdb ``` {% endstep %} {% step %} #### Оставьте автообновление выключенным ```bash MAXMIND_AUTO_UPDATE="false" ``` Затем запустите бэкенд. Он найдёт файлы и загрузит их. {% endstep %} {% endstepper %} {% hint style="info" %} При варианте B вы обновляете файлы сами по мере выхода новых релизов MaxMind. После замены перезапускать сервер не нужно — наблюдатель за файлами замечает изменение и перезагружает читатели через несколько секунд. {% endhint %} ## Проверка При успешном запуске в журнале появляется: ``` 📦 Базы данных MaxMind загружены (запуск) ``` При включённом автообновлении вы также увидите расписание: ``` 🗓️ План автообновления MaxMind: следующая проверка в ..., затем каждые 24 часа ``` ## Устранение неполадок
❌ MaxMind API будет возвращать 503, пока базы данных не будут успешно загружены Бэкенд не смог открыть обе `.mmdb` файла. Прокрутите журнал вверх — выше всегда есть более конкретная строка, объясняющая причину. Частые причины: * Учётные данные отсутствуют, поэтому ничего так и не было загружено. * Загрузка не удалась (см. записи ниже). * Присутствует только один из двух файлов. MyIP нужны **оба** City и ASN.
⚠️ Базы данных MaxMind отсутствуют, а MAXMIND_ACCOUNT_ID / MAXMIND_LICENSE_KEY не настроены Переменные так и не дошли до процесса. Проверьте, что: * Ваш `.env` находится в корне проекта, и вы перезапустили приложение после его редактирования. * В Docker `-e` флаги указаны в `docker run` команде (или в `environment:` блоке) — а не в `docker exec`. * Имена переменных должны быть написаны точно так же, как указано выше.
Не удалось проверить GeoLite2-City: HTTP 401 MaxMind отклонил учётные данные. Идентификатор учётной записи и лицензионный ключ используются как HTTP Basic auth для `download.maxmind.com`, поэтому 401 означает, что один из них неверен. * Убедитесь, что идентификатор учётной записи — это числовой ID, а не ваш email. * Сгенерируйте лицензионный ключ заново — ключи могут быть отозваны, а вставка с потерянным символом выглядит точно так же, как действительный ключ. * Убедитесь, что ключ был создан для **GeoLite2**, в рамках той же учётной записи.
Первоначальная загрузка MaxMind не удалась: загрузка не завершилась в течение 5 минут Начальная загрузка упёрлась в ограничение по времени. Это проблема сети, а не учётных данных — проверьте, что хост может достичь `download.maxmind.com` (брандмауэр, правила исходящего трафика, прокси). Сервер всё равно запускается, а запланированный обновлятор попробует ещё раз.
План автообновления MaxMind: отключён `MAXMIND_AUTO_UPDATE` не ровно `"true"`. Только это буквальное значение включает периодическое обновление. Учтите, это влияет только на **24-часовое обновление** . Начальная загрузка всё равно выполняется, когда файлы отсутствуют и учётные данные присутствуют.
Автообновление MaxMind пропущено: отсутствует MAXMIND_ACCOUNT_ID или MAXMIND_LICENSE_KEY Автообновление было запрошено, но один из двух учётных данных пуст. Нужны оба.
Обновление MaxMind пропущено: другой процесс обновляет базы данных Ожидаемо, когда вы запускаете несколько экземпляров бэкенда — один удерживает блокировку обновления, остальные отходят в сторону. Безопасно. Если вы видите это при каждой попытке, предыдущий запуск, вероятно, аварийно завершился и оставил блокировку. Она автоматически снимается, когда ей исполняется 2 часа; чтобы снять её сейчас, удалите `.maxmind-update.lock` из `common/maxmind-db/`.
## Дальнейшие шаги * [Развёртывание с Docker](/developer/ru/getting-started/deploy-with-docker.md) — где базы данных находятся внутри контейнера * [Необязательные API-ключи](/developer/ru/configuration/optional-api-keys.md) — дополнительные источники IP-данных помимо MaxMind * [Источники IP-данных](/developer/ru/architecture/ip-data-sources.md) — как MyIP объединяет свои источники --- # 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/ru/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.