Перейти к содержанию

Добавление удостоверяющего центра

Чтобы 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)

  1. Скопируйте файлы УЦ в каталог локальных сертификатов. Один сертификат — один файл с расширением .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/
    
  2. Обновите системное хранилище:

    sudo update-ca-certificates
    

    При первом добавлении утилита обычно сообщает 1 added. Повторный запуск может вывести 0 added.

  3. Направьте библиотеки 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.

  4. Проверьте, что УЦ попал в системный набор и что 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.

  1. Возьмите системный набор из контейнера (он может отличаться от набора хоста) и допишите свои УЦ:

    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 различаются, берите базовый набор из контейнера.

  2. В /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, допишите строки в него, а не создавайте второй одноимённый блок. Если исходящие запросы выполняет ещё один бэкенд, повторите настройку и для него.

  3. Примените конфигурацию:

    docker compose -f /etc/webim/docker-compose.yml up -d
    

После смены образа заново соберите бандл: базовый набор УЦ в новом образе может отличаться.

Способ 3. Смонтировать отдельные УЦ и обновить хранилище в контейнере

Используйте, если стандартный start.sh почему-то не подходит и Вы хотите выполнить аналогичные действия самостоятельно.

Учитывайте, что по умолчанию эти изменения затрутся в последнем слое контейнера после рестарта.

  1. Смонтируйте каталог с файлами .crt в /usr/local/share/ca-certificates/webim контейнеров Chat Backend и Admin Backend.

  2. После создания контейнера выполните:

    docker compose -f /etc/webim/docker-compose.yml exec chat_backend update-ca-certificates
    

    Повторите для Admin Backend и остальных бэкендов, которые ходят наружу по HTTPS.

  3. Задайте те же переменные 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 в типовой поставке уже смонтирован в контейнеры.

  1. Положите 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
    
  2. Перезапустите контейнеры, чтобы скрипт запуска отработал снова:

    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/.

  1. Положите тот же 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
    
  2. Перезапустите контейнер, чтобы скрипт запуска отработал снова:

    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.