Решение проблем#

В этом разделе собраны типовые проблемы, способы их решения и подсказки, где посмотреть логи. Выберите нужную категорию и откройте выпадающий блок с инструкцией.

Окружение#

Ошибки при установке Python-библиотек

Если при установке библиотек появляется ошибка:

error: externally-managed-environment

Причина: в системе включен режим защиты Python-пакетов (externally managed environment).

Решение:

Вариант 1 (сервер только под Compass):

sudo pip3 install pyyaml==6.0.2 pyopenssl==24.0.0 docker==7.1.0 \
  mysql-connector-python==8.2.0 python-dotenv==1.0.0 psutil==5.9.6 \
  pycryptodome==3.21.0 --break-system-packages

Вариант 2 (использовать виртуальное окружение):

sudo apt update
sudo apt install -y python3-venv
python3 -m venv venv
source ./venv/bin/activate
pip install --upgrade pip
pip install pyyaml==6.0.2 pyopenssl==24.0.0 docker==7.1.0 mysql-connector-python==8.2.0 \
  python-dotenv==1.0.0 psutil==5.9.6 pycryptodome==3.21.0

Запускайте установочные скрипты из виртуального окружения:

sudo -E env "PATH=$PATH" python3 script/install.py
Ошибка отсутствия Python-библиотеки

Если при запуске любого Python-скрипта появляется ошибка отсутствующей библиотеки, например:

ModuleNotFoundError: No module named 'docker'

Вместо docker может быть указана другая библиотека.

Причина: библиотека не установлена в том окружении Python, из которого запускается скрипт (системный Python на сервере или виртуальное окружение).

Что проверить / Решение:

  • Если запускаете скрипт на хосте (без venv):

    1. Проверьте, что зависимости установлены:

    python3 -m pip list | grep -E \
 "PyYAML|pyOpenSSL|docker|mysql-connector-python|python-dotenv|psutil|pycryptodome"

    1. Если каких-то пакетов нет — установите зависимости:

    sudo python3 -m pip install \
  pyyaml==6.0.2 pyopenssl==24.0.0 docker==7.1.0 \
  mysql-connector-python==8.2.0 python-dotenv==1.0.0 psutil==5.9.6 \
  pycryptodome==3.21.0

    1. Если при установке появляется error: externally-managed-environment — используйте инструкции из блока Ошибки при установке Python-библиотек.

    2. Повторите запуск скрипта:

    sudo python3 script/install.py

  • Если запускаете скрипт в виртуальном окружении (venv):

    1. Убедитесь, что окружение активировано.

    Обычно после активации в начале строки терминала появляется префикс вида (<имя_окружения>). Также можно проверить через переменную окружения:

    echo $VIRTUAL_ENV

    Интерпретация:

    • если вывело путь (например /home/user/venv) — окружение активировано;

    • если пусто — не активировано.

    Активируйте виртуальное окружение (путь зависит от имени директории окружения). Если окружение создавали командой python3 -m venv venv:

    source ./venv/bin/activate

    Если окружение создавали с другим именем (например my-venv) — подставьте его вместо venv в команде выше.

    1. Проверьте зависимости в venv:

    python3 -m pip list | grep -E \
 "PyYAML|pyOpenSSL|docker|mysql-connector-python|python-dotenv|psutil|pycryptodome"

    1. Если каких-то пакетов нет — установите зависимости в venv:

    python3 -m pip install \
  pyyaml==6.0.2 pyopenssl==24.0.0 docker==7.1.0 \
  mysql-connector-python==8.2.0 python-dotenv==1.0.0 psutil==5.9.6 \
  pycryptodome==3.21.0

    1. Запускайте скрипт из активированного venv:

    sudo -E env "PATH=$PATH" python3 script/install.py

Развертывание#

Ошибка при развертывании приложения

Если при развертывании появляется:

php_monolith не может подняться
php_monolith не поднялся

