Переменные окружения и Docker Compose
Назначение
Конфигурация узла Клавдий хранится в двух файлах в папке установки:
-
.env— переменные окружения (пути, роли, параметры подключения). Не содержит паролей. -
docker-compose.yml— описание контейнеров, томов, секретов.
Вы можете редактировать эти файлы вручную, чтобы настроить узел под себя.
Важно:
update.shобновляет только образы контейнеров. Файлы.envиdocker-compose.ymlне перезаписываются — ваши настройки сохраняются при обновлении.update.shвносит точечные миграции (переименование сервисов, добавление HTTPS), но не трогает ваши значения. Перед редактированием делайте резервную копию.
Переменные окружения (.env)
Файл .env находится в папке установки (по умолчанию /opt/klvd/.env, права 0600). Пароли и ключи в нём не хранятся — они в папке secrets/.
Подключение к базе данных
| Переменная | По умолчанию | Назначение |
|---|---|---|
POSTGRESQL_HOST |
127.0.0.1 |
адрес сервера базы данных |
POSTGRESQL_PORT |
5432 |
порт подключения |
POSTGRESQL_DB |
klvd |
название базы данных |
POSTGRESQL_SSL |
prefer |
режим SSL: disable, prefer, require, verify-ca, verify-full |
Учётные данные (логин и пароль) хранятся в
secrets/pg_userиsecrets/pg_password(Docker secrets), не в.env.
Роли узла
| Переменная | По умолчанию | Назначение |
|---|---|---|
KLVD_ROLES |
(из установщика) | разрешённые роли через запятую: storage,importer(!),indexer(!),imap,smtp. Роль ui добавляется принудительно |
Веб-интерфейс
| Переменная | По умолчанию | Назначение |
|---|---|---|
KLVD_WEB_LISTEN_PORT |
8001 |
порт веб-интерфейса (ENV-override: приоритет выше значения узла в «Размещении слушателей») |
KLVD_WEB_LISTEN_IP |
0.0.0.0 |
адрес прослушивания |
KLVD_WEB_THREADS |
8 |
число потоков веб-сервера |
Приём почты (SMTP / IMAP) — порты-override
Переменные ниже — необязательные deployment-override портов слушателей. Они имеют приоритет выше значения узла (раздел [Кластер → Узлы → Размещение слушателей]); в интерфейсе это показано индикатором «используется из ENV». Чтобы вступило значение узла — не задавайте переменную. См. Кластер и узлы → Порты слушателей.
| Переменная | По умолчанию | Назначение |
|---|---|---|
KLVD_SMTP_LISTEN_PORT |
(пусто) | ENV-override порта SMTP-слушателя (иначе — значение узла / глобал smtp_listen_port / 25) |
KLVD_IMAP_LISTEN_PORT |
(пусто) | ENV-override порта IMAP-слушателя (иначе — значение узла / глобал imap_listen_port / 993) |
Поиск (Solr)
| Переменная | По умолчанию | Назначение |
|---|---|---|
KLVD_SOLR_URL |
(из установщика) | URL службы поиска. При локальном Solr — https://127.0.0.1:8983/solr. Пусто — поиск отключён |
Хранилище
| Переменная | По умолчанию | Назначение |
|---|---|---|
KLVD_STORAGE_LISTEN_PORT |
8444 |
порт сервера хранилища (ENV-override: приоритет выше значения узла в «Размещении слушателей») |
KLVD_STORAGE_LISTEN_IP |
0.0.0.0 |
адрес прослушивания |
KLVD_STORAGE_THREADS |
8 |
число потоков сервера хранилища. Увеличить при замедлении WUI во время перебалансировки |
KLVD_STORAGE_EXTERNAL_URL |
(пусто) | внешний URL хранилища, если узел за обратным прокси или на другом адресе. Формат: http(s)://IP:порт |
KLVD_STORAGE_SSL_VERIFY |
0 |
проверка сертификата внутрикластерного трафика: 0 — отключена (self-signed(!) принимается), 1 — строгая (нужен сертификат от доверенного центра) |
KLVD_STORAGE_PARALLEL |
4 |
число параллельных push-целей при перебалансировке (cap 16). При R>1 — копии льются параллельно |
KLVD_STORAGE_BATCH_SIZE |
16 |
число чанков в одном batch-запросе при перебалансировке (cap 64). R=1, 2 узла — пакетная отправка |
KLVD_STORAGE_PUSH_RETRIES |
3 |
сколько раз повторить push чанка при транспортной ошибке (цель недоступна/таймаут) до фиксации ошибки. Cap 10; 0 — без retry |
KLVD_STORAGE_PUSH_RETRY_DELAY_MS |
2000 |
пауза между попытками retry (мс, cap 30000). Фиксированная, не экспоненциальная — транспортный сбой чаще кратковременный |
Метрики узла
| Переменная | По умолчанию | Назначение |
|---|---|---|
KLVD_DISK_MOUNTS |
/,/var/klvd |
точки монтирования (через запятую), по которым собирать метрики дискового пространства. В Kubernetes — тома пода. См. Панель состояния → Ресурсы узла |
Пути (тома на хосте)
| Переменная | По умолчанию | Назначение |
|---|---|---|
KLVD_STORAGE_DATA_HOST |
./data-storage |
папка на хосте для данных хранилища писем |
KLVD_LOGS_HOST |
./logs |
папка на хосте для журналов приложения |
KLVD_TMP_HOST |
./tmp/klvd |
папка на хосте для временных файлов |
KLVD_SEARCH_INDEX_HOST |
./search-index |
папка на хосте для поискового индекса Solr |
POSTGRESQL_CONF_HOST |
./postgresql |
папка с конфигурацией локальной PostgreSQL |
Очередь SMTP
| Переменная | По умолчанию | Назначение |
|---|---|---|
KLVD_SMTP_QUEUE_DIR |
/var/klvd/smtp-queue |
путь очереди исходящих оповещений (роль smtp) |
Docker secrets (secrets/)
Секреты хранятся в папке secrets/ (права 0600) и монтируются в контейнер как Docker secrets (только чтение).
| Файл | Назначение |
|---|---|
secrets/klvd_secret_key |
главный секрет кластера (HMAC, шифрование). Одинаковый на всех узлах |
secrets/pg_user |
имя пользователя базы данных |
secrets/pg_password |
пароль базы данных |
secrets/ssl_cert |
TLS-сертификат веб-интерфейса (сертификат и ключ в одном PEM-файле) |
Меняйте секреты только через замену файлов в
secrets/с последующим перезапуском контейнера. Не храните пароли в.env.
docker-compose.yml
Файл docker-compose.yml описывает контейнеры, тома и секреты. Основные сервисы:
| Сервис | Назначение |
|---|---|
klvd-node |
узел Клавдия (веб-интерфейс, импорт, хранилище, индексация, IMAP, SMTP) |
klvd_postgres |
локальная база данных (только в режиме standalone(!)) |
klvd-solr |
служба полнотекстового поиска (при локальном Solr) |
klvd-zookeeper |
координация SolrCloud (при локальном Solr) |
Функциональные блоки
В compose есть маркеры блоков, которые установщик оставляет или удаляет по выбору:
-
{{POSTGRES}}…{{/POSTGRES}}— блок локальной PostgreSQL. Удаляется при внешней базе. -
{{SOLR}}…{{/SOLR}}— блок локального Solr и ZooKeeper. Удаляется при внешнем Solr. -
{{PG_DEPS}}…{{/PG_DEPS}}— зависимость узла от PostgreSQL. -
{{SOLR_DEPS}}…{{/SOLR_DEPS}}— зависимость узла от Solr.
Что можно менять
-
Пути томов — переменные
KLVD_*_HOSTв.env(см. выше). -
Порты — переменные
KLVD_WEB_LISTEN_PORT,KLVD_STORAGE_LISTEN_PORTв.env. -
Роли — переменная
KLVD_ROLESв.env. -
Параметры PostgreSQL — файлы в папке
POSTGRESQL_CONF_HOST(postgresql.conf,pg_hba.conf,init.sql).
Чего нельзя делать
-
Не удаляйте тома
app_data,pg_data,klvd_shared— в них хранятся данные узла и базы. -
Не меняйте
container_name— другие компоненты ссылаются на имена контейнеров. -
Не меняйте
network_mode: hostна bridge без понимания последствий — порты и адреса рассчитаны на host-сеть.
Как применить изменения
После редактирования .env или docker-compose.yml:
cd /opt/klvd
docker compose up -d --force-recreate
Контейнеры пересоздадутся с новыми параметрами. Данные в томах не затрагиваются.
Миграции базы данных применяются автоматически при старте узла — вручную изменять схему не нужно.
См. также
- Обновление системы — что update.sh трогает, а что нет
- База данных — пул соединений, миграции
- Установка — первичная установка
Навигация по книге
- Следующая статья: Модель безопасности