Matrix (Synapse) на Ubuntu 24.04: пошаговая установка

MAATRIX

Matrix — открытый децентрализованный протокол обмена сообщениями со сквозным шифрованием: вы поднимаете собственный сервер (домашний сервер, homeserver), а пользователи регистрируются на нём и общаются между собой и с людьми на других серверах, если разрешена федерация. В отличие от Telegram или Slack, здесь нет единой компании, которая держит все ваши переписки — данные лежат там, где вы сами их разместили. Ниже — рабочая пошаговая установка эталонной реализации Matrix, сервера Synapse, на чистой Ubuntu 24.04, с PostgreSQL, Nginx и SSL.

Что такое Matrix и зачем свой сервер Synapse

Synapse — это референсная (эталонная) реализация Matrix-сервера, написанная на Python, которую поддерживает сама команда Matrix.org. Есть более лёгкие альтернативы (Conduit, Dendrite), но Synapse — самая зрелая, с полным набором функций: федерация, мосты в другие мессенджеры, широкие возможности модерации и админ-API. Это же и его минус — Synapse прожорлив к памяти и диску на активных серверах, особенно с включённой федерацией.

Свой сервер имеет смысл в двух сценариях. Первый — вы хотите закрытый корпоративный или командный чат без федерации вовне: данные не покидают ваш периметр, вы полностью контролируете хранение и бэкапы, а сквозное шифрование Olm/Megolm защищает переписку даже от вас самих как администратора сервера. Второй — вы хотите быть частью открытой федеративной сети Matrix, общаться с пользователями других серверов, но при этом не зависеть от чужой инфраструктуры и политики matrix.org.

Для install-теста хватит 2 vCPU и 4 ГБ RAM с несколькими активными пользователями; при федерации с большим числом внешних серверов Synapse начинает есть память заметнее, и 8 ГБ — более комфортный запас. Диск — от 20 ГБ под систему и БД, плюс место под медиа-хранилище (файлы, аватары, превью), которое растёт быстрее всего остального.

Подготовка сервера и домен

Вам понадобится домен (или поддомен) и доступ к его DNS. В Matrix действует разделение между «именем сервера» (server_name) — доменом, который войдёт в ваши Matrix ID вида @user:example.com, и фактическим хостом, на котором крутится Synapse. Часто их разносят: server_name: example.com, а сам Synapse живёт на matrix.example.com. Это называется delegation (делегирование) и позволяет держать красивый короткий ID без необходимости обслуживать веб-сервер на голом домене.

Заведите две A-записи (или A + AAAA, если есть IPv6):

matrix.example.com.   A   203.0.113.10
example.com.          A   203.0.113.10

Обновите систему и поставьте базовые пакеты:

sudo apt update && sudo apt upgrade -y
sudo apt install -y lsb-release wget apt-transport-https gnupg curl

Если сервер смотрит наружу открытым портом кроме SSH и веба, сразу настройте файрвол UFW — понадобятся только 22, 80 и 443 (порт 8448 для прямой федерации в этой схеме не нужен, см. ниже).

Установка Synapse из репозитория Matrix.org

На Ubuntu 24.04 удобнее ставить не через pip, а из официального apt-репозитория Matrix.org — так проще получать обновления безопасности:

sudo wget -O /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

sudo apt update
sudo apt install -y matrix-synapse-py3

В процессе установки debconf задаст два вопроса: имя сервера (server_name) — впишите сюда именно «внешнее» имя, например example.com, а не matrix.example.com, и адрес для отчётов об ошибках (можно оставить пустым). Имя сервера меняется в дальнейшем крайне тяжело — по сути потребуется разворачивать всё заново, — так что определитесь заранее.

После установки конфиг лежит в /etc/matrix-synapse/homeserver.yaml, дополнительные файлы — в /etc/matrix-synapse/conf.d/, данные и медиа — в /var/lib/matrix-synapse/. Сервис называется matrix-synapse и уже умеет стартовать через systemd:

sudo systemctl status matrix-synapse

По умолчанию Synapse слушает http://localhost:8008 — наружу его отдаст Nginx.

PostgreSQL вместо SQLite

По умолчанию пакет ставит SQLite, но это годится только для теста «оно вообще работает». На любой сервер с реальными пользователями нужен PostgreSQL — SQLite не тянет параллельные запросы и заметно проседает уже на паре десятков активных пользователей.