Что проверить:

  • Соответствие минимальным требованиям.

    Минимальные требования:

    • CPU: 12 cores

    • RAM: 20 GB

    • SSD: 200 GB

    • IOPS: ≈ 1200 суммарно (read + write)

    Команды:

    • CPU: lscpu

    • RAM: free -h

    • Диск (объем): df -h

  • IOPS диска (fio).

    Установить fio:

    sudo apt update
sudo apt install -y fio

    Запустить тест:

    fio --name=iops-test \
  --ioengine=libaio \
  --rw=randrw \
  --rwmixread=50 \
  --bs=4k \
  --direct=1 \
  --size=2G \
  --numjobs=4 \
  --iodepth=32 \
  --runtime=30s \
  --time_based \
  --group_reporting

    Ориентир: сумма avg для read iops и write iops должна быть ≈ 1200.

  • Готовность сервисов после запуска установки (обычно 3–15 минут).

    Проверьте состояние сервисов:

    sudo docker service ls | grep -vE "default-file|jitsi-custom"

    В колонке REPLICAS значения должны совпадать (например, 1/1). Если у сервиса не сходятся реплики — посмотрите детали:

    sudo docker service ps <ID_или_NAME_сервиса> --no-trunc

    И логи сервиса:

    sudo docker service logs -f --tail 200 <ID_или_NAME_сервиса>

Решение:

  • Если ресурсы/IOPS ниже требований — приведите сервер к минимальным значениям и повторите установку.

  • Если ресурсы/IOPS в норме — найдите сервис, который не выходит в нужные реплики (REPLICAS), и проверьте service ps и service logs.

  • Если по логам не ясно — выполните переустановку.

Удаление (с подтверждением удаления данных — два раза):

sudo python3 script/uninstall.py

Конфигурационные файлы не удалятся — повторно заполнять их не потребуется.

Перезапустите Docker:

sudo systemctl restart docker

Запустите установку повторно:

sudo python3 script/install.py
Ошибка при активации сервера

Если при активации появляется сообщение:

Не удалось активировать сервер. Сервер недоступен по адресу <your-domain.com>.

Причина: домен недоступен извне или DNS настроен неверно.

Что проверить:

  • A-запись домена указывает на публичный IP сервера;

  • По домену доступен HTTPS (443/tcp);

  • Если сеть закрытая — вход на 443/tcp разрешен для сервера лицензии 45.92.177.63.

Проверить A-запись домена:

dig +short A your-domain.com

Проверить доступность домена по HTTPS (с любого внешнего хоста):

curl -vk https://your-domain.com

Если запрос не проходит, проверьте:

  • входящие правила firewall (UFW/iptables/Security Group) для порта 443/tcp;

  • настройки обратного прокси (если используется).

Если сеть закрытая (доступ ограничен по IP):

Убедитесь, что firewall разрешает входящие подключения на 443/tcp для 45.92.177.63. Команды зависят от фаервола, ниже пример для iptables.

Проверить правила для 443:

sudo iptables -L INPUT -n --line-numbers | grep 443

Если правила не выводятся — проверьте политику INPUT:

sudo iptables -L INPUT -n | head -n 1

  • policy ACCEPT — входящие подключения разрешены.

  • policy DROP или REJECT — нужен явный allow на 443 (или на IP 45.92.177.63).

Решение: исправьте DNS/доступность домена и убедитесь, что вход на 443 разрешен, затем повторите активацию.

Диагностика#

Логи с ошибками приложения

Проверить ошибки приложения можно в следующих логах контейнера php_monolith:

sudo docker exec -it $(sudo docker ps | grep php_monolith | awk '{print $1}') \
  bash -c "cat /app/logs/__php_critical.log"

sudo docker exec -it $(sudo docker ps | grep php_monolith | awk '{print $1}') \
  bash -c "cat /app/logs/__php_error.log"

Авторизация#

Не приходит код на почту

Причина: SMTP недоступен / неверные параметры или соединение блокируется.

Что проверить:

  • Лог отправки писем:

