Установка Matrix Synapse на Ubuntu 18.04

О чём этот документ

Это подробная инструкция по развёртыванию Matrix Synapse — серверной реализации протокола Matrix — на Ubuntu 18.04. Руководство показывает проверенный путь: установка через репозиторий Debian, конфигурация Synapse на 127.0.0.1, получение сертификатов Let’s Encrypt, настройка Nginx как TLS-терминатора и обратного прокси, базовая жёсткая настройка брандмауэра и создание первого пользователя. Включены советы по отладке, варианты альтернативных подходов, краткие чек-листы и рекомендации по безопасности.

Важно: этот материал показывает один из рабочих подходов. Если у вас уже есть Docker/Kubernetes или другой архитектурный подход, смотрите раздел «Альтернативные подходы». Для продакшена дополнительно рассмотрите резервное копирование и управление ключами.

Основные понятия в одной строке

• Matrix: открытый протокол федеративного обмена сообщениями в реальном времени.
• Synapse: официальная реализация сервера (homeserver) для Matrix, написанная на Python/Twisted.
• Riot/Element: популярный клиент для Matrix.

Предварительные условия

• Сервер с Ubuntu 18.04.
• Привилегии root или sudo.
• Домен или поддомен, указывающий на сервер (в примерах matrix.hakase-labs.io).
• Свободные порты 80 и 443 на внешнем интерфейсе для проверки и HTTPS.

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

1. Обновим систему.
2. Установим Matrix Synapse из официального репозитория Debian.
3. Настроим Synapse работать на локальном адресе 127.0.0.1.
4. Получим TLS-сертификат Let’s Encrypt.
5. Установим и настроим Nginx как обратный прокси (TLS-терминатор).
6. Откроем необходимые порты в UFW.
7. Создадим нового Matrix-пользователя.
8. Проверим работу через клиент (Riot/Element).

Шаг 1 — Обновление системы

Подключитесь к серверу и выполните обновление пакетов:

sudo apt update  
sudo apt upgrade

После этого все пакеты будут обновлены до актуальных версий для Ubuntu 18.04.

Шаг 2 — Установка Matrix Synapse

Добавим официальный репозиторий Matrix и ключ:

wget -qO - https://matrix.org/packages/debian/repo-key.asc | sudo apt-key add -  
sudo add-apt-repository https://matrix.org/packages/debian/

Репозиторий обновится автоматически. Затем установим пакет:

sudo apt install matrix-synapse -y

В процессе установки будет запрошено имя сервера (введите ваш домен, например matrix.hakase-labs.io). Также система спросит о телеметрии — можно выбрать “Нет”.

Запустите и включите сервис, чтобы он стартовал при загрузке:

sudo systemctl start matrix-synapse  
sudo systemctl enable matrix-synapse

По умолчанию Synapse слушает на портах 8008 и 8448. Проверьте это с помощью netstat или ss:

netstat -plntu

(alt: Скриншот процесса установки Matrix Synapse и вывода терминала)

Шаг 3 — Настройка Matrix Synapse

Мы перенастроим Synapse так, чтобы он слушал только на локальном интерфейсе 127.0.0.1 и включим режим создания учётных записей по shared secret (регистрация обычных пользователей будет отключена).

Сначала сгенерируйте надёжный общий секрет (registration_shared_secret):

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

Скопируйте полученную строку — она понадобится в конфиге.

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

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

Найдите секции listeners и измените bind_addresses для портов 8448 и 8008 на ‘127.0.0.1’, чтобы внешний доступ к Synapse выполнялся только через локальный интерфейс (Nginx будет проксировать запросы):

    port: 8448
    bind_addresses:
      - '127.0.0.1'

    - port: 8008
    bind_addresses: ['127.0.0.1']

Найдите параметр enable_registration и установите False, затем раскомментируйте и вставьте registration_shared_secret с ранее сгенерированным значением:

enable_registration: False
registration_shared_secret: "<ВАШ_СЕКРЕТ_ЗДЕСЬ>"

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

sudo systemctl restart matrix-synapse

Проверьте, что Synapse теперь слушает на 127.0.0.1:8008/8448:

netstat -plntu

(alt: Редактирование homeserver.yaml и установка bind_addresses на 127.0.0.1)

(alt: Скриншот конфигурации портов Synapse в файле homeserver.yaml)

