Matrix Synapse на Ubuntu 20.04 — установка и настройка

Установите Matrix Synapse на сервер Ubuntu 20.04, закройте публичные слушатели, разместите Synapse за Nginx с SSL от Let’s Encrypt и включите федерацию на порту 8448. В статье пошагово показаны команды, конфигурации, тестирование, рекомендации по безопасности и чеклисты для администраторов.

Важно: подразумевается доступ root или пользователь с sudo. Минимальные ресурсы: 1 ГБ ОЗУ, 25 ГБ свободного места, 2 CPU.

Matrix — это открытая федеративная экосистема для обмена сообщениями и VoIP в реальном времени. Она предоставляет RESTful HTTP JSON API для создания распределённых и федеративных серверов чата без единой точки управления и отказа.

Synapse — эталонная реализация Matrix home server, написанная на Python/Twisted. Запустив Synapse, вы получаете собственный сервер хранения учётных записей, истории чатов и комнат с возможностью федерации с другими Matrix-серверами.

В этом руководстве показано, как установить и настроить Matrix Synapse на Ubuntu 20.04, разместить его за Nginx в качестве обратного прокси и защитить SSL-сертификатами от Let’s Encrypt.

Кому полезно

Системным администраторам, желающим развернуть приватный Matrix сервер.
Командам, которым нужна федерация и контроль над данными.
Тем, кто хочет интегрировать Matrix в существующую инфраструктуру.

Что мы сделаем

Установим Matrix Synapse через официальный репозиторий
Настроим Synapse (слушатели, регистрация, shared secret)
Получим SSL через certbot
Настроим Nginx как обратный прокси и федерационный порт 8448
Откроем порты в UFW
Зарегистрируем пользователя
Протестируем работу и приведём рекомендации по безопасности

Сервер с Ubuntu 20.04
Свободный публичный домен, указывающий на этот сервер (A/AAAA)
Доступ к root или sudo
Порт 80 и 443 должны быть доступны для получения сертификата

Примечание: если на сервере уже запущен другой веб-сервер, используйте режим certbot –webroot или поднимите сертификаты вручную.

Подготовьте зависимости и добавьте официальный репозиторий Matrix.

Сначала установите вспомогательные пакеты:

sudo apt install -y lsb-release wget apt-transport-https

Добавьте ключ GPG и репозиторий:

sudo wget -qO /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/matrix-org.list

Добавление репозитория Matrix Synapse на Ubuntu 20.04

Обновите индексы пакетов и установите Synapse:

sudo apt update
sudo apt install matrix-synapse-py3

Во время установки вас попросят указать домен сервера. Введите полностью квалифицированное доменное имя (FQDN), например: hakase-labs.io, и подтвердите.

При запросе о сборе анонимной статистики выберите “No” (или “Нет”).

После установки запустите и включите службу:

systemctl start matrix-synapse
systemctl enable matrix-synapse

Проверьте статус:

systemctl status matrix-synapse
ss -plnt

Проверка статуса сервиса Matrix Synapse

По умолчанию Synapse слушает локально порт 8008 (HTTP) — мы закроем его для внешнего доступа позже.

Мы пропишем bind-addresses, отключим открытую регистрацию и настроим shared secret для безопасной программной регистрации.

Генерация секретного ключа для регистрации:

cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1

Скопируйте сгенерированную строку, например:

GH7AP4Zcthz02Cmg58sqUgonm7zlwH0f

Отредактируйте конфигурацию:

cd /etc/matrix-synapse/
sudo vim homeserver.yaml

Найдите раздел listeners и измените bind_addresses так, чтобы Synapse слушал только локальный интерфейс. Это повышает безопасность, когда вы используете обратный прокси:

listeners:

  - port: 8008
    tls: false
    type: http
    x_forwarded: true
    bind_addresses: ['127.0.0.1']

    resources:
      - names: [client, federation]
        compress: false

Отключите открытые регистрации и задайте registration_shared_secret:

enable_registration: false
registration_shared_secret: "GH7AP4Zcthz02Cmg58sqUgonm7zlwH0f"

Сохраните файл и перезапустите службу:

systemctl restart matrix-synapse
ss -plnt
systemctl status matrix-synapse

Конфигурация Matrix Synapse

Теперь Synapse слушает только на 127.0.0.1:8008, а внешние запросы будут идти через Nginx.

Установите certbot (если сертификаты получаете через standalone):

