> For the complete documentation index, see [llms.txt](https://docs.iexexchanger.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iexexchanger.com/learn/2.-nastroiki/04-geoip.md).

# GeoIP

Настройте локальные и внешние GeoIP-провайдеры, приоритет, кэш, обновления и диагностику

## Что вы получите

Система определяет страну и город по публичному IP через доступные провайдеры, быстро отвечает из кэша и продолжает работу при временном отказе одного источника. Секреты внешних сервисов сохранены отдельно, а результат подтверждён тестовым запросом и диагностикой.

Откройте **«Настройки» — «Общие настройки» — «Дополнительно» — «GeoIP»**. Для страницы требуется отдельное право на настройки GeoIP.

## Сначала выберите источники

| Провайдер        | Тип             | Что подготовить                                  |
| ---------------- | --------------- | ------------------------------------------------ |
| MaxMind GeoLite2 | База на сервере | Account ID, лицензионный ключ и загруженная база |
| DB-IP Lite       | База на сервере | Загруженная база и видимая атрибуция на сайте    |
| IPLocate.io      | Внешний API     | API-ключ и допустимый лимит запросов             |
| IP2Location.io   | Внешний API     | API-ключ и допустимый лимит запросов             |

Начните хотя бы с одного готового локального источника. Внешний API добавляйте как осознанный резерв или источник дополнительных данных после проверки условий провайдера, приватности, лимитов и стоимости.

{% hint style="warning" %}
Не включайте DB-IP Lite до размещения на публичном сайте видимой ссылки **«IP Geolocation by DB-IP»** и подтверждения атрибуции в панели. Не отмечайте условие выполненным, если ссылка существует только в черновике страницы.
{% endhint %}

## Настройте вкладку «Основное»

Для обычного рабочего режима:

* включите **«Определять страну и город по IP»**;
* оставьте включёнными кэширование, проверку и дополнение данных и ускорение списков IP;
* оставьте **«Временно не обращаться к провайдерам»** выключенным;
* выберите **«Продолжить и записать ошибку в журнал»**, если местоположение не найдено;
* используйте **«Учитывать доверенные прокси»**, если инфраструктура настроена штатно;
* пропускайте частные и зарезервированные IP;
* не включайте подробный режим постоянно без задачи диагностики.

Язык названий стран и городов берётся из основной настройки клиентского сайта. Отдельный язык GeoIP выбирать не нужно.

{% hint style="danger" %}
Режим **«Остановить операцию с ошибкой»** способен превратить отказ GeoIP в отказ клиентского процесса. Не используйте его как стартовое значение без отдельного требования риска и проверенного резервного провайдера.
{% endhint %}

## Подключите провайдеры

{% stepper %}
{% step %}

### Проверьте готовность локальных баз

Откройте вкладку **«Провайдеры»**. Для MaxMind и DB-IP панель сама показывает **«База доступна»** или **«База не установлена»**. Не включайте отсутствующую базу как будто она готова.
{% endstep %}

{% step %}

### Сохраните данные MaxMind

Нажмите **«Настроить доступ»**, укажите Account ID и лицензионный ключ. После сохранения секрет полностью не отображается. Затем загрузите базы на вкладке **«Обновления»** или подтвердите уже найденные файлы.
{% endstep %}

{% step %}

### Подтвердите DB-IP только после атрибуции

Убедитесь, что публичная ссылка видна посетителю, включите подтверждение атрибуции и только затем разрешите провайдер.
{% endstep %}

{% step %}

### Добавьте внешний API при необходимости

Для IPLocate.io или IP2Location.io сохраните ключ через отдельный диалог. Пустое поле при следующем открытии означает, что секрет скрыт, а не обязательно удалён; ориентируйтесь на признак **«Данные сохранены»**.
{% endstep %}

{% step %}

### Выполните тест каждого включённого источника

Укажите принадлежащий вам публичный IP, выберите полную геолокацию, страну или ASN и нажмите **«Проверить»**. Тест внешнего API расходует запрос из лимита провайдера.
{% endstep %}
{% endstepper %}

## Задайте стратегию

На вкладке **«Стратегия»** выберите **«Сначала установленные базы»**, включите **«Переключение провайдеров»** и перетащите источники в утверждённом порядке.

**«Объединять результаты»** обращается к следующим источникам, когда первому ответу не хватает полей. На старте оставьте объединение выключенным, если полный состав данных не нужен: оно увеличивает число запросов и усложняет разбор источника результата.

```mermaid
flowchart LR
    A["Публичный IP"] --> B["Первый готовый провайдер"]
    B -->|"Ответ найден"| C["Кеш и результат"]
    B -->|"Ошибка или пусто"| D["Следующий провайдер"]
    D --> C
```

## Не меняйте кэш без причины

На вкладке **«Кеш»** обычно достаточно:

* хранить результаты только для публичных IP;
* использовать основное хранилище приложения;
* оставить служебный префикс, сроки хранения, блокировку и лимит быстрого кэша по умолчанию;
* держать дополнительное быстрое кэширование включённым.

Очистка кэша GeoIP не очищает остальные разделы. Используйте её после смены провайдера, обновления базы или доказанного устаревшего результата, а не как регулярное действие.

## Оставьте защиту от сбоев

На вкладке **«Отказоустойчивость»** включённая автоматическая пауза временно пропускает источник после серии ошибок. Оставьте порог, окно, время паузы, таймауты, повторы и ограничение одинаковых предупреждений по умолчанию, если специалист не измерил другую потребность.

Кнопка **«Снять временную паузу»** не исправляет провайдера. Сначала устраните ошибку базы, ключа или сети, затем выполните тест и только после этого сбросьте защитное состояние.

## Настройте обновление локальных баз

{% tabs %}
{% tab title="Вручную" %}
На вкладке **«Обновления»** выберите готовый локальный источник и нажмите **«Обновить сейчас»**. MaxMind требует сохранённых данных доступа, DB-IP — подтверждённой атрибуции.
{% endtab %}

{% tab title="По расписанию" %}
Включите автообновление, выберите MaxMind и/или DB-IP, интервал в днях и час UTC. Убедитесь, что планировщик работает и выбранное окно не конфликтует с обслуживанием сервера.
{% endtab %}
{% endtabs %}

Система скачивает локальные базы с предусмотренных источников, проверяет новый файл и заменяет его без ручного редактирования путей. После обновления проверьте дату успеха и повторите тест.

## Завершите диагностикой

1. Откройте вкладку **«Диагностика»**.
2. Убедитесь, что хотя бы один включённый провайдер доступен.
3. Проверьте последнюю успешную работу, задержку и отсутствие необъяснённой временной паузы.
4. Сверьте состояние кэша и историю обновления локальных баз.
5. Выполните тест по собственному публичному IP.
6. Создайте новую контрольную клиентскую сессию и проверьте места панели, где проект использует географию посетителя.

GeoIP является вспомогательным сигналом и не доказывает личность, резидентство или право клиента на операцию. Юридические и риск-решения не должны основываться только на определённой стране IP.

## Этап завершён, если

* [ ] страницу открывает только роль с нужным правом;
* [ ] готов хотя бы один включённый провайдер;
* [ ] секреты сохранены через отдельные защищённые поля;
* [ ] DB-IP включён только после публичной атрибуции;
* [ ] локальные источники стоят раньше внешних либо другой порядок обоснован;
* [ ] переключение провайдеров и автоматическая пауза при сбоях включены;
* [ ] частные и зарезервированные IP не отправляются провайдерам;
* [ ] тест выполнен по разрешённому публичному IP;
* [ ] расписание обновления подтверждено либо назначено ручное обновление;
* [ ] диагностика показывает готовый источник и понятное состояние кэша.

Условия поставщиков сверяйте по их актуальным материалам: [обновление баз MaxMind](https://dev.maxmind.com/geoip/updating-databases/), [лицензия и атрибуция DB-IP Lite](https://db-ip.com/db/lite.php), [аутентификация IPLocate.io](https://www.iplocate.io/docs/getting-started/authentication) и [API IP2Location.io](https://www.ip2location.io/ip2location-documentation).

После GeoIP переходите к [кодам валют](https://docs.iexexchanger.com/learn/3.-valyuty-i-dengi/01-currency-codes.md).
