# Диагностика ошибок TLS

Сообщения об ошибке проверки сертификата на **Webim Server** редко называют исходную причину. Одна и та же строка появляется при обрыве цепочки, отсутствии корневого УЦ, устаревшем OpenSSL, расхождении хранилищ хоста и контейнера и при неверном имени в сертификате.

## Как выглядит ошибка

В логах **Chat Backend** / **Admin Backend** и в трассировке Python чаще всего встречается:

```
ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED]
...
certificate verify failed: unable to get local issuer certificate (_ssl.c:1091)
...
Connection #0 to host some.domain.local left intact
```

Встречаются и близкие формулировки библиотеки OpenSSL:

  * `unable to get local issuer certificate` — не найден издатель очередного сертификата в цепочке (нет промежуточного в ответе сервера или нет корневого/промежуточного УЦ в локальном хранилище);

  * `self signed certificate` / `self signed certificate in certificate chain` — самоподписной сертификат, который не добавлен в доверенные;

  * `certificate has expired` — истек срок действия листа, промежуточного или корневого CA;

  * `Hostname mismatch` / `certificate verify failed: IP address mismatch` — имя в сертификате не совпадает с именем, к которому подключаются.

Номер `(_ssl.c:…)` указывает строку исходного кода Python/OpenSSL и **не** кодирует причину.

