Изменения
30 янв. 2026
- Добавлено: Настройка и интеграция SSO
27 янв. 2026
- Добавлено: Как сделать красивые юзернеймы
- Добавлено: Настройка и включение федерации
- Дополнение: Исправление для PostgreSQL v18+
13 авг. 2025
- Добавлено: Установка TURN сервера (Coturn)
Введение
Это именно то о чем вы думаете. Вам не придется покупать дорогой VPS для хостинга Matrix. Достаточно простого VPS и средне-мощного ПК прямо у вас дома.
О Matrix
Matrix – это открытый протокол для обмена сообщениями в реальном времени. Проект был запущен в 2014 году командой из компании Amdocs 1 . Протокол определяет модель событий, формат данных и API для обмена сообщениями между клиентами и серверами, а также для их федерации, то есть взаимодействия между собой.
Для передачи данных Matrix использует стандартные транспорты, такие как HTTP/HTTPS, WebSockets и WebRTC. События и сообщения представлены в формате JSON и передаются через REST-подобные интерфейсы.
Главная особенность Matrix – это его федеративная и децентрализованная архитектура 1 . Множество серверов могут объединяться в единую открытую федерацию, что устраняет зависимость от одного центрального узла и обеспечивает гибкость развертывания.
Matrix поддерживает передачу текста, файлов и медиа, а также интеграции с другими системами 2 . Это позволяет пользователям общаться, независимо от используемого клиента или провайдера.
Для защиты данных Matrix использует сквозное шифрование (E2E). При включенном шифровании содержимое сообщений хранится на серверах в зашифрованном виде, и только участники чата с соответствующими ключами могут его расшифровать. При этом серверы видят служебную информацию, такую как метаданные и состав комнат.
Matrix используется как частными лицами, так и организациями, включая корпоративный и государственный сектор. Например, решения на базе Matrix применяются в вооруженных силах 3 и системе здравоохранения Германии 4 .
Matrix это Synapse?
Matrix это не программа, это протокол, набор правил, экосистема. Фактически чат работает на Synapse, но есть и другие, например Dendrite.
Подобно тому как электронная почта работает на основе протоколов IMAP/SMTP, Matrix определяет, как клиенты и сервера должны обмениваться данными. Это позволяет разным серверам и клиентам работать вместе.
Что будем делать?
Захостим Matrix мессенджер на домашнем ПК с динамическим IP, который будет доступен в интернете через VPS.
Synapse довольно требователен к железу (зависит от кол-ва юзеров), особенно в контексте дискового пространства (медиа файлы), и подходящий VPS/VDS будет не дешевым. Поэтому я покажу как поднять Matrix именно на домашнем ПК/сервере с конфигурацией заточенной под Pangolin.
Что понадобится:
- Домашний сервер, >2 CPU & RAM, и побольше дискового пространства
- Дешевый VPS, >=1 CPU & RAM, желательно с каналом пошире (>=1 Gbit)
- Доменное имя
Ну и в идеале базовые знания Linux, Docker, настройки DNS и знание Pangolin.
Подразумевается что вы уже установили, настроили Pangolin и проверили что все работает, но если нет:
В данной статье я покажу как поднять и Synapse и Element. Element нужен чтобы была некая страница (frontend, клиент) где юзеры прямо в браузере могли бы зарегистрировать аккаунт и/или войти в аккаунт, а так же чтобы была совместимость с клиентами Element и в целом Matrix можно было бы пользоваться прямо в браузере без программ.
Два отдельных сервиса, Synapse и Element. Их можно повесить на два разных домена/поддомена, но могут возникнуть проблемы, Element в некоторых сценариях будет обращаться к домену на котором он работает, но на нем НЕ работает Synapse, поэтому будет куча ошибок, и учитывая что в этой статье рассматривается хостинг Synapse и Element на одной машине, мы не будет парится, и сделаем как проще.
Чтобы элегантно это решить, мы будем использовать сеть внутри Docker, и использовать Nginx чтобы сделать reverse proxy на localhost, который уже будет пробрасываться через Pangolin.
Типо такого:
services:
synapse and etc:
networks:
m_network:
ipv4_address: 10.10.10.X
reverse-proxy:
ports:
- "4100:80"
networks:
m_network:
ipv4_address: 10.10.10.X
networks:
m_network:
ipam:
driver: default
config:
- subnet: "10.10.10.0/24"
# Synapse API
location ~ ^(/_matrix|/_synapse/client) {
...
}
# Element
location / {
...
}
Контейнеры общаются между собой в своей Docker сети, весь внешний трафик входит через nginx, который работает на 4100 порту и хост которого пробрасывается через Pangolin.
Установка Matrix
Установка Docker:
| |
Клонирование репозитория с приготовленными конфигами:
| |
Создание конфигурации Synapse (homeserver.yaml):
| |
Где domain.org ваш домен или поддомен, на него должно/будет указывать DNS запись на ваш VPS сервер на котором установлен Pangolin.
Редактирование конфига, например через nano 5 :
| |
В самый конец нужно добавить:
| |
enable_registration- включает регистрацию.enable_registration_without_verification- отключает предупреждения если нету никакой защиты типа капчи.
Установить пароль для базы данных:
| |
Если строка содержит спец. символы убедитесь что все нормально:
| |
Переменная POSTGRES_PASSWORD должна содержать ту же строку что вы туда и положили (в “.env”).
Дальше нужно поменять базу данных на PostgreSQL. Из “homeserver.yaml.example” скопируйте конфигурацию database и замените в вашем “homeserver.yaml”:
| |
Не забудьте установить “password” такой же, какой вы установили в “.env”.
Редактирование конфига Element:
| |
В base_url ваш домен с протоколом и без “/” в конце. Используйте “https”, Pangolin сам работает с SSL сертификатами.
"disable_custom_urls": true - запрещает использовать НЕ ваш Matrix сервер, иначе можно будет использовать другой Matrix сервер через ваш Element instance.
Аналогично:
| |
И так же:
| |
Поменяйте server_name domain.org на ваш домен.
Далее нужно раскомментировать две строки в “docker-compose.yaml”:
| |
| |
ВАЖНО: О PostgreSQL >=18
В новой версии PostgreSQL изменены пути, поэтому если вы не используете версию <18 то необходимо их изменить в вашем docker-compose.yaml.
Если установка новая (данных еще нету или есть, но их не жалко), то
| |
Далее:
| |
matrix-1-synapse_db-1 можно посмотреть через sudo docker ps.Например вывело PGDATA=/var/lib/postgresql/18/docker, значит в docker-compose.yaml изменить:
| |
Некоторые вещи из “Дополнительно” желательно сделать до запуска.
🚀 - лучше сделать до первого запуска
🧩 - значения не имеет
Запуск:
| |
Element должен открываться по ip:port (в конфиге 4100) и домену если вы уже настроили Pangolin.
Дополнительно
🚀 Красивые юзернеймы
Если вы используете поддомен, и везде укажите поддомен “sub.domain.org” (потому что там у вас synapse/element), то юзернемы будут такими “user:sub.domain.org”. Я покажу как сделать чтобы они были такими – “user:domain.org”.
Если вы уже все настроили, все запустили, и все уже давно работает – то ничего не делайте, чтобы это сделать нужно очистить базу данных. Ну, а если вы еще ничего не запускали то смело делайте. А если запускали, но хотите переделать выполните:
| |
| |
Это для очистки БД. Ну или можете вручную попробовать править базу.
Домашний сервер
| |
| |
Вот element-config.json менять чисто для общей эстетики, не обязательно.
| |
| |
| |
Убрать:
| |
VPS
В корне сайта domain.org:
| |
client:
| |
server:
| |
NGINX для “domain.org” (НЕ “sub.domain.org”):
| |
Если вы используете федерацию, проверьте что она работает здесь.
У “sub.domain.org” вероятно будет ошибка “MatchingServerName”, это нормально. Но у “domain.org” – ошибок быть не должно, то есть проверять нужно то что указано в server_name в homeserver.yaml.
🧩 Включение/Настройка федерации
Домашний сервер
docker-compose.yaml:
| |
NGINX default.conf:
| |
VPS
Открыть порт 8448 в firewall и указать его в Docker если вы используете Docker, на примере ufw и ZT:
| |
| |
NGINX, в конце добавить еще один server блок:
| |
Проверить работоспособность федерации можно здесь.
🧩 Отключение федерации
homeserver.yaml:
| |
Или отключить федерацию со всеми, кроме некоторых:
| |
Разницы форматирования между этими двумя нету, это просто разный синтаксис, но если перечислять – так просто удобнее, чем в строку.
🧩 Подключение Google reCaptcha
Создать ключи тут (v2, “I’m not a robot”).
homeserver.yaml:
| |
Обратите внимание, капча будет работать только на домене. При доступе через ip:port капча работать не будет и вы не сможете зарегистрировать аккаунт соответственно.
🚀 Разделение хранилища
На примере LVM дисков.
Есть SSD и HDD, оба LVM, нужно сделать так, чтобы был отдельный логический том SSD диска для БД Synapse и отдельный логический том HDD для медиа файлов, а сам Docker контейнер работал в home/root.
Это рабочий пример, где “vg0” ваш Volume Group, где sda1 и nvme0n1 ваши диски:
| |
| |
| |
Права:
| |
Потому что docker-compose.yaml:
| |
На “synapse-1-db” тоже нужно будет установить владельца и группу, если:
| |
покажет не:
| |
docker-compose.yaml:
| |
homeserver.yaml:
| |
Путь получится “/data/data/”, в корень файлы лучше не записывать, потому что корень зачастую не пустой из-за “lost+found” (зависит от файловой системы). А программа может требовать чтобы директория была пуста, так например требует PostgreSQL, к тому же зачем смешивать файлы.
Не красиво, но точно будет работать.
🧩 Максимальный размер загружаемых файлов (Max Upload Size)
homeserver.yaml:
| |
nginx:
| |
🧩 Другие размеры миниатюр
Может работать некорректно, или не работать вовсе. Лично у меня не работало и сломало аватарки.
homeserver.yaml:
| |
В любом случае миниатюры обычно создаются сами.
🧩 Мосты
Telegram
В существующем docker-compose.yaml:
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
🧩 Настройка и интеграция SSO
Зачем это нужно? Помимо общих применений SSO, так же для авторизации в matrix через стороние сервисы типа Google, GitHub и др. (но об этом тут не будет), и/или для улучшения защиты аккаунтов пользователей посредством 2FA. Потому что synapse/element сами по себе не поддерживают 2FA.
То есть, чтобы войти в аккаунт matrix нужно будет не только ввести логин, пароль и ключ восстановления или подтвердить авторизацию с другого устройства, а вести логин, пароль, 2FA или использовать аппаратный ключ и только потом ключ восстановления или подтвердить вход с другого устройства чтобы расшифровать сообщения.
Своего рода «Defense in Depth». По факту просто круто + может пригодится если у вас будет очень много selfhosted сервисов с поддержкой SSO, чтобы был один вход на все сервисы вместо огромной кучи пар логин и пароль.
Можно поднять в том же docker-compose.yaml файле где synapse и element, или в отдельном – разницы нет. Что использовать в качестве сервиса SSO и как это поднять я не покажу, это вы решайте сами. Я же покажу только как настроить на примере Authentik.
- Applications ==> Providers ==> Create ==> “OAuth2/OpenID Provider”. Provider Name - что-нибудь связанное с matrix.
- Authorization flow - на ваш вкус, но если не знаете что это, выбирайте “explicit”.
- Client type - Confidential.
- Redirect URIs/Origins (RegEx) - указать ваш URL Synapse (в этой статье писалось про Synapse и Element на одном домене поэтому), например
https://element.domain.org/_synapse/client/oidc/callback, без/в конце. Путь должен быть точно таким, как указано. - Applications ==> Applications ==> Create, ввести имя и slug, в Provider выбрать созданный ранее провайдер.
В homeserver.yaml:
| |
Моя конфигурация OIDC
| |
NGINX:
| |
allow_existing_users: true – нужен для миграции текущих юзеров, если таковы есть. Для миграции нужно создать юзера с тем же username что и в matrix, если “john:domain.org” то “john”, и когда Джон залогинится, к аккаунту SSO автоматически привяжется аккаунт Synapse.
allow_existing_users: true опция ОЧЕНЬ НЕ безопасная, если у вас будет включена публичная регистрация на SSO платформе любой сможет украсть аккаунт просто зарегистрировав существующий юзернейм.enable_registration: true – если у вас приватный сервер и вы делаете аккаунты вручную, то вам нужно будет создать аккаунт в Synapse и SSO, но если true, то только в SSO, аккаунт Synapse будет создан и привязан к SSO автоматически при первом входе. По умолчанию “true”.
Чтобы отключить вход по логину и паролю, оставив только SSO, в homeserver.yaml:
| |
Группы (Authentik)
Группы нужны если вы например хотите иметь 100 юзеров, но что бы лишь 20 из них могли залогинится в matrix.
Можно сделать через homeserver.yaml, искать пример attribute_requirements тут.
Но есть так же как по мне лучший вариант сделать это чисто на стороне Authentik: Applications ==> Applications ==> ваше приложение ==> Policy / Group / User Bindings ==> Bind existing Policy / Group / User ==> Group ==> выбрать нужную ранее созданную группу.
Капча (Authentik)
Если вы не задумались “а как же капча?” – задумайтесь. Капча есть и ее можно настроить. Нужно создать “stage” в “stages” с типом “Captcha Stage”, выбрать провайдера и вписать ключи, тут все просто.
Далее зайти в Flows and Stages ==> Flows, выбрать нужный Flow куда нужно добавить капчу – “default-authentication-flow” ==> Stage Bindings ==> Bind existing stage ==> Выбрать ту капчу что вы создали ранее, order нужно установить между “identification” и “password” – обычно это 15.
🧩 Установка TURN сервера (Coturn)
TURN сервер лучше установить на VPS с публичным IP, можно рядом с Pangolin, все будет работать. В Pangolin для TURN сервера ничего добавлять и настраивать не нужно.
| |
Открыть порты UFW (на всякий случай):
| |
| |
Поменять external-ip, realm и server-name. А также данные user=test:test - логин:пароль.
Сертификаты можно получить через certbot, или в другом месте, например Cloudflare:
- “cert.pem” - публичный ключ
- “private.key” - приватный ключ
| |
Если вы создали сертификаты с помощью “certbot” то нужно использовать “fullchain.pem” и “privkey.pem”:
- /etc/letsencrypt/live/turn.domain.org/fullchain.pem
- /etc/letsencrypt/live/turn.domain.org/privkey.pem
| |
Если при запуске все виснет – уберите порты и используйте:
| |
Более того, так лучше сделать в любом случае, потому что Docker будет открывать все эти порты с 59000 до 60100, это довольно много, и может быть плохо.
homeserver.yaml:
| |
Протестировать turn сервер независимо от matrix можно здесь, но если у вас в браузере отключен WebRTC – временно включите его.
Удаление “старых” медиа файлов
Это может не работать:
homeserver.yaml:
| |
100% рабочий вариант через API:
Создать админ аккаунт – см. Synapse Admin.
Получить токен:
| |
Удалить все что старше 1 минуты (60000 в мс):
| |
Или в одну команду, получить токен, выполнить удаление, отозвать токен:
| |
Или скриптом. И сделать cron задачу, типо такого:
| |
Будет запускать скрипт каждые 30 дней в 00:00.
Synapse Admin (админка)
Админку можно запускать где угодно, необязательно пробрасывать в Pangolin, более того, лично я не рекомендую этого делать для безопасности (и это невозможно с конфигурацией из этой статьи (из-за конфигурации nginx)).
Админка от Awesome-Technologies:
| |
Админка от etkecc:
| |
Создать админ аккаунт:
| |
SSH туннель:
| |
“10.10.10.2” ip Synapse:
| |
Порт 8008 - это порт Synapse по умолчанию.
What’s the Matrix protocol? And how will it change modern messaging? ↩︎ ↩︎
Matrix: a decentralized open-source messaging platform for the future ↩︎
Текстовый редактор nano: CTRL + X,
y,Enter– сохранить и выйти. ↩︎
