Справочник по установке и настройке Matrix Synapse

[Admin]

Справочник по Matrix Synapse (Пункты 1–100)

Основные понятия и архитектура

1. Matrix — это открытый, децентрализованный протокол для обмена сообщениями в реальном времени (альтернатива Telegram, Discord).
2. Synapse — это эталонная реализация сервера Matrix на Python, самая популярная и распространенная.
3. Федерация (Federation) — возможность общаться с пользователями на других серверах Matrix.
4. Домашний сервер (Homeserver) — сервер, на котором зарегистрирован пользователь и где хранятся его данные.
5. Element — самый популярный клиент (веб, мобильный, десктоп) для работы с сетью Matrix.
6. Coturn — TURN/STUN сервер, необходимый для голосовых и видеозвонков (WebRTC) в Matrix.

Установка Synapse (Основные способы)

7. Synapse можно установить из официального репозитория Matrix.org для Debian/Ubuntu.
8. Команда добавления ключа репозитория: wget -qO /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg.
9. Команда добавления репозитория в список источников: echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/matrix-org.list.
10. Установка Synapse из репозитория: apt install matrix-synapse-py3.
11. Во время установки пакет запросит server_name (домен сервера) и согласие на отправку статистики.
12. После установки Synapse запускается как системная служба: systemctl start matrix-synapse.
13. Включение автозапуска Synapse: systemctl enable matrix-synapse.
14. Основной конфигурационный файл Synapse: /etc/matrix-synapse/homeserver.yaml.
15. Для установки в Docker используется образ matrixdotorg/synapse:latest.
16. Генерация конфигурации для Docker: docker run -it --rm --mount type=volume,src=synapse-data,dst=/data -e SYNAPSE_SERVER_NAME=example.com matrixdotorg/synapse:latest generate.
17. Запуск Synapse в Docker: docker run -d --name synapse --restart unless-stopped --mount type=volume,src=synapse-data,dst=/data -p 8008:8008 matrixdotorg/synapse:latest run.

PostgreSQL вместо SQLite

18. Для продакшена настоятельно рекомендуется использовать PostgreSQL вместо встроенной SQLite.
19. Установка PostgreSQL: apt install postgresql postgresql-contrib -y.
20. Создание пользователя БД: sudo -u postgres psql -c "CREATE USER synapse_user WITH PASSWORD 'secure_password';".
21. Создание базы данных: sudo -u postgres psql -c "CREATE DATABASE synapse ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE=template0 OWNER synapse_user;".
22. Настройки базы данных в Synapse лучше выносить в отдельный файл в /etc/matrix-synapse/conf.d/database.yaml.
23. Пример конфигурации для PostgreSQL:

    database:
      name: psycopg2
      args:
        user: synapse_user
        password: secure_password
        database: synapse
        host: localhost
        cp_min: 5
        cp_max: 10
    

24. Подключение Synapse к PostgreSQL можно проверить командой ss -antp | grep 5432 — должны быть ESTAB соединения с процессом python.
25. Проверить, что Synapse использует PostgreSQL, можно SQL-запросом: sudo -u postgres psql -d synapse -c "SELECT count(*) FROM users;".

Структура конфигурации (conf.d)

26. В Debian/Ubuntu пакет Synapse поддерживает модульную конфигурацию через папку /etc/matrix-synapse/conf.d/.
27. Все файлы с расширением .yaml в этой папке автоматически загружаются и применяются поверх основного homeserver.yaml.
28. Использование conf.d/ — лучшая практика, так как при обновлении пакета основной файл может быть перезаписан.
29. В conf.d/ рекомендуется хранить настройки базы данных, регистрации, TURN-сервера, федерации и другие специфические параметры.
30. Файл /etc/matrix-synapse/conf.d/server_name.yaml обычно содержит только одну строку: server_name: "ваш.домен".

Настройка Nginx в качестве Reverse Proxy

31. Matrix Synapse не должен быть напрямую доступен из интернета. Его проксируют через Nginx или Apache.
32. Synapse по умолчанию слушает на порту 8008 (localhost).
33. Конфигурация Nginx для проксирования должна включать передачу заголовков X-Forwarded-For и X-Forwarded-Proto.
34. Пример базового location для проксирования:

    location / {
        proxy_pass http://127.0.0.1:8008;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $host;
    }
    

35. Для работы больших файлов (вложения) нужно увеличить client_max_body_size (например, до 50M или 2000M).
36. Важно: в конфиге Synapse в секции listeners должен быть параметр x_forwarded: true.

