Справочник по Matrix Synapse (Пункты 301–374)
Сборный: сетевые проблемы в контейнерах, продвинутая диагностика, API, сравнение установок и практические советы
Incus/LXD, Docker и Сетевые Конфликты
Incus/LXD создает изолированную сеть для контейнеров, что приводит к двойному NAT (Double NAT) и усложняет прохождение WebRTC-трафика.
В отличие от нативной установки, в контейнере Incus сервис (Synapse/Coturn) видит только свой внутренний IP (например, 10.214.97.46), а не реальный внешний IP хоста.
Это требует обязательной настройки external-ip в Coturn в формате external-ip=ВНЕШНИЙ_IP/ВНУТРЕННИЙ_IP (например, external-ip=91.221.70.18/10.214.97.46).
Docker и Incus на одном хосте часто конфликтуют, так как оба активно управляют цепочками iptables, вставляя свои правила в самый верх.
Конфликт с Jitsi — частая проблема, так как Jitsi Videobridge по умолчанию использует порт 10000 UDP и может перехватывать трафик, предназначенный для Matrix.
Проверить, какие UDP-порты заняты Docker-контейнерами, можно командой: sudo ss -lupn | grep docker-proxy.
Чтобы избежать конфликтов, необходимо разносить диапазоны портов для разных сервисов (например, Jitsi — 10000, Matrix — 49152-65535).
При использовании Incus стандартные пробросы портов через incus config device add неэффективны для больших диапазонов UDP, требуется прямое вмешательство в iptables на хосте.
Правила iptables, добавленные вручную, живут только в памяти и исчезают после перезагрузки, если их не сохранить.
Команда для сохранения правил iptables: sudo netfilter-persistent save (требуется пакет iptables-persistent).
Просмотр сохраненных правил: cat /etc/iptables/rules.v4.
Глубокая Диагностика Сети и Пакетов
Если tcpdump внутри контейнера показывает входящие пакеты от клиента, а Coturn в логах молчит — значит, Coturn отклоняет пакеты на уровне приложения.
Самая частая причина такого молчания — блокировка подсети клиента через директиву denied-peer-ip в turnserver.conf.
Для контейнеров с IP в диапазоне 10.x.x.x критически важно закомментировать строку denied-peer-ip=10.0.0.0-10.255.255.255.
Пакеты могут "стучаться" в порт 3478, но Coturn не считает их валидными STUN-запросами из-за несовпадения realm или отсутствия fingerprint.
Ошибка "401 Unauthorized" в логах Coturn при попытке звонка — явный признак несовпадения static-auth-secret в Coturn и turn_shared_secret в Synapse.
Для детальной диагностики WebRTC-соединения в браузере (Element) нужно открыть инструменты разработчика (F12) и изучить вкладку "Network" и "Console".
Поиск в консоли по словам "ICE", "TURN", "STUN" покажет, какие серверы пытается использовать клиент.
Если в консоли нет упоминаний вашего TURN-сервера, значит Synapse не отдал клиенту его настройки (проблема в секции turn_uris).
Команда для проверки, что Synapse "видит" свой TURN-сервер изнутри контейнера: curl http://localhost:8008/_matrix/client/versions (это не проверит TURN, но проверит работу Synapse).
API Администратора (Практические Примеры)
Получение короткого токена администратора одной строкой (замените admin и password
TOKEN=$(curl -s -X POST "http://localhost:8008/_matrix/client/r0/login" -H "Content-Type: application/json" -d '{"type":"m.login.password","user":"admin","password":"ПАРОЛЬ"}' | jq -r '.access_token')
Создание алиаса для удобного получения токена:
alias matrix-token='curl -s -X POST http://localhost:8008/_matrix/client/r0/login -d '\''{"type":"m.login.password","user":"admin","password":"ваш_пароль"}'\'' | jq -r .access_token'
Получение списка всех комнат на сервере (осторожно, может быть много):
curl -s "http://localhost:8008/_synapse/admin/v1/rooms?limit=100" -H "Authorization: Bearer $TOKEN" | jq '.rooms[].room_id'
Удаление комнаты (очистка данных):
curl -X DELETE "http://localhost:8008/_synapse/admin/v1/rooms/!room_id:domain" -H "Authorization: Bearer $TOKEN"
Получение статистики по медиафайлам:
curl -s "http://localhost:8008/_synapse/admin/v1/statistics" -H "Authorization: Bearer $TOKEN" | jq .
Просмотр активных сессий пользователя:
curl -s "http://localhost:8008/_synapse/admin/v1/whois/@user:domain" -H "Authorization: Bearer $TOKEN" | jq .devices
Блокировка сервера на уровне федерации (Server ACL) через API — сложная задача, проще через интерфейс комнаты.
Сброс пароля пользователя через API одной командой (функция оболочки):
```
matrix-passwd() {
TOKEN=$(matrix-token)
curl -X PUT "http://localhost:8008/_synapse/admin/v2/users/$1" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d "{\"password\": \"$2\"}"
}
```
Сравнение Способов Установки
Нативная установка (Debian/Ubuntu) — максимальная простота, лучшая производительность, легкая интеграция с Coturn, но "засоряет" систему и сложнее в изоляции.
Установка в Docker — хорошая изоляция, легкие обновления, но сложнее с пробросом UDP-портов и работой WebRTC.
Установка в Incus/LXD — отличная изоляция, удобные снапшоты, но самые большие проблемы с WebRTC из-за двойного NAT.
YunoHost — максимальная простота для новичков, все работает "из коробки", включая звонки, но меньше гибкости и контроля.
Вывод: для продакшена с видео/звонками лучше всего подходит нативная установка на хост. Контейнеры хороши для тестов и изолированных сред без VoIP.
Проблемы с PostgreSQL и Базами Данных
Проверить, использует ли Synapse PostgreSQL, можно командой ss -antp | grep 5432 | grep python. Наличие ESTAB соединений — признак использования PostgreSQL.
Если в логах нет ошибок, но база данных не растет, возможно, Synapse все еще пишет в SQLite. Проверьте дату изменения файла /var/lib/matrix-synapse/homeserver.db.
Конфликт между настройками БД в homeserver.yaml и conf.d/ может привести к тому, что Synapse не запустится с ошибкой Duplicate key.
При миграции с SQLite на PostgreSQL дамп SQLite требует ручной корректировки (удаление команд, специфичных для SQLite, например, BEGIN TRANSACTION может дублироваться).
Параметр cp_min и cp_max в конфиге БД управляют размером пула соединений. Для больших серверов cp_max можно увеличить до 20-30.
Практические Команды Администратора (Продолжение)
Быстрый просмотр последних ошибок в логах Synapse:
journalctl -u matrix-synapse -n 50 -f | grep -i error
Проверка, слушает ли Coturn нужные порты внутри контейнера:
ss -ulnp | grep 3478 (UDP) и ss -tlnp | grep 3478 (TCP).
Проверка версии Synapse из командной строки:
dpkg -l | grep matrix-synapse (для пакетной установки) или docker exec synapse pip show matrix-synapse.
Просмотр переменных окружения внутри контейнера Docker:
docker exec synapse env.
Интерактивный вход в контейнер Docker:
docker exec -it synapse /bin/bash.
Просмотр логов конкретного контейнера Docker с временными метками:
docker logs -t synapse.
Остановка всех контейнеров Docker разом (для теста конфликтов):
docker stop $(docker ps -q).
Поиск файлов конфигурации Coturn:
find / -name "turnserver.conf" 2>/dev/null.
Просмотр открытых файлов процессом Coturn:
lsof -p $(pgrep turnserver).
Теория NAT и WebRTC (Почему это сложно)
STUN позволяет клиенту узнать свой внешний IP и порт, чтобы сообщить их собеседнику для прямого соединения.
TURN используется, когда прямое соединение невозможно (симметричный NAT, корпоративные файерволы). Сервер ретранслирует трафик.
ICE — это протокол, который собирает все возможные кандидаты (STUN, TURN, локальные адреса) и пытается установить соединение, перебирая их.
В контейнере Incus Coturn видит только свой внутренний IP (10.214.97.46). Без external-ip он сообщит клиенту именно его, и клиент не сможет подключиться.
Эффект "пробитого NAT" (UDP Hole Punching) — когда после успешного прохождения одного пакета NAT "запоминает" маршрут и временно открывает его для обратного трафика.
Именно поэтому иногда "вчера не работало, а сегодня работает": таблица трансляции адресов (conntrack) могла очиститься или, наоборот, зафиксировать успешный проход.
Разное Важное
При использовании внешнего реверс-прокси (Nginx) в конфиге Synapse обязателен параметр x_forwarded: true в секции listeners.
Для корректной работы федерации server_name в Synapse должен быть именно доменом, а не поддоменом (если вы хотите короткие ID @user:domain.com). Иначе используйте .well-known делегирование.
Параметр max_upload_size измеряется в байтах. 50M = 50 * 1024 * 1024 = 52428800.
При изменении server_name на уже работающем сервере все существующие пользователи и комнаты "сломаются", так как их ID привязаны к старому имени.
Synapse поддерживает ротацию логов. Настройки ротации находятся в /etc/logrotate.d/matrix-synapse.
Для мониторинга можно использовать готовый дашборд Grafana для Synapse (например, из официального репозитория).
Ошибка "Connection refused" при попытке curl с хоста в контейнер почти всегда означает, что сервис внутри контейнера слушает только 127.0.0.1, а не 0.0.0.0.
Команда для изменения bind_addresses в Synapse внутри контейнера: отредактировать файл в /conf.d/ или изменить основной конфиг.
Файл /etc/matrix-synapse/conf.d/server_name.yaml создается автоматически при установке из пакета и содержит только server_name: "ваш.домен".
Не рекомендуется редактировать этот файл, если вы уже указали домен при установке. Для изменения домена проще переустановить сервер.
Параметр enable_registration_captcha включает капчу при регистрации. Требует настройки ReCaptcha от Google.
Для использования капчи нужно получить ключи на сайте Google ReCaptcha и указать их в конфиге.
Модули Synapse (spam checker, 3pid providers) расширяют функциональность сервера и настраиваются в секции modules.
Официальная документация Synapse — лучший источник информации: https://element-hq.github.io/synapse/latest/.
Сообщество Matrix в Telegram (@matrix_ru) — отличное место для получения помощи на русском языке.
Итоговые проверки работоспособности
Финальная проверка федерации без внешних тестеров: с одного сервера пригласить пользователя с другого сервера и отправить сообщение.
Финальная проверка звонков: позвонить с пользователя на одном сервере пользователю на другом сервере.
Проверка логирования: убедиться, что логи пишутся и не забивают диск.
Проверка автоматического запуска: systemctl is-enabled matrix-synapse и systemctl is-enabled coturn.
Проверка открытых портов снаружи: использовать онлайн-сервисы вроде yougetsignal.com или portchecker.co.
Проверка валидности SSL-сертификата: openssl s_client -connect matrix.domain.com:443 -servername matrix.domain.com < /dev/null 2>/dev/null | openssl x509 -text | grep -A2 Validity.