Параметры .env
Параметры окружения задают подключение Webim к инфраструктуре (PostgreSQL, Redis, Kafka, ClickHouse, S3-хранилищу, поисковому движку и почтовому серверу), ключи шифрования, адреса и домены, а также параметры производительности и мониторинга. Параметры действуют на всю установку и читаются при запуске процессов Webim.
В облаке Webim параметры окружения задают сотрудники Webim. Раздел предназначен для технических специалистов hosted-клиентов.
Где хранятся параметры
При установке на сервер параметры хранятся в файле /opt/webim/django-chat/django-chat/.env. Владелец файла — пользователь www-data, права доступа — 640: файл содержит пароли и ключи. При первой установке файл создаётся из шаблона /opt/webim/django-chat/configs/.env, при обновлении Webim файл сохраняется. Переменные VERSION и APP_VERSION* процедура развёртывания перезаписывает сама.
При установке в Kubernetes параметры хранятся в пространстве имён chatback:
-
ConfigMap
chatback-config— несекретные параметры; -
Secret
chatback-secrets— пароли, токены и ключи.
Установщик создаёт эти ресурсы из файлов комплекта поставки: несекретные параметры — из configmap-patch.yaml, секретные — из файла secret.env.
Формат файла
-
Каждый параметр записывается в отдельной строке в виде
ИМЯ=значение, без пробелов вокруг=. -
Строки, которые начинаются с
#, — комментарии. Комментарий можно добавить и в конце строки: после значения поставьте пробел и#. Если значение само содержит#, заключите его в кавычки. -
Пустое значение (
ИМЯ=) не равно отсутствующему параметру: для большинства параметров пустая строка — допустимое значение, которое отключает соответствующую функцию. Чтобы действовало значение по умолчанию, удалите строку или закомментируйте её. -
Логические значения:
TrueилиFalse. Также принимаются1и0,yesиno,onиoff. -
Списки записываются через запятую без пробелов, например
chat.example.local,admin.example.local. -
В адресах подключения (
postgresql://…,redis://…,clickhouse://…) специальные символы в имени пользователя и пароле (@,:,/,#,%,?) кодируются по правилам URL: например,@записывается как%40.
Приоритет источников
Если параметр задан в нескольких местах, действует значение с наибольшим приоритетом:
-
при установке на сервер переменные окружения процесса важнее файла
.env. Конфигурация supervisor задаёт для всех процессов WebimLOG_LEVEL="warning", поэтому значениеLOG_LEVELиз.envне действует: уровень журналирования меняется в конфигурации supervisor; -
в Kubernetes значения, заданные в манифесте контейнера (раздел
env), важнее Secret, а Secret важнее ConfigMap. Например, для веб-сервера в манифесте заданыDB_POOL_SIZEиPROMETHEUS_MULTIPROC_DIR, для планировщика —SCHEDULER_LEADER_LOCK_ENABLED,SCHEDULER_LOCK_KEYиSCHEDULER_LOCK_TTL.
Изменение параметров
Параметры читаются при запуске процессов, поэтому после изменения перезапустите приложения Webim.
Установка на сервер
-
Откройте файл
.envв текстовом редакторе от имени пользователяwww-data:sudo -u www-data nano /opt/webim/django-chat/django-chat/.env -
Измените значения и сохраните файл. Не меняйте владельца и права доступа к файлу.
-
Проверьте имена групп процессов Webim в supervisor. Обычно это
djangochatиdjangochat-kafka:sudo supervisorctl status -
Перезапустите процессы Webim:
sudo supervisorctl restart 'djangochat:*' 'djangochat-kafka:*'
Установка в Kubernetes
-
Измените несекретный параметр в ConfigMap:
kubectl -n chatback edit configmap chatback-configСекретный параметр измените в Secret. Удобнее всего пересоздать Secret из файла
secret.envкомплекта поставки:kubectl -n chatback create secret generic chatback-secrets \ --from-env-file=secret.env --dry-run=client -o yaml | kubectl apply -f - -
Внесите то же изменение в файлы комплекта поставки (
configmap-patch.yamlилиsecret.env). Иначе при следующем обновлении Webim значение будет перезаписано. -
Перезапустите приложения Webim. Инфраструктурные сервисы (PostgreSQL, Redis, Kafka и другие) перезапускать не нужно:
kubectl -n chatback rollout restart deployment -l 'role in (web,poll,kafka-worker)' kubectl -n chatback rollout restart statefulset -l 'role in (scheduler,watchdog)'
Параметры сборки фронтенда
Значения BASE_DOMAIN, S3_BASE_URL и S3_STATIC_BUCKET_NAME встраиваются в интерфейс Webim при сборке. После их изменения перезапуска недостаточно: требуется повторное развёртывание Webim.
Проверка при запуске
При запуске Webim проверяет обязательные параметры и формат значений. Если параметр не задан или задан неверно, процесс не запускается, а в журнале появляется ошибка с именем параметра: ImproperlyConfigured, UndefinedValueError или ValueError.
Проверить подключения к PostgreSQL, Redis, ClickHouse и другим сервисам можно командой check_connectivity.
Установка на сервер:
sudo -u www-data PYTHONPATH=/opt/webim/django-chat/django-chat \
/opt/webim/django-chat/venv/bin/python /opt/webim/django-chat/django-chat/manage.py check_connectivity
Установка в Kubernetes:
kubectl -n chatback exec -it deploy/chatback-web -c web -- python manage.py check_connectivity
Обязательные параметры
| Параметр | Назначение | Описание |
|---|---|---|
SECRET_KEY |
Ключ подписи данных | Ключи и шифрование |
PASSWORD_SALT |
Соль токенов авторизации | Ключи и шифрование |
ACCOUNT_NAME |
Имя аккаунта | Режим работы и адреса |
ROOT_URL |
Внешний адрес Webim | Режим работы и адреса |
DOMAINS |
Разрешённые домены (обязателен при DEBUG=False) |
Режим работы и адреса |
AUTH_COOKIE_NAME, STATUS_FROM_LOGIN_COOKIE_NAME, DEVICE_ID_COOKIE_NAMES |
Имена cookie | Cookie и сессии |
DATABASE_URL |
Подключение к PostgreSQL | PostgreSQL |
REDIS_CACHE_LOCATION |
Подключение к Redis | Redis |
S3_ENDPOINT_URL, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_REGION_NAME |
Подключение к S3-хранилищу | Файлы и S3-хранилище |
STATS_DATABASE_DEFAULT_URLS, STATS_DATABASE_TEMPLATE, STATS_CLUSTER_NAME |
Подключение к базе статистики в ClickHouse | ClickHouse и аналитика |
Некоторые параметры обязательны только вместе с другими: DEFAULT_HIDDEN_COUNTRIES — если задан GEO_DB_PATH, SENTRY_ENV — если задан SENTRY_DSN.
Значения по умолчанию параметров KAFKA_BOOTSTRAP_SERVERS (см. Kafka) и EMAIL_HOST (см. Почта и внешние сервисы) рассчитаны на среду разработки: в рабочей установке задайте и эти параметры.
Секретные параметры
Храните значения секретных параметров так же, как пароли: не передавайте их в открытом виде и не публикуйте в системах контроля версий. Смена некоторых ключей на работающей установке приводит к потере данных или доступа:
-
SECRET_KEY— подписанные ссылки и cookie становятся недействительными. Если не заданCREDENTIALS_ENCRYPTION_KEY, перестают расшифровываться учётные данные пуш-уведомлений и токены ботов; -
PASSWORD_SALT— всем сотрудникам нужно войти заново; -
ENCRYPTION_CONFIGS— нельзя удалять ключ, которым зашифрованы сохранённые данные: секреты каналов перестанут расшифровываться; -
CREDENTIALS_ENCRYPTION_KEY— устанавливать и менять ключ на работающей установке можно только вместе с перешифрованием токенов ботов. Обратитесь в техническую поддержку Webim.
Разделы справочника
-
Основные параметры и безопасность — режим работы, адреса и домены, ключи шифрования, cookie, защита веб-интерфейса.
-
PostgreSQL — подключение к основной базе данных и реплике, пулы соединений.
-
Redis — подключение к Redis и Sentinel, пулы соединений.
-
Kafka — подключение к брокеру, обработчики очередей, топики и мониторинг шины.
-
ClickHouse и аналитика — базы статистики и BI-отчётов.
-
Поиск и проверка текста — Elasticsearch или OpenSearch, LanguageTool.
-
Файлы и S3-хранилище — S3-хранилище, бакеты, ограничения размера файлов и изображений.
-
Почта и внешние сервисы — SMTP, Telegram, исходящие HTTP-соединения.
-
Журналы и мониторинг — журналирование, Sentry, Prometheus, пороги уведомлений.
-
Защита от перегрузки — ограничение конкурентности, замедление опроса, автоматический выключатель, мониторинг пулов соединений, лимиты частоты запросов.
-
Тайм-ауты, кэш и фоновые задачи — сроки действия токенов авторизации, сроки актуальности фоновых задач, кэш, блокировки и планировщик.
Число рабочих процессов веб-сервера, параметры gunicorn, топики и группы Kafka-обработчиков задаются не в .env, а в конфигурации supervisor или в манифестах Kubernetes: см. Параметры процессов.