Переменные окружения узла: карта настроек
Узел Клавдия при запуске читает переменные окружения: подключение к базе данных, роли, порты, пути к данным, параметры поиска и хранения. Большую часть значений задаёт установщик; остальные можно добавить при необходимости. Эта статья — карта всех переменных, которые учитывает узел, с указанием, кто их задаёт и когда их стоит менять. Подробные ограничения и особенности каждой переменной — в {{ССЫЛКА:reference.env|справочнике переменных окружения}}.
Перед началом
- {{ССЫЛКА:install.aio|Установка «всё-в-одном» на Linux через Docker Compose}} или {{ССЫЛКА:install.join-node|добавление узла}} выполнены.
Где задаются переменные
В папке установки (по умолчанию /opt/klvd) лежат:
| Файл |
Что в нём |
.env |
значения, выбранные при установке: роли, порты, адреса базы данных и поиска, папки данных на сервере |
docker-compose.yml |
описание контейнеров; в секции environment сервиса klvd-node — переменные, которые установщик фиксирует для контейнера (пути внутри контейнера, сертификаты, секреты) |
secrets/ |
пароли, ключ кластера и сертификат — передаются в контейнер файлами |
Все строки из .env попадают в контейнер узла. Поэтому, чтобы задать переменную, которой нет в файлах, достаточно добавить её в .env. Если та же переменная указана в секции environment файла docker-compose.yml, действует значение из docker-compose.yml.
Как применить изменения
cd /opt/klvd
docker compose up -d --force-recreate klvd-node
Переменные читаются только при запуске узла: без пересоздания контейнера изменения не действуют. Данные в томах не затрагиваются.
Перед правкой сохраните копию .env и docker-compose.yml. Обновление (update.sh) эти файлы не перезаписывает — ваши значения сохраняются.
Пароли и ключи — только файлами
Пароли, ключ кластера и сертификаты не записывайте в .env. Для таких переменных узел принимает вариант с суффиксом _FILE: значение читается из указанного файла. Так установщик передаёт KLVD_SECRET_FILE, POSTGRESQL_USER_FILE и POSTGRESQL_PASSWORD_FILE из папки secrets/.
Карта переменных
Обозначения в столбце «Кто задаёт»: У — установщик в .env, C — установщик в docker-compose.yml, — — по умолчанию не задаётся, добавляйте при необходимости.
Основные
| Переменная |
Кто задаёт |
По умолчанию |
Назначение |
KLVD_SECRET / KLVD_SECRET_FILE |
C |
— |
ключ кластера (подпись и шифрование данных). Одинаковый на всех узлах. Обязателен: без него узел не запускается |
KLVD_ROLES |
У |
все роли |
разрешённые роли узла: storage, importer, indexer, imap, smtp. Веб-интерфейс включён всегда |
KLVD_PERSISTENT_DIR |
C |
/var/klvd |
папка постоянных данных узла внутри контейнера |
KLVD_TMP_DIR |
C |
/tmp/klvd |
папка временных файлов |
KLVD_LOG_DIR |
C |
— |
папка журналов. Не задана — журнал только в вывод контейнера |
KLVD_SHARED_DIR |
— |
/shared |
общая папка узла и контейнеров поиска (настройки кластера Solr, сертификат для Solr) |
База данных PostgreSQL
| Переменная |
Кто задаёт |
По умолчанию |
Назначение |
POSTGRESQL_HOST |
У |
— |
адрес сервера базы данных |
POSTGRESQL_PORT |
У |
5432 |
порт |
POSTGRESQL_DB |
У |
— |
имя базы данных |
POSTGRESQL_USER / POSTGRESQL_USER_FILE |
C |
— |
пользователь базы данных |
POSTGRESQL_PASSWORD / POSTGRESQL_PASSWORD_FILE |
C |
— |
пароль |
POSTGRESQL_SSL |
У |
prefer |
режим шифрования: disable, prefer, require, verify-ca, verify-full |
POSTGRESQL_SSLROOTCERT |
— |
— |
путь к сертификату центра сертификации для verify-ca / verify-full |
POSTGRESQL_POOL_INITIAL_SIZE |
— |
10 |
соединений с базой при запуске |
POSTGRESQL_POOL_MAX_SIZE |
— |
100 |
максимум соединений с базой у одного узла |
POSTGRESQL_STARTUP_WAIT_SECONDS |
— |
60 |
сколько секунд узел ждёт доступности базы при запуске |
Веб-интерфейс
| Переменная |
Кто задаёт |
По умолчанию |
Назначение |
KLVD_WEB_LISTEN_PORT |
У |
8001 |
порт веб-интерфейса |
KLVD_WEB_LISTEN_IP |
C |
0.0.0.0 |
адрес прослушивания |
KLVD_WEB_HTTP_PORT |
У |
— |
порт перенаправления с http:// на https://. Пусто — перенаправления нет |
KLVD_WEB_THREADS |
C |
8 |
потоков веб-сервера |
KLVD_WEB_SSL_CERT |
C |
— |
сертификат HTTPS (сертификат и ключ в одном PEM-файле). Сертификат, загруженный через веб-интерфейс, имеет приоритет |
KLVD_WEB_FORCE_SSL |
— |
— |
любое значение запрещает запуск без сертификата |
Приём почты и доступ по IMAP
| Переменная |
Кто задаёт |
По умолчанию |
Назначение |
KLVD_SMTP_LISTEN_PORT |
— |
25 |
порт приёма SMTP; имеет приоритет над настройкой узла в интерфейсе |
KLVD_IMAP_LISTEN_PORT |
— |
993 |
порт IMAP; имеет приоритет над настройкой узла в интерфейсе |
KLVD_SMTP_QUEUE_DIR |
У, C |
/var/klvd/smtp-queue |
очередь принятых по SMTP писем до записи в архив |
KLVD_SMTP_MAX_CONN_PER_IP |
— |
из настроек, иначе 40 |
одновременных SMTP-соединений с одного адреса |
KLVD_SMTP_DRAIN_WORKERS |
— |
4 |
потоков записи писем из очереди SMTP в архив |
KLVD_SMTP_BATCH_SIZE |
— |
10 |
писем, которые один поток забирает из очереди за раз |
KLVD_SMTP_RECLAIM_LEASE_SEC |
— |
300 |
через сколько секунд письмо, взятое в обработку и не записанное, возвращается в очередь |
Хранилище
| Переменная |
Кто задаёт |
По умолчанию |
Назначение |
KLVD_STORAGE_LISTEN_PORT |
C |
8444 |
порт сервера хранилища |
KLVD_STORAGE_LISTEN_IP |
C |
0.0.0.0 |
адрес прослушивания |
KLVD_STORAGE_CONTENT_PATH |
C |
— |
папка с содержимым писем внутри контейнера |
KLVD_STORAGE_DATABASE_PATH |
C |
— |
файл служебной базы хранилища |
KLVD_STORAGE_SSL_CERT |
C |
— |
сертификат HTTPS хранилища |
KLVD_STORAGE_FORCE_SSL |
— |
— |
любое значение запрещает запуск хранилища без сертификата |
KLVD_STORAGE_SSL_VERIFY |
— |
0 |
1 — строгая проверка сертификатов при обмене между узлами |
KLVD_STORAGE_EXTERNAL_URL |
— |
определяется автоматически |
адрес хранилища для других узлов, если узел доступен по другому адресу (прокси, NAT) |
KLVD_STORAGE_THREADS |
— |
8 |
потоков сервера хранилища |
KLVD_STORAGE_PARALLEL |
— |
4 |
узлов, на которые копия отправляется одновременно (до 16) |
KLVD_STORAGE_BATCH_SIZE |
— |
16 |
частей письма в одном пакете при перераспределении (до 64) |
KLVD_STORAGE_PUSH_RETRIES |
— |
3 |
повторов отправки при сбое связи (до 10) |
KLVD_STORAGE_PUSH_RETRY_DELAY_MS |
— |
2000 |
пауза между повторами, мс (до 30000) |
Поиск
| Переменная |
Кто задаёт |
По умолчанию |
Назначение |
KLVD_SOLR_URL |
У |
— |
адрес службы поиска. Адрес, заданный в интерфейсе, имеет приоритет |
KLVD_SOLR_HOST |
— |
определяется автоматически |
адрес этого узла, публикуемый другим узлам для подключения к его Solr |
KLVD_SOLR_PORT |
— |
8983 |
порт Solr этого узла |
KLVD_SOLR_SCHEME |
— |
схема KLVD_SOLR_URL, иначе http |
http или https для адреса Solr этого узла |
KLVD_SOLR_EXTERNAL_URL |
— |
— |
полный адрес Solr этого узла для других узлов (вместо KLVD_SOLR_HOST/PORT/SCHEME) |
KLVD_SOLR_SSL_VERIFY |
— |
— |
1 — строгая проверка сертификата Solr; иначе самоподписанный сертификат принимается |
KLVD_SOLR_CA_PATH |
— |
— |
сертификат центра сертификации для проверки Solr (вместе с KLVD_SOLR_SSL_VERIFY=1) |
KLVD_INDEXER_WORKERS |
— |
4 |
потоков извлечения текста из вложений (до 32) |
Подключение к почтовым серверам
| Переменная |
Кто задаёт |
По умолчанию |
Назначение |
KLVD_VERIFY_CERTS_CA |
— |
false |
true — проверять TLS-сертификаты серверов Exchange (EWS) и IMAP при сборе почты, восстановлении писем и просмотре папок источника |
Мониторинг и диагностика
| Переменная |
Кто задаёт |
По умолчанию |
Назначение |
KLVD_METRICS_PORT |
— |
— |
включает порт метрик Prometheus (/metrics, /livez, /readyz) |
KLVD_DISK_MOUNTS |
— |
/,/var/klvd |
точки монтирования для метрик дискового пространства, через запятую |
KLVD_VERBOSE_LOGS |
— |
— |
1 — расширенные диагностические сообщения в журнале |
Прочее
| Переменная |
Кто задаёт |
По умолчанию |
Назначение |
KLVD_EXPORT_ZIP_MAX |
— |
500 |
сколько писем можно выгрузить одним ZIP-архивом из интерфейса |
KLVD_CONN_GRAPH_MANIFEST_DIR |
— |
/var/klvd/conn-graph |
папка подписанного списка внутренних доменов организации |
Папки на сервере (только .env)
Эти переменные использует docker-compose.yml, чтобы подключить папки сервера к контейнерам; сам узел их не читает.
| Переменная |
Назначение |
KLVD_IMAGE_TAG |
версия образа узла |
KLVD_STORAGE_DATA_HOST |
папка на сервере для содержимого писем |
KLVD_LOGS_HOST |
папка на сервере для журналов |
KLVD_TMP_HOST |
папка на сервере для временных файлов |
KLVD_SEARCH_INDEX_HOST |
папка на сервере для поискового индекса |
POSTGRESQL_CONF_HOST |
папка конфигурации локальной PostgreSQL |
Типовые изменения
| Задача |
Что сделать |
| Сменить порт веб-интерфейса |
изменить KLVD_WEB_LISTEN_PORT в .env |
| Включить перенаправление с HTTP на HTTPS |
задать свободный порт в KLVD_WEB_HTTP_PORT |
| Подключить внешнюю базу данных по шифрованному каналу |
POSTGRESQL_HOST, POSTGRESQL_SSL=verify-full, POSTGRESQL_SSLROOTCERT |
| Включить проверку сертификатов почтовых серверов |
KLVD_VERIFY_CERTS_CA=true |
| Подключить Prometheus |
KLVD_METRICS_PORT=9100 и открыть порт в межсетевом экране |
| Собрать диагностику для поддержки |
временно KLVD_VERBOSE_LOGS=1, после сбора — удалить |
Порты SMTP и IMAP удобнее задавать в интерфейсе для каждого узла — см. {{ССЫЛКА:maintenance.cluster-config|Изменение ролей и конфигурации узла}}. Переменная окружения имеет приоритет над интерфейсом, и интерфейс отмечает такой порт как «используется из ENV».
Что дальше
- {{ССЫЛКА:reference.env|Справочник: переменные окружения и Docker Compose}}
- {{ССЫЛКА:install.first-start|Первый вход и смена пароля администратора}}
Навигация по книге
- Следующая статья: {{ССЫЛКА:install.first-start|Первый вход и смена пароля администратора}}