SSL-сертификаты (Let's Encrypt)

37. Для работы федерации и безопасных клиентов обязателен валидный SSL-сертификат.
38. Установка Certbot для Nginx: apt install certbot python3-certbot-nginx -y.
39. Получение сертификата: certbot --nginx -d matrix.ваш-домен.ru.
40. Certbot автоматически обновляет конфигурацию Nginx, добавляя пути к сертификатам и настраивая редирект с HTTP на HTTPS.
41. При использовании федерации сертификат должен быть доверенным (самоподписанный не подойдет).

Настройка федерации (.well-known)

42. Федерация позволяет серверам Matrix обмениваться сообщениями.
43. Для работы федерации сервер должен корректно отвечать на запросы к /.well-known/matrix/server.
44. Правильный ответ должен быть JSON: {"m.server": "matrix.ваш-домен.ru:443"}.
45. В Nginx это настраивается через location:

    location /.well-known/matrix/server {
        default_type application/json;
        return 200 '{"m.server": "matrix.ваш-домен.ru:443"}';
    }
    

46. Аналогично для клиентов настраивается /.well-known/matrix/client с base_url.
47. Проверить федерацию можно через инструмент Matrix Federation Tester.
48. Если matrix.org заблокирован, можно обойтись без внешних доверенных серверов ключей, установив trusted_key_servers: [].
49. Для изоляции сервера (только свои домены) используется параметр federation_domain_whitelist.

Управление пользователями и паролями

50. Создание нового пользователя через командную строку: register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://localhost:8008.
51. Утилита запросит имя, пароль и подтверждение администратора.
52. Если утилита не видит registration_shared_secret, нужно указать путь к конфигу из conf.d/ дополнительным флагом -c.
53. Получение списка всех пользователей из SQLite: sudo sqlite3 /var/lib/matrix-synapse/homeserver.db "SELECT name, creation_ts FROM users;".
54. Получение списка пользователей из PostgreSQL: sudo -u postgres psql -d synapse -c "SELECT name, admin FROM users;".
55. Сброс пароля пользователя через curl (с админским токеном):

    curl -X PUT -H "Authorization: Bearer ТОКЕН" "http://localhost:8008/_synapse/admin/v2/users/@user:domain" -d '{"password": "новый_пароль"}'
    

56. Получение access_token администратора:

    curl -X POST "http://localhost:8008/_matrix/client/r0/login" -d '{"type":"m.login.password","user":"admin","password":"пароль"}'
    

57. Назначение пользователя администратором через API: curl -X PUT -H "Authorization: Bearer ТОКЕН" "http://localhost:8008/_synapse/admin/v2/users/@user:domain" -d '{"admin": true}'.
58. Деактивация пользователя: curl -X PUT -H "Authorization: Bearer ТОКЕН" "http://localhost:8008/_synapse/admin/v2/users/@user:domain" -d '{"deactivated": true}'.

Настройка TURN-сервера (Coturn) для звонков

59. Для голосовых и видеозвонков необходим TURN-сервер (Coturn), так как клиенты часто находятся за NAT.
60. Установка Coturn: apt install coturn -y.
61. Основной конфигурационный файл Coturn: /etc/turnserver.conf.
62. Генерация секретного ключа (static-auth-secret) для аутентификации: echo "static-auth-secret=$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1)" | tee /etc/turnserver.conf.
63. В конфиге обязательно указать:

    listening-port=3478
    external-ip=ВНЕШНИЙ_IP_СЕРВЕРА
    realm=ваш-домен.ru
    

64. Если сервер находится в контейнере, для external-ip используется формат: external-ip=ВНЕШНИЙ_IP/ВНУТРЕННИЙ_IP.
65. Включение авторизации: use-auth-secret.
66. Важно: Не блокировать подсеть сервера. Если сервер в сети 10.x.x.x, нужно закомментировать или удалить строку denied-peer-ip=10.0.0.0-10.255.255.255.
67. Запрет на использование TCP-релея (no-tcp-relay) лучше отключить (закомментировать) для надежности.
68. Указание диапазона портов для медиа-трафика: min-port=49152 и max-port=65535.
69. Включение подробного логирования: verbose и fingerprint.
70. Настройка в Synapse (homeserver.yaml):

    turn_uris:
      - "turn:ваш-домен.ru:3478?transport=udp"
      - "turn:ваш-домен.ru:3478?transport=tcp"
    turn_shared_secret: "ВАШ_СЕКРЕТ"
    turn_user_lifetime: 1h
    turn_allow_guests: true
    

71. Для работы звонков в контейнере Incus/LXD необходим проброс UDP-портов через iptables на хосте.
72. Команды для проброса портов (на хосте):

    iptables -t nat -I PREROUTING -p udp --dport 3478 -j DNAT --to-destination IP_КОНТЕЙНЕРА:3478
    iptables -t nat -I PREROUTING -p udp --dport 49152:65535 -j DNAT --to-destination IP_КОНТЕЙНЕРА
    iptables -I FORWARD -p udp -d IP_КОНТЕЙНЕРА --dport 3478 -j ACCEPT
    iptables -I FORWARD -p udp -d IP_КОНТЕЙНЕРА --dport 49152:65535 -j ACCEPT
    

73. Сохранение правил iptables после перезагрузки: apt install iptables-persistent и netfilter-persistent save.

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

74. Просмотр логов Synapse: journalctl -u matrix-synapse -f.
75. Поиск ошибок в логах: journalctl -u matrix-synapse -n 100 | grep -i error.
76. Проверка статуса сервера: systemctl status matrix-synapse.
77. Проверка, на каких интерфейсах и портах слушает Synapse: ss -tlnp | grep 8008.
78. Проверка, слушает ли Coturn: ss -ulnp | grep 3478.
79. Просмотр логов Coturn: journalctl -u coturn -f.
80. В логах Coturn при успешном звонке должны появляться записи allocate request или success.
81. Мониторинг трафика в реальном времени на хосте: tcpdump -n -i any udp port 3478.
82. Проверка активных соединений к PostgreSQL: ss -antp | grep 5432.
83. Проверка валидности конфигурации Synapse без запуска: /usr/bin/python3 -m synapse.app.homeserver --config-path /etc/matrix-synapse/homeserver.yaml --config-path /etc/matrix-synapse/conf.d/ --check-config.
84. Проверка доступности TURN-сервера извне через онлайн-инструменты (например, Trickle ICE).

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

85. Ошибка [] is not of type 'string': возникает при неверном синтаксисе trusted_key_servers: []. Нужно закомментировать всю секцию.
86. Нет звука/видео: 90% проблема в неработающем TURN-сервере или закрытых UDP-портах (3478, 49152-65535).
87. Приглашение висит, но чат не создается: проблема в федерации, проверьте .well-known и открытый порт 443.
88. Ошибка Unable to connect to server при curl с хоста в контейнер: сервис слушает только 127.0.0.1, нужно изменить bind_addresses на 0.0.0.0.
89. Дублирование ключей (Duplicate key) в конфиге: настройка прописана и в основном файле, и в conf.d/. Оставить только в одном месте.
90. Конфликт с Jitsi или другими сервисами: используют общие UDP-порты, нужно разносить диапазоны (Jitsi — 10000, Matrix — 49152+).
91. Пакеты в iptables есть, но Coturn молчит: Coturn блокирует подсеть через denied-peer-ip (особенно 10.x.x.x).
92. Сервер не запускается после изменения конфига: проверьте синтаксис YAML (отступы важен!).
93. Бесконечное «Устанавливается соединение» при звонке: TURN-сервер не отвечает или ключи не совпадают.
94. Регистрация не работает: проверьте enable_registration и наличие registration_shared_secret.
95. Федерация не работает с matrix.org (блокировка): удалите matrix.org из trusted_key_servers и оставьте пустой список [].

Полезные команды и алиасы

96. Просмотр всех пользователей с датой регистрации:
    sudo sqlite3 /var/lib/matrix-synapse/homeserver.db "SELECT name, datetime(creation_ts,'unixepoch') FROM users WHERE is_deactivated = 0;".
97. Количество активных пользователей: alias matrix-count="sudo sqlite3 /var/lib/matrix-synapse/homeserver.db \"SELECT count(*) FROM users WHERE is_deactivated = 0;\"".
98. Список администраторов: alias matrix-admins="sudo sqlite3 /var/lib/matrix-synapse/homeserver.db \"SELECT name FROM users WHERE is_admin = 1;\"".
99. Быстрая проверка логов звонков: journalctl -u coturn -f | grep -E "success|error|allocate".
100. Путь к основным каталогам Synapse:
     * Конфигурация: /etc/matrix-synapse/
     * База данных SQLite: /var/lib/matrix-synapse/homeserver.db
     * Медиафайлы: /var/lib/matrix-synapse/media/
     * Логи: /var/log/matrix-synapse/homeserver.log

[Admin]

Справочник по Matrix Synapse (Пункты 101–200)

Глубокая настройка Synapse

101. Параметр public_baseurl в homeserver.yaml должен быть полным URL-адресом вашего сервера (например, https://matrix.nbics.net/).
102. Он используется для генерации ссылок в уведомлениях по электронной почте и для других сервисов.
103. max_upload_size задает максимальный размер загружаемого файла (например, 100M или 2000M).
104. enable_registration: false отключает публичную регистрацию, позволяя создавать аккаунты только через административную утилиту.
105. enable_registration_without_verification: true позволяет регистрироваться без подтверждения email (опасно для публичных серверов).
106. registration_shared_secret — секретный ключ, используемый для регистрации новых пользователей через утилиту register_new_matrix_user.
107. Его нужно генерировать случайным образом (например, cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1).
108. Параметр rc_message позволяет ограничить скорость отправки сообщений для борьбы со спамом.

```yaml
rc_message:
  per_second: 0.2
  burst_count: 10
```

109. media_store_path указывает путь к хранилищу медиафайлов (обычно /var/lib/matrix-synapse/media).
110. signing_key_path — путь к ключу подписи сервера, используемому для федерации (/etc/matrix-synapse/homeserver.signing.key).
111. Ключ подписи генерируется автоматически при первой установке и НИКОГДА не должен быть скомпрометирован.
112. pid_file указывает путь к PID-файлу процесса Synapse (/var/run/matrix-synapse.pid).

Настройка слушателей (listeners)

113. Секция listeners определяет, на каких портах и интерфейсах Synapse принимает соединения.
114. Пример настройки для работы через 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
```

115. x_forwarded: true указывает Synapse доверять заголовкам X-Forwarded-For от прокси.
116. Если сервер должен принимать соединения извне напрямую, bind_addresses нужно изменить на ['0.0.0.0'].
117. Ресурс client обслуживает клиентские запросы (логин, отправка сообщений, синхронизация).
118. Ресурс federation обслуживает запросы от других серверов Matrix.

Безопасность и изоляция

119. federation_ip_range_blacklist — список IP-диапазонов, к которым серверу запрещено подключаться (защита от SSRF-атак).
120. Включает приватные диапазоны (10.0.0.0/8, 192.168.0.0/16, 172.16.0.0/12 и IPv6 аналоги).
121. trusted_key_servers: [] делает сервер независимым от внешних серверов ключей (полезно при блокировке matrix.org).
122. Без списка доверенных серверов федерация работает напрямую: серверы обмениваются ключами друг с другом.
123. suppress_key_server_warning: true отключает предупреждение об отсутствии доверенных серверов ключей.
124. enable_room_list_search: false отключает публичный каталог комнат, если он не нужен.
125. limit_usage_by_membership позволяет ограничить использование ресурсов в зависимости от членства в комнатах.
126. require_auth_for_profile_requests: true требует аутентификации для запросов профиля пользователя.

Установка из пакетов Debian/Ubuntu (детали)

127. Пакет называется matrix-synapse-py3 (а не просто matrix-synapse).
128. После установки создается системный пользователь matrix-synapse, от которого запускается сервис.
129. Файлы конфигурации по умолчанию находятся в /etc/matrix-synapse.
130. Логи по умолчанию пишутся в /var/log/matrix-synapse/homeserver.log.
131. Настройки логирования управляются файлом /etc/matrix-synapse/log.yaml.
132. Для изменения уровня логирования (например, на DEBUG для отладки) нужно отредактировать log.yaml.
133. Встроенная команда проверки конфигурации: python3 -m synapse.app.homeserver --config-path /etc/matrix-synapse/homeserver.yaml --config-path /etc/matrix-synapse/conf.d/ --check-config.
134. Python для пакета может находиться в системном окружении или в виртуальном окружении по пути /opt/venvs/matrix-synapse/bin/python.

Установка в Docker (детали)

135. При использовании Docker данные Synapse хранятся в Docker-томе (volume) synapse-data.
136. Файлы конфигурации внутри контейнера находятся в /data.
137. Чтобы отредактировать homeserver.yaml, нужно зайти в контейнер: docker exec -it synapse /bin/bash.
138. Переменная окружения SYNAPSE_CONFIG_PATH указывает путь к конфигурационному файлу.
139. Для проброса портов при запуске используются ключи -p 8008:8008 (клиентский API) и -p 8448:8448 (федерация).
140. Логи Docker-контейнера смотрят командой docker logs -f synapse.
141. Обновление Synapse в Docker: docker pull matrixdotorg/synapse:latest && docker stop synapse && docker rm synapse && (запустить контейнер заново).
142. Преимущество Docker — изоляция и простота обновления (не нужно чистить конфиги).

Продвинутая диагностика

143. Команда для проверки, какие соединения с БД держит Synapse: ss -antp | grep python.*5432.
144. Множество соединений в состоянии ESTAB — это нормально (пул соединений).
145. Проверка версии Synapse: dpkg -l | grep matrix-synapse или docker exec synapse pip show matrix-synapse.
146. Проверка, какие правила iptables активны для Matrix: sudo iptables -L FORWARD -v -n | grep 10.214.97.46.
147. Просмотр статистики по пакетам в iptables (колонка pkts показывает, сколько пакетов прошло).
148. Если счетчики пакетов в iptables растут, а звонка нет — проблема внутри контейнера (Coturn).
149. Если счетчики не растут — проблема на хосте (Firewall, проброс портов).
150. Для диагностики конфликтов портов используется sudo ss -lupn | grep <порт>.

Решение проблем с конфигурацией (conf.d)

151. При использовании conf.d/ важно помнить, что файлы загружаются в алфавитном порядке.
152. Позже загруженные настройки могут переопределить более ранние.
153. Если в основном homeserver.yaml и в conf.d/ есть одинаковые секции, сервер может не запуститься с ошибкой Duplicate key.
154. Правильный подход: в основном файле оставлять только то, что нужно, а специфичные настройки выносить в conf.d/.
155. Для отключения какой-либо опции лучше закомментировать её во всех местах.
156. Файлы в conf.d/ должны иметь права на чтение для пользователя matrix-synapse.
157. Проверить, какие файлы из conf.d/ загружаются, можно в логах при запуске сервера (уровень INFO).

Интеграция с Coturn и WebRTC

158. Параметр turn_user_lifetime определяет время жизни учетных данных TURN (например, 86400000 мс или 1h).
159. turn_allow_guests: true разрешает гостевым пользователям использовать TURN-сервер.
160. В конфиге Coturn listening-ip можно указать как 0.0.0.0, чтобы слушать на всех интерфейсах.
161. min-port и max-port должны точно совпадать с диапазоном, проброшенным в iptables.
162. fingerprint в Coturn включает добавление отпечатка в пакеты STUN, что требуется некоторыми WebRTC-клиентами.
163. lt-cred-mech включает механизм долговременных учетных данных.
164. Для отладки звонков полезно включить verbose в Coturn и смотреть логи.
165. Если в логах Coturn появляется 401 Unauthorized, значит не совпадает static-auth-secret с turn_shared_secret в Synapse.
166. Если в логах пусто, а пакеты в iptables есть, скорее всего, Coturn блокирует подсеть клиента (проверить denied-peer-ip).

Настройка Element Web

167. Element можно разместить на отдельном поддомене (например, element.nbics.net) или на том же, что и Synapse.
168. Скачать последнюю версию Element: wget https://github.com/vector-im/element-web/releases/latest/download/element.tar.gz.
169. Распаковать архив в веб-директорию: tar -xzf element.tar.gz -C /var/www/element.
170. Конфигурационный файл Element — config.json в корне веб-директории.
171. В config.json обязательно указать base_url вашего Synapse:

```json
{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.nbics.net",
      "server_name": "nbics.net"
    }
  }
}
```

172. Можно отключить гостевой доступ: "disable_guests": true.
173. Для изменения названия бренда используется параметр "brand": "Мой Мессенджер".
174. Element лучше проксировать через тот же Nginx, что и Synapse, с отдельным server_name.
175. Для кэширования статических файлов Element в Nginx можно добавить заголовки expires 1y; add_header Cache-Control "public, immutable";.

Управление медиафайлами

176. Медиафайлы (изображения, видео, документы) хранятся в директории media_store_path.
177. Synapse автоматически создает хэш-директории внутри этой папки для хранения файлов.
178. Просмотр занятого места под медиа: du -sh /var/lib/matrix-synapse/media.
179. Удаление старых или неиспользуемых медиафайлов можно делать через API администратора.
180. max_image_pixels: 32M ограничивает максимальный размер изображения (в пикселях) для предотвращения DoS-атак.

API администратора (примеры)

181. Для использования API администратора нужен access_token пользователя с правами администратора.
182. Получение списка пользователей (с пагинацией):
     curl -s "http://localhost:8008/_synapse/admin/v2/users?from=0&limit=100" -H "Authorization: Bearer ТОКЕН" | jq .
183. Получение информации о конкретном пользователе:
     curl -s "http://localhost:8008/_synapse/admin/v2/users/@user:domain" -H "Authorization: Bearer ТОКЕН"
184. Деактивация пользователя (мягкое удаление):
     curl -X PUT -H "Authorization: Bearer ТОКЕН" "http://localhost:8008/_synapse/admin/v2/users/@user:domain" -d '{"deactivated": true}'
185. Удаление пользователя (без возможности восстановления):
     curl -X DELETE -H "Authorization: Bearer ТОКЕН" "http://localhost:8008/_synapse/admin/v1/deactivate/@user:domain"
186. Очистка медиафайлов пользователя:
     curl -X POST -H "Authorization: Bearer ТОКЕН" "http://localhost:8008/_synapse/admin/v1/media/@user:domain/delete" -d '{"delete_profiles": true}'

Интеграция с почтой (необязательно)

187. Synapse может отправлять email-уведомления (например, для сброса пароля).
188. Для этого нужно настроить секцию 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>"
```