Примечание: registration_shared_secret позволяет создавать аккаунты только тем, кто знает секрет, даже при отключённой публичной регистрации.

Шаг 4 — Получение TLS-сертификатов Let’s Encrypt

Мы настроим HTTPS на уровне Nginx. Установим certbot и запросим сертификат с помощью standalone-режима:

sudo apt install letsencrypt -y

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

Команда запустит временный веб-сервер для подтверждения права на домен и создаст сертификаты в /etc/letsencrypt/live/matrix.hakase-labs.io/.

(alt: Вывод certbot после успешного получения сертификата Let’s Encrypt)

Шаг 5 — Установка и настройка Nginx как обратного прокси

Установим Nginx и включим сервис:

sudo apt install nginx -y
sudo systemctl start nginx  
sudo systemctl enable nginx

Создайте виртуальный хост для домена:

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

Вставьте следующий блок конфигурации (указаны пути к сертификатам Let’s Encrypt):

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

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name matrix.hakase-labs.io;

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

    # If you don't wanna serve a site, comment this out
    root /var/www/html;
    index index.html index.htm;

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

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

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

Если ошибок нет, Nginx будет принимать HTTPS-запросы и проксировать их на локальный Synapse.

(alt: Настройка файла конфигурации Nginx и проверка синтаксиса)

Шаг 6 — Настройка UFW (брандмауэр)

Разрешим только SSH, HTTP и HTTPS:

ufw allow ssh  
ufw allow http  
ufw allow https

ufw enable  
ufw status

После включения брандмауэра убедитесь, что доступ по SSH и HTTPS доступен извне.

(alt: Команды для открытия SSH, HTTP и HTTPS в UFW и вывод статуса)

(alt: Статус UFW с разрешёнными сервисами)

Шаг 7 — Создание нового Matrix-пользователя

Добавлять пользователей можно с помощью утилиты register_new_matrix_user, используя локальный endpoint Synapse:

register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml https://127.0.0.1:8448

Утилита спросит имя пользователя, пароль и будет ли это администратор. Для управления сервером удобно создать администратора.

Пример: создан пользователь hakase с правами администратора.

Шаг 8 — Тестирование через клиент

Скачайте и установите клиент Riot (теперь известен как Element) для своей платформы. В окне авторизации выберите “Custom server” (пользовательский сервер) и укажите домен matrix.hakase-labs.io как URL сервера. Введите логин и пароль созданного пользователя и выполните вход.

(alt: Экран входа в клиент Riot/Element с полями для сервера и учётных данных)

После входа вы увидите панель управления Riot/Element и сможете создать комнаты, отправлять сообщения и проверять функциональность:

(alt: Панель управления Riot/Element после успешного входа на Matrix-сервер)

Примеры экранов настроек и чата:

(alt: Настройки пользователя в клиенте Matrix)

(alt: Окно группового чата в Matrix клиенте)

Отладка и типичные проблемы

• Synapse не слушает на 127.0.0.1:8008/8448: проверьте синтаксис homeserver.yaml, перезапустите сервис и смотрите логи через journalctl -u matrix-synapse.
• Certbot не получает сертификат: убедитесь, что порт 80 свободен и домен указывает на ваш сервер. Для проверки используйте curl -v http://matrix.hakase-labs.io/.
• Ошибки в Nginx: nginx -t покажет синтаксические ошибки; проверьте пути к сертификатам и права доступа на файлы в /etc/letsencrypt/live/.
• Клиент не подключается по HTTPS: проверьте, что Nginx проксирует путь /_matrix на 127.0.0.1:8008 и что TLS сертификат действителен.

Короткий набор команд для диагностики:

sudo journalctl -u matrix-synapse -f
sudo tail -n 100 /var/log/nginx/error.log
ss -plntu | grep 8008
nginx -t
certbot certificates

Альтернативные подходы

1. Docker / docker-compose: разворачивание Synapse и Nginx в контейнерах упрощает изоляцию и обновления. Официальный образ Synapse и готовые docker-compose файлы доступны в сообществе.
2. Обновление через pip/virtualenv: для разработческих сред можно собрать Synapse из исходников и управлять зависимостями через виртуальные окружения Python.
3. Kubernetes: для крупных инсталляций рекомендована оркестрация, автоматическое масштабирование и хранение данных в управляемом хранилище.

