Как настроить пользовательские псевдонимы комнат Matrix в вашем домене

Псевдоним комнаты Matrix присваивает комнате удобочитаемый адрес, например #support:example.org, . Часть после двоеточия — это имя сервера домашнего сервера , домен, которому принадлежит пространство имен псевдонима. Это не произвольная метка домена, которую можно изменить, добавив запись DNS. Чтобы использовать свой собственный домен, ваш домашний сервер должен быть настроен с этим доменом в качестве имени сервера; после этого федерацию можно делегировать отдельному хосту.

example.orgВ этом руководстве в качестве домена используется matrix.example.orgимя хоста Synapse, а #support:example.orgв качестве целевого псевдонима — другое имя. Замените эти заполнители своими значениями. Основное внимание уделяется самостоятельно размещенному Synapse. Если вы используете хостинг Matrix, проверьте, позволяет ли он использовать пользовательское имя сервера; многие хостинговые аккаунты позволяют создавать псевдонимы только в рамках домена провайдера.

Что делает псевдоним комнаты в Матрице?

Домашний сервер — это сервер Matrix, который хранит данные о комнатах пользователей и подключается к другим серверам. Идентификатор комнаты , например !opaqueid:example.org, , технически идентифицирует комнату. Псевдоним комнаты , например #support:example.org, , — это читаемая запись в каталоге, которая разрешается в идентификатор комнаты и список серверов, которые могут помочь пользователю присоединиться.

Псевдоним не переименовывает комнату, не изменяет ее конфиденциальность и не гарантирует ее отображение в общедоступном каталоге комнат. Это отдельные настройки комнаты. У комнаты может быть несколько псевдонимов. Канонический псевдоним — это предпочтительный адрес, отображаемый или используемый клиентами; он публикуется как состояние комнаты, в то время как домашний сервер поддерживает сопоставление псевдонима с комнатой. Спецификация Matrix предупреждает, что сопоставление псевдонимов может меняться, поэтому перед тем, как полагаться на него, необходимо определить адрес.

Прежде чем начать

• Управляйте доменом, который вы хотите использовать, например example.org, [укажите домен], включая возможность предоставления HTTPS-контента по этому домену.
• Запустите домашний сервер, например Synapse, с параметром Matrix, server_nameустановленным на example.org. Это значение выбирается при настройке сервера и не должно изменяться бездумно позже: идентификаторы пользователей и псевдонимы используют его в качестве своего пространства имен.
• Необходимо наличие работающего TLS-сертификата и маршрута федерации. Делегированный хост Matrix, например matrix.example.org, должен предоставить действительный сертификат.
• Необходимо быть подключенным к комнате и иметь необходимые разрешения для изменения ее адресов. Synapse также имеет серверные правила, которые могут разрешать или запрещать создание псевдонимов.

Если сервер уже работает с другим именем, например provider.net, , создание #support:example.orgне является способом быстрого сопоставления доменов. Обратитесь к провайдеру за информацией о поддержке пользовательских доменов или спланируйте отдельное развертывание и миграцию домашнего сервера. Matrix не определяет процесс создания псевдонимов для одного домашнего сервера в пространстве имен другого сервера.

Шаг 1: Выберите имя сервера и маршрут федерации.

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

Когда домашний сервер недоступен напрямую по example.orgстандартному порту федерации 8448, Matrix необходимо найти способ обнаружения своей конечной точки федерации. Один из распространенных методов — делегирование через .well-known : небольшой HTTPS JSON-ответ по адресу server-name направляет трафик федерации на фактический хост Matrix. Разместите его по адресу https://example.org/.well-known/matrix/server:

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

Убедитесь, что ответ представляет собой корректный JSON, передается по HTTPS, и что целевой хост имеет действительный сертификат и направляет запросы федерации в Synapse. Порт можно опустить, если конечная точка федерации использует порт 8448; в этом примере явно указан порт 443. Если Synapse уже предоставляет федерацию в домене имени сервера на порту 8448, делегирование может не потребоваться. /.well-known/matrix/clientФайл, предназначенный для клиента, представляет собой другой механизм обнаружения и не заменяет делегирование сервера.

В текущей документации по настройке Synapse предусмотрена serve_server_wellknownопция для случаев, когда запросы к домену с именем сервера на порту 443 перенаправляются в Synapse. Используйте эту опцию только в том случае, если ваш прокси-сервер и маршрутизация домена соответствуют описанным требованиям. В противном случае настройте JSON-ответ на вашем веб-сервере или прокси-сервере.

Шаг 2: Проверьте политики псевдонимов Synapse.