sudo apt install certbot -y

Запрос сертификата (замените email и домен на ваши):

certbot certonly --rsa-key-size 2048 --standalone --agree-tos --no-eff-email --email [email protected] -d hakase-labs.io

Если certbot успешно завершился, сертификаты будут в /etc/letsencrypt/live/ваш_домен/

ls -lah /etc/letsencrypt/live/ваш_домен/

fullchain.pem — публичный сертификат, privkey.pem — приватный ключ.

Получение SSL сертификата Let's Encrypt для Matrix Synapse

Важно: автоматическое обновление certbot настроится через системную службу/таймер (certbot.timer). Проверьте работу:

sudo systemctl list-timers | grep certbot

Мы запустим Nginx и настроим три блока: редирект 80→443, HTTPS для /_matrix и отдельный SSL-порт 8448 для федерации.

Установите Nginx:

sudo apt install nginx -y

Создайте конфигурацию виртуального хоста в /etc/nginx/sites-available/matrix:

cd /etc/nginx/sites-available/
sudo vim matrix

Вставьте (измените domain и пути на ваши):

server {
    listen 80;
    server_name hakase-labs.io;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name hakase-labs.io;

    ssl_certificate /etc/letsencrypt/live/hakase-labs.io/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/hakase-labs.io/privkey.pem;

    location /_matrix {
        proxy_pass http://localhost:8008;
        proxy_set_header X-Forwarded-For $remote_addr;
        # Nginx по умолчанию ограничивает загрузку файлов до 1M
        # Увеличьте client_max_body_size в соответствии с max_upload_size в homeserver.yaml
        client_max_body_size 10M;
    }
}