sudo docker exec -it $(sudo docker ps | grep php_monolith | awk '{print $1}') \
  bash -c "cat /app/logs/info/mail_sender.log"

  • Проверьте параметры SMTP в configs/auth.yaml (host/port/username/password/from и протокол). В конфигурации используется один из протоколов: ssl или tls. Попробуйте типовые варианты:

    • ssl + порт 465

    • tls + порт 587

    Для применения изменений в конфигурации выполните:

    sudo python3 script/update.py

  • Если после смены порта/протокола проблема не ушла — проверьте SMTP-подключение с сервера вручную через swaks.

Установка swaks:

sudo apt-get update
sudo apt-get install -y swaks

Пример для ssl (обычно порт 465):

swaks --to test@gmail.com \
  --from test1@yandex.ru \
  --server smtp.yandex.ru \
  --port 465 \
  --auth LOGIN \
  --auth-user test@yandex.ru \
  --auth-password '<app-password>' \
  --tls-on-connect

Пример для tls (обычно порт 587):

swaks --to test@gmail.com \
  --from test1@yandex.ru \
  --server smtp.yandex.ru \
  --port 587 \
  --auth LOGIN \
  --auth-user test@yandex.ru \
  --auth-password '<app-password>' \
  --tls

Что подставлять в параметры:

  • --to — почта, на которую будет отправлено письмо.

  • --from — адрес из smtp.from в auth.yaml.

  • --server — хост из smtp.host в auth.yaml.

  • --auth-user — значение smtp.username в auth.yaml.

  • --auth-password — пароль приложения/SMTP из smtp.password в auth.yaml.

Решение:

  • Попробуйте стандартные сочетания ssl:465 и tls:587.

  • Если не помогло — используйте swaks для диагностики.

Ошибка авторизации LDAP

Причина: LDAP недоступен или неверные параметры в configs/auth.yaml.

Что проверить:

  • Лог авторизации LDAP:

sudo docker exec -it $(sudo docker ps | grep php_monolith | awk '{print $1}') \
  bash -c "cat /app/logs/info/sso_ldap.log"

  • Подключение к LDAP можно проверить с помощью утилиты ldapsearch:

Установка ldapsearch:

sudo apt-get update
sudo apt-get install -y ldap-utils

Пример проверки подключения:

ldapsearch -x \
  -H ldap://<ldap.server_host>:389 \
  -D "<ldap.user_search_account_dn>" \
  -w "<ldap.user_search_account_password>" \
  -b "<ldap.user_search_base>" \
  "<ldap.user_search_filter>"

Значения в <> замените на параметры из configs/auth.yaml.

Ошибка авторизации через OIDC

Причина: ошибка настройки OIDC / недоступен провайдер / неверные параметры в configs/auth.yaml.

Что проверить:

Лог авторизации OIDC:

sudo docker exec -it $(sudo docker ps | grep php_monolith | awk '{print $1}') \
  bash -c "cat /app/logs/info/sso_oidc.log"

Решение: исправьте настройки OIDC в configs/auth.yaml по логам и примените изменения:

sudo python3 script/update.py
Ошибка авторизации на Android
Ошибка авторизации на Android

Причина: неполная цепочка SSL-сертификатов.

Что проверить:

Проверьте корректность цепочки SSL-сертификатов (домен + промежуточный). Замените your-domain.com на ваш реальный домен:

echo | openssl s_client -showcerts -servername your-domain.com \
  -connect your-domain.com:443 | openssl x509 -text -noout

Если в ответе есть verify error num: 20 или 21 — цепочка неполная.

Решение:

Разместите полную цепочку сертификатов в /etc/nginx/ssl/ и перезапустите nginx:

sudo nginx -s reload

Если используется внешний прокси, измените сертификат и на нем.

Звонки и конференции#

Ошибка соединения при звонках и в конференциях
Ошибка соединения при звонках

Причина: домен недоступен из контейнеров (NAT/DNS/маршрутизация).