189. Email используется только для системных уведомлений, а не для регистрации (если она отключена).

Миграция с SQLite на PostgreSQL

190. Если изначально использовался SQLite, можно перенести данные в PostgreSQL.
191. Остановить Synapse: systemctl stop matrix-synapse.
192. Сделать дамп SQLite: sqlite3 /var/lib/matrix-synapse/homeserver.db .dump > synapse_dump.sql.
193. Создать базу и пользователя в PostgreSQL (как описано выше).
194. Импортировать дамп в PostgreSQL: sudo -u postgres psql -d synapse < synapse_dump.sql.
195. Важно: дамп SQLite может потребовать ручной правки (удаление строк, специфичных для SQLite).
196. После импорта настроить Synapse на использование PostgreSQL и перезапустить.

Безопасность и мониторинг

197. Регулярно обновляйте Synapse: apt update && apt upgrade matrix-synapse-py3.
198. Подпишитесь на рассылку безопасности Matrix.org.
199. Следите за логами на предмет подозрительной активности (попытки брутфорса, спам-регистрации).
200. Настройте автоматическое резервное копирование базы данных и папки с медиафайлами.

[Admin]

Справочник по Matrix Synapse (Пункты 201–300)

Глубокая настройка федерации

201. Для федерации через порт 443 (вместо 8448) используется делегирование через .well-known/matrix/server.
202. Альтернативный метод делегирования — SRV-запись в DNS: _matrix._tcp.domain.com. 3600 IN SRV 10 0 443 matrix.domain.com.
203. SRV-запись имеет приоритет перед .well-known, но сложнее в настройке.
204. Если федерация не работает, проверьте, что порт 443 открыт для входящих соединений из любых IP-адресов.
205. Другие серверы Matrix подключаются к вашему серверу по протоколу HTTPS и ожидают валидный SSL-сертификат.
206. Ошибка "Certificate signed by unknown authority" означает, что сертификат не доверенный (самоподписанный).
207. Ошибка "Connection refused" означает, что порт 443 закрыт файерволом или сервис не слушает.
208. Ошибка "401 Unauthorized" при федерации возникает из-за проблем с подписью ключей или неверным server_name.
209. Параметр federation_verify_dns (по умолчанию true) заставляет Synapse проверять SRV-записи при федерации.
210. federation_client_minimum_version позволяет задать минимальную версию протокола для федерации.
211. Для отладки федерации включите логирование на уровень DEBUG в log.yaml для модуля synapse.federation.

