TLS и каналы связи

Назначение

Клавдий использует TLS для всех каналов: веб-интерфейс, серверы IMAP и SMTP, внутрикластерный трафик между узлом и сервером хранилища, поиск (Solr). Сертификаты хранятся централизованно в зашифрованном виде в базе и применяются всеми ролями на узле — без раздельных файлов на диске.

Загрузка и замена сертификата через веб-интерфейс — см. {{ССЫЛКА:install.tls-web|Установка → Общие настройки → TLS-сертификат}}. Здесь — технические детали.

Источник сертификата

Сертификат выбирается в следующем приоритете:

Хранилище в базе (config.tls_certificates, is_active=true) — приоритетнее. Загружается через веб-интерфейс. Расшифровывается (AES-256-GCM) и пишется во временный PEM-файл.
Переменная окружения KLVD_WEB_SSL_CERT (путь к PEM-файлу, сертификат и ключ в одном файле) — резерв, если в базе сертификата нет.
Отсутствие — только HTTP, без HTTPS. Не рекомендуется для рабочей эксплуатации.

При смене активного сертификата фоновая задача tls.cert.watch раз в 60 секунд сравнивает отпечаток сертификата и при изменении перезапускает слушатели веб-интерфейса, IMAP, SMTP и хранилища без перезапуска узла.

Веб-интерфейс

Порт: KLVD_WEB_LISTEN_PORT (по умолчанию 8001). При наличии сертификата служба работает по HTTPS.
Сертификат: из базы или KLVD_WEB_SSL_CERT.
Принудительный HTTPS: KLVD_WEB_FORCE_SSL=1 — узел остановится с ошибкой при отсутствии сертификата (защита от случайного HTTP в рабочей эксплуатации).

IMAP и SMTP

IMAP: сертификат из базы (тег imap) или KLVD_IMAP_SSL_CERT. См. {{ССЫЛКА:install.imap-service|Установка → Сервер IMAP}}.
SMTP: сертификат из базы (тег smtp) или KLVD_SMTP_SSL_CERT. См. {{ССЫЛКА:install.smtp-service|Установка → Сервер SMTP}}.

Внутрикластерный трафик хранилища (порт 8444)

Узел обращается к серверу хранилища (роль storage, порт KLVD_STORAGE_LISTEN_PORT, по умолчанию 8444) для чтения и записи чанков писем. Этот трафик тоже шифруется TLS — переиспользуется тот же активный сертификат из базы (тег storage).

Как это работает

Сервер хранилища (роль storage) при запуске загружает сертификат из базы и включает HTTPS на порту 8444. Путь к PEM-файлу сохраняется в контексте узла.
URL узла хранилища регистрируется в config.storages.url со схемой https://, если сертификат настроен. Внешний адрес можно переопределить через KLVD_STORAGE_EXTERNAL_URL.
Клиент на любом узле загружает сертификат из базы как CA для проверки соединения и передаёт его в curl.

Проверка сертификата — по умолчанию отключена

KLVD_STORAGE_SSL_VERIFY (по умолчанию 0):

Значение	Поведение
`0` (по умолчанию)	Проверка сертификата отключена. Самоподписанный сертификат принимается без проверки цепочки доверия. Режим предназначен для трафика между доверенными узлами Клавдия.
`1`	Строгая проверка: сертификат должен быть подписан доверенным центром сертификации, а имя или SAN — соответствовать адресу подключения.

По умолчанию строгая проверка отключена, поскольку в типовой установке узлы взаимодействуют внутри доверенной сети и используют общий самоподписанный сертификат из базы. Для строгой проверки требуется сертификат от доверенного центра с именем, соответствующим KLVD_STORAGE_EXTERNAL_URL. При обмене с узлами хранения через публичную сеть строгую проверку рекомендуется включить.

Переменные окружения (TLS хранилища)

Переменная	По умолчанию	Назначение
`KLVD_STORAGE_SSL_CERT`	(пусто)	Путь к PEM-файлу (резерв, если в базе сертификата нет). При наличии → HTTPS.
`KLVD_STORAGE_FORCE_SSL`	(пусто)	`1` → остановка при отсутствии сертификата (защита от случайного HTTP).
`KLVD_STORAGE_SSL_VERIFY`	`0`	`1` → включить проверку сертификата (нужен сертификат от доверенного центра).
`KLVD_STORAGE_LISTEN_PORT`	`8444`	Порт сервера хранилища.
`KLVD_STORAGE_EXTERNAL_URL`	(пусто)	Внешний URL хранилища (если за обратным прокси или на другом хосте). Формат: `http(s)://IP:порт`.

Поиск (Solr)

При локальном Solr контейнер klvd-solr получает тот же сертификат через секрет Docker и включает HTTPS на порту 8983. Скрипт запуска преобразует PEM в PKCS12 и настраивает Jetty. Для внешнего Solr использование HTTPS определяется его собственной конфигурацией; адрес задаётся в KLVD_SOLR_URL.

Проверка сертификата Solr по умолчанию отключена (KLVD_SOLR_SSL_VERIFY=0), поэтому самоподписанный сертификат принимается. Для внешнего Solr с доверенным сертификатом задайте KLVD_SOLR_SSL_VERIFY=1 и KLVD_SOLR_CA_PATH с путём к CA.

Ротация сертификата

Загрузите новый сертификат в веб-интерфейсе ([Общие настройки → TLS-сертификат → Загрузить]). Старый помечается как неактивный.
Фоновая задача tls.cert.watch в течение 60 секунд обнаруживает смену отпечатка и передаёт менеджеру ролей команду на перезапуск слушателей веб-интерфейса, IMAP, SMTP и хранилища.
URL узла хранилища в config.storages.url обновляется при следующем сигнале активности (heartbeat).
Та же фоновая задача обновляет сертификат Solr в /shared/solr-tls.pem. Solr применит его при следующем перезапуске (docker compose restart klvd-solr).

Ротация сертификата не требует перезапуска узла — слушатели перезапускаются автоматически. Веб-интерфейс кратко (около секунды) недоступен в момент перезапуска.

Самоподписанный сертификат

При установке создаётся самоподписанный сертификат (CN=klvd-wui), поэтому браузер показывает предупреждение о недоверенном сертификате. Для рабочей эксплуатации замените его сертификатом от доверенного центра сертификации через веб-интерфейс. Самоподписанный сертификат без SAN не проходит строгую проверку имени, поэтому внутрикластерная проверка сертификата по умолчанию отключена.

См. также

{{ССЫЛКА:install.tls-web|Установка → Общие настройки → TLS-сертификат}} — загрузка через веб-интерфейс
{{ССЫЛКА:maintenance.security-ops|Защита данных}} — общие принципы защиты
{{ССЫЛКА:reference.env|Конфигурация: .env и docker-compose}} — переменные окружения

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

Следующая статья: {{ССЫЛКА:reference.storage-encryption|Шифрование архива на диске}}