sudo apt install -y postgresql
sudo -u postgres psql -c "CREATE USER synapse_user WITH PASSWORD 'замените-на-свой-пароль';"
sudo -u postgres psql -c "CREATE DATABASE synapse ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE template0 OWNER synapse_user;"

Кодировка UTF8 и локаль C для базы обязательны — Synapse явно проверяет это при старте и откажется работать с базой, созданной с локалью по умолчанию (обычно en_US.UTF-8).

В homeserver.yaml замените блок database:

database:
  name: psycopg2
  args:
    user: synapse_user
    password: замените-на-свой-пароль
    database: synapse
    host: localhost
    port: 5432
    cp_min: 5
    cp_max: 10

Если сервер уже успел что-то записать в SQLite, есть штатный скрипт synapse_port_db для переноса в Postgres — но проще перенести данные, пока их ещё нет, сразу после установки.

Nginx, делегирование и федерация без порта 8448

Классическая схема федерации Matrix требует открытого порта 8448 с валидным TLS. Более удобный вариант — делегирование через .well-known: тогда весь трафик, и клиентский, и федеративный, идёт через привычный 443, а порт 8448 вообще не нужен наружу.

Настройте reverse proxy для matrix.example.com (по образцу из статьи про Nginx как обратный прокси):

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name matrix.example.com;

    ssl_certificate     /etc/letsencrypt/live/matrix.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/matrix.example.com/privkey.pem;

    client_max_body_size 50M;

    location ~ ^(/_matrix|/_synapse/client) {
        proxy_pass http://localhost: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;
    }
}

А на голом домене example.com (server_name из конфига) добавьте отдачу двух JSON-файлов делегирования:

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    location /.well-known/matrix/server {
        default_type application/json;
        return 200 '{"m.server": "matrix.example.com:443"}';
    }

    location /.well-known/matrix/client {
        default_type application/json;
        add_header Access-Control-Allow-Origin *;
        return 200 '{"m.homeserver": {"base_url": "https://matrix.example.com"}}';
    }
}

Проверить делегирование после запуска можно инструментом Federation Tester от matrix.org — он покажет, видят ли внешние серверы ваш .well-known корректно.

SSL-сертификаты и запуск

Получите сертификаты для обоих доменов (подробный разбор — в статье про Let's Encrypt SSL):

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d example.com -d matrix.example.com

Перезапустите Nginx и Synapse:

sudo nginx -t && sudo systemctl reload nginx
sudo systemctl restart matrix-synapse

Если сервер предназначен для закрытой команды, а не для открытой федерации, сразу отключите публичную регистрацию и ограничьте федерацию в homeserver.yaml:

enable_registration: false
federation_domain_whitelist: []

Пустой federation_domain_whitelist полностью отрезает сервер от внешней федеративной сети — останутся только пользователи вашего собственного homeserver. Это осознанный выбор для приватного корпоративного хаба; для полноценного участия в сети Matrix эту опцию просто не добавляйте.

Первого пользователя (обычно — админа) создают отдельной утилитой, а не через публичную форму регистрации:

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

Утилита спросит логин, пароль и права администратора — этого пользователя удобно оставить как основной аккаунт для управления сервером через admin API.

Клиент Element и первая проверка

Проверить, что сервер жив, можно без всякого клиента:

curl https://matrix.example.com/_matrix/client/versions

Ответ с перечнем поддерживаемых версий API означает, что Synapse отвечает через Nginx корректно. Дальше нужен клиент — самый распространённый выбор — Element (десктоп, мобильные приложения или веб-версия). Указывать домен сервера при входе нужно тот, что стоит в server_name — то есть example.com, а не matrix.example.com: клиент сам найдёт актуальный адрес через .well-known/matrix/client.

Если хотите держать веб-клиент на своём же сервере, а не пользоваться app.element.io, Element Web разворачивается отдельным Docker-контейнером и отдаётся тем же Nginx на своём поддомене (например, chat.example.com) — это отдельная от Synapse задача и не требует дополнительной настройки самого homeserver.

Логи при разборе проблем смотрите через journalctl:

sudo journalctl -u matrix-synapse -f

Там же видно ошибки подключения к БД, проблемы с федерацией к конкретным серверам и предупреждения о медленных запросах.

Частые вопросы