Как настроить сервер Matrix за прокси-сервером Cloudflare

Сервер Matrix может располагаться за Cloudflare, но настройка зависит от того, как клиенты и другие домашние серверы его обнаруживают. Стандартный HTTP-прокси Cloudflare поддерживает HTTPS на порту 443; федерация Synapse обычно использует порт 8448 по умолчанию, которого нет в стандартном списке портов проксирования Cloudflare. Надежное решение — предоставить доступ к Synapse через обратный прокси на порту 443 и опубликовать известные записи Matrix, которые направляют трафик клиентов и федерации на это имя хоста. В качестве альтернативы, можно оставить федерацию на порту 8448 и сделать эту DNS-запись только для DNS.

В этом руководстве используется Synapse, официальная реализация домашнего сервера Matrix, с примерами идентификаторов Matrix @alice:example.comи конечной точки клиента matrix.example.com. Замените эти имена и адреса на свои собственные. Инструкции предполагают, что Synapse и обратный прокси-сервер HTTPS уже установлены. Они не применимы без изменений ко всем реализациям домашнего сервера. Проверено по текущей документации Cloudflare и Element Synapse по состоянию на 6 октября 2026 года.

Выберите правильную схему сети.

Прокси-сервер orange-cloud от Cloudflare — это обратный HTTP/HTTPS-прокси. Он располагается между клиентами и вашим источником для обработки веб-запросов; он не проксирует каждый произвольный TCP-порт. В число его стандартных HTTPS-портов входят 443 и 8443, но не используется широко распространенный порт федерации Synapse — 8448. См. список поддерживаемых сетевых портов и ограничения проксирования Cloudflare .

Ниже используется первый вариант компоновки. Проксированная DNS-запись сама по себе не настраивает обнаружение Matrix, обратное проксирование, TLS или политику брандмауэра.

1. Определите имя сервера Matrix до настройки DNS.

Имя сервера Matrix — это часть, следующая за двоеточием в идентификаторе пользователя. В этом примере это example.com, поэтому у пользователей есть идентификаторы, например @alice:example.com. Техническое имя хоста клиента — matrix.example.com. Такое разделение позволяет домену, используемому в идентификаторах пользователей, оставаться стабильным, в то время как трафик делегируется другому имени хоста. Если Synapse уже инициализирован, не меняйте его server_nameбездумно: он является частью идентификации пользователя и комнаты, и его изменение — это миграция, а не настройка прокси.

Планируется отправить два небольших JSON-документа для обнаружения угроз из домена имени сервера:

• https://example.com/.well-known/matrix/clientуказывает совместимым клиентам использовать https://matrix.example.com.
• https://example.com/.well-known/matrix/serverуказывает другим домашним серверам подключаться к федерации по адресу matrix.example.com:443.

В клиентском документе необходим Access-Control-Allow-Origin: *заголовок ответа. В руководстве по делегированию Synapse приведены примеры таких записей и их ожидаемая структура: Делегирование федерации Synapse .

2. Создайте DNS-записи Cloudflare.

В настройках DNS Cloudflare создайте Aзапись matrix, указывающую на публичный IPv4-адрес сервера. Добавляйте AAAAзапись только в том случае, если у источника есть работающее IPv6-соединение и настроен брандмауэр для IPv6. Установите статус прокси для имени хоста веб-сервера на «Проксировано» (оранжевое облако). Если корневой домен также указывает на этот сервер и будет обслуживать общеизвестные файлы, проксируйте и его веб-запись.

Храните несвязанные записи, включая почтовые, в соответствующих настройках DNS. Записи MX и TXT не проксируются. Cloudflare поясняет, что проксируемая запись A, AAAA или CNAME направляет HTTP/HTTPS-запросы через Cloudflare, в то время как DNS возвращает исходный адрес напрямую: поведение статуса прокси Cloudflare .

Разрешите входящий HTTPS-трафик от Cloudflare к источнику. Для более надежной защиты ограничьте диапазон IP-адресов источника опубликованными Cloudflare и регулярно обновляйте эти диапазоны. Если IP-адрес сервера был открыт до активации зоны, проксирование DNS не аннулирует старый адрес; рассмотрите возможность изменения IP-адреса источника после активации. Не следует предполагать, что одно лишь оранжевое облако предотвращает прямой доступ к источнику.

3. Настройте HTTPS-соединение между Cloudflare и источником.

В настройках SSL/TLS Cloudflare используйте режим Full (strict), если источник предоставляет действительный сертификат для имени хоста, например, общедоступный доверенный сертификат или сертификат центра сертификации Cloudflare Origin CA. Режим Full (strict) шифрует соединение Cloudflare с источником и проверяет сертификат источника; режим Flexible не обеспечивает такой же сквозной TLS-трафик. См. документацию Cloudflare по режиму Full (strict) .

