Переменные окружения
> Кратко. Полный перечень переменных API и веба по функциям: что делает переменная, какое у неё значение по умолчанию в коде и что не работает без неё. Список собран по коду, а не по .env.example: в примерах есть не всё.
Читаю как
Как читать таблицы. «По умолчанию» — значение в коде. Прочерк значит, что значения нет. Для секретов значение
не приводится никогда. Логические флаги API включаются словами true, 1, yes, on. Исключения:
TELEMETRY_REGIME_AUTO — только 1; флаги веба (GEOSERVER_MVT_PROBE_TILES, GEOSERVER_MERGE_STYLE_LAYERS) — только true.
Как API читает переменные
- API и воркер при старте читают
.envиз своего каталога (load_dotenv). Переменные окружения службы важнее.env: файл только дополняет окружение. - Большинство переменных читается на каждом обращении, но меняет их всё равно перезапуск службы: окружение процесса после старта не меняется.
- Для копии базы на стенде рядом кладут
.env.copy: в нём только отличия — база, база пользователей, номер базы Redis.
API: базы данных
| Переменная | Что делает | По умолчанию | Без неё |
|---|---|---|---|
DB_HOST, DB_PORT, DB_USER, DB_PASSWORD |
Сервер PostgreSQL баз городов | порт 5432 | API не стартует |
DB_NAME |
База города в режиме одного города | — | нет данных сети |
TGID_CITY_DBS |
Несколько городов: код=база,… — Несколько городов |
— | режим одного города |
TGID_CITY |
Код города API одного города | по имени базы | — |
TGID_CITIES |
Справочник городов код:Название[:путь] |
12 встроенных | — |
USERS_DB_HOST, USERS_DB_PORT, USERS_DB_USER, USERS_DB_PASSWORD, USERS_DB_NAME |
UsersDB: пользователи, права, журнал действий | порт 5432 | вход только мастер-учёткой, журнала действий нет |
USERS_DB_ECHO |
Печатать SQL UsersDB в журнал | выкл. | — |
SPRAV_DB_HOST, SPRAV_DB_PORT, SPRAV_DB_USER, SPRAV_DB_PASSWORD, SPRAV_DB_NAME |
База справочников расчёта | как DB_*, база sprav |
движок берёт CSV из sety/sprav |
DB_POOL_MIN_SIZE, DB_POOL_MAX_SIZE |
Пул соединений на город и процесс | 2 и 20 | — |
DB_COMMAND_TIMEOUT |
Предел запроса пула, с | 60 | — |
DB_POOL_MAX_INACTIVE_LIFETIME |
Закрывать простаивающее соединение через, с | 300 | — |
DB_UPKEEP_INTERVAL_S |
Доводка схемы базы города, с; 0 — выключить |
600 | — |
FILES_DIR |
Каталог kls/ (справочники карточек), шаблонов Word, статичных тайлов |
./files |
API не стартует, если каталога нет |
MSSQL_SERVER, MSSQL_USER, MSSQL_PASSWORD |
Подключение к MS SQL у старых модулей паспорта и sety | — | не нужны при PostgreSQL |
API: вход и права
| Переменная | Что делает | По умолчанию | Без неё |
|---|---|---|---|
AUTH_DISABLED |
Выключить проверку входа: каждый запрос — пользователь dev с ролью администратора |
true |
— |
AUTH_REQUIRED_GET |
Требовать токен на всех адресах, кроме открытых (/health, /docs, /openapi.json, /fragments, вход, публичные отключения, встраивание) |
false |
чтение без входа; GeoServer открыт |
STRICT_AUTH |
Не запускать API с небезопасными настройками: AUTH_DISABLED=true, JWT_SECRET по умолчанию, DEV_LOGIN_ENABLED=true, AUTH_REQUIRED_GET=false |
false |
проверки нет |
DEV_LOGIN_ENABLED |
Вход с любым логином и любой ролью без пароля | false |
— |
AUTH_BACKEND |
usersdb — пользователи UsersDB; pg — роли PostgreSQL |
usersdb |
— |
AUTH_LIVE_USER_CHECK |
Сверять токен с UsersDB: блокировка, роль, города | true |
— |
USER_STATUS_TTL |
Кеш этой сверки, с | 30 | — |
JWT_SECRET |
Ключ подписи токенов | небезопасная строка-заглушка | токены можно подделать |
JWT_ALGORITHM |
Алгоритм подписи | HS256 |
— |
JWT_EXPIRE_MINUTES |
Срок сессии, мин | 480 | — |
MASTER_LOGIN, MASTER_PASSWORD_HASH |
Мастер-учётка вне UsersDB (хеш bcrypt) | логин admin, хеша нет |
мастер-учётки нет |
LOGIN_MAX_FAILS, LOGIN_MAX_FAILS_PER_IP, LOGIN_FAIL_WINDOW_SECONDS |
Временный запрет входа после неудач: на логин, на адрес, окно, с | 5, 30, 600 | — |
MUTATIONS_ENABLED |
Разрешить запись данных сети и журналов: карточки, групповая правка, журналы, наряды, отключения, телеметрия, сохранение расчётов | false |
данные только читаются (503) |
TOPOLOGY_MUTATIONS_ENABLED |
Разрешить правку сети: создание, перемещение, удаление, импорт сети, сценарии, перенос фрагментов. Нужен ещё MUTATIONS_ENABLED |
false |
сеть не правится (503) |
DB_ROLE_SWITCH, DB_DEV_ROLE |
SET ROLE пользователя на каждом соединении (роли PostgreSQL) и роль при выключенном входе |
выкл., tgid_admin |
— |
CORS_ALLOWED_ORIGINS |
С каких сайтов браузер может обращаться к API и /mcp |
адрес прода и localhost:3000, localhost:3007 |
— |
Что каждый флаг блокирует — Роли и права.
API: персональные данные и журнал действий
| Переменная | Что делает | По умолчанию | Без неё |
|---|---|---|---|
PII_MASKING |
Маскировать ПДн без права pii_view; false — выключить |
true |
— |
PII_MAX_BYTES |
Ответ больше — не разбирается и не маскируется | 16 МБ | — |
ACTIVITY_LOG_ENABLED |
Писать журнал действий | true |
— |
ACTIVITY_LOG_DAYS |
Хранить записи журнала, дней (не меньше 30) | 730 | — |
API: очереди, Redis и файлы
| Переменная | Что делает | По умолчанию | Без неё |
|---|---|---|---|
REDIS_ADDR, REDIS_PASSWORD |
Redis: брокер Celery, статусы задач | 127.0.0.1:6379, без пароля |
нет расчётов и фоновых выгрузок |
REDIS_DB |
Номер базы Redis. Стенд и прод на одном Redis — разные номера, иначе воркеры заберут чужие задачи | 0 | — |
FILE_STORAGE |
Где лежат готовые выгрузки: redis, local, s3 |
redis |
— |
FILE_STORAGE_DIR |
Каталог для local, общий для API и воркеров |
— | local не работает |
FILE_S3_ENDPOINT, FILE_S3_BUCKET, FILE_S3_ACCESS_KEY, FILE_S3_SECRET_KEY, FILE_S3_SECURE |
Хранилище S3 (MinIO, SeaweedFS) | корзина tgid-files, FILE_S3_SECURE=false |
s3 не работает |
FILE_STORAGE_SWEEP_S |
Как часто удалять просроченные файлы, с | 300 | — |
FILE_JOBS_TTL |
Срок жизни выгрузки, с (не меньше 60) | 3600 | — |
FILE_JOBS_QUEUE, HEAT_LOSSES_QUEUE, STATIC_TILES_QUEUE |
Отдельные очереди выгрузок, теплопотерь и износа, запекания тайлов | очередь города | — |
STATIC_TILES_DIR |
Каталог архивов PMTiles (по подкаталогу на город) | files/static_tiles |
— |
API: расчёт
SETY_ENGINE, HEATNET_PROFILE, HEATNET_CORE, HEATNET_QUIRKS_OFF, HEATNET_WRITE, HEATNET_CORE_STATS,
SETY_TIMEOUT_S, CALC_PROTOCOL_KEEP_DAYS — на странице Расчётные движки. Ещё:
| Переменная | Что делает | По умолчанию | Без неё |
|---|---|---|---|
ZULU_TIMEOUT_S |
Предел конвертации из ZuluGIS, с (не меньше 60) | 1800 | — |
PASSPORT_FORM_WORKERS |
Потоки построения форм паспорта (1–8) | 3 | — |
API: ИИ
| Переменная | Что делает | По умолчанию | Без неё |
|---|---|---|---|
AI_ENABLED |
Включить помощника и ИИ-кнопки | false |
функций ИИ нет |
ANTHROPIC_API_KEY |
Ключ Claude API | — | функций ИИ нет, даже при AI_ENABLED=true |
AI_MODEL |
Модель помощника и разборов | claude-opus-5-5 |
— |
AI_RERANK_MODEL |
Модель пересортировки похожих аварий | claude-sonnet-5-5 |
— |
AI_TIMEOUT_S |
Предел ответа модели, с | 120 | — |
AI_MAX_INPUT_CHARS, AI_MAX_OUTPUT_TOKENS |
Пределы запроса и ответа | 60 000 и 8 000 | — |
API: внешние интерфейсы
| Переменная | Что делает | По умолчанию | Без неё |
|---|---|---|---|
MCP_ENABLED |
MCP-сервер для ИИ-клиентов | true |
— |
MCP_TOKEN_DAYS |
Срок токена MCP, дней (не больше 90) | 30 | — |
API_TOKEN_DAYS |
Срок ключа API v2, дней (не больше 730) | 365 | — |
ARCGIS_TOKEN_DAYS |
Срок ключа ArcGIS FeatureServer, дней (не больше 365) | 90 | — |
API_PUBLIC_PREFIX |
Внешний адрес API для ссылок OGC API ({city} заменяется кодом города) |
— | ссылки строятся от адреса запроса |
WEBHOOK_POLL_S |
Фоновый проход событий: вебхуки, лента API v2, тревоги телеметрии, с; 0 — выключить всё это |
10 | — |
WEBHOOK_ALLOW_HTTP |
Разрешить адреса вебхуков http:// |
false |
только https:// |
WEBHOOK_ALLOW_PRIVATE |
Разрешить вебхуки на внутренние адреса | false |
— |
PUBLIC_OUTAGES_ENABLED |
Публичная карта отключений без входа | false |
страница закрыта |
OVERPASS_URL |
Сервер Overpass для социальных объектов из OSM | overpass-api.de |
— |
MARTIN_SQL_FILE, MARTIN_SQL_DIR |
Файл функций тайлов martin одного города или каталог <код>.sql для всех |
— | API не возвращает функции после переконвертации |
API: телеметрия, погода, водопровод
| Переменная | Что делает | По умолчанию |
|---|---|---|
TELEMETRY_STALE_MIN |
Датчик «молчит», если нет показаний дольше, мин | 60 |
TELEMETRY_REGIME_WINDOW_MIN |
Окно усреднения режима источника, мин | 15 |
TELEMETRY_REGIME_AUTO, TELEMETRY_REGIME_AUTO_MIN |
1 — расчёт по факту запускается сам, когда режим источника изменился, не чаще раза в N мин на фрагмент (не меньше 15). Это настоящие расчёты в очереди города |
0, 60 |
TELEMETRY_CAL_WINDOW_MIN, TELEMETRY_PRESSURE_ACCURACY_M |
Калибровка: окно, мин, и точность манометра, м | 30, 0,5 |
TELEMETRY_FLOW_ACCURACY_PCT, TELEMETRY_BALANCE_WINDOW_MIN, TELEMETRY_NIGHT_GROWTH_TH, TELEMETRY_BALANCE_EVERY_S |
Баланс расхода: точность расходомера, %, окно, мин, рост ночного расхода, т/ч, проверка, с | 2,0, 60, 5, 900 |
WEATHER_PROVIDER |
open-meteo или none |
open-meteo |
WEATHER_REFRESH_MIN, WEATHER_PAST_DAYS, WEATHER_FORECAST_DAYS |
Обновление, мин, дней назад (0–92) и вперёд (1–16) | 60, 3, 3 |
WEATHER_LAT, WEATHER_LON |
Точка прогноза | центр источников тепла города |
WATER_ENGINE_URL, WATER_ENGINE_TOKEN |
Адрес и секрет движка водопровода | http://127.0.0.1:8070, без секрета |
WATER_ORIGIN_LAT, WATER_ORIGIN_LON |
Точка на карте для сети водопровода без географической привязки (учебные сети EPANET) | как точка погоды |
WEATHER_LAT/LON и WATER_ORIGIN_LAT/LON действуют на весь процесс. В API на несколько городов они задают одну
точку для всех городов — лучше их не задавать, тогда у каждого города будет центр его источников.
API: наблюдение
| Переменная | Что делает | По умолчанию | Без неё |
|---|---|---|---|
METRICS_TOKEN |
Токен /metrics (Prometheus) |
— | /metrics отвечает 404 |
PROMETHEUS_MULTIPROC_DIR |
Общий каталог счётчиков нескольких процессов uvicorn | — | каждый процесс отдаёт только свои |
LOOP_STALL_S |
Сторож цикла событий: порог, с; 0 — выключить |
5 | — |
API: скрипты обслуживания
TGID_NEW_PASSWORD — пароль для scripts/create_user.py (иначе спрашивается). TGID_API_KEY, OPCUA_PASSWORD —
ключ API v2 и пароль OPC UA шлюза телеметрии (имена переменных можно сменить в настройке шлюза).
SMOKE_TOKEN, API_BASE, MIN_ROUTES — проверочные скрипты scripts/smoke_all.py и scripts/verify_prod_routes.py.
SETY_GOLDEN_DIR, SETY_ROOT, SETY_PROBE, FORMS — сверочные скрипты scripts/golden/.
Веб
Веб читает переменные дважды:
- При сборке (
npm run build).nuxt.config.tsберёт значения из окружения и из.envв каталоге сборки и запекает их в.outputкак значения по умолчанию. - При запуске собранного сервера (
node .output/server/index.mjs). Значения можно перекрыть только переменными Nuxt с префиксом:NUXT_PUBLIC_<ИМЯ>для общих ключей иNUXT_<ИМЯ>для серверных. Например,martinTilesUrl→NUXT_MARTIN_TILES_URL,geoserver.workspace→NUXT_PUBLIC_GEOSERVER_WORKSPACE. Имена без префикса (MARTIN_TILES_URL) у собранного веба действуют только там, где сервер читает их прямо из окружения. Такие отмечены ниже словом «запуск».
Всё, что начинается с NUXT_PUBLIC_, попадает в браузер. Секреты туда не кладут. Ключи MapTiler, Cesium
и VISICOM публичные по своей природе: ограничивайте их по домену в кабинете поставщика.
| Переменная | Что делает | По умолчанию | Без неё |
|---|---|---|---|
NUXT_PUBLIC_MAP_API_BASE_URL |
Адрес API для браузера | EXTERNAL_API_URL, иначе http://localhost:8000 |
— |
EXTERNAL_API_URL |
Прежнее имя адреса API | http://localhost:8000 |
— |
NUXT_APP_BASE_URL |
Путь приложения (/tgid/<код>/); одна сборка на все города |
/itwin-map/ |
— |
PORT, NITRO_HOST |
Порт и адрес сервера веба (Nitro) | 3000 | — |
NUXT_PUBLIC_MAPTILER_KEY |
Подложка MapTiler | — | подложки MapTiler нет |
NUXT_PUBLIC_CESIUM_ION_TOKEN |
Рельеф и 3D Cesium ion | — | 3D без рельефа ion |
NUXT_PUBLIC_CESIUM_PHOTOREALISTIC_ASSET_ID |
Фотореалистичные 3D Tiles; 0 — скрыть кнопку |
2275207 | — |
NUXT_PUBLIC_NETWORK_TILESET_URL |
3D Tiles сети | — | — |
NUXT_PUBLIC_VISICOM_TILES_URL, NUXT_PUBLIC_VISICOM_KEY, NUXT_PUBLIC_VISICOM_SCHEME, NUXT_PUBLIC_VISICOM_ATTRIBUTION, NUXT_PUBLIC_VISICOM_MAX_ZOOM |
Подложка VISICOM | схема tms |
без ключа подложка скрыта |
NUXT_PUBLIC_CITY_BBOX, NUXT_PUBLIC_MAP_CENTER |
Охват minLon,minLat,maxLon,maxLat и центр lon,lat города |
Алматы | карта открывается на Алматы |
NUXT_PUBLIC_DEFAULT_FRAGMENTS |
Фрагменты, видимые при открытии (2-46,48) |
все | — |
NUXT_PUBLIC_STORAGE_PREFIX |
Префикс настроек в браузере | — | города на одном домене делят настройки |
NUXT_PUBLIC_CAD_MIN_BUILDING_M, NUXT_PUBLIC_CAD_MIN_ROAD_M |
Охранные расстояния трассы до зданий и оси улицы, м | — | размеры без проверки |
NUXT_PUBLIC_SITE_INDEXABLE, NUXT_PUBLIC_SITE_URL |
Индексация поисковиками и канонический адрес | — | noindex |
NUXT_PUBLIC_GEOSERVER_URL |
Публичный адрес GeoServer | из каталога слоёв | — |
GEOSERVER_LAYER_CATALOG |
Каталог рабочих областей и слоёв (JSON) | — | только автообнаружение слоёв |
GEOSERVER_CAPABILITIES_URL, GEOSERVER_REST_URL |
GetCapabilities WMTS и REST GeoServer | — | — |
GEOSERVER_REST_USER, GEOSERVER_REST_PASSWORD |
Учётная запись REST GeoServer (запуск) | пользователь admin |
стили и атрибуты без REST |
GEOSERVER_INTERNAL_URL |
Внутренний адрес GeoServer для сервера веба (запуск) | — | при закрытом GeoServer пропадают слои |
GEOSERVER_DISCOVER_WORKSPACES |
Автообнаружение слоёв: рабочие области через запятую или * (запуск) |
— | — |
GEOSERVER_SERVICE_LAYERS |
Вспомогательные слои, скрытые по умолчанию (запуск) | — | — |
GEOSERVER_MVT_TEMPLATE_URL |
Шаблон адреса векторного тайла | — | — |
GEOSERVER_MVT_GWC |
false — не брать тайлы из кеша GWC (запуск) |
кеш GWC | — |
GEOSERVER_MVT_PROBE_TILES |
Проверять тайл перед добавлением слоя | false |
— |
GEOSERVER_MERGE_STYLE_LAYERS |
Склеивать слои стиля участков — для замеров (запуск) | false |
— |
MARTIN_TILES_URL, MARTIN_SOURCE_PREFIX, MARTIN_LAYERS, MARTIN_WORKSPACE |
Тайлы сети из martin: адрес, префикс источников города, слои, рабочая область | слои heatpipesections,uzel,zdaniya_2,zdaniya_tu |
тайлы из GeoServer |
NITRO_COMPRESS_PUBLIC_ASSETS |
Сжимать статику при сборке; false — нет |
true |
— |
NUXT_PUBLIC_MUTATIONS_ENABLED и NUXT_PUBLIC_TOPOLOGY_EDITING_ENABLED больше не используются. Кнопки записи
веб показывает по флагам сервера из /api/v1/auth/config.
Для разработчика
- Новая переменная API — в
.env.exampleс комментарием и в эту таблицу. Секреты в примере — пустые. - Новая переменная веба — ключ
runtimeConfigвnuxt.config.ts. Если её надо менять без пересборки — серверный код читаетuseRuntimeConfig(), тогда её перекрываетNUXT_…. - Текущие флаги сервера без входа видны в
GET /api/v1/auth/configи в полеflagsответа/health.
Хотите увидеть эту функцию на своих данных?Покажем ТГИД на демонстрации и ответим на вопросы инженеров.
Запросить демо