# Это используется для федерации Matrix
# Порт по умолчанию 8448
server {
    listen 8448 ssl;
    server_name hakase-labs.io;

    ssl_certificate /etc/letsencrypt/live/hakase-labs.io/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/hakase-labs.io/privkey.pem;

    location / {
        proxy_pass http://localhost:8008;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

Сделайте симлинк, проверьте конфигурацию и перезапустите Nginx:

sudo ln -s /etc/nginx/sites-available/matrix /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
sudo systemctl enable nginx

Настройка Nginx как обратного прокси для Matrix Synapse

Проверьте, что Nginx слушает 80, 443 и 8448:

ss -plnt
systemctl status nginx

Nginx настроен как обратный прокси для Matrix Synapse

Откройте необходимые службы: ssh, http, https и порт 8448 для федерации.

for svc in ssh http https 8448
do
  sudo ufw allow $svc
done

sudo ufw enable

Подтвердите ‘y’ и проверьте правила:

ufw status numbered

Включение UFW для защиты Matrix Synapse

Создайте локальную учётную запись через CLI. Если регистрация отключена в homeserver.yaml, используйте registration_shared_secret или утилиту register_new_matrix_user.

sudo register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://localhost:8008

Вводите имя пользователя (localpart), пароль и при необходимости сделайте пользователя администратором:

New user localpart [root]: changbin
Password:
Confirm password:
Make admin [no]: yes
Sending registration request...
Success!

Теперь у вас есть локальный пользователь.

Тест федерации

Используйте официальный тест федерации:

https://federationtester.matrix.org/

Введите домен вашего сервера и нажмите “Go”. Успешный результат подтверждает доступность федерации по 8448.

Тест федерации Matrix Synapse

Тест входа через веб-клиент

Откройте веб-клиент Element (старое имя Riot):

https://riot.im/app/

Нажмите “Sign In”, укажите ваш домен, далее введите имя пользователя и пароль. При первом входе клиент может запросить дополнительные параметры безопасности.

Вход в Matrix Synapse через Riot

Ввод домена для Riot

Вход выполнен успешно:

Успешный вход в Matrix Synapse через Riot

Важно обеспечить защиту сервера и резервное копирование данных. Ниже — рекомендуемые шаги.

Базовые меры безопасности

Держите систему и пакеты в актуальном состоянии: sudo apt update && sudo apt upgrade
Ограничьте доступ к административным портам по IP, если возможно
Используйте сильные пароли и, при возможности, двухфакторную аутентификацию на клиентах
Резервное копирование homeserver.db (Postgres/RDS при использовании внешней БД) и каталога /etc/matrix-synapse/

TLS и Nginx

Включите безопасные TLS-сuites и HSTS в конфигурации Nginx
Отключите слабые протоколы TLS (например, TLS 1.0/1.1)
Настройте автоматическое обновление сертификатов certbot

Пример дополнительных директив для ssl в ngnix-конфиге:

ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:...';
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

Жёсткая настройка Synapse

Логи: убедитесь, что логи ротаируются и не накапливаются бесконечно (/etc/logrotate.d/)
Ограничьте размер загрузки файлов в homeserver.yaml (max_upload_size)
Используйте внешнюю базу данных PostgreSQL при высоких нагрузках вместо SQLite

Минимально нужно резервировать:

Файлы конфигурации: /etc/matrix-synapse/
Базу данных Synapse (SQLite или Postgres)
Сертификаты Let’s Encrypt: /etc/letsencrypt/

Пример простого бэкапа:

sudo systemctl stop matrix-synapse
sudo tar -czf /root/synapse-backup-$(date +%F).tar.gz /etc/matrix-synapse /var/lib/matrix-synapse /etc/letsencrypt
sudo systemctl start matrix-synapse

Certbot не может получить порт 80: отключите временно Nginx или используйте –webroot
Ошибка federation: проверьте, открыт ли порт 8448 и корректны ли сертификаты
Клиенты не могут загрузить файлы: увеличьте client_max_body_size в Nginx и max_upload_size в homeserver.yaml
Нагрузка на Synapse высокая: перенесите базу в Postgres, увеличьте ресурсы, настройте caching

Если вам нужна мгновенная масштабируемость для десятков тысяч одновременных пользователей — Synapse потребует тонкой настройки и отдельных серверов для БД и кэша. Рассмотрите Dendrite (альтернатива) или коммерческие SaaS решения.
Если вы не хотите поддерживать сервер и обновления — используйте хостинг Matrix как сервис.

Synapse: зрелая, простая развёртка, требует ресурсов при росте
Dendrite: экспериментальный сервер от Matrix, легче масштабируется, но может требовать доработок
SaaS Matrix-провайдеры: низкая поддержка, высокая простота

Принятие решения: если вам важна простота и совместимость — Synapse. Если важна горизонтальная масштабируемость — смотрите Dendrite или выделяемая архитектура с Postgres и кластерами.

Администратор

Получил доступ к домену и DNS
Проанализировал требования к ресурсам
Настроил резервное копирование
Настроил мониторинг и алерты

Оператор

Установил и настроил Synapse
Настроил и проверил Nginx
Настроил SSL и автоматические обновления сертификатов
Настроил UFW и мониторинг портов

Разработчик интеграции

Проверил API /_matrix
Проверил webhooks и внешние интеграции
Подготовил инструкции регистрации и использования client SDK

Synapse слушает только на 127.0.0.1:8008
Nginx принимает HTTPS на 443 и перенаправляет /_matrix на 127.0.0.1:8008
Порт федерации 8448 доступен и использует TLS
Certbot автоматически обновляет сертификаты
Создан хотя бы один рабочий пользователь и выполнён вход через web-клиент

Регистрация локального пользователя через CLI — ожидается Success!
Вход в Element/Riot через ваш домен — ожидается удачный вход и видимость комнат
Federation тест на https://federationtester.matrix.org — ожидается успешный результат
Загрузка файла < client_max_body_size — файл успешно загружен
Попытка регистрации через публичный endpoint — ожидание отказа, если enable_registration false

Остановите Synapse: systemctl stop matrix-synapse
Разархивируйте последний бэкап конфигурации и БД
Восстановите сертификаты в /etc/letsencrypt/
Запустите Synapse: systemctl start matrix-synapse
Проверьте логи и состояние сервисов

Matrix: федеративный протокол обмена сообщениями
Synapse: reference-реализация Matrix home server
Federation: обмен событиями между разными Matrix серверами
homeserver.yaml: основной конфигурационный файл Synapse

Вы развернули Matrix Synapse на Ubuntu 20.04, настроили Nginx как обратный прокси, защитили соединения сертификатами Let’s Encrypt и включили федерацию через порт 8448. После развёртывания рекомендуется настроить резервное копирование, мониторинг и план обновлений.

Ключевые рекомендации: используйте PostgreSQL при росте нагрузки, храните secrets в защищённом хранилище, автоматизируйте обновления сертификатов и проверяйте федерацию регулярно.

Спасибо за чтение. Удачного развертывания!