Установите сертификат и закрытый ключ на обратном прокси-сервере, не обязательно в Synapse. Обратный прокси-сервер должен прослушивать публичный порт 443 и перенаправлять запросы Matrix внутрь системы на HTTP-прослушиватель Synapse, обычно на порт 8008. Не делайте публичный доступ к прослушивателю Synapse, если обратный прокси-сервер предназначен быть единственной точкой входа.

4. Сообщите Synapse, что он использует доверенный обратный прокси-сервер.

В соответствующем HTTP-слушателе homeserver.yamlвключите обработку пересылаемых заголовков. Упрощенный пример для неконтейнеризированного сервера:

listeners:
  - port: 8008
    type: http
    tls: false
    x_forwarded: true
    bind_addresses: ['127.0.0.1']
    resources:
      - names: [client, federation]
        compress: false

Вместо замены всей конфигурации, объедините эти настройки с существующим прослушивателем. В поддерживаемой документации Synapse рекомендуется x_forwarded: trueиспользовать обратный прокси-сервер и привязываться к localhost, если прокси работает на том же хосте. При развертывании в контейнере привязка Synapse к локальной сети контейнера может помешать прокси-серверу хоста связаться с ним; вместо этого используйте сетевой адрес контейнера или службы и заблокируйте этот путь брандмауэром. Перед изменением настроек прослушивателя ознакомьтесь с текущим руководством по обратному прокси-серверу Synapse .

Пересылаемые заголовки заслуживают доверия только тогда, когда Synapse принимает трафик от вашего контролируемого прокси. Если Cloudflare — единственный доступный из интернета маршрут, предотвратите прямой публичный доступ к источнику и настройте прокси для передачи правильного адреса клиента. $remote_addrВ противном случае адрес Nginx будет адресом Cloudflare, поскольку Cloudflare подключился к Nginx. Настройте модуль real-IP Nginx так, чтобы он доверял только опубликованным диапазонам IP-адресов Cloudflare перед использованием CF-Connecting-IP; никогда не доверяйте этому заголовку от произвольных интернет-клиентов. Держите административный API Synapse закрытым, если у вас нет особой причины его открывать.

5. Прокладывайте пути в матрице маршрутизации без их перезаписи.

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

Вот компактный пример использования Nginx matrix.example.com. Предполагается, что директивы TLS-сертификатов уже настроены для этого блока сервера и что обратный прокси и Synapse работают на одном хосте:

server {
    listen 443 ssl;
    server_name matrix.example.com;

    location ~ ^(/_matrix|/_synapse/client) {
        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;
        proxy_http_version 1.1;
        client_max_body_size 50M;
    }
}

Не добавляйте суффикс URI к этому местоположению в регулярном выражении proxy_pass. В документации Synapse по прокси-серверам указывается, что канонизация URI является причиной ошибок подписи федерации. Также настройте параметры client_max_body_sizeв соответствии с лимитом загрузки Synapse и любым лимитом плана Cloudflare, применимым к вашей зоне. 50MПриведенное выше значение является лишь примером, а не универсальной рекомендацией.

Cloudflare поддерживает WebSockets в своих тарифных планах, и клиенты Matrix могут использовать долговременные соединения. Убедитесь, что ваш прокси-сервер разрешает обновление и что правила WAF или ограничения скорости не отклоняют легитимные запросы Matrix. В документации Cloudflare по WebSockets описана обработка обновленных соединений.

6. Опубликовать известные ответы.

Отправьте следующие два ответа по example.comпротоколу HTTPS. Вы можете получить их со своего веб-сервера, статического хоста или отдельного виртуального хоста. Разделяйте документы клиента и федерации:

GET /.well-known/matrix/client
HTTP/1.1 200 OK
Content-Type: application/json
Access-Control-Allow-Origin: *

{"m.homeserver":{"base_url":"https://matrix.example.com"}}

GET /.well-known/matrix/server
HTTP/1.1 200 OK
Content-Type: application/json

{"m.server":"matrix.example.com:443"}

Не используйте перенаправление на несвязанный хост в качестве замены, не проверив предварительно требования к обнаружению Matrix и поведение клиента. Убедитесь, что хост с именем сервера защищен действительным HTTPS-сертификатом и что Cloudflare не кэширует устаревшие ответы обнаружения во время их изменения.

7. Поддерживайте динамичность трафика API и контролируйте объемы загрузки в пределах установленных лимитов.