Когда использовать альтернативы: Docker/K8s — если у вас уже есть контейнерная платформа и требования к отказоустойчивости; pip — только для тестирования и разработки.

Безопасность и конфиденциальность (кратко)

• TLS: используйте сильные параметры TLS в Nginx и автоматически обновляйте сертификаты через certbot renew.
• Бэкапы: регулярно делайте резервные копии базы данных и конфигурационных файлов.
• Secrets: храните registration_shared_secret и приватные ключи в защищённом хранилище, а не в открытых скриптах.
• Минимизация прав: Synapse не должен быть доступен извне напрямую — только через доверенный прокси.
• GDPR/конфиденциальность: если вы храните персональные данные пользователей, обеспечьте их шифрование и ясные политики хранения и удаления.

Когда этот подход не подходит (ограничения)

• Если нужна высокая доступность с автоматическим failover — требуется кластеризация и репликация БД, а предложенная схема “один сервер“ недостаточна.
• Для больших федераций и высоких нагрузок потребуется тюнинг, мониторинг (Prometheus/Grafana) и отдельные узлы для медиасервера и workers.

Рекомендации по развёртыванию в продакшн (чек-лист)

• Настройте резервные копии БД и шифрование хранения.
• Используйте автоматическое обновление сертификатов и контроль доступа к ключам.
• Включите мониторинг сервисов и алёрты (matrices metrics из Synapse).
• Разделяйте роли: веб-прокси, приложение, база данных.
• Планируйте масштабирование: отдельные workers Synapse при росте нагрузки.

Роль-based чек-лист (администратор):

• Проверьте доступность 80/443.
• Убедитесь, что Synapse работает только на 127.0.0.1.
• Проверяйте логи ежедневно и храните ротацию логов.

Роль-based чек-лист (операции):

• Автоматизируйте бэкапы конфигурации и БД.
• Настройте мониторинг и оповещения.

Мини-методология развертывания (быстрый SOP)

1. Протестировать план на тестовом хосте.
2. Настроить DNS и проверить разрешение домена.
3. Установить и настроить Synapse локально.
4. Получить TLS сертификат.
5. Настроить Nginx и UFW.
6. Создать минимум одного администратора и тестировать подключение клиента.
7. Внедрить мониторинг и бэкапы.

Критерии приёмки

• Synapse отвечает на локальных портах 8008/8448 только на 127.0.0.1.
• Nginx принимает HTTPS-запросы на 443 и корректно проксирует /_matrix на Synapse.
• Клиент успешно аутентифицируется и может отправлять/получать сообщения.
• Certbot выдал действительный сертификат для домена.

Тестовые сценарии (коротко)

1. Попытка подключения клиента через HTTPS: ожидается успешная аутентификация.
2. Доступ к Synapse с внешнего IP напрямую на 8448: должен быть закрыт.
3. Переход по http://matrix.hakase-labs.io должен редиректить на https://.
4. Обновление сертификата certbot renew тестируется вручную и без ошибок.

Быстрый шаблон конфигурации Nginx (шаблон)

Пример секции location для проксирования запросов к Synapse:

location /_matrix {
  proxy_pass http://127.0.0.1:8008;
  proxy_set_header X-Forwarded-For $remote_addr;
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-Proto $scheme;
}

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

Короткий глоссарий

• homeserver: серверная часть Matrix, реализующая аккаунты и комнаты.
• registration_shared_secret: общий секрет для создания учётных записей через скрипты.
• reverse proxy: сервер (Nginx), который принимает внешние запросы и перенаправляет их внутренним сервисам.

Пример простой decision flow (выбор стратегии развёртывания)

flowchart TD
  A[Нужен быстрый тест?] -->|Да| B[Установить на VM по инструкции]
  A -->|Нет, продакшн| C[Требуется надёжность]
  C --> D{Есть контейнерная платформа?}
  D -->|Да| E[Развернуть через Docker/K8s]
  D -->|Нет| F[Разделить роли, подготовить HA и бэкапы]

Ссылки и ресурсы

• Репозиторий Synapse: https://github.com/matrix-org/synapse

Краткое резюме

Вы установили и настроили Synapse на Ubuntu 18.04, защитили доступ HTTPS через Nginx с сертификатом Let’s Encrypt, включили брандмауэр и создали первого пользователя. Далее рекомендовано настроить мониторинг, бэкапы и, при росте нагрузки, разделить роли сервера.