Обеспечьте доступность вашего сервера Matrix Synapse для федерации.

Чтобы сделать домашний сервер Matrix Synapse федеративным, необходимо обеспечить доступность его имени сервера из общедоступного интернета по протоколу HTTPS, а затем направлять запросы между серверами Matrix в Synapse. В стандартной конфигурации обратный прокси-сервер обрабатывает TLS на порту 443, а файл /.well-known/matrix/serverуказывает вашему домену Matrix на этот прокси. Если Synapse уже отвечает на запросы вашего домена с именем сервера на порту 8448, делегирование может не потребоваться.

example.comВ этом руководстве в качестве постоянного имени сервера Matrix используется имя matrix.example.comмашины или прокси-сервера. Замените оба имени на свои собственные. Домашний сервер хранит учетные записи и комнаты Matrix; федерация позволяет домашним серверам взаимодействовать друг с другом. DNS, правила брандмауэра, синтаксис прокси, сетевые возможности контейнеров и сертификаты зависят от вашего хоста.

Перед изменением конфигурации

Определите, должны ли идентификаторы Matrix ID пользователей выглядеть как @name:example.comили @name:matrix.example.com. Значение server_nameв homeserver.yamlстановится частью идентификаторов Matrix ID и адресов помещений. В документации по установке Synapse указано, что его следует выбрать до установки, поскольку впоследствии его нельзя будет изменить без последствий. Если Synapse уже используется, не меняйте его только для соответствия веб-адресу; используйте делегирование для сохранения существующих идентификаторов.

В редакторе YAML отображается server_name: example.com и напоминание о необходимости выбрать это значение перед установкой.
Имя сервера входит в состав идентификаторов Matrix ID, поэтому подтвердите его перед продолжением.

Перед редактированием убедитесь, что у вас есть доступ к Synapse, прокси-серверу и публичному DNS, а также действительный TLS-сертификат для конечной точки федерации. Создайте резервную копию homeserver.yamlключа подписи, который определяет подлинность домашнего сервера. Храните этот ключ в безопасном месте; при стандартной настройке федерации его повторная генерация не требуется.

Организуйте общественный маршрут.

1. Подтвердите наличие HTTP-слушателя в Synapse.

Synapse обычно прослушивает HTTP-трафик на порту 8008за обратным прокси-сервером. В прослушивателе, принимающем трафик прокси, установите параметры x_forwarded: true, чтобы Synapse мог использовать адрес клиента и схему, перенаправляемые прокси. Прокси должен устанавливать соответствующие X-Forwarded-Forзаголовки X-Forwarded-Proto, а не передавать произвольные значения, предоставленные внешними клиентами.

Фрагмент YAML-файла прослушивателя показывает работу Synapse на HTTP-порту 8008 с включенной функцией x_forwarded и адресом привязки обратной связи.
Слушатель принимает HTTP-запросы от локального прокси-сервера и включает обработку переадресованных заголовков Synapse.

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

2. Маршруты матрицы маршрутизации проходят через прокси-сервер.

Настройте виртуальный хост HTTPS прокси-сервера для переадресации обоих запросов /_matrixна /_synapse/clientHTTP-слушатель Synapse. Первый путь содержит API Matrix, включая федерацию; второй используется для конечных точек клиента Synapse. Следуйте официальному примеру для вашего прокси-сервера, сохраните путь запроса и отправьте заголовки переадресации, которые ожидает Synapse. Не нормализуйте, не декодируйте и не переписывайте пути URI: подписи запросов Matrix могут завершиться неудачей, если прокси-сервер изменит закодированный путь.

Редактор конфигурации обратного прокси показывает пути к API Matrix и клиенту Synapse, перенаправляемые на локальный хост, порт 8008, с переадресацией заголовков.
Прокси-сервер должен передавать оба пути API Matrix в Synapse без перезаписи URI.