Не кэшируйте аутентифицированные ответы Matrix API. Добавьте правило кэширования Cloudflare, чтобы обойти кэширование для путей Matrix API, включая /_matrix/*и /_synapse/client/*, если у вас нет тщательно проверенной причины обрабатывать конкретный публичный ответ иначе. Избегайте общих правил WAF или ботов, которые проверяют или блокируют конечные точки федерации; запросы федерации поступают со многих независимых домашних серверов. Если правило безопасности необходимо, протестируйте его на входе клиента, синхронизации, загрузке медиафайлов и федерации, прежде чем применять его повсеместно.

Для загрузки файлов существует несколько независимых ограничений: на стороне клиента, в настройках плана или зоны загрузки Cloudflare, в ограничении размера тела запроса, устанавливаемом обратным прокси-сервером, и в настройках Synapse max_upload_size. Ошибка 413 означает, что один из этих лимитов отклонил запрос. Cloudflare публикует лимиты загрузки, зависящие от плана, и отмечает, что эти настройки можно корректировать в рамках документированных ограничений: страница устранения неполадок 413 на сайте Cloudflare . Увеличивайте только необходимые лимиты и проверяйте результат с файлом меньшего размера, чем установленный лимит, прежде чем увеличивать их дальше.

8. Проверка доступа, обнаружения и федерации клиентов.

Выполните эти проверки на компьютере, находящемся за пределами сети вашего сервера. Замените приведенные примеры имен хостов:

curl -i https://example.com/.well-known/matrix/client
curl -i https://example.com/.well-known/matrix/server
curl -i https://matrix.example.com/_matrix/client/versions
curl -i https://matrix.example.com/health

Первые два запроса должны возвращать HTTP 200, JSON-контент и ожидаемые значения. Документ клиента должен включать заголовок CORS. Конечная точка версий клиента должна возвращать JSON из Synapse через Cloudflare. Конечная точка проверки работоспособности Synapse возвращает HTTP 200 при обращении через настроенный слушатель, но она не заменяет проверку авторизации или федерации.

Затем войдите в систему с помощью клиента Matrix, используя идентификатор, заканчивающийся на :example.com, присоединитесь к комнате, размещенной на другом сервере, и убедитесь, что сообщения и обновления членства синхронизируются. Используйте тестер федерации Matrix или второй домашний сервер для проверки обнаружения сервера и федерации. Успешный запрос к /_matrix/client/versionsдоказывает только работоспособность клиентского маршрута; он не доказывает корректность обнаружения федерации, подписи или исходящей федерации.

Как выглядит успех — и когда следует изменить дизайн.

• Клиенты подключаются через Cloudflare: DNS-запросы разрешаются в адреса Cloudflare, HTTPS использует соответствующий сертификат, а API клиента Matrix возвращает ответ.
• Проверка подлинности верна: оба известных URL-адреса возвращают правильный JSON, и клиентский документ проходит междоменные проверки.
• Федерация работает: удалённый сервер обнаруживает вашу заявленную конечную точку и может обмениваться данными о состоянии комнаты. Если делегирование порта 443 не удаётся, но прямой доступ через порт 8448 работает, проверьте известные записи, маршрутизацию прокси-сервера и правила WAF.
• Загрузка работает с ожидаемым размером: протестируйте типичную загрузку. Если небольшие файлы загружаются успешно, а более крупные возвращают ошибку 413, сравните все четыре ограничения по размеру, а не изменяйте только настройки Synapse.
• Исходный путь не является альтернативным общедоступным маршрутом: прямые запросы к исходному пути должны блокироваться или ограничиваться в соответствии с задумкой. Если они все же достигают сервиса Matrix, исправьте конфигурацию брандмауэра и доверенного прокси-сервера.

Используйте федерацию только по DNS на порту 8448, если ваши требования или реализация не позволяют маршрутизировать федерацию через порт 443, но имейте в виду, что это раскрывает исходный адрес и отключает защиту HTTP-прокси Cloudflare для этого имени хоста. Spectrum — еще один вариант для нестандартных портов, в зависимости от доступности продукта и ограничений тарифного плана. Проксирование Cloudflare также означает, что TLS завершается на Cloudflare до второго TLS-соединения с вашим источником; сквозное шифрование Matrix защищает содержимое зашифрованных сообщений, но не скрывает метаданные соединения или содержимое, не зашифрованное сквозным шифрованием, от служб, обрабатывающих HTTP-запрос. Выберите топологию в зависимости от ваших требований к конфиденциальности, федерации и доступности, а затем повторно протестируйте после внесения изменений в DNS, сертификаты, Synapse или правила Cloudflare.