Мосты (Bridges)

212. Мосты позволяют подключать к Matrix другие мессенджеры: Telegram, WhatsApp, Signal, Slack, Discord и др.
213. Мосты обычно запускаются как отдельные сервисы (часто в Docker) и подключаются к Synapse через API.
214. Самый популярный мост для Telegram — mautrix-telegram.
215. Для установки моста требуется отдельный домен (обычно telegram.domain.com или bridge.domain.com).
216. Мосты часто используют собственные базы данных (SQLite/PostgreSQL) и могут потреблять много ресурсов.
217. При настройке моста необходимо создать в Synapse специального пользователя для моста (например, @telegrambot:domain.com).
218. В конфиге Synapse может потребоваться добавление моста в federation_domain_whitelist, если он настроен на отдельном домене.
219. Логи мостов обычно хранятся отдельно и помогают диагностировать проблемы с доставкой сообщений.
220. После настройки моста пользователи могут приглашать контакт моста в комнату для связи с внешним мессенджером.

Интеграция с SSO (OIDC/LDAP)

221. Synapse поддерживает Single Sign-On (SSO) через OpenID Connect (OIDC).
222. Это позволяет входить в Matrix, используя учетные записи Google, GitHub, Keycloak или корпоративного провайдера.
223. Настройка OIDC производится в секции oidc_providers конфигурации Synapse.
224. Пример настройки для Keycloak:

