Добавление удостоверяющего центра
Чтобы Webim Server доверял нестандартному сертификату, соответствующий удостоверяющий центр (УЦ, CA) нужно добавить в хранилище, которым реально пользуются процессы Webim Server. Одной команды update-ca-certificates часто недостаточно: системные компоненты (openssl, curl) и библиотеки Python (requests, httpx, certifi) читают разные наборы УЦ.
Эту процедуру выполняют и для входящих, и для исходящих соединений. Меняется только состав файлов УЦ.
Важно
Отключать проверку сертификатов (smtp_skip_ssl_checks) вместо добавления УЦ не рекомендуется. Так можно скрыть подмену сертификата и другие атаки на канал.
Что понадобится
-
права администратора на сервере Webim;
-
актуальные версии пакетов
ca-certificatesиopenssl(есть в типовой установке Debian 12.5, см. требования к ПО); -
файлы УЦ в формате PEM, по одному сертификату в файле, с расширением
.crt.
Проверьте формат:
grep -c -- '-----BEGIN CERTIFICATE-----' custom-ca.crt
openssl x509 -inform PEM -in custom-ca.crt -noout -subject -issuer -dates
В каждом файле должна быть ровно одна строка BEGIN CERTIFICATE. Если файл в бинарном формате DER, преобразуйте его:
openssl x509 -inform DER -in custom-ca.cer -outform PEM -out custom-ca.crt
Почему одного системного хранилища мало
| Кто проверяет сертификат | Откуда берёт УЦ | Обновляется update-ca-certificates |
|---|---|---|
openssl, curl, часть системных утилит |
/etc/ssl/certs/ca-certificates.crt |
Да |
Модуль ssl в Python (зависит от сборки) |
пути OpenSSL, см. ssl.get_default_verify_paths() |
Обычно да |
requests, httpx и другие библиотеки с certifi |
собственный файл cacert.pem внутри пакета certifi |
Нет |
Компоненты Webim используют requests и httpx. Поэтому после добавления УЦ в ОС нужно либо направить эти библиотеки на системный набор, либо дописать УЦ в файл certifi. Первый способ устойчивее: обновление пакета certifi не затирает настройку.
Установка на хост (без Docker)
-
Скопируйте файлы УЦ в каталог локальных сертификатов. Один сертификат — один файл с расширением
.crt:sudo install -d -m 0755 /usr/local/share/ca-certificates/webim sudo install -m 0644 custom-ca.crt /usr/local/share/ca-certificates/webim/ -
Обновите системное хранилище:
sudo update-ca-certificatesПри первом добавлении утилита обычно сообщает
1 added. Повторный запуск может вывести0 added. -
Направьте библиотеки Python на системный набор. Для systemd-служб Webim создайте drop-in, например
/etc/systemd/system/webim-tornado.service.d/tls.confдля Chat Backend и аналогичный файл для Admin Backend:[Service] Environment=SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt Environment=REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt Environment=CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crtЗатем:
sudo systemctl daemon-reload sudo systemctl restart webim-tornado sudo systemctl restart webim-admin-backendЕсли в Вашей установке имена служб другие, задайте те же переменные в их unit-файлах или в окружении процессов Chat Backend и Admin Backend.
-
Проверьте, что УЦ попал в системный набор и что Python видит тот же файл:
ls /etc/ssl/certs | grep -i custom python3 -c "import ssl; print(ssl.get_default_verify_paths())" python3 -c "import os; print(os.environ.get('SSL_CERT_FILE')); print(os.environ.get('REQUESTS_CA_BUNDLE'))"
Переменные окружения должны быть заданы у процесса Webim, а не только в Вашей терминальной сессии.
Запасной способ: дописать УЦ в certifi
Если задать переменные окружения нельзя, добавьте УЦ в файл пакета certifi. Путь зависит от окружения Python:
python3 -c "import certifi; print(certifi.where())"
Пример:
CERTIFI_BUNDLE="$(python3 -c 'import certifi; print(certifi.where())')"
sudo cp "$CERTIFI_BUNDLE" "${CERTIFI_BUNDLE}.bak"
cat custom-ca.crt | sudo tee -a "$CERTIFI_BUNDLE" >/dev/null
Этот файл перезаписывается при обновлении пакета или образа. После обновления Python-зависимостей или смены образа проверку нужно повторить.
Установка в Docker
Здесь и далее подразумевается, что YAML от Docker Compose находится в /etc/webim/docker-compose.yml. При необходимости замените путь и имя на другое.
Хранилище УЦ хоста контейнерам не передаётся.
Для Chat Backend и Admin Backend подходят три способа ниже. Способ с готовым бандлом устойчив к пересозданию контейнеров и не требует менять command сервисов. Для Delta Proxy достаточно штатного импорта при запуске контейнера, см. отдельное описание.
Подготовьте каталог на хосте и положите туда PEM-файлы с расширением .crt. Директорию /etc/webim/extra-ca-certificates Webim Server по умолчанию не читает, скрипты образов ждут файл /etc/webim/ssl/ca-certificates.crt. Том /etc/webim уже смонтирован в образы в стандартном Docker Compose YAML.
Способ 1. Использовать скрипт start.sh (предпочтительный)
У Docker-образов стандартной поставки Webim есть entrypoint-скрипт start.sh (у компонентов Chat Backend, Admin Backend, History Backend, Image Robot).
Скрипт при старте берёт /etc/webim/ssl/ca-certificates.crt и вызывает update-ca-certificates. Достаточно положить УЦ в этот файл и перезапустить сервисы. Собирать полный системный набор по такой директории и добавлять volume напрямую на этот файл в Docker Compose YAML в этом случае не нужно — монтируется /etc/webim/.
Способ 2. Смонтировать готовый PEM-бандл
Данный способ в стандартной поставке Webim не используется.
Держите исходные УЦ отдельными файлами (custom-ca.crt, russian_trusted_root_ca_pem.crt) и собирайте из них бандл явно — так в него не попадёт сам ca-bundle.crt.
-
Возьмите системный набор из контейнера (он может отличаться от набора хоста) и допишите свои УЦ:
docker compose -f /etc/webim/docker-compose.yml exec -T chat_backend \ cat /etc/ssl/certs/ca-certificates.crt \ | sudo tee /etc/webim/extra-ca-certificates/ca-bundle.crt >/dev/null sudo sh -c 'cat /etc/webim/extra-ca-certificates/custom-ca.crt \ >> /etc/webim/extra-ca-certificates/ca-bundle.crt'Если УЦ несколько (например, корневой и выпускающий сертификаты Минцифры РФ), допишите каждый файл отдельной командой
cat … >>.Если на хосте и в контейнере одна и та же Debian 12.5, можно сначала выполнить
update-ca-certificatesна хосте и взять за основу/etc/ssl/certs/ca-certificates.crtхоста. Если версии ОС или пакетаca-certificatesразличаются, берите базовый набор из контейнера. -
В
/etc/webim/docker-compose.ymlдля Chat Backend и Admin Backend добавьте том и переменные окружения:volumes: - /etc/webim/extra-ca-certificates/ca-bundle.crt:/etc/ssl/certs/ca-certificates.crt:ro environment: SSL_CERT_FILE: /etc/ssl/certs/ca-certificates.crt REQUESTS_CA_BUNDLE: /etc/ssl/certs/ca-certificates.crt CURL_CA_BUNDLE: /etc/ssl/certs/ca-certificates.crtДанные переменные по умолчанию заданы в Dockerfile образов (
/etc/ssl/certs/ca-certificates.crt), представляют интерес, если их значения нужно изменить.При этом
CURL_CA_BUNDLEв Dockerfile нет.Точные имена сервисов смотрите в выданном архиве
docker-compose. Если у сервиса уже есть блокenvironmentилиvolumes, допишите строки в него, а не создавайте второй одноимённый блок. Если исходящие запросы выполняет ещё один бэкенд, повторите настройку и для него. -
Примените конфигурацию:
docker compose -f /etc/webim/docker-compose.yml up -d
После смены образа заново соберите бандл: базовый набор УЦ в новом образе может отличаться.
Способ 3. Смонтировать отдельные УЦ и обновить хранилище в контейнере
Используйте, если стандартный start.sh почему-то не подходит и Вы хотите выполнить аналогичные действия самостоятельно.
Учитывайте, что по умолчанию эти изменения затрутся в последнем слое контейнера после рестарта.
-
Смонтируйте каталог с файлами
.crtв/usr/local/share/ca-certificates/webimконтейнеров Chat Backend и Admin Backend. -
После создания контейнера выполните:
docker compose -f /etc/webim/docker-compose.yml exec chat_backend update-ca-certificatesПовторите для Admin Backend и остальных бэкендов, которые ходят наружу по HTTPS.
-
Задайте те же переменные
SSL_CERT_FILE,REQUESTS_CA_BUNDLEиCURL_CA_BUNDLE, что и в способе 2, и перезапустите сервисы:docker compose -f /etc/webim/docker-compose.yml restart chat_backendКоманда
restartсохраняет изменения в файловой системе контейнера. Командыdown/up --force-recreateи смена образа создают контейнер заново —update-ca-certificatesнужно выполнить снова.
Способ 3 уместен для разовой проверки. Для постоянной эксплуатации надёжнее способ 1.
Скрипт запуска бэкендов
В образах бэкендов есть и штатный скрипт запуска (start.sh). Если при старте существует /etc/webim/ssl/ca-certificates.crt, скрипт копирует его в /usr/share/ca-certificates/ и выполняет update-ca-certificates. Так устроены, в частности, Chat Backend, Admin Backend, History Backend, image_robot. Каталог /etc/webim в типовой поставке уже смонтирован в контейнеры.
-
Положите PEM-файл с дополнительными УЦ в
/etc/webim/ssl/ca-certificates.crtна хосте. Если УЦ несколько, объедините их в этот файл:sudo install -d -m 0755 /etc/webim/ssl sudo install -m 0644 custom-ca.crt /etc/webim/ssl/ca-certificates.crt -
Перезапустите контейнеры, чтобы скрипт запуска отработал снова:
docker compose -f /etc/webim/docker-compose.yml restart chat_backend agent_backend
После смены образа файл на хосте остаётся на месте: новый контейнер снова прочитает его при старте. Если после update-ca-certificates библиотека requests всё ещё отвечает CERTIFICATE_VERIFY_FAILED, задайте процессу переменные SSL_CERT_FILE и REQUESTS_CA_BUNDLE, как в установке на хост.
Сертификат и ключ, которые nginx предъявляет клиентам, — это другие файлы. Их пути фиксированы в образе, см. Входящие соединения.
Delta Proxy
Delta Proxy — отдельный компонент (специальные сборки), который ходит на HTTPS-адрес аккаунта (ROOT_URL_FORMAT) как клиент. Production-образ запускается скриптом start.sh: Dockerfile добавляет его в /usr/local/bin и указывает в CMD. Если при старте существует /etc/webim/ssl/ca-certificates.crt, скрипт копирует его в /usr/share/ca-certificates/ и выполняет update-ca-certificates. Скрипт задаёт SSL_CERT_FILE и REQUESTS_CA_BUNDLE равными /etc/ssl/certs/ca-certificates.crt и после этого запускает poetry run python api.py. Каталог /etc/webim/ssl/ca-certs тоже подхватывается: файлы из него копируются в /usr/local/share/ca-certificates/.
-
Положите тот же PEM-файл
/etc/webim/ssl/ca-certificates.crtна хост. Если вdocker-composeдля Delta Proxy уже смонтирован каталог/etc/webim, отдельный том не нужен. Иначе смонтируйте файл явно:volumes: - /etc/webim/ssl/ca-certificates.crt:/etc/webim/ssl/ca-certificates.crt:ro -
Перезапустите контейнер, чтобы скрипт запуска отработал снова:
docker compose -f /etc/webim/docker-compose.yml restart delta_proxyИмя сервиса возьмите из Вашей поставки Delta Proxy.
Чтобы обновить сертификат, замените файл на хосте и перезапустите контейнер — пересобирать образ не нужно. После down / up --force-recreate или смены образа файл на хосте остаётся на месте: новый контейнер снова копирует его в хранилище УЦ при старте.
Что не нужно делать
-
Не кладите в хранилище УЦ закрытый ключ серверного сертификата.
-
Для файлов в
/usr/local/share/ca-certificates/: не кладите в каталог УЦ сразу всю цепочку одним файлом:update-ca-certificatesожидает один сертификат в каждом.crt. Готовый бандл из способа 2 и файл/etc/webim/ssl/ca-certificates.crtдля скрипта запуска — отдельные случаи: туда как раз собирают несколько PEM-блоков. -
Для штатного
/etc/webim/ssl/ca-certificates.crtнаоборот: в один файл можно дописать несколько PEM-блоков (корневой и промежуточный Минцифры РФ). -
Не ограничивайтесь установкой УЦ в браузер администратора: процессы Webim Server этот набор не используют.
-
Не считайте достаточной установку только в хранилище хоста, если Webim работает в Docker: контейнер должен увидеть УЦ через один из способов выше.
-
Не путайте файл дополнительных УЦ (
/etc/webim/ssl/ca-certificates.crt) с сертификатом и ключом nginx (/etc/webim/ssl/server.crt,/etc/webim/ssl/server.key).
Дальше вернитесь к сценарию, из-за которого Вы добавляли УЦ: входящие соединения или исходящие соединения. Проверка и разбор ошибок — в статье Диагностика ошибок TLS.