Точная конфигурация различается в зависимости от используемого Nginx, Caddy, Apache, балансировщиков нагрузки и управляемого хостинга. Используйте текущий синтаксис поставщика и документацию по обратному прокси-серверу Synapse в качестве справочного материала. Правило прокси, которое обслуживает веб-клиент, но не включает путь к API федерации, недостаточно.

3. Настройте DNS, HTTPS и выбранный порт в соответствии друг с другом.

В качестве примера, маршрут matrix.example.comдолжен разрешаться в прокси-сервер или балансировщик нагрузки, а порт 443должен быть доступен извне. Прокси-серверу необходим действительный сертификат для matrix.example.com. Если вы вместо этого обслуживаете федерацию напрямую по адресу example.com:8448, опубликуйте этот маршрут и сертификат и откройте порт 8448. Используйте либо прямой порт 8448, обычный порт по умолчанию, либо делегирование другому хосту и порту, например, 443.

Проверьте правила DNS, брандмауэра или группы безопасности облачной инфраструктуры, а также сертификат извне вашей частной сети. Если перед вами находится CDN или туннель, поддержка необходимого трафика Matrix зависит от текущей конфигурации этой службы; проверьте ее документацию и протестируйте фактический маршрут, а не предполагайте совместимость.

При необходимости публикуйте результаты обнаружения федерации.

4. Добавьте делегирование сервера для отдельной конечной точки.

Если домен Matrix ID — example.com, но Synapse доступен по адресу matrix.example.com:443, то передайте этот JSON по HTTPS по адресу https://example.com/.well-known/matrix/server:

{
  "m.server": "matrix.example.com:443"
}
В представлении JSON в браузере по адресу example.com/.well-known/matrix/server содержится значение m.server matrix.example.com:443.
Эта запись обнаружения федерации перенаправляет example.com на HTTPS-конечную точку matrix.example.com на порту 443.

В этом примере порт 443 указан явно; если вы его опустите, обнаружение Matrix по умолчанию будет осуществляться через порт 8448. Не путайте этот файл с файлом /.well-known/matrix/client, который помогает клиентам находить API клиент-сервер и отделен от федерации сервер-сервер. Synapse может самостоятельно предоставлять доступ к известному серверу файлу, если доменное имя сервера напрямую перенаправляется в Synapse, но при использовании отдельной конечной точки обычно файл публикуется на веб-сервере доменного имени сервера.

Обнаружение федерации определяется спецификацией Matrix и документируется Synapse. Спецификация Matrix позволяет обнаруживать федерацию с помощью ; перед выбором другого метода, например, записи SRV, /.well-known/matrix/serverпроверьте инструкции по делегированию Synapse , так как это также влияет на ожидания TLS.

Тестирование извне сервера

5. Проверьте запись, затем выполните проверку федерации.

Запросите URL-адрес обнаружения с компьютера, находящегося за пределами частной сети сервера. Он должен вернуть указанный выше JSON-объект по протоколу HTTPS без страницы входа в систему, перенаправления HTML, предупреждения о сертификате или посторонних веб-сайтов. Затем проверьте, что делегированное имя хоста разрешается, его сертификат действителен, а заявленный порт достигает Synapse. Перед тестированием используйте средство проверки конфигурации вашего прокси-сервера и процедуру перезагрузки.

Наконец, введите имя вашего сервера (например, example.com, а не делегированное имя хоста, если это не ваш server_name) в официальном тестере федерации Matrix . В руководстве по федерации Synapse также рекомендуется проводить тестирование, присоединившись к общедоступной комнате, например #synapse:matrix.org, . Успешная проверка подтверждает, что общие проверки обнаружения и доступности пройдены; это не гарантирует работоспособность каждого удаленного сервера или каждой операции в комнате, поскольку удаленные политики и сетевые условия могут различаться.