```yaml
oidc_providers:
  - idp_id: keycloak
    idp_name: "Keycloak"
    issuer: "https://keycloak.domain.com/realms/myrealm"
    client_id: "matrix-client"
    client_secret: "secret"
    scopes: ["openid", "profile", "email"]
    user_mapping_provider:
      config:
        localpart_template: "{{ user.preferred_username }}"
        display_name_template: "{{ user.name }}"
        email_template: "{{ user.email }}"
```

225. При использовании SSO регистрация новых пользователей происходит автоматически при первом входе (если включена).
226. LDAP-аутентификация также поддерживается через модуль matrix-synapse-ldap3.
227. Установка модуля LDAP: pip install matrix-synapse-ldap3 или через пакетный менеджер (если доступен).
228. Настройка LDAP требует указания URI сервера, базы поиска (base DN) и фильтров для поиска пользователей.
229. При использовании LDAP пароли не хранятся в Synapse, а проверяются напрямую у LDAP-сервера.

Пространства (Spaces)

230. Spaces (пространства) — это способ организации комнат в иерархические структуры (аналог серверов в Discord).
231. Spaces v2 поддерживаются начиная с Synapse 1.121+.
232. Пространства могут быть публичными (видны всем) или приватными.
233. Для создания пространства используется клиент Element (или другой, поддерживающий Spaces).
234. API для управления пространствами доступно администраторам для массового создания/удаления.
235. Пространства могут содержать другие пространства, создавая древовидную структуру.

Голосовые и видеозвонки (WebRTC)

