# Основные параметры и безопасность

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

Как изменить параметры и применить изменения, описано в разделе [Параметры .env](https://webim.ru/kb/11.0/settings/env/).

## Режим работы и адреса { #mode }

| Параметр | Тип | По умолчанию | Обязательный | Описание |
|---|---|---|---|---|
| `EDITION` | Выбор из списка | Пусто | Нет | Издание поставки: `self_hosted` — установка на серверах клиента с одним аккаунтом и без самостоятельной регистрации, `cloud` — облако **Webim**. Если параметр не задан, издание определяется по `HOSTED_MODE`, а если не задан и он — используется `self_hosted`.<br>Для hosted-установки укажите `self_hosted` или не задавайте параметр. |
| `HOSTED_MODE` | Логический | Не задано | Нет | Устаревший способ задать издание: `True` соответствует `EDITION=self_hosted`, `False` — `EDITION=cloud`. Если `EDITION` и `HOSTED_MODE` противоречат друг другу, **Webim** не запускается. Задавайте только `EDITION`. |
| `DEBUG` | Логический | `False` | Нет | Режим отладки — только для разработки. В рабочей установке значение должно быть `False`: в режиме отладки сервер показывает в ответах на ошибки внутренние сведения. При выключенном режиме **Webim** включает HSTS, передаёт cookie сессии административного интерфейса только по HTTPS и не запускается с небезопасными значениями `SECRET_KEY` и `DOMAINS`.<br>От режима зависят значения по умолчанию `MINIFY_ASSETS` и `KAFKA_EAGER_MODE`. |
| `ACCOUNT_NAME` | Строка | Не задано | Да | Имя аккаунта: строчные латинские буквы, цифры и дефис, первый символ — буква или цифра, длина — от 1 до 63 символов. Записывается в данные аккаунта при первом запуске; не меняйте его после установки.<br>Пример: `company`. |
| `ROOT_URL` | URL | Не задано | Да | Внешний адрес **Webim** со схемой, например `https://chat.example.local`. Используется в ссылках, которые **Webim** формирует для виджета, писем, ботов и внешних сервисов. Завершающий символ `/` отбрасывается. |
| `BASE_DOMAIN` | Строка | Домен из `ROOT_URL` без первой метки | Нет | Базовый домен установки. По умолчанию вычисляется из `ROOT_URL`: для `https://chat.example.local` это `example.local`, для домена из одной метки — сам домен. Встраивается в интерфейс при сборке, поэтому после изменения требуется повторное развёртывание **Webim**. |
| `DOMAINS` | Список через запятую | `*` | Да, если `DEBUG=False` | Доменные имена, по которым **Webim** принимает запросы (заголовок `Host`), например `chat.example.local`. Значение `*` разрешает любые домены; при `DEBUG=False` оно запрещено, и **Webim** не запускается. |
| `ACCOUNT_TIME_ZONE` | Строка | `Europe/Moscow` | Нет | Часовой пояс аккаунта в формате базы IANA, например `Asia/Yekaterinburg`. Записывается в данные аккаунта при первом запуске; последующие изменения параметра не действуют. Часовой пояс работающего аккаунта задаётся настройкой Constance `COMPANY_TIMEZONE` (см. [Общие настройки](https://webim.ru/kb/11.0/settings/constance/general.html#general)); если она не задана, используется значение, записанное при первом запуске. |
| `ACCOUNT_TIME_ZONE_OFFSET` | Строка | `+0300` | Нет | Смещение часового пояса аккаунта относительно UTC в формате `±ЧЧММ`. Записывается в данные аккаунта при первом запуске вместе с `ACCOUNT_TIME_ZONE` и должно ему соответствовать. |
| `BI_ACCOUNT_ID` | Целое число | `1` | Нет | Идентификатор аккаунта в таблицах BI-отчётов в ClickHouse. Записывается в данные аккаунта при первом запуске; не меняйте его после установки. |
| `GEO_DB_PATH` | Путь к файлу | Не задано | Нет | Путь к файлу базы геолокации [Sypex Geo](https://sypexgeo.net) в формате `.dat`. Если путь задан, оператор видит страну и город посетителя, определённые по IP-адресу. Если не задан, местоположение по IP-адресу не определяется. |
| `DEFAULT_HIDDEN_COUNTRIES` | Список через запятую | Не задано | Да, если задан `GEO_DB_PATH` | Страны, название которых не показывается в местоположении посетителя. Указываются русские или английские названия так, как они записаны в базе геолокации, например `Россия,Украина`. |
| `MINIFY_ASSETS` | Логический | `True`, если `DEBUG=False` | Нет | Минификация ресурсов виджета (JavaScript, CSS, HTML и SVG), которые генерирует сервер. |
| `USE_ASYNC_CUSTOM_CHANNEL` | Логический | `True` | Нет | Асинхронная обработка входящих запросов пользовательского канала (Custom Channel). Выключайте только по рекомендации технической поддержки **Webim**. |
| `VERSION` | Строка | `dev` | Нет | Версия сборки. Используется как префикс статических файлов в S3-хранилище, чтобы браузеры загружали новые файлы после обновления. Записывается процедурой развёртывания; вручную не меняйте. |
| `APP_VERSION` | Строка | Значение `VERSION` | Нет | Версия **Webim**, которая отображается в интерфейсе. Записывается процедурой развёртывания. |
| `APP_VERSION_DATE` | Строка | `dev` | Нет | Дата сборки. Записывается процедурой развёртывания. |
| `APP_BUILD_BRANCH` | Строка | `dev` | Нет | Ветка, из которой собран дистрибутив. Записывается процедурой развёртывания. |

## Ключи и шифрование { #secrets }

| Параметр | Тип | По умолчанию | Обязательный | Описание |
|---|---|---|---|---|
| `SECRET_KEY` | Строка | Не задано | Да | Секретный ключ для подписи cookie, ссылок восстановления пароля и других подписанных данных. Задайте длинную случайную строку. При `DEBUG=False` значение с заглушкой (например, содержащее `REPLACE_THIS` или `change-me`) запрещено.<br>Смена ключа делает подписанные данные недействительными. Если не задан `CREDENTIALS_ENCRYPTION_KEY`, после смены перестают расшифровываться учётные данные пуш-уведомлений и токены ботов. |
| `PASSWORD_SALT` | Строка | Не задано | Да | Соль для хешей токенов авторизации сотрудников. Задайте длинную случайную строку. После смены значения всем сотрудникам нужно войти заново. |
| `ENCRYPTION_CONFIGS` | JSON-массив | `[]` | Нет | Ключи шифрования секретов каналов и интеграций (токенов, паролей почтовых ящиков, закрытых ключей), которые хранятся в базе данных. Каждый элемент — объект с полями `algo` (значение `fernet-pbkdf2`), `password`, `salt` и `id`. Если список пуст, такие данные хранятся в базе в открытом виде.<br>Новые данные шифруются последним ключом списка, расшифровываются — ключом, которым были зашифрованы. Чтобы сменить ключ, добавьте новый элемент в конец списка; не удаляйте старые элементы, пока в базе есть данные, зашифрованные ими.<br>Пример: `[{"algo":"fernet-pbkdf2","password":"<пароль>","salt":"<соль>","id":"v1"}]`. |
| `CREDENTIALS_ENCRYPTION_KEY` | Строка | Пусто | Нет | Отдельный ключ шифрования учётных данных пуш-уведомлений (iOS, FCM, Huawei) и токенов ботов в базе данных. Если не задан, используется `SECRET_KEY`. Отдельный ключ позволяет менять `SECRET_KEY` без потери этих данных.<br>Устанавливать и менять ключ на работающей установке можно только вместе с перешифрованием токенов ботов, иначе аутентификация ботов перестанет работать. Обратитесь в техническую поддержку **Webim**. |
| `PBKDF2_ITERATIONS` | Целое число | `600000` | Нет | Число итераций алгоритма PBKDF2 при хешировании паролей сотрудников. Меньшее значение ослабляет защиту паролей: не уменьшайте его в рабочей установке. |

## Cookie и сессии { #cookies }

| Параметр | Тип | По умолчанию | Обязательный | Описание |
|---|---|---|---|---|
| `AUTH_COOKIE_NAME` | Строка | Не задано | Да | Имя cookie с токеном авторизации сотрудника, например `CHAT_AUTH_TOKEN`. После смены имени всем сотрудникам нужно войти заново. |
| `STATUS_FROM_LOGIN_COOKIE_NAME` | Строка | Не задано | Да | Имя cookie, в которой сохраняется статус, выбранный сотрудником в форме входа, например `CHAT_STATUS_FROM_LOGIN`. |
| `DEVICE_ID_COOKIE_NAMES` | Список через запятую | Не задано | Да | Имена cookie с идентификатором устройства, с которого сотрудник входит в **Webim**. Используется первая непустая cookie из списка. Идентификатор устройства привязывается к сессии сотрудника.<br>Пример: `CHAT_DEVICE_ID,WEBIM_DEVICE_ID`. |
| `DEVICE_ID_COOKIE_NAME` | Строка | Пусто | Нет | Устаревший вариант `DEVICE_ID_COOKIE_NAMES` с одним именем cookie. Используется, только если `DEVICE_ID_COOKIE_NAMES` не задан. |
| `SESSION_COOKIE_AGE` | Целое число, секунды | `86400` | Нет | Время жизни сессии административного интерфейса сервера (по умолчанию — 24 часа). На сессии сотрудников в интерфейсе **Webim** не влияет. |

## Защита веб-интерфейса { #web-security }

| Параметр | Тип | По умолчанию | Обязательный | Описание |
|---|---|---|---|---|
| `SECURE_SSL_REDIRECT` | Логический | `True` | Нет | Перенаправление HTTP-запросов на HTTPS. Действует только при `DEBUG=False`. Протокол исходного запроса определяется по заголовку `X-Forwarded-Proto` от обратного прокси-сервера. |
| `TRUSTED_PROXY_COUNT` | Целое число | `1` | Нет | Число доверенных обратных прокси-серверов перед **Webim** (обычно nginx — `1`). По нему из заголовка `X-Forwarded-For` определяется IP-адрес клиента, от которого зависят ограничения доступа по IP-адресам и лимиты частоты запросов. Если перед nginx есть балансировщик, который тоже дописывает этот заголовок, увеличьте значение. |
| `CSRF_TRUSTED_ORIGINS` | Список через запятую | Пусто | Нет | Дополнительные доверенные источники для проверки CSRF в административном интерфейсе сервера: схема и домен, например `https://admin.example.local`. Для поддоменов можно использовать подстановку: `https://*.example.local`. |
| `ORIGIN_CHECK_ENABLED` | Логический | `True` | Нет | Проверка заголовка `Origin` у изменяющих запросов с cookie авторизации сотрудника: такие запросы принимаются только со своего домена. Защищает от подделки межсайтовых запросов; не выключайте в рабочей установке. |
| `ORIGIN_CHECK_TRUSTED_HOSTS` | Список через запятую | Пусто | Нет | Дополнительные домены (без схемы и порта), с которых принимаются изменяющие запросы сотрудников при проверке заголовка `Origin`. |
| `CSP_REPORT_ONLY_POLICY` | Строка | Не задано | Нет | Политика Content Security Policy, которая отправляется в заголовке `Content-Security-Policy-Report-Only`. Если параметр не задан, политика формируется автоматически; пустое значение отключает заголовок. |
| `CSP_REPORT_URI` | Строка | `/l/csp-report` | Нет | Адрес, на который браузер отправляет отчёты о нарушениях политики CSP. По умолчанию отчёты принимает сам **Webim**. Пустое значение отключает отчёты; без них браузеры не применяют политику в режиме отчётов, поэтому очищайте значение только вместе с `CSP_REPORT_ONLY_POLICY`. |
| `CSP_ALLOW_LEGACY_INLINE` | Логический | `False` | Нет | Разрешает встроенные скрипты без атрибута `nonce` (`'unsafe-inline'` в директиве `script-src`). Аварийная настройка: включайте, только если из-за политики CSP перестали работать страницы. |
| `CSP_ENFORCE` | Логический | `False` | Нет | Блокирующий режим политики CSP вместо режима отчётов. Включайте, только когда отчёты о нарушениях перестали поступать: в блокирующем режиме браузер запрещает всё, что не разрешено политикой. |

## Доступ по IP-адресам { #ip }

| Параметр | Тип | По умолчанию | Обязательный | Описание |
|---|---|---|---|---|
| `TRUSTED_IPS` | Список через запятую | Пусто | Нет | IP-адреса и подсети (в нотации CIDR) с повышенным лимитом попыток входа: 30 попыток вместо 5 за период `LOGIN_ATTEMPTS_TIMEOUT_MINUTES` (см. [Тайм-ауты, кэш и фоновые задачи](https://webim.ru/kb/11.0/settings/env/timeouts.html#auth)).<br>Пример: `10.0.0.0/8,192.0.2.15`. |
| `MY_IPS` | Список через запятую | Пусто | Нет | IP-адреса серверов **Webim**. Запросы с этих адресов не проверяются по спискам разрешённых IP-адресов сотрудников и Stored Data API (настройки Constance `OPERATOR_ALLOWED_IPS` и `STORED_DATA_API_ALLOWED_IPS`). Указываются отдельные адреса, без подсетей. |
| `SSRF_ALLOWED_HOSTS` | Список через запятую | Пусто | Нет | Имена хостов, которым при исходящих запросах **Webim** (например, к боту или вебхуку) разрешено указывать на адреса внутренней сети (частные сети IPv4 и IPv6 ULA). По умолчанию исходящие запросы во внутреннюю сеть запрещены. Адреса loopback, `0.0.0.0` и адреса метаданных облачных платформ запрещены всегда.<br>Пример: `bot.example.local`. |

## Вход технической поддержки Webim { #support-gate }

Инженер технической поддержки **Webim** может войти в аккаунт только с разрешения сервиса проверки доступа. Если адрес сервиса не задан, вход технической поддержки отключён.

| Параметр | Тип | По умолчанию | Обязательный | Описание |
|---|---|---|---|---|
| `SUPPORT_GATE_URL` | URL | Пусто | Нет | Адрес сервиса проверки доступа технической поддержки **Webim**. Пустое значение отключает вход технической поддержки. |
| `SUPPORT_GATE_REVOKE_TOKEN` | Строка | Пусто | Нет | Токен, которым сервис проверки доступа подтверждает запрос на досрочное завершение сессии инженера. Без токена досрочное завершение сессии не работает. |
| `SUPPORT_TOKEN_TTL_HOURS` | Целое число, часы | `2` | Нет | Максимальная длительность сессии инженера технической поддержки. Сервис проверки доступа может только сократить этот срок. |
| `SUPPORT_GATE_HTTP_TIMEOUT_SECONDS` | Целое число, секунды | `5` | Нет | Тайм-аут запросов к сервису проверки доступа. |

---

Источник: https://webim.ru/kb/11.0/settings/env/general.html