Synapse может ограничивать круг лиц, имеющих право создавать псевдонимы, и круг разрешенных адресов помещений. В настройках homeserver.yamlпроверьте, alias_creation_rulesотклонен ли запрос на создание псевдонима. Synapse оценивает настроенные правила по порядку; первое соответствующее правило определяет запрос, и если ни одно правило не соответствует, запрос отклоняется. Пустой список отклоняет все запросы на создание псевдонимов. Пустой или отсутствующий список разрешает создание псевдонимов по умолчанию, с учетом других проверок.

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

Шаг 3: Создайте псевдоним для комнаты.

Присоединитесь к нужной комнате в клиенте Matrix и откройте ее настройки. Найдите раздел адреса или псевдонима; текст и структура клиента могут различаться в зависимости от версии. Введите полный адрес, включая начальный ключ #и домен домашнего сервера, например #support:example.org. Добавьте его в качестве адреса комнаты и, если клиент предлагает такую ​​возможность, установите его в качестве канонического или предпочтительного псевдонима. Сохраните изменения.

Если ваш клиент не предоставляет управление псевдонимами, сопоставление можно создать с помощью запроса API клиент-сервер. Аутентифицированная PUT /_matrix/client/v3/directory/room/{roomAlias}конечная точка требует указания идентификатора комнаты в теле запроса. Например, авторизованный участник комнаты или учетная запись сервера могут отправить запрос на домашний сервер, которому принадлежит example.org:

curl -X PUT \
  "https://matrix.example.org/_matrix/client/v3/directory/room/%23support%3Aexample.org" \
  -H "Authorization: Bearer $MATRIX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"room_id":"!yourRoomId:example.org"}'

Замените указанный в примере ID комнаты на точный ID комнаты и используйте действительный токен доступа с необходимыми авторизациями. Относитесь к токену как к паролю: не публикуйте его, не вставляйте в сообщения службы поддержки и не добавляйте в систему контроля версий. Процент экранируется при кодировании URL #и :для HTTP-пути. Успешный ответ означает, что сопоставление создано. Ответ «уже существует» означает, что имя занято; перед изменением или удалением чего-либо подтвердите, кто является владельцем.

Шаг 4: Проверьте адрес и поделитесь им.

Разрешите псевдоним, используя общедоступный API клиент-сервер. Для этого поиска аутентификация не требуется:

curl -i \
  "https://matrix.example.org/_matrix/client/v3/directory/room/%23support%3Aexample.org"

Успешный ответ должен содержать ожидаемый идентификатор комнаты room_idи serversсписок. Сравните полученный идентификатор комнаты с предполагаемым идентификатором комнаты. Ошибка 404 означает, что псевдоним не имеет сопоставления на сервере, обрабатывающем это пространство имен. Ошибка 400 указывает на некорректно отформатированный адрес. Затем проверьте полный псевдоним во второй учетной записи или клиенте Matrix, чтобы убедиться, что комната разрешается и к ней можно присоединиться в соответствии с правилами присоединения.

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

Распространенные проблемы, которых следует избегать

• Использование домена, не принадлежащего домашнему серверу: имя сервера в псевдониме должно совпадать с пространством имен домашнего сервера, который его создал. DNS CNAME сам по себе не может авторизовать домен другого сервера.
• Неправильное использование домена и хоста: example.org может быть пространством имен псевдонимов, а matrix.example.org— хостом службы. Задавайте имя сервера Synapse и делегирование намеренно.
• Неправильное размещение файла обнаружения клиентов: делегирование федерации использует /.well-known/matrix/server. Файл обнаружения клиентов имеет другой путь и предназначение.
• Предположим, что псевдоним публикует комнату в открытом доступе: разрешение псевдонима и публикация публичного каталога комнат — это отдельные операции, регулируемые отдельными правилами.
• Изменение имени сервера в уже существующей системе развертывания: существующие идентификаторы Matrix зависят от этого пространства имен. Рассматривайте изменение домена как архитектурную миграцию, а не как быструю настройку псевдонима.
• Совместное использование без проверки сопоставления: перед публикацией необходимо разрешить псевдоним и сравнить полученный идентификатор комнаты. Читаемый адрес удобен, но именно сопоставление сервера определяет, куда он ведет.

Подробности протокола см. в разделах « Формат идентификатора и псевдонима Matrix» и «API псевдонимов комнат Matrix» . Для настройки Synapse обратитесь к руководству по делегированию федерации и руководству по настройке Element . Параметры Synapse и экраны клиента могут меняться между версиями; проверьте документацию для используемой вами версии.