236. WebRTC использует ICE (Interactive Connectivity Establishment) для поиска пути между клиентами.
237. STUN-сервер помогает клиентам узнать свой внешний IP-адрес.
238. TURN-сервер ретранслирует трафик, если прямое соединение невозможно.
239. В конфиге Synapse для TURN указывается несколько URI для разных протоколов (UDP, TCP, TLS).
240. Параметр turn_uris должен содержать полные URI: turn:turn.domain.com:3478?transport=udp.
241. TURN-сервер Coturn может использовать TLS на порту 5349 для защищенного соединения.
242. Для этого в конфиге Coturn нужно указать cert и pkey (пути к SSL-сертификатам) и tls-listening-port=5349.
243. Клиенты автоматически выбирают наиболее эффективный путь (P2P если возможно, иначе через TURN).
244. WebRTC требует открытого диапазона UDP-портов для медиа-трафика (обычно 49152-65535).
245. Если звонки не работают, проверьте, что клиенты получают правильные turn_uris (через F12 в Element).
246. Для тестирования TURN/STUN можно использовать сайт https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/.

Шифрование (E2EE)

247. Matrix поддерживает сквозное шифрование (E2EE) по умолчанию для приватных комнат.
248. Шифрование основано на протоколе Olm и Megolm.
249. Ключи шифрования хранятся на клиентах пользователей, сервер не имеет доступа к содержимому сообщений.
250. Для восстановления доступа к зашифрованным сообщениям используется механизм "key backup" (резервное копирование ключей).
251. Резервное копирование ключей может быть защищено парольной фразой или храниться на сервере в зашифрованном виде.
252. При первом входе в Element клиент предложит настроить резервное копирование ключей.
253. Администратор не может расшифровать сообщения пользователей без их ключей.
254. Шифрование может быть отключено для публичных комнат, но не рекомендуется.

Модерация и управление комнатами

255. Администраторы комнат могут назначать модераторов (power level 50) и администраторов (power level 100).
256. Команды модерации в Element:
     - /kick @user:domain — исключить пользователя
     - /ban @user:domain — забанить пользователя
     - /unban @user:domain — разбанить
     - /redact <event_id> — удалить сообщение
257. Можно устанавливать правила комнаты (server ACLs) для блокировки определенных серверов.
258. Server ACLs настраиваются в конфигурации комнаты (в Element: Настройки комнаты -> Безопасность).
259. Для массовой модерации используется модуль Mjolnir (бота-модератора).
260. Mjolnir позволяет синхронизировать списки заблокированных пользователей и серверов между комнатами.
261. Установка Mjolnir требует отдельного сервера или контейнера и доступа к API Synapse.

Масштабирование и производительность

262. При росте числа пользователей (сотни и тысячи) SQLite перестает справляться — PostgreSQL обязателен.
263. Synapse поддерживает горизонтальное масштабирование через разделение компонентов (worker-архитектура).
264. Воркеры (workers) позволяют вынести обработку разных типов запросов на отдельные процессы.
265. Типы воркеров:
     - synapse.app.generic_worker — общий воркер
     - synapse.app.federation_sender — отправка федеративных событий
     - synapse.app.media_repository — обслуживание медиафайлов
     - synapse.app.pusher — отправка push-уведомлений
266. Настройка воркеров сложна и требует изменений в конфигурации Nginx и Synapse.
267. Для небольших установок (до 1000 пользователей) одного процесса Synapse достаточно.
268. Медиафайлы можно вынести на отдельное хранилище (NFS, S3) при масштабировании.
269. Synapse поддерживает хранение медиа в S3-совместимых хранилищах (через модуль s3-storage-provider).
270. Кэширование в Redis (начиная с Synapse 1.113+) значительно улучшает производительность.
271. Настройка Redis: указать параметры в секции redis конфигурации.

Резервное копирование и восстановление

272. Критически важные данные для бэкапа: база данных (PostgreSQL) и папка с медиафайлами.
273. Для PostgreSQL используется pg_dump:
     sudo -u postgres pg_dump synapse > /backup/synapse_$(date +%Y%m%d).sql
274. Для восстановления: sudo -u postgres psql -d synapse < backup.sql.
275. Медиафайлы можно копировать через rsync или tar:
     tar -czf /backup/media_$(date +%Y%m%d).tar.gz /var/lib/matrix-synapse/media
276. Ключ подписи сервера (homeserver.signing.key) также необходимо сохранить, иначе федерация сломается.
277. Автоматизацию бэкапов лучше настроить через cron.
278. Для инкрементального бэкапа больших медиа-хранилищ используйте rsync.
279. При восстановлении убедитесь, что версия Synapse совпадает с той, на которой был сделан бэкап (из-за миграций БД).
280. Тестируйте восстановление на тестовом сервере, чтобы убедиться в целостности бэкапов.

Мониторинг и алертинг

281. Synapse предоставляет метрики в формате Prometheus на порту 9000 (если включено).
282. Включение метрик: добавить enable_metrics: true и открыть порт в listeners.
283. Пример listeners для метрик:

```yaml
listeners:
  - port: 9000
    type: metrics
    bind_addresses: ['127.0.0.1']
```

284. Метрики доступны по URL: http://localhost:9000/_synapse/metrics.
285. Prometheus может собирать эти метрики, а Grafana — отображать дашборды.
286. Ключевые метрики для мониторинга:
     - Количество активных пользователей
     - Количество отправленных сообщений
     - Время отклика API
     - Использование памяти и CPU
     - Размер базы данных
287. Для мониторинга логов можно использовать Loki или Elasticsearch.
288. Алертинг можно настроить в Prometheus Alertmanager для отправки уведомлений в Telegram/Slack.

Ограничения и лимиты

289. Максимальный размер одного сообщения (текст + вложения) ограничен max_request_size (по умолчанию 50M).
290. Максимальный размер загружаемого файла — max_upload_size (по умолчанию 10M, рекомендуется увеличить до 100M+).
291. Количество пользователей в комнате технически не ограничено, но производительность падает при тысячах участников.
292. Для больших комнат рекомендуется использовать архитектуру с выделенными воркерами.
293. Количество одновременных подключений к базе данных ограничено параметром cp_max в настройках БД.
294. Скорость отправки сообщений может быть ограничена параметрами rc_message, rc_login и другими.
295. При превышении лимитов Synape возвращает ошибки с кодом 429 (Too Many Requests).