!!! Note "N.B."
    Сначала определите направление: Webim **принимает** соединение или **сам ходит** наружу. Текст ошибки при этом может совпадать. См. [обзор сценариев](https://webim.ru/kb/devops/tls-certificates/#two-scenarios).

## Где смотреть

**Docker**

```
docker compose -f /etc/webim/docker-compose.yml logs --tail=200 chat_backend
```

**Установка на хост**

```
tail -n 200 /var/log/pro/tornado-8260.log
```

Порт в имени файла совпадает с портом **Chat Backend**. Для **Admin Backend** смотрите журнал соответствующей службы.

Дополнительно полезны системные журналы (`journalctl`) и время узла: при большом расхождении часов сертификат может считаться ещё недействительным или уже просроченным.

## Порядок проверки

Идите по шагам сверху вниз. На каждом шаге фиксируйте, **из какого** окружения Вы запускаете команду: с хоста или из контейнера. Результат `openssl` на хосте ничего не говорит о процессе внутри Docker.

### 1. Уточните хост и направление

Из текста ошибки или соседних строк лога возьмите имя узла (`platform-api2.max.ru`, значение `base_domain`, URL интеграции).

  * Если это внешний API канала, CRM, SMTP — сценарий [исходящих соединений](https://webim.ru/kb/devops/tls-certificates/outgoing.html).

  * Если это домен самого Webim или внутреннее имя за балансировщиком — сценарий [входящих соединений](https://webim.ru/kb/devops/tls-certificates/incoming.html).

### 2. Посмотрите цепочку, которую реально отдаёт сервер

Замените `host.example.local` на имя из шага 1:

```
echo | openssl s_client -connect host.example.local:443 \
  -servername host.example.local -showcerts
```

Обратите внимание на:

  * `Verify return code` — `0 (ok)` или текст ошибки;

  * число блоков `BEGIN CERTIFICATE` — листовой плюс промежуточные;

  * `subject` и `issuer` каждого звена: `issuer` листа должен совпадать с `subject` следующего сертификата;

  * `notBefore` / `notAfter`.

Если в ответе только листовой сертификат, а его `issuer` — не корневой УЦ из системного набора, цепочка оборвана на стороне **сервера-источника**. Для входящего HTTPS-трафика Webim это значит: в файл `ssl_certificate` не добавлен промежуточный УЦ. Для исходящего — либо удалённый сервис не отдаёт промежуточный, либо его нужно положить в локальное хранилище.

### 3. Проверьте системное хранилище

```
openssl version
apt-cache policy openssl ca-certificates
ls /usr/local/share/ca-certificates
grep -c 'BEGIN CERTIFICATE' /etc/ssl/certs/ca-certificates.crt
```

  * Пакеты `openssl` и `ca-certificates` должны быть из актуального обновления серверной ОС, не старее `1.1.1`. Устаревший OpenSSL может не понимать современные алгоритмы и расширения.

  * Файлы нестандартных УЦ должны лежать в директории `/usr/local/share/ca-certificates/` (или в поддиректории) с расширением `.crt` и пройти `update-ca-certificates`.

Проверка конкретного УЦ против системного набора:

```
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt custom-ca.crt
```

### 4. Проверьте то хранилище, которым пользуется Python

```
cd /opt/webim/envs/eta/chat_backend.venv/bin
source activate
python3 -c "import ssl, certifi; print(ssl.get_default_verify_paths()); print(certifi.where())"
python3 -c "import os; print(os.environ.get('SSL_CERT_FILE')); print(os.environ.get('REQUESTS_CA_BUNDLE'))"
```

В Docker те же команды запускайте через `docker compose … exec` в контейнере `chat_backend`.

Частый рассогласованный результат:

  * `openssl s_client` на хосте — `Verify return code: 0`;

  * `requests.get(...)` в контейнере — `CERTIFICATE_VERIFY_FAILED`.

Это значит, что УЦ добавлен не туда: хостовое хранилище обновлено, а процесс Webim читает `certifi` внутри контейнера. Исправление — в статье [Добавление удостоверяющего центра](https://webim.ru/kb/devops/tls-certificates/adding-ca.html).

Проверка из окружения **Webim Chat Backend**:

```
cd /opt/webim/envs/eta/chat_backend.venv/bin
source activate
python3 -c "import requests; requests.get('https://host.example.local', timeout=10)"
```

### 5. Сверьте имя в сертификате

```
echo | openssl s_client -connect host.example.local:443 \
  -servername host.example.local 2>/dev/null \
  | openssl x509 -noout -subject -ext subjectAltName
```

Имя, к которому подключается Webim, должно совпадать с CN или SAN. Подключение по IP при сертификате на FQDN проверку не пройдёт. **Webim Server** и так требует FQDN, см. [требования к доменному имени](https://webim.ru/kb/devops/sys-reqs-for-server/sys-reqs-server-nw.html#domain-name-requirements).

### 6. Исключите прокси с подменой сертификата

Если исходящий трафик идёт через прокси с SSL inspection, клиент видит сертификат прокси, а не MAX или CRM. Тогда в доверенные нужно добавить УЦ прокси. Настройки прокси Webim описаны в статье [Использование прокси](https://webim.ru/kb/devops/proxy.html).

## Типовые причины

| Что наблюдаете                                                                    | Вероятная причина                                                  | Что сделать                                                                                         |
|-----------------------------------------------------------------------------------|--------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
| `unable to get local issuer certificate`, в `s_client -showcerts` один сертификат | В файле сертификата нет промежуточного УЦ                          | Собрать fullchain (лист + промежуточные) и перечитать **nginx** / балансировщик                     |
| Та же ошибка, цепочка на сервере полная                                           | Нет корневого (или промежуточного) УЦ в хранилище клиента          | [Добавить УЦ](https://webim.ru/kb/devops/tls-certificates/adding-ca.html) в то окружение, где работает процесс Webim                              |
| `openssl` на хосте успешен, канал (например, MAX) в Docker — нет                  | Нет файла `/etc/webim/ssl/ca-certificates.crt` или контейнер не перезапущен | Положить УЦ в этот файл и перезапустить бэкенды, см. [установку в Docker](https://webim.ru/kb/devops/tls-certificates/adding-ca.html#install-in-docker) |
| `openssl` в контейнере успешен, `requests` — нет                                  | Python читает `certifi`, а не системный набор                      | Задать `SSL_CERT_FILE` и `REQUESTS_CA_BUNDLE` процессу Webim                                        |
| Ошибка в **Delta Proxy** после пересоздания контейнера                            | Нет файла `/etc/webim/ssl/ca-certificates.crt` на хосте или контейнер не перезапущен | Положить УЦ в этот файл и перезапустить контейнер: `start.sh` импортирует его при старте, см. [Delta Proxy](https://webim.ru/kb/devops/tls-certificates/adding-ca.html#delta-proxy) |
| Ошибка появилась после `docker compose pull` / `up --force-recreate`              | Нет файла `/etc/webim/ssl/ca-certificates.crt` на хосте            | Проверить файл и перезапустить контейнер: скрипт запуска импортирует УЦ при старте                  |
| `certificate has expired`                                                         | Истёк лист, промежуточный или корневой УЦ                          | Выпустить новый сертификат или обновить файл УЦ                                                      |
| Ошибка только в рабочее время / после смены часов                                 | Неверное время на сервере                                          | Настроить NTP; сравнить `date -Is` с контрольным источником                                         |
| Ошибка после обновления ОС                                                        | Старый OpenSSL / пакет `ca-certificates`                           | `apt-get update && apt-get install --only-upgrade openssl ca-certificates`                          |
| Самоподписной сертификат на **внешнем** домене, жалуются посетители               | Браузер или SDK не доверяет сертификату                            | Вынести доверенный сертификат на балансировщик; самоподписной оставить только на внутреннем участке |

## Что приложить в обращение в поддержку

Если после этих шагов ошибка остаётся, напишите в [техническую поддержку](mailto:support@webim.ru) **Webim**. К письму приложите:

  * направление (входящее к Webim или исходящее к конкретному хосту);

  * способ установки (Docker или хост) и версию **Webim**;

  * фрагмент лога с полной строкой `SSLCertVerificationError`;

  * вывод `openssl s_client … -showcerts` к проблемному хосту **из того же окружения**, где падает процесс;

  * вывод `python3 -c "import ssl, certifi, os; …"` (пути хранилищ и переменные `SSL_CERT_FILE` / `REQUESTS_CA_BUNDLE`);

  * версии `openssl` и `ca-certificates`.

Не присылайте закрытые ключи из соображений безопасности.

## Связанные статьи

  * [TLS-сертификаты: обзор](https://webim.ru/kb/devops/tls-certificates/)

  * [Добавление удостоверяющего центра](https://webim.ru/kb/devops/tls-certificates/adding-ca.html)

  * [Входящие соединения](https://webim.ru/kb/devops/tls-certificates/incoming.html)

  * [Исходящие соединения](https://webim.ru/kb/devops/tls-certificates/outgoing.html)

  * [Безопасность исходящих HTTP(S)-запросов](https://webim.ru/kb/devops/outgoing-http-tls.html)

---

Источник: https://webim.ru/kb/devops/tls-certificates/troubleshooting.html
