Переменные окружения и 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». Чтобы вступило значение узла — не задавайте переменную. См. {{ССЫЛКА:maintenance.cluster-status|Кластер и узлы → Порты слушателей}}.

Переменная	По умолчанию	Назначение
`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 — тома пода. См. {{ССЫЛКА:maintenance.dashboard

Пути (тома на хосте)

Переменная	По умолчанию	Назначение
`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

Контейнеры пересоздадутся с новыми параметрами. Данные в томах не затрагиваются.

Миграции базы данных применяются автоматически при старте узла — вручную изменять схему не нужно.

См. также

{{ССЫЛКА:maintenance.update-compose|Обновление системы}} — что update.sh трогает, а что нет

{{ССЫЛКА:maintenance.db-health|База данных}} — пул соединений, миграции

{{ССЫЛКА:install.choose-topology|Установка}} — первичная установка

Навигация по книге

Следующая статья: {{ССЫЛКА:reference.security-model|Модель безопасности}}