Устаревшие настройки и миграции

296. Ранее Synapse использовал /opt/venvs/matrix-synapse для виртуального окружения Python. Сейчас пакеты устанавливаются системно.
297. Если вы видите старые пути в инструкциях (до 2024 года), они могут быть неактуальны.
298. Миграция со старой версии на новую обычно описывается в официальном блоге Matrix.org.
299. Перед обновлением всегда читайте release notes и проверяйте наличие обязательных миграций БД.
300. При обновлении с пропуском нескольких версий могут потребоваться промежуточные обновления.

[Admin]

Справочник по Matrix Synapse (Пункты 301–374)

Сборный: сетевые проблемы в контейнерах, продвинутая диагностика, API, сравнение установок и практические советы

Incus/LXD, Docker и Сетевые Конфликты

301. Incus/LXD создает изолированную сеть для контейнеров, что приводит к двойному NAT (Double NAT) и усложняет прохождение WebRTC-трафика.
302. В отличие от нативной установки, в контейнере Incus сервис (Synapse/Coturn) видит только свой внутренний IP (например, 10.214.97.46), а не реальный внешний IP хоста.
303. Это требует обязательной настройки external-ip в Coturn в формате external-ip=ВНЕШНИЙ_IP/ВНУТРЕННИЙ_IP (например, external-ip=91.221.70.18/10.214.97.46).
304. Docker и Incus на одном хосте часто конфликтуют, так как оба активно управляют цепочками iptables, вставляя свои правила в самый верх.
305. Конфликт с Jitsi — частая проблема, так как Jitsi Videobridge по умолчанию использует порт 10000 UDP и может перехватывать трафик, предназначенный для Matrix.
306. Проверить, какие UDP-порты заняты Docker-контейнерами, можно командой: sudo ss -lupn | grep docker-proxy.
307. Чтобы избежать конфликтов, необходимо разносить диапазоны портов для разных сервисов (например, Jitsi — 10000, Matrix — 49152-65535).
308. При использовании Incus стандартные пробросы портов через incus config device add неэффективны для больших диапазонов UDP, требуется прямое вмешательство в iptables на хосте.
309. Правила iptables, добавленные вручную, живут только в памяти и исчезают после перезагрузки, если их не сохранить.
310. Команда для сохранения правил iptables: sudo netfilter-persistent save (требуется пакет iptables-persistent).
311. Просмотр сохраненных правил: cat /etc/iptables/rules.v4.

Глубокая Диагностика Сети и Пакетов

312. Если tcpdump внутри контейнера показывает входящие пакеты от клиента, а Coturn в логах молчит — значит, Coturn отклоняет пакеты на уровне приложения.
313. Самая частая причина такого молчания — блокировка подсети клиента через директиву denied-peer-ip в turnserver.conf.
314. Для контейнеров с IP в диапазоне 10.x.x.x критически важно закомментировать строку denied-peer-ip=10.0.0.0-10.255.255.255.
315. Пакеты могут "стучаться" в порт 3478, но Coturn не считает их валидными STUN-запросами из-за несовпадения realm или отсутствия fingerprint.
316. Ошибка "401 Unauthorized" в логах Coturn при попытке звонка — явный признак несовпадения static-auth-secret в Coturn и turn_shared_secret в Synapse.
317. Для детальной диагностики WebRTC-соединения в браузере (Element) нужно открыть инструменты разработчика (F12) и изучить вкладку "Network" и "Console".
318. Поиск в консоли по словам "ICE", "TURN", "STUN" покажет, какие серверы пытается использовать клиент.
319. Если в консоли нет упоминаний вашего TURN-сервера, значит Synapse не отдал клиенту его настройки (проблема в секции turn_uris).
320. Команда для проверки, что Synapse "видит" свой TURN-сервер изнутри контейнера: curl http://localhost:8008/_matrix/client/versions (это не проверит TURN, но проверит работу Synapse).

API Администратора (Практические Примеры)