Если программа тестирования сообщает о недоступности вашего сервера, проверьте домен и порт, DNS, правила брандмауэра, имя сертификата, пути прокси, переадресованные заголовки и наличие изменений в запросе, вызванных перенаправлением. В текущей документации по федерации Synapse особо предупреждается, что федеративные серверы Synapse в некоторых случаях могут не следовать перенаправлениям HTTP 308. Избегайте использования перенаправлений 308 для конечной точки федерации и повторите тестирование после исправления ошибки. Для получения информации о поведении, специфичном для вашей версии Synapse, обратитесь к документации, соответствующей вашей установленной версии.

Для работы федерации удаленные домашние серверы должны обнаруживать и обращаться к вашему API федерации. Невозможно определить, будет ли это работать на каждом удаленном сервере, основываясь только на конфигурации. Подтвердите маршрут с помощью тестировщика и реального подключения к комнате, а затем исследуйте конкретную неработающую конечную точку или ошибку.

Эти панели интерфейса представляют собой схематические примеры данных конфигурации и обнаружения, а не скриншоты с работающего сервера. Ссылки на документацию проверены 10 октября 2026 года.

Оставить комментарий

Устранение ошибок доступа администратора Matrix Room с помощью действий.

Найдите в сообщении M_FORBIDDEN информацию об уровне мощности комнаты, членстве в группе или доступе администратора сервера Synapse, а затем восстановите только те разрешения, которые необходимы для заблокированного действия.

Обеспечьте доступность вашего сервера Matrix Synapse для федерации.

Обеспечьте доступность вашего сервера Matrix Synapse для федерации.

Настройте обнаружение Synapse, HTTPS и маршрутизацию через прокси, чтобы другие домашние серверы Matrix могли найти ваш сервер и связаться с ним.

Подключите Element Web к Keycloak через Synapse OIDC.

Настройте клиент Keycloak OIDC и провайдер Synapse, чтобы пользователи Element Web могли входить в систему через ваш сервер идентификации, не раскрывая секретные данные клиентов.

Настройте безопасное резервное копирование ключей элементов и перекрестную подпись.

Настройте безопасное резервное копирование ключей элементов и перекрестную подпись.

Сохраните ключ восстановления, проверьте свои сеансы Element и убедитесь, что ключи зашифрованных сообщений можно восстановить, не путая резервную копию с паролем вашей учетной записи.

Остановите сбои памяти Matrix Synapse во время синхронизации клиента.

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

Устранение ошибок TLS-сертификата Synapse Federation

Выявите причину сбоев сертификатов федерации Matrix и определите правильный сервер, восстановите цепочку TLS или доверие к центру сертификации, а также проверьте правильность решения без отключения проверок безопасности.

Безопасная установка сервера Synapse Matrix за Cloudflare.

Безопасная установка сервера Synapse Matrix за Cloudflare.

Маршрутизация клиентов Matrix и федерация через Cloudflare по протоколу HTTPS 443, сохранение обнаружения Synapse и предотвращение кэширования API-трафика или нарушения загрузки медиафайлов.

Безопасное восстановление Matrix Synapse с помощью дампа PostgreSQL

Создайте резервную копию Synapse с помощью pg_dump, защитите ключ подписи и носители, а затем восстановите данные в чистую базу данных PostgreSQL, не используя повторно устаревшие одноразовые ключи.

Запустите Mjölnir в качестве бота для модерации комнат Matrix с помощью Docker.

Запустите Mjölnir в качестве бота для модерации комнат Matrix с помощью Docker.

Настройте Mjölnir, используя выделенный аккаунт Matrix, зашифрованную комнату управления, Docker Compose, список политик и проверки разрешений.

Включите встроенную синхронизацию Matrix Sliding для более быстрой загрузки на мобильных устройствах.

Включите встроенную синхронизацию Matrix Sliding для более быстрой загрузки на мобильных устройствах.

Откажитесь от устаревшего прокси и настройте встроенную в Synapse функцию Sliding Sync. Проверьте обнаружение клиентов, затем измерьте скорость загрузки списка комнат и поведение при переподключении на совместимом телефоне.