Проверьте, доступен ли ваш домен из контейнера Compass. Замените your-domain.com на ваш реальный домен:

sudo docker exec -it $(sudo docker ps | grep php_monolith | awk '{print $1}') \
  bash -c "curl -vk https://your-domain.com"

Если запрос не проходит — контейнер не может обратиться к вашему домену. Из-за этого могут не работать звонки и конференции.

Решение:

  • Рекомендуемый вариант — решить на уровне DNS: настройте внутренний DNS так, чтобы домен your-domain.com резолвился во внутренний IP сервера Compass. Конкретные шаги зависят от вашего DNS.

  • Альтернативный вариант — завернуть трафик обратно на сервер через NAT (iptables):

    iptables -t nat -A PREROUTING \
  -d <public-ip>/32 -p tcp --dport 443 \
  -j DNAT --to-destination <local-ip>:443

iptables -t nat -A POSTROUTING \
  -s 0.0.0.0/0 -d <local-ip>/32 -p tcp --dport 443 \
  -j MASQUERADE

    Чтобы сохранить правила после перезагрузки (Debian/Ubuntu), установите iptables-persistent:

    sudo apt-get update
sudo apt-get install -y iptables-persistent

    Сохраните текущие правила:

    sudo netfilter-persistent save

    Либо настройте постоянное правило NAT на внешнем фаерволе/маршрутизаторе.

Не завершается конференция или звонок

Причина: неполная цепочка SSL-сертификатов.

Что проверить:

Проверьте корректность цепочки SSL-сертификатов (домен + промежуточный). Замените your-domain.com на ваш реальный домен:

echo | openssl s_client -showcerts -servername your-domain.com \
  -connect your-domain.com:443 | openssl x509 -text -noout

Если в ответе есть verify error num: 20 или 21 — цепочка неполная.

Решение:

Разместите полную цепочку сертификатов в /etc/nginx/ssl/ и перезапустите nginx:

sudo nginx -s reload

Если используется внешний прокси, измените сертификат и на нем.

После исправления:

Зайдите в приложение и завершите текущий звонок/конференцию, который(ая) не завершился(лась) из-за проблемы с сертификатом. Для этого создайте новую конференцию и перейдите в нее — при подключении появится диалоговое окно о наличии активной конференции. Нажмите «Завершить». После этого завершение конференций и звонков будет работать корректно.

Не работает видео/аудио в звонках (конференциях)

Причина: медиатрафик (UDP) не доходит до сервера Compass или не указан advertise IP.

Что проверить:

  • Убедитесь, что 10000/UDP разрешен во входящих правилах на пограничном уровне (Security Group / внешний firewall / панель провайдера / маршрутизатор) и проброшен до сервера Compass, если сервер находится за NAT.

  • Проверьте, доходят ли пакеты до сервера Compass.

    На сервере с Compass запустите прослушивание 10000/UDP:

    sudo tcpdump -n -i any udp port 10000

    Затем с внешнего хоста отправьте тестовые UDP-пакеты:

    echo "udp-test" | nc -u -w1 your-domain.com 10000

    • Если в tcpdump появились пакеты — трафик до сервера доходит.

    • Если пакетов нет — порт 10000/UDP блокируется или не проброшен на одном из узлов по пути.

  • Если трафик доходит — проверьте advertise IP.

    В configs/global.yaml поле jitsi.service.jvb.media_advertise_ips должно содержать внешний и локальный IP сервера через запятую.

Решение:

  • Откройте/пробросьте 10000/UDP до сервера Compass и убедитесь, что пакеты доходят (по tcpdump).

  • Проверьте jitsi.service.jvb.media_advertise_ips и примените изменения:

sudo python3 script/update.py

Напишите нам в пространстве поддержки On-premise, Telegram или на почту support@getcompass.ru, чтобы получить индивидуальную демонстрацию функционала и помощь по вопросам интеграции мессенджера в вашей компании.