321. Получение короткого токена администратора одной строкой (замените 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')
322. Создание алиаса для удобного получения токена:
     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'
323. Получение списка всех комнат на сервере (осторожно, может быть много):
     curl -s "http://localhost:8008/_synapse/admin/v1/rooms?limit=100" -H "Authorization: Bearer $TOKEN" | jq '.rooms[].room_id'
324. Удаление комнаты (очистка данных):
     curl -X DELETE "http://localhost:8008/_synapse/admin/v1/rooms/!room_id:domain" -H "Authorization: Bearer $TOKEN"
325. Получение статистики по медиафайлам:
     curl -s "http://localhost:8008/_synapse/admin/v1/statistics" -H "Authorization: Bearer $TOKEN" | jq .
326. Просмотр активных сессий пользователя:
     curl -s "http://localhost:8008/_synapse/admin/v1/whois/@user:domain" -H "Authorization: Bearer $TOKEN" | jq .devices
327. Блокировка сервера на уровне федерации (Server ACL) через API — сложная задача, проще через интерфейс комнаты.
328. Сброс пароля пользователя через 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\"}"
}
```

Сравнение Способов Установки

329. Нативная установка (Debian/Ubuntu) — максимальная простота, лучшая производительность, легкая интеграция с Coturn, но "засоряет" систему и сложнее в изоляции.
330. Установка в Docker — хорошая изоляция, легкие обновления, но сложнее с пробросом UDP-портов и работой WebRTC.
331. Установка в Incus/LXD — отличная изоляция, удобные снапшоты, но самые большие проблемы с WebRTC из-за двойного NAT.
332. YunoHost — максимальная простота для новичков, все работает "из коробки", включая звонки, но меньше гибкости и контроля.
333. Вывод: для продакшена с видео/звонками лучше всего подходит нативная установка на хост. Контейнеры хороши для тестов и изолированных сред без VoIP.

Проблемы с PostgreSQL и Базами Данных

334. Проверить, использует ли Synapse PostgreSQL, можно командой ss -antp | grep 5432 | grep python. Наличие ESTAB соединений — признак использования PostgreSQL.
335. Если в логах нет ошибок, но база данных не растет, возможно, Synapse все еще пишет в SQLite. Проверьте дату изменения файла /var/lib/matrix-synapse/homeserver.db.
336. Конфликт между настройками БД в homeserver.yaml и conf.d/ может привести к тому, что Synapse не запустится с ошибкой Duplicate key.
337. При миграции с SQLite на PostgreSQL дамп SQLite требует ручной корректировки (удаление команд, специфичных для SQLite, например, BEGIN TRANSACTION может дублироваться).
338. Параметр cp_min и cp_max в конфиге БД управляют размером пула соединений. Для больших серверов cp_max можно увеличить до 20-30.

Практические Команды Администратора (Продолжение)

339. Быстрый просмотр последних ошибок в логах Synapse:
     journalctl -u matrix-synapse -n 50 -f | grep -i error
340. Проверка, слушает ли Coturn нужные порты внутри контейнера:
     ss -ulnp | grep 3478 (UDP) и ss -tlnp | grep 3478 (TCP).
341. Проверка версии Synapse из командной строки:
     dpkg -l | grep matrix-synapse (для пакетной установки) или docker exec synapse pip show matrix-synapse.
342. Просмотр переменных окружения внутри контейнера Docker:
     docker exec synapse env.
343. Интерактивный вход в контейнер Docker:
     docker exec -it synapse /bin/bash.
344. Просмотр логов конкретного контейнера Docker с временными метками:
     docker logs -t synapse.
345. Остановка всех контейнеров Docker разом (для теста конфликтов):
     docker stop $(docker ps -q).
346. Поиск файлов конфигурации Coturn:
     find / -name "turnserver.conf" 2>/dev/null.
347. Просмотр открытых файлов процессом Coturn:
     lsof -p $(pgrep turnserver).

Теория NAT и WebRTC (Почему это сложно)

348. STUN позволяет клиенту узнать свой внешний IP и порт, чтобы сообщить их собеседнику для прямого соединения.
349. TURN используется, когда прямое соединение невозможно (симметричный NAT, корпоративные файерволы). Сервер ретранслирует трафик.
350. ICE — это протокол, который собирает все возможные кандидаты (STUN, TURN, локальные адреса) и пытается установить соединение, перебирая их.
351. В контейнере Incus Coturn видит только свой внутренний IP (10.214.97.46). Без external-ip он сообщит клиенту именно его, и клиент не сможет подключиться.
352. Эффект "пробитого NAT" (UDP Hole Punching) — когда после успешного прохождения одного пакета NAT "запоминает" маршрут и временно открывает его для обратного трафика.
353. Именно поэтому иногда "вчера не работало, а сегодня работает": таблица трансляции адресов (conntrack) могла очиститься или, наоборот, зафиксировать успешный проход.

Разное Важное

354. При использовании внешнего реверс-прокси (Nginx) в конфиге Synapse обязателен параметр x_forwarded: true в секции listeners.
355. Для корректной работы федерации server_name в Synapse должен быть именно доменом, а не поддоменом (если вы хотите короткие ID @user:domain.com). Иначе используйте .well-known делегирование.
356. Параметр max_upload_size измеряется в байтах. 50M = 50 * 1024 * 1024 = 52428800.
357. При изменении server_name на уже работающем сервере все существующие пользователи и комнаты "сломаются", так как их ID привязаны к старому имени.
358. Synapse поддерживает ротацию логов. Настройки ротации находятся в /etc/logrotate.d/matrix-synapse.
359. Для мониторинга можно использовать готовый дашборд Grafana для Synapse (например, из официального репозитория).
360. Ошибка "Connection refused" при попытке curl с хоста в контейнер почти всегда означает, что сервис внутри контейнера слушает только 127.0.0.1, а не 0.0.0.0.
361. Команда для изменения bind_addresses в Synapse внутри контейнера: отредактировать файл в /conf.d/ или изменить основной конфиг.
362. Файл /etc/matrix-synapse/conf.d/server_name.yaml создается автоматически при установке из пакета и содержит только server_name: "ваш.домен".
363. Не рекомендуется редактировать этот файл, если вы уже указали домен при установке. Для изменения домена проще переустановить сервер.
364. Параметр enable_registration_captcha включает капчу при регистрации. Требует настройки ReCaptcha от Google.
365. Для использования капчи нужно получить ключи на сайте Google ReCaptcha и указать их в конфиге.
366. Модули Synapse (spam checker, 3pid providers) расширяют функциональность сервера и настраиваются в секции modules.
367. Официальная документация Synapse — лучший источник информации: https://element-hq.github.io/synapse/latest/.
368. Сообщество Matrix в Telegram (@matrix_ru) — отличное место для получения помощи на русском языке.

Итоговые проверки работоспособности

369. Финальная проверка федерации без внешних тестеров: с одного сервера пригласить пользователя с другого сервера и отправить сообщение.
370. Финальная проверка звонков: позвонить с пользователя на одном сервере пользователю на другом сервере.
371. Проверка логирования: убедиться, что логи пишутся и не забивают диск.
372. Проверка автоматического запуска: systemctl is-enabled matrix-synapse и systemctl is-enabled coturn.
373. Проверка открытых портов снаружи: использовать онлайн-сервисы вроде yougetsignal.com или portchecker.co.
374. Проверка валидности SSL-сертификата: openssl s_client -connect matrix.domain.com:443 -servername matrix.domain.com < /dev/null 2>/dev/null | openssl x509 -text | grep -A2 Validity.