Справочник по Matrix Synapse (Пункты 101–200)
Глубокая настройка Synapse
- Параметр
public_baseurl в homeserver.yaml должен быть полным URL-адресом вашего сервера (например, https://matrix.nbics.net/).
- Он используется для генерации ссылок в уведомлениях по электронной почте и для других сервисов.
max_upload_size задает максимальный размер загружаемого файла (например, 100M или 2000M).enable_registration: false отключает публичную регистрацию, позволяя создавать аккаунты только через административную утилиту.enable_registration_without_verification: true позволяет регистрироваться без подтверждения email (опасно для публичных серверов).registration_shared_secret — секретный ключ, используемый для регистрации новых пользователей через утилиту register_new_matrix_user.- Его нужно генерировать случайным образом (например,
cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1).
- Параметр
rc_message позволяет ограничить скорость отправки сообщений для борьбы со спамом.
```yaml
rc_message:
per_second: 0.2
burst_count: 10
```
media_store_path указывает путь к хранилищу медиафайлов (обычно /var/lib/matrix-synapse/media).signing_key_path — путь к ключу подписи сервера, используемому для федерации (/etc/matrix-synapse/homeserver.signing.key).- Ключ подписи генерируется автоматически при первой установке и НИКОГДА не должен быть скомпрометирован.
pid_file указывает путь к PID-файлу процесса Synapse (/var/run/matrix-synapse.pid).
Настройка слушателей (listeners)
- Секция
listeners определяет, на каких портах и интерфейсах Synapse принимает соединения.
- Пример настройки для работы через reverse proxy (слушать только localhost):
```yaml
listeners:
- port: 8008
tls: false
type: http
x_forwarded: true
bind_addresses: ['127.0.0.1', '::1']
resources:
- names: [client, federation]
compress: false
```
x_forwarded: true указывает Synapse доверять заголовкам X-Forwarded-For от прокси.- Если сервер должен принимать соединения извне напрямую,
bind_addresses нужно изменить на ['0.0.0.0'].
- Ресурс
client обслуживает клиентские запросы (логин, отправка сообщений, синхронизация).
- Ресурс
federation обслуживает запросы от других серверов Matrix.
Безопасность и изоляция
federation_ip_range_blacklist — список IP-диапазонов, к которым серверу запрещено подключаться (защита от SSRF-атак).- Включает приватные диапазоны (
10.0.0.0/8, 192.168.0.0/16, 172.16.0.0/12 и IPv6 аналоги).
trusted_key_servers: [] делает сервер независимым от внешних серверов ключей (полезно при блокировке matrix.org).- Без списка доверенных серверов федерация работает напрямую: серверы обмениваются ключами друг с другом.
suppress_key_server_warning: true отключает предупреждение об отсутствии доверенных серверов ключей.enable_room_list_search: false отключает публичный каталог комнат, если он не нужен.limit_usage_by_membership позволяет ограничить использование ресурсов в зависимости от членства в комнатах.require_auth_for_profile_requests: true требует аутентификации для запросов профиля пользователя.
Установка из пакетов Debian/Ubuntu (детали)
- Пакет называется
matrix-synapse-py3 (а не просто matrix-synapse).
- После установки создается системный пользователь
matrix-synapse, от которого запускается сервис.
- Файлы конфигурации по умолчанию находятся в
/etc/matrix-synapse.
- Логи по умолчанию пишутся в
/var/log/matrix-synapse/homeserver.log.
- Настройки логирования управляются файлом
/etc/matrix-synapse/log.yaml.
- Для изменения уровня логирования (например, на DEBUG для отладки) нужно отредактировать
log.yaml.
- Встроенная команда проверки конфигурации:
python3 -m synapse.app.homeserver --config-path /etc/matrix-synapse/homeserver.yaml --config-path /etc/matrix-synapse/conf.d/ --check-config.
- Python для пакета может находиться в системном окружении или в виртуальном окружении по пути
/opt/venvs/matrix-synapse/bin/python.
Установка в Docker (детали)
- При использовании Docker данные Synapse хранятся в Docker-томе (volume)
synapse-data.
- Файлы конфигурации внутри контейнера находятся в
/data.
- Чтобы отредактировать
homeserver.yaml, нужно зайти в контейнер: docker exec -it synapse /bin/bash.
- Переменная окружения
SYNAPSE_CONFIG_PATH указывает путь к конфигурационному файлу.
- Для проброса портов при запуске используются ключи
-p 8008:8008 (клиентский API) и -p 8448:8448 (федерация).
- Логи Docker-контейнера смотрят командой
docker logs -f synapse.
- Обновление Synapse в Docker:
docker pull matrixdotorg/synapse:latest && docker stop synapse && docker rm synapse && (запустить контейнер заново).
- Преимущество Docker — изоляция и простота обновления (не нужно чистить конфиги).
Продвинутая диагностика
- Команда для проверки, какие соединения с БД держит Synapse:
ss -antp | grep python.*5432.
- Множество соединений в состоянии
ESTAB — это нормально (пул соединений).
- Проверка версии Synapse:
dpkg -l | grep matrix-synapse или docker exec synapse pip show matrix-synapse.
- Проверка, какие правила iptables активны для Matrix:
sudo iptables -L FORWARD -v -n | grep 10.214.97.46.
- Просмотр статистики по пакетам в iptables (колонка
pkts показывает, сколько пакетов прошло).
- Если счетчики пакетов в iptables растут, а звонка нет — проблема внутри контейнера (Coturn).
- Если счетчики не растут — проблема на хосте (Firewall, проброс портов).
- Для диагностики конфликтов портов используется
sudo ss -lupn | grep <порт>.
Решение проблем с конфигурацией (conf.d)
- При использовании
conf.d/ важно помнить, что файлы загружаются в алфавитном порядке.
- Позже загруженные настройки могут переопределить более ранние.
- Если в основном
homeserver.yaml и в conf.d/ есть одинаковые секции, сервер может не запуститься с ошибкой Duplicate key.
- Правильный подход: в основном файле оставлять только то, что нужно, а специфичные настройки выносить в
conf.d/.
- Для отключения какой-либо опции лучше закомментировать её во всех местах.
- Файлы в
conf.d/ должны иметь права на чтение для пользователя matrix-synapse.
- Проверить, какие файлы из
conf.d/ загружаются, можно в логах при запуске сервера (уровень INFO).
Интеграция с Coturn и WebRTC
- Параметр
turn_user_lifetime определяет время жизни учетных данных TURN (например, 86400000 мс или 1h).
turn_allow_guests: true разрешает гостевым пользователям использовать TURN-сервер.- В конфиге Coturn
listening-ip можно указать как 0.0.0.0, чтобы слушать на всех интерфейсах.
min-port и max-port должны точно совпадать с диапазоном, проброшенным в iptables.fingerprint в Coturn включает добавление отпечатка в пакеты STUN, что требуется некоторыми WebRTC-клиентами.lt-cred-mech включает механизм долговременных учетных данных.- Для отладки звонков полезно включить
verbose в Coturn и смотреть логи.
- Если в логах Coturn появляется
401 Unauthorized, значит не совпадает static-auth-secret с turn_shared_secret в Synapse.
- Если в логах пусто, а пакеты в iptables есть, скорее всего, Coturn блокирует подсеть клиента (проверить
denied-peer-ip).
Настройка Element Web
- Element можно разместить на отдельном поддомене (например,
element.nbics.net) или на том же, что и Synapse.
- Скачать последнюю версию Element:
wget https://github.com/vector-im/element-web/releases/latest/download/element.tar.gz.
- Распаковать архив в веб-директорию:
tar -xzf element.tar.gz -C /var/www/element.
- Конфигурационный файл Element —
config.json в корне веб-директории.
- В
config.json обязательно указать base_url вашего Synapse:
```json
{
"default_server_config": {
"m.homeserver": {
"base_url": "https://matrix.nbics.net",
"server_name": "nbics.net"
}
}
}
```
- Можно отключить гостевой доступ:
"disable_guests": true.
- Для изменения названия бренда используется параметр
"brand": "Мой Мессенджер".
- Element лучше проксировать через тот же Nginx, что и Synapse, с отдельным
server_name.
- Для кэширования статических файлов Element в Nginx можно добавить заголовки
expires 1y; add_header Cache-Control "public, immutable";.
Управление медиафайлами
- Медиафайлы (изображения, видео, документы) хранятся в директории
media_store_path.
- Synapse автоматически создает хэш-директории внутри этой папки для хранения файлов.
- Просмотр занятого места под медиа:
du -sh /var/lib/matrix-synapse/media.
- Удаление старых или неиспользуемых медиафайлов можно делать через API администратора.
max_image_pixels: 32M ограничивает максимальный размер изображения (в пикселях) для предотвращения DoS-атак.
API администратора (примеры)
- Для использования API администратора нужен access_token пользователя с правами администратора.
- Получение списка пользователей (с пагинацией):
curl -s "http://localhost:8008/_synapse/admin/v2/users?from=0&limit=100" -H "Authorization: Bearer ТОКЕН" | jq .
- Получение информации о конкретном пользователе:
curl -s "http://localhost:8008/_synapse/admin/v2/users/@user:domain" -H "Authorization: Bearer ТОКЕН"
- Деактивация пользователя (мягкое удаление):
curl -X PUT -H "Authorization: Bearer ТОКЕН" "http://localhost:8008/_synapse/admin/v2/users/@user:domain" -d '{"deactivated": true}'
- Удаление пользователя (без возможности восстановления):
curl -X DELETE -H "Authorization: Bearer ТОКЕН" "http://localhost:8008/_synapse/admin/v1/deactivate/@user:domain"
- Очистка медиафайлов пользователя:
curl -X POST -H "Authorization: Bearer ТОКЕН" "http://localhost:8008/_synapse/admin/v1/media/@user:domain/delete" -d '{"delete_profiles": true}'
Интеграция с почтой (необязательно)
- Synapse может отправлять email-уведомления (например, для сброса пароля).
- Для этого нужно настроить секцию
email в homeserver.yaml:
```yaml
email:
smtp_host: mail.nbics.net
smtp_port: 587
smtp_user: noreply@nbics.net
smtp_pass: "пароль"
notif_from: "Matrix <noreply@nbics.net>"
```
- Email используется только для системных уведомлений, а не для регистрации (если она отключена).
Миграция с SQLite на PostgreSQL
- Если изначально использовался SQLite, можно перенести данные в PostgreSQL.
- Остановить Synapse:
systemctl stop matrix-synapse.
- Сделать дамп SQLite:
sqlite3 /var/lib/matrix-synapse/homeserver.db .dump > synapse_dump.sql.
- Создать базу и пользователя в PostgreSQL (как описано выше).
- Импортировать дамп в PostgreSQL:
sudo -u postgres psql -d synapse < synapse_dump.sql.
- Важно: дамп SQLite может потребовать ручной правки (удаление строк, специфичных для SQLite).
- После импорта настроить Synapse на использование PostgreSQL и перезапустить.
Безопасность и мониторинг
- Регулярно обновляйте Synapse:
apt update && apt upgrade matrix-synapse-py3.
- Подпишитесь на рассылку безопасности Matrix.org.
- Следите за логами на предмет подозрительной активности (попытки брутфорса, спам-регистрации).
- Настройте автоматическое резервное копирование базы данных и папки с медиафайлами.
