> 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/reference/environment-variables.md). # Переменные окружения Это авторитетный список. Каждая переменная ниже где-то читается в коде (`process.env.*` на сервере, `import.meta.env.*` в браузерном бандле). Всё, чего нет в этом списке, игнорируется. Копировать `.env.example` в `.env` для запуска: {% code title="shell" %} ```bash cp .env.example .env ``` {% endcode %} `dotenv` загружает `.env` из корня репозитория в `backend-server.js`, `frontend-server.js`, `common/logger.js`, `sentry-instrument.js`, и `vite.config.js`. ## Сборка против выполнения У MyIP есть два типа переменных, и путать их — самая распространённая ошибка при развёртывании. | Тип | Префикс | Читается | Когда вступает в силу | | ---------------- | ------------ | ------------------------------------------------------------------------------- | ------------------------ | | Время выполнения | без префикса | процессами Node.js (`backend-server.js`, `frontend-server.js`, обработчики API) | При перезапуске процесса | | Во время сборки | `VITE_` | Vite, во время `pnpm run build` | Только после пересборки | `значения VITE_*` встраиваются **в JavaScript-бандл** Vite на этапе сборки. Во время работы приложения в браузере они не читаются из среды. Изменение `значения VITE_*` переменной и перезапуск сервера ничего не даст — нужно пересобрать. {% hint style="warning" %} **Следствие для Docker.** Официальный `jason5ng32/myip:latest` образ запускался `pnpm run build` во время сборки образа без `.env` присутствует (`.env` указан в `.dockerignore`). Передача `-e VITE_CURL_IPV4_DOMAIN=...` этому образу не влияет **на фронтенд-бандл**. Чтобы использовать переменные времени сборки в Docker, нужно собирать собственный образ с этими значениями, присутствующими во время сборки. {% endhint %} ## Все переменные вкратце Нажмите на имя переменной, чтобы перейти к её полному описанию. | Переменная | По умолчанию | Область применения | Обязательно | | ------------------------------------------------------------------------- | -------------- | ------------------- | ----------------------------- | | [MAXMIND\_ACCOUNT\_ID](#maxmind-account-id) | `""` | Время выполнения | Функции MaxMind | | [MAXMIND\_LICENSE\_KEY](#maxmind-license-key) | `""` | Время выполнения | Функции MaxMind | | [MAXMIND\_AUTO\_UPDATE](#maxmind-auto-update) | `"false"` | Время выполнения | — | | [CAIDA\_AUTO\_UPDATE](#caida-auto-update) | `"false"` | Время выполнения | — | | [BACKEND\_PORT](#backend-port) | `11966` | Время выполнения | — | | [FRONTEND\_PORT](#frontend-port) | `18966` | Время выполнения | — | | [ALLOWED\_DOMAINS](#allowed-domains) | `""` | Время выполнения | Развёртывания не на localhost | | [SECURITY\_RATE\_LIMIT](#security-rate-limit) | `0` | Время выполнения | — | | [SECURITY\_DELAY\_AFTER](#security-delay-after) | `0` | Время выполнения | — | | [SECURITY\_BLACKLIST\_LOG\_FILE\_PATH](#security-blacklist-log-file-path) | `""` | Время выполнения | — | | [LOG\_LEVEL](#log-level) | `"info"` | Время выполнения | — | | [LOG\_FORMAT](#log-format) | pretty | Время выполнения | — | | [LOG\_HTTP](#log-http) | `"false"` | Время выполнения | — | | [VITE\_SENTRY\_DSN\_FRONTEND](#vite-sentry-dsn-frontend) | `""` | Сборка + выполнение | — | | [SENTRY\_DSN\_BACKEND](#sentry-dsn-backend) | `""` | Время выполнения | — | | [SENTRY\_ENVIRONMENT](#sentry-environment) | `"production"` | Выполнение + сборка | — | | [SENTRY\_ORG](#sentry-org) | `""` | Сборка | — | | [SENTRY\_PROJECT\_FRONTEND](#sentry-project-frontend) | `""` | Сборка | — | | [SENTRY\_AUTH\_TOKEN](#sentry-auth-token) | `""` | Сборка | — | | [GOOGLE\_MAP\_API\_KEY](#google-map-api-key) | `""` | Время выполнения | — | | [IPINFO\_API\_KEY](#ipinfo-api-key) | `""` | Время выполнения | — | | [IPAPIIS\_API\_KEY](#ipapiis-api-key) | `""` | Время выполнения | — | | [IP2LOCATION\_API\_KEY](#ip2location-api-key) | `""` | Время выполнения | — | | [CLOUDFLARE\_API\_KEY](#cloudflare-api-key) | `""` | Время выполнения | Обмен отчётами | | [MAC\_LOOKUP\_API\_KEY](#mac-lookup-api-key) | `""` | Время выполнения | — | | [RIPESTAT\_SOURCE\_APP](#ripestat-source-app) | `"myip"` | Время выполнения | — | | [CLOUDFLARE\_ACCOUNT\_ID](#cloudflare-account-id) | `""` | Время выполнения | Обмен отчётами | | [CLOUDFLARE\_KV\_NAMESPACE\_ID](#cloudflare-kv-namespace-id) | `""` | Время выполнения | Обмен отчётами | | [VITE\_CURL\_IPV4\_DOMAIN](#vite-curl-ipv4-domain) | `""` | Сборка | Все три или ни одного | | [VITE\_CURL\_IPV6\_DOMAIN](#vite-curl-ipv6-domain) | `""` | Сборка | Все три или ни одного | | [VITE\_CURL\_IPV64\_DOMAIN](#vite-curl-ipv64-domain) | `""` | Сборка | Все три или ни одного | | [VITE\_SITE\_URL](#vite-site-url) | `""` | Сборка + выполнение | — | | [VITE\_DOCS\_URL](#vite-docs-url) | `""` | Сборка | — | | [VITE\_GOOGLE\_ANALYTICS\_ID](#vite-google-analytics-id) | `""` | Сборка | — | | [VITE\_INVISIBILITY\_TEST\_KEY](#vite-invisibility-test-key) | `""` | Сборка | — | | [IPCHECKING\_API\_KEY](#ipchecking-api-key) | `""` | Время выполнения | — | | [IPCHECKING\_API\_ENDPOINT](#ipchecking-api-endpoint) | `""` | Время выполнения | — | ## Требуется — MaxMind и офлайн-наборы данных Собственный источник IP-геолокации MyIP и значки стран во всём интерфейсе обслуживаются локальными базами данных MaxMind GeoLite2. Без них, `GET /api/maxmind` отвечает **503**. См. [Настройка MaxMind](/developer/ru/getting-started/maxmind-setup.md). #### `MAXMIND_ACCOUNT_ID` По умолчанию `""` · Выполнение · **Требуется для функций MaxMind** ID аккаунта MaxMind. Используется вместе с `MAXMIND_LICENSE_KEY` как учётные данные HTTP Basic при загрузке баз данных GeoLite2. #### `MAXMIND_LICENSE_KEY` По умолчанию `""` · Выполнение · **Требуется для функций MaxMind** Лицензионный ключ MaxMind, созданный на странице вашего аккаунта «Manage License Keys». #### `MAXMIND_AUTO_UPDATE` По умолчанию `"false"` · Выполнение · Необязательно `"true"` запускает периодический обновлятор: первая проверка через 60 секунд после запуска, затем каждые 24 часа. #### `CAIDA_AUTO_UPDATE` По умолчанию `"false"` · Выполнение · Необязательно `"true"` обновляет наборы данных CAIDA каждые 24 часа — as2org для названий организаций ASN, as-rel2 для графа связности ASN. {% hint style="info" %} `MAXMIND_AUTO_UPDATE` ограничивает **только периодический планировщик**. Путь при запуске «скачать базы данных, если их нет» его не учитывает — если действительные учётные данные присутствуют, базы будут загружены при первом запуске в любом случае (с ограничением по таймауту 5 минут). Аналогично, `CAIDA_AUTO_UPDATE=false` всё равно позволяет отсутствующим снимкам CAIDA загружаться при запуске; он лишь отключает ежедневное обновление. {% endhint %} Бэкенд никогда не отказывается запускаться из-за отсутствующих баз данных. Он лишь пишет предупреждение и всё равно слушает. ## Порты #### `BACKEND_PORT` По умолчанию `11966` · Выполнение · Необязательно Порт, на котором привязывается API-сервер Express. Также используется как целевой адрес прокси в `frontend-server.js` и в дев-сервере Vite `/api` прокси. #### `FRONTEND_PORT` По умолчанию `18966` · Выполнение · Необязательно Порт, на котором в продакшене привязывается сервер статических файлов/SPA, а в разработке — порт дев-сервера Vite. Оба разбираются с помощью `parseInt(..., 10)`. В Dockerfile `EXPOSE`s `18966` только; порт бэкенда остаётся внутренним для контейнера. ## Безопасность См. [Параметры безопасности](/developer/ru/configuration/security-options.md) и [Обратный прокси и домены](/developer/ru/getting-started/reverse-proxy-and-domains.md). #### `ALLOWED_DOMAINS` По умолчанию `""` · Выполнение · **Фактически требуется для развёртываний не на localhost** Белый список доменов, разделённых запятыми, для глобальной проверки `Referer` на `/api/*`. `localhost` всегда разрешён; всё остальное должно быть перечислено здесь, иначе каждый API-вызов с вашего домена получает 403. #### `SECURITY_RATE_LIMIT` По умолчанию `0` (отключено) · Выполнение · Необязательно Максимум `/api/*` запросов на IP клиента за **20-минутный** интервал. При превышении лимита → `429 {"message":"Too Many Requests"}`. `0` или unset полностью отключает ограничитель. #### `SECURITY_DELAY_AFTER` По умолчанию `0` (отключено) · Выполнение · Необязательно После этого числа `/api/*` запросов с одного IP в течение **60-минутного** интервала каждый следующий запрос задерживается на `число срабатываний × 400 мс`. `0` или unset отключает его. #### `SECURITY_BLACKLIST_LOG_FILE_PATH` По умолчанию `""` · Выполнение · Необязательно Необязательный журнал на диске для IP с ограничением по скорости, например `"logs/blacklist-ip.log"`, разрешается относительно корня репозитория. Пустое значение означает, что файл не записывается; предупреждение `об ограничении IP по скорости` в любом случае логируется. Примечания по поведению, прямо из кода: * **Сопоставление Referer — это точное сопоставление по имени хоста.** `ALLOWED_DOMAINS=example.com` не **разрешает** sub.example.com `— перечислите каждый хостнейм, с которого вы обслуживаете сайт.` Запрос с * отсутствующим **заголовком** `Referer` отклоняется с `403 {"error":"Что вы делаете?"}`. Запрос с запрещённым `Referer` получает `403 {"error":"Доступ запрещён"}`. * Оба ограничителя **пропускают** `/api/monitoring`; туннель Sentry имеет собственный фиксированный ограничитель (600 запросов за 20 минут на IP). * Ограничитель скорости логирует только при переходе в состояние ограничения, а не при каждом заблокированном запросе. * `app.set('trust proxy', 1)` установлено, поэтому впереди должен быть ровно один доверенный прокси. IP клиента определяется из `cf-connecting-ip`, затем `x-forwarded-for` (первый элемент), затем `cf-connecting-ipv6`, затем адрес сокета. ## Логирование См. [Логирование](/developer/ru/configuration/logging.md). #### `LOG_LEVEL` По умолчанию `"info"` · Выполнение · Необязательно Минимальный уровень pino: `debug` / `info` / `warn` / `error`. Сообщения более низкого уровня отбрасываются — включая их отражение в Sentry. #### `LOG_FORMAT` По умолчанию pretty · Выполнение · Необязательно `"json"` выдаёт одно JSON-событие на строку для сборщиков логов. Любое другое значение (или unset) использует цветной `pino-pretty` вывод. #### `LOG_HTTP` По умолчанию `"false"` · Выполнение · Необязательно `"true"` монтирует `pino-http` на `/api/*`: одна строка на запрос с методом, URL и статусом. Монтируется до ограничителя скорости, поэтому 429 тоже логируются. ## Sentry Все опционально. Если DSN не задан, ни один SDK Sentry не загружается и никакой код Sentry не попадает в бандл. См. [Мониторинг ошибок (Sentry)](/developer/ru/configuration/error-monitoring.md). #### `VITE_SENTRY_DSN_FRONTEND` По умолчанию `""` · Сборка **и** выполнение · Необязательно Frontend DSN, встраивается в бандл на этапе сборки. **Также читается во время выполнения** через `backend-server.js` — `POST /api/monitoring` (туннель envelope первого лица) монтируется только когда это задано в процессе сервера. #### `SENTRY_DSN_BACKEND` По умолчанию `""` · Выполнение · Необязательно Backend DSN, читается `sentry-instrument.js` (загружается через `node --import`) и `common/logger.js`, который отражает `warn+` строки в Sentry Logs и повышает `error+` до Issues. #### `SENTRY_ENVIRONMENT` По умолчанию `"production"` · Выполнение + сборка · Необязательно Тег окружения в backend-ивентах Sentry. Также управляет загрузкой source map: загрузки выполняются только когда это не задано или production `production`. #### `SENTRY_ORG` По умолчанию `""` · Сборка · Необязательно Slug организации Sentry для загрузки source map на этапе сборки. #### `SENTRY_PROJECT_FRONTEND` По умолчанию `""` · Сборка · Необязательно Slug проекта Sentry для загрузки source map на этапе сборки. #### `SENTRY_AUTH_TOKEN` По умолчанию `""` · Сборка · Необязательно Токен авторизации для загрузки source map на этапе сборки. Если не задан, Vite вообще не генерирует source map, так что они никогда не будут публично обслуживаться из `dist/`. Секрет времени сборки — никогда не раскрывается браузеру. {% hint style="warning" %} Если вы сами собираете Docker-образ с `VITE_SENTRY_DSN_FRONTEND` встроенным значением, передайте это же значение контейнеру и во время выполнения. Иначе бандл отправляет envelope в `/api/monitoring`, маршрут, который бэкенд никогда не монтировал, и каждый отчёт получает 404. {% endhint %} ## Необязательные API-ключи Каждый ключ открывает один источник IP-данных или инструмент. `GET /api/configs` сообщает, какие из них заданы — только как булевы значения, никогда не сами значения — и фронтенд скрывает соответствующий UI, когда ключ отсутствует. См. [Необязательные API-ключи](/developer/ru/configuration/optional-api-keys.md) и [Источники IP-данных](/developer/ru/architecture/ip-data-sources.md). #### `GOOGLE_MAP_API_KEY` По умолчанию `""` · Выполнение · Необязательно Ключ Google Static Maps, используется `/api/map`. Принимает список, разделённый запятыми; один ключ выбирается случайно для каждого запроса. #### `IPINFO_API_KEY` По умолчанию `""` · Выполнение · Необязательно токен ipinfo.io для `/api/ipinfo`. Поддерживается список через запятую. Точка по-прежнему работает без ключа, на анонимной скорости ipinfo.io. #### `IPAPIIS_API_KEY` По умолчанию `""` · Выполнение · Необязательно ключ api.ipapi.is для `/api/ipapiis`. Поддерживается список через запятую. #### `IP2LOCATION_API_KEY` По умолчанию `""` · Выполнение · Необязательно ключ ip2location.io для `/api/ip2location`. Поддерживается список через запятую. #### `CLOUDFLARE_API_KEY` По умолчанию `""` · Выполнение · **Требуется для обмена отчётами** Токен API Cloudflare с двумя ролями: токен Bearer для Cloudflare Radar (`/api/cfradar`), и — вместе с двумя переменными в [Обмен отчётами](#report-sharing-cloudflare-kv) — учётные данные для хранения доступных для обмена отчётов в Workers KV. Роль KV дополнительно требует разрешения **Workers KV Storage: Edit** на токене. #### `MAC_LOOKUP_API_KEY` По умолчанию `""` · Выполнение · Необязательно ключ maclookup.app для `/api/macchecker`. Точка по-прежнему работает без него, на анонимной скорости. #### `RIPESTAT_SOURCE_APP` По умолчанию `"myip"` · Выполнение · Необязательно Значение, отправляемое как параметр запроса RIPEstat `sourceapp` , чтобы RIPE мог связать трафик с вашим развёртыванием. {% hint style="info" %} `/api/ipapiis` и `/api/ip2location` строят свой upstream-URL, вызывая `.split(',')` для ключа без проверки на null. Если ключ не задан, обработчик выбрасывает исключение и возвращает 500. Фронтенд никогда не вызывает их в этом состоянии, потому что `/api/configs` сообщает, что источник недоступен, и UI скрывает его. {% endhint %} ## Обмен отчётами (Cloudflare KV) Доступные для обмена диагностические отчёты хранятся в Cloudflare Workers KV через REST API. **Все три** переменные — [`CLOUDFLARE_API_KEY`](#cloudflare-api-key) плюс две ниже — должны быть заданы, иначе `POST /api/report` и `GET /api/report/:id` оба отвечают `503 {"error":"Обмен отчётами не настроен"}` и `/api/configs` отчёты `reportSharing: false`, что скрывает UI обмена. #### `CLOUDFLARE_ACCOUNT_ID` По умолчанию `""` · Выполнение · **Требуется для обмена отчётами** ID аккаунта Cloudflare, которому принадлежит пространство имён KV. #### `CLOUDFLARE_KV_NAMESPACE_ID` По умолчанию `""` · Выполнение · **Требуется для обмена отчётами** Точный **hex-ID** из панели управления — не его отображаемое имя. Ограничения отчёта, из `common/report-schema.js`: выбираемый срок хранения составляет 1, 3 или 7 дней (всё остальное принудительно сводится к 1 дню), а объём сохраняемого полезного груза ограничен 256 КБ (`413` свыше этого). Лимит JSON-тела в Express составляет 500 КБ, намеренно выше лимита отчёта. ## API cURL #### `VITE_CURL_IPV4_DOMAIN` По умолчанию `""` · Сборка · Все три или ни одного Имя хоста только для IPv4, отображаемое в карточке API cURL. #### `VITE_CURL_IPV6_DOMAIN` По умолчанию `""` · Сборка · Все три или ни одного Имя хоста только для IPv6. #### `VITE_CURL_IPV64_DOMAIN` По умолчанию `""` · Сборка · Все три или ни одного Двухстековое имя хоста. {% hint style="warning" %} Карточка API cURL отображается только когда **все три** не пусты — `curlDomainsHadSet` в `frontend/store.js` объединяет их через AND. Если задать одно или два, ничего не будет показано. А поскольку это `значения VITE_*`, они должны быть заданы на этапе сборки. {% endhint %} Эти переменные лишь задают имена хостов, показываемые пользователям. Сам MyIP не обслуживает эти конечные точки — вы указываете DNS-записи на любой свой сервис-эхо IP в виде обычного текста. ## Разное #### `VITE_SITE_URL` По умолчанию `""` · Сборка **и** выполнение · Необязательно Абсолютный origin вашего развёртывания. На этапе сборки он подставляется в `__SITE_URL__` в `index.html` (канонические / OG-теги); если пусто, весь этот помеченный блок удаляется. Во время выполнения он становится последним сегментом upstream `User-Agent` (`MyIP/v7.2.0/https://example.com`), чтобы форки идентифицировали себя в upstream API, а не выдавали себя за ipcheck.ing. Завершающие слэши обрезаются. #### `VITE_DOCS_URL` По умолчанию `""` · Сборка · Необязательно Origin сайта документации GitBook, который используется ассистентом справки в приложении и ссылкой на Центр помощи в нижнем колонтитуле, например `https://docs.ipcheck.ing`. Завершающие слэши обрезаются; встроенный скрипт загружается из `/~gitbook/embed/script.js` при первом использовании, а не при загрузке страницы. Когда пусто, ни ассистент, ни ссылка в нижнем колонтитуле вообще не включаются в сборку. Точка входа навигации дополнительно требует каноническое развёртывание — см. [Функции, привязанные к IPCheck.ing](/developer/ru/configuration/features-tied-to-ipcheck-ing.md). #### `VITE_GOOGLE_ANALYTICS_ID` По умолчанию `""` · Сборка · Необязательно Идентификатор отслеживания Google Analytics. Когда пусто, `gtag.js` никогда не внедряется, а страница конфиденциальности сообщает, что аналитика отключена. При самостоятельном размещении следует оставить его пустым. #### `VITE_INVISIBILITY_TEST_KEY` По умолчанию `""` · Сборка · Необязательно Ключ, передаваемый как `pdKey` в сторонний скрипт определения прокси, используемый тестом невидимости. Имеет смысл только в развёртываниях, где также есть `IPCHECKING_API_KEY`. Отсутствует в `.env.example`. #### `IPCHECKING_API_KEY` По умолчанию `""` · Выполнение · Необязательно API-ключ для закрытого сопутствующего API IPCheck.ing. Открывает доступ к `/api/ipchecking`, `/api/getuserinfo`, `PUT /api/updateuserachievement`, `/api/invisibility`, и `/api/dnsleaktest/session/:token` — без него эти маршруты возвращают `500 {"error":"API-ключ отсутствует"}`. Также отображается как `ipChecking` в `/api/configs`. Не в `.env.example`. #### `IPCHECKING_API_ENDPOINT` По умолчанию `""` · Выполнение · Необязательно Базовый URL этого сопутствующего API, используемый вместе с `IPCHECKING_API_KEY`. Не в `.env.example`. {% hint style="info" %} `IPCHECKING_API_KEY` / `IPCHECKING_API_ENDPOINT` и `VITE_INVISIBILITY_TEST_KEY` принадлежат сопутствующему сервису с закрытым исходным кодом. Самостоятельно размещённые форки не могут получить их, а функции, доступ к которым они открывают, скрыты в не-`ipcheck.ing` развёртываниях в любом случае. См. [Функции, привязанные к IPCheck.ing](/developer/ru/configuration/features-tied-to-ipcheck-ing.md). {% endhint %} ## Устаревшие псевдонимы Две переменные были переименованы. Старые написания по-прежнему читаются как запасные варианты, чтобы существующие развёртывания не теряли функции при обновлении. Предпочитайте новые имена. | Старое имя | Текущее имя | Читать где | | ------------------ | -------------------- | ---------------------------------------------------------- | | `IPINFO_API_TOKEN` | `IPINFO_API_KEY` | `api/ipinfo-io.js`, `api/configs.js` | | `CLOUDFLARE_API` | `CLOUDFLARE_API_KEY` | `api/cf-radar.js`, `api/share-report.js`, `api/configs.js` | Порядок разрешения: `NEW || OLD` — если заданы оба, побеждает новое имя. ## Минимальная рабочая конфигурация {% code title=".env" %} ```bash BACKEND_PORT=11966 FRONTEND_PORT=18966 ALLOWED_DOMAINS="myip.example.com" MAXMIND_ACCOUNT_ID="идентификатор-аккаунта" MAXMIND_LICENSE_KEY="ваш-ключ-лицензии" MAXMIND_AUTO_UPDATE="true" ``` {% endcode %} Всё остальное необязательно и лишь добавляет источники данных или инструменты. См. [Быстрый старт](/developer/ru/getting-started/quickstart.md). --- # 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/reference/environment-variables.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.