Matrix Synapse + Element и Coturn на Debian 12

В этой инструкции описано, как развернуть самостоятельный Matrix-хост (Synapse) на Debian 12, настроить веб‑клиент Element и TURN (Coturn) для аудио/видеозвонков, а также nginx и SSL от Let’s Encrypt. Приведены команды, конфигурационные файлы, рекомендации по безопасности и пошаговые контрольные списки для администраторов.

Введение

Логотип Matrix и схема децентрализованной сети

Matrix — это открытый стандарт для децентрализованной и сквозного шифрования коммуникации. Система состоит из серверов и сервисов, которые обмениваются данными через стандартизованный API и синхронизируют события в режиме реального времени. Для хранения учётных данных и истории сообщений используются homeserver’ы. При падении одного сервера остальные продолжают обмениваться сообщениями благодаря децентрализации. Вы можете использовать чужой публичный homeserver или развернуть собственный, чтобы сохранить полный контроль над данными.

В этой статье вы по шагам установите Synapse (реализация Matrix homeserver), развернёте веб‑клиент Element и при желании настроите Coturn для голосовых и видеозвонков. Nginx будет выступать обратным прокси и точкой SSL‑терминации.

Важно: команды приведены для Debian 12. Замените example.com на ваши FQDN: matrix.example.com, element.example.com, coturn.example.com.

Что понадобится

Сервер с Debian 12.
Непривилегированный пользователь с возможностью sudo.
UFW (Uncomplicated Firewall) включён и работает.
Полные доменные имена (FQDN) для Matrix, Element и Coturn, указывающие на ваш сервер.
Права на изменение DNS и возможность получить сертификат Let’s Encrypt.
Базовые знания systemd, nano/vim и работы с сетью.

Быстрый обзор шагов

Откройте нужные порты в UFW.
Установите Synapse (Matrix homeserver).
Установите и настроите PostgreSQL и используйте его как СУБД для Synapse.
Установите Nginx как обратный прокси.
Получите SSL‑сертификаты с помощью Certbot (Let’s Encrypt).
Настройте Synapse через /etc/matrix-synapse/conf.d.
Настройте Nginx для Synapse и Element.
По желанию: установите Coturn и интегрируйте с Synapse.
Разверните Element как статический сайт и подключите к вашему homeserver.

Шаг 0 — Проверка и обновление системы

Перед началом убедитесь, что система обновлена:

$ sudo apt update && sudo apt upgrade

Важно: перезапуски ядра и сервисов выполняйте в удобное окно обслуживания.

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

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

$ sudo ufw status

Откройте порты для HTTP/HTTPS и федерации Matrix (8448):

$ sudo ufw allow 8448
$ sudo ufw allow http
$ sudo ufw allow https

Ещё раз проверьте статус:

$ sudo ufw status

Ожидаемый вывод покажет OpenSSH, 80, 443, 8448 и их IPv6‑эквиваленты.

Важно: если у вас нестандартные политики UFW (например, DENY по умолчанию), добавьте правила для SSH перед остальными изменениями, чтобы не потерять соединение.

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

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

$ 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

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

$ sudo apt install matrix-synapse-py3

Во время установки вас попросят указать имя сервера (server name). Введите ваш домен, например matrix.example.com — это часть вашего Matrix ID и адрес homeserver.

Окно конфигурации homeserver Synapse

Вам также предложат отправлять анонимную статистику — по умолчанию откажитесь (N). Настройки можно поменять позже в /etc/matrix-synapse/conf.d/server_name.yaml.

Проверьте статус службы Synapse:

$ sudo systemctl status matrix-synapse

Вы увидите, что служба запущена и включена (enabled). Если в логах видна ошибка о macaroon_secret_key или других обязательных ключах — проверьте конфигурацию и наличие файлов в /etc/matrix-synapse.

Шаг 3 — Установка и настройка PostgreSQL

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

$ curl https://www.postgresql.org/media/keys/ACCC4CF8.asc | gpg --dearmor | sudo tee /usr/share/keyrings/postgresql-key.gpg >/dev/null
$ sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/postgresql-key.gpg arch=amd64] http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
$ sudo apt update

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

$ sudo apt install postgresql postgresql-contrib

(Если нужно конкретное число версии, введите postgresql-14 и т.д.)

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

$ sudo systemctl status postgresql

Создайте пользователя и базу данных для Synapse:

$ sudo -su postgres
$ createuser --pwprompt synapse
$ createdb --encoding=UTF8 --locale=C --template=template0 --owner=synapse synapsedb
$ exit

Запомните пароль пользователя synapse — он пригодится при настройке Synapse.

Шаг 4 — Установка Nginx (рекомендуется для production)

Добавим официальный репозиторий Nginx для актуальной ветки stable:

$ curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null
$ echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] http://nginx.org/packages/debian `lsb_release -cs` nginx" | sudo tee /etc/apt/sources.list.d/nginx.list
$ sudo apt update
$ sudo apt install nginx

Проверьте версию и запустите сервер:

$ sudo nginx -v
$ sudo systemctl start nginx
$ sudo systemctl status nginx

Шаг 5 — SSL (Let’s Encrypt + Certbot)

Установим snapd и Certbot (рекомендованный способ для актуальной версии сертификатора):

$ sudo apt install snapd -y
$ sudo snap install core
$ sudo snap refresh core
$ sudo snap install --classic certbot
$ sudo ln -s /snap/bin/certbot /usr/bin/certbot
$ certbot --version

Получите сертификат для вашего домена (пример для matrix.example.com):

$ sudo certbot certonly --nginx --agree-tos --no-eff-email --staple-ocsp --preferred-challenges http -m [email protected] -d matrix.example.com

Сертификаты будут сохранены в /etc/letsencrypt/live/matrix.example.com.

Создайте Diffie‑Hellman группу (может занять время):

$ sudo openssl dhparam -dsaparam -out /etc/ssl/certs/dhparam.pem 4096

Проверьте автоматическое обновление certbot (snap):

$ sudo systemctl list-timers
$ sudo certbot renew --dry-run

Если dry run прошёл без ошибок, автоматическое продление настроено.

Важно: дождитесь завершения получения сертификата прежде чем настраивать nginx на их использование.

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

Не рекомендуется редактировать /etc/matrix-synapse/homeserver.yaml напрямую — файл может перезаписываться при обновлениях. Для production используйте /etc/matrix-synapse/conf.d/*.yaml.

Посмотрите текущие файлы:

$ ls /etc/matrix-synapse/conf.d
report_stats.yaml  server_name.yaml

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

$ sudo nano /etc/matrix-synapse/conf.d/database.yaml

Вставьте (замените your-password на пароль пользователя synapse):

database:
  name: psycopg2
  args:
    user: synapse
    password: 'your-password'
    database: synapsedb
    host: localhost
    cp_min: 5
    cp_max: 10

Создайте секретный ключ для регистрации (registration_shared_secret). Он позволит создавать аккаунты через скрипт регистрации даже при выключенной публичной регистрации. Секрет нужно хранить в защищённом месте:

$ echo "registration_shared_secret: '$(cat /dev/urandom | tr -cd '[:alnum:]' | fold -w 256 | head -n 1)'" | sudo tee /etc/matrix-synapse/conf.d/registration_shared_secret.yaml

По умолчанию в Synapse включены presence‑индикаторы (онлайн/оффлайн), которые могут нагружать CPU. Для снижения нагрузки можно отключить их:

$ sudo nano /etc/matrix-synapse/conf.d/presence.yaml

Вставьте:

presence:
  enabled: false

Перезапустите сервис:

$ sudo systemctl restart matrix-synapse

Создайте первого пользователя (администратора):

$ register_new_matrix_user -c /etc/matrix-synapse/conf.d/registration_shared_secret.yaml http://localhost:8008

Следуйте подсказкам: введите localpart (например, admin), пароль и подтвердите создание администратора.

Если вы хотите открыть публичную регистрацию (не рекомендовано без защиты), создайте:

$ sudo nano /etc/matrix-synapse/conf.d/registration.yaml

Вставьте:

enable_registration: true

Для включения обязательной email‑верификации укажите блок email/registrations_require_3pid с параметрами SMTP. Для отключения верификации используйте enable_registration_without_verification: true.

После изменений перезапустите Synapse:

$ sudo systemctl restart matrix-synapse

Шаг 7 — Настройка Nginx для Synapse

Откройте основной конфиг nginx и увеличьте server_names_hash_bucket_size, если требуется:

$ sudo nano /etc/nginx/nginx.conf

Добавьте перед include /etc/nginx/conf.d/*.conf;:

server_names_hash_bucket_size  64;

Создайте файл /etc/nginx/conf.d/synapse.conf:

$ sudo nano /etc/nginx/conf.d/synapse.conf

Вставьте конфигурацию (замените matrix.example.com на ваш домен):

# enforce HTTPS
server {
    # Client port
    listen 80;
    listen [::]:80;
    server_name matrix.example.com;
    return 301 https://$host$request_uri;
}

server {
    server_name matrix.example.com;

    # Client port
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    # Federation port
    listen 8448 ssl http2 default_server;
    listen [::]:8448 ssl http2 default_server;

    access_log  /var/log/nginx/synapse.access.log;
    error_log   /var/log/nginx/synapse.error.log;

    # TLS configuration
    ssl_certificate /etc/letsencrypt/live/matrix.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/matrix.example.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/matrix.example.com/chain.pem;
    ssl_session_timeout 1d;
    ssl_session_cache shared:MozSSL:10m;
    ssl_session_tickets off;
    ssl_prefer_server_ciphers on;
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_dhparam /etc/ssl/certs/dhparam.pem;
    resolver 1.1.1.1 1.0.0.1 [2606:4700:4700::1111] [2606:4700:4700::1001] 8.8.8.8 8.8.4.4 [2001:4860:4860::8888] [2001:4860:4860::8844] valid=60s;
    resolver_timeout 2s;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;

    tcp_nopush on;
    gzip on;

    location ~ ^(/_matrix|/_synapse/client) {
            proxy_pass http://localhost:8008;
            proxy_http_version 1.1;

            proxy_set_header X-Forwarded-For $remote_addr;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header Host $host;

            # Nginx by default only allows file uploads up to 1M in size
            # Increase client_max_body_size to match max_upload_size defined in homeserver.yaml
            client_max_body_size 50M;
    }
}

Если example.com и matrix.example.com указывают на разные сервера, добавьте конфигурацию делегирования через /.well-known (см. шаблон в исходном руководстве).

Проверьте синтаксис и перезапустите nginx:

$ sudo nginx -t
$ sudo systemctl restart nginx

Шаг 8 — Установка Coturn (TURN) для звонков — опционально

Для голосовых/видеозвонков через WebRTC необходим TURN сервер (Coturn), чтобы обеспечить ретрансляцию трафика в сетях с NAT/файерволом.

Установка:

$ sudo apt install coturn

Откройте порты:

$ sudo ufw allow 3478
$ sudo ufw allow 5349
$ sudo ufw allow 49152:65535/udp

Получите SSL сертификат для TURN (turn.example.com):

$ sudo certbot certonly --nginx --agree-tos --no-eff-email --staple-ocsp --preferred-challenges http -m [email protected] -d turn.example.com

Сгенерируйте секрет для статической аутентификации и запишите его в /etc/turnserver.conf:

$ echo "static-auth-secret=$(cat /dev/urandom | tr -cd '[:alnum:]' | fold -w 256 | head -n 1)" | sudo tee /etc/turnserver.conf

Откройте /etc/turnserver.conf и добавьте конфигурацию (пример):

use-auth-secret
realm=turn.example.com
cert=/etc/letsencrypt/live/turn.example.com/fullchain.pem
pkey=/etc/letsencrypt/live/turn.example.com/privkey.pem

# VoIP is UDP, no need for TCP
no-tcp-relay

# Do not allow traffic to private IP ranges
no-multicast-peers
denied-peer-ip=0.0.0.0-0.255.255.255
denied-peer-ip=10.0.0.0-10.255.255.255
... (см. полный список в примере)

# Limit number of sessions per user
user-quota=12
# Limit total number of sessions
total-quota=1200

Перезапустите coturn:

$ sudo systemctl restart coturn

Интегрируйте Coturn с Synapse: создайте /etc/matrix-synapse/conf.d/turn.yaml и укажите turn_uris и turn_shared_secret (значение static-auth-secret из /etc/turnserver.conf):

turn_uris: [ "turn:turn.example.com?transport=udp", "turn:turn.example.com?transport=tcp" ]
turn_shared_secret: 'static-auth-secret'
turn_user_lifetime: 86400000
turn_allow_guests: True

Затем перезапустите Synapse:

$ sudo systemctl restart matrix-synapse

Примечание: если у вас строгая политика NAT/ACL, убедитесь, что UDP диапазон 49152–65535 доступен и не блокируется хостингом.

Шаг 9 — Доступ к Matrix через Element

Откройте https://app.element.io и нажмите Sign in. Нажмите Edit под Homeserver и введите https://matrix.example.com как адрес homeserver.

Страница входа Element Web

Если клиент обнаружит ваш homeserver, индикатор станет зелёным, иначе — красным. Нажмите Continue и выполните вход.

В процессе настройки Element предложит создать зашифрованный бэкап ключей. Рекомендуется выбрать «Enter a Security Phrase» и сохранить recovery keys в защищённом месте.

Страница настройки безопасного бэкапа Matrix

После входа вы попадёте в дашборд Element. Создайте комнату, используя Create a Group Chat, и при необходимости ограничьте доменные участники в расширенных настройках.

Element дашборд с комнатой HowtoForge

Шаг 10 — Разворачивание Element (самостоятельный хост)

Установите jq для разбора JSON и создайте каталог для Element:

$ sudo apt install jq
$ sudo mkdir -p /var/www/element

Создайте скрипт автообновления /var/www/element/update.sh:

#!/bin/sh
set -e

install_location="/var/www/element"
latest="$(curl -s https://api.github.com/repos/vector-im/element-web/releases/latest | jq -r .tag_name)"

cd "$install_location"

[ ! -d "archive" ] && mkdir -p "archive"
[ -d "archive/element-${latest}" ] && rm -r "archive/element-${latest}"
[ -f "archive/element-${latest}.tar.gz" ] && rm "archive/element-${latest}.tar.gz"

wget "https://github.com/vector-im/element-web/releases/download/${latest}/element-${latest}.tar.gz" -P "archive"
tar xf "archive/element-${latest}.tar.gz" -C "archive"

[ -L "${install_location}/current" ] && rm "${install_location}/current"
ln -sf "${install_location}/archive/element-${latest}" "${install_location}/current"
ln -sf "${install_location}/config.json" "${install_location}/current/config.json"

Сделайте скрипт исполняемым и запустите его:

$ sudo chmod +x /var/www/element/update.sh
$ sudo /var/www/element/update.sh

Шаг 11 — Настройка Element (конфигурация клиента)

Скопируйте образец конфигурации и отредактируйте:

$ sudo cp /var/www/element/current/config.sample.json /var/www/element/config.json
$ sudo nano /var/www/element/config.json

Найдите блок m.homeserver и укажите ваш адрес:

"m.homeserver": {
    "base_url": "https://matrix.example.com",
    "server_name": "example.com"
},

Можно поменять бренд сайта (brand), отключить гостевой доступ (disable_guests: true) и другие параметры интерфейса.

Получите сертификат для element.example.com и создайте конфигурацию nginx /etc/nginx/conf.d/element.conf:

server {
    listen 80;
    listen [::]:80;
    server_name element.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    server_name element.example.com;

    root /var/www/element/current;
    index index.html;

    access_log  /var/log/nginx/element.access.log;
    error_log   /var/log/nginx/element.error.log;

    add_header Referrer-Policy "strict-origin" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "SAMEORIGIN" always;

    # TLS configuration
    ssl_certificate /etc/letsencrypt/live/element.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/element.example.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/element.example.com/chain.pem;
    ssl_session_timeout 1d;
    ssl_session_cache shared:MozSSL:10m;
    ssl_session_tickets off;
    ssl_prefer_server_ciphers on;
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_dhparam /etc/ssl/certs/dhparam.pem;
    resolver 1.1.1.1 1.0.0.1 [2606:4700:4700::1111] [2606:4700:4700::1001] 8.8.8.8 8.8.4.4 [2001:4860:4860::8888] [2001:4860:4860::8844] valid=60s;
    resolver_timeout 2s;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
}

Проверьте nginx и перезапустите:

$ sudo nginx -t
$ sudo systemctl restart nginx

Откройте https://element.example.com и выполните вход. При первом входе Element попросит подтвердить подключение к https://app.element.io (если вы используете централизованный сервис для проверки). Следуйте подсказкам в клиенте.

Панель саморазвёрнутого Element

Дополнительные разделы: методология, безопасность и практические чеклисты

Краткая методология развёртывания (мини‑методология)

План: перечислите FQDN, IP, требования по доступности и лимиты хранилища.
Подготовка: резервные копии, доступы SSH, политика брандмауэра.
Установка: Synapse → БД → nginx → SSL → Coturn → Element.
Тестирование: локальные подключения, федерация, звонки, обновление certbot.
Операции: мониторинг, ротация ключей, обновления пакетов.

Роли и контрольные списки (role‑based checklists)

Администратор сервера:

Обновить систему и установить необходимые пакеты.
Настроить UFW и открыть нужные порты.
Настроить автоматическое обновление сертификатов.

Администратор Matrix/Synapse:

Настроить базу данных и connection pool.
Сгенерировать registration_shared_secret.
Настроить политики регистрации и email (если нужно).
Проверить federation через порт 8448.

Оператор VoIP/RTC:

Установить и проверить coturn.
Открыть UDP диапазон 49152–65535.
Убедиться в корректности static-auth-secret.

Разработчик/Интегратор Element:

Настроить config.json и brand.
Проверить кросс‑доменные политики и CORS.

Безопасность и жёсткая настройка

Ограничьте доступ к /etc/matrix-synapse и ключам сертификатов (chmod 600/640 для секретов).
Включите автоматическое обновление пакетов (apt unattended‑upgrades) и мониторьте обновления Synapse.
Ограничьте публичную регистрацию или используйте email‑верификацию и CAPTCHA/доп. защиту.
Для федерации используйте DNSSEC, если возможно, и следите за реестром доверенных ключей.
Логи: собирайте и анализируйте /var/log/nginx/*.log и логи synapse (systemd journal).
Для Coturn используйте use-auth-secret и ограничьте denied-peer-ip для приватных диапазонов.

Важно: никогда не публикуйте registration_shared_secret или static-auth-secret в публичных репозиториях.

Отладка, проверка работоспособности и откат (incident runbook)

Симптом: Synapse не отвечает на запросы через nginx.

Проверить статус systemd: sudo systemctl status matrix-synapse
Проверить логи journalctl -u matrix-synapse -e
Проверить, доступен ли локально порт 8008: curl -v http://localhost:8008/_matrix/client/versions
Проверить права доступа к файлам конфигурации и ключам.

Симптом: nginx не стартует после правки конфига.

Выполнить sudo nginx -t и по сообщениям вернуть прежнюю конфигурацию.
Проверить, что сертификаты существуют в /etc/letsencrypt/live.

Симптом: Coturn не раздаёт креденшалы.

Убедиться, что static-auth-secret совпадает в /etc/turnserver.conf и в /etc/matrix-synapse/conf.d/turn.yaml.
Проверить, что coturn слушает нужные порты: sudo ss -ltnup | grep turn

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

Храните резервные копии файлов /etc/matrix-synapse/conf.d/.yaml и /etc/nginx/conf.d/.conf.
Для быстрого отката замените изменённый файл на резервную копию и перезапустите сервисы.

Совместимость и заметки о миграции

Synapse поддерживает SQLite для тестовых окружений, но PostgreSQL рекомендуется для production.
При миграции с SQLite на PostgreSQL следует следовать официальной документации Synapse по экспорт/импорту данных.
Версии пакетов (nginx, postgresql, synapse) со временем обновляются: тестируйте обновления в staging перед production.

Факто‑блок (ключевые значения и порты)

HTTP: 80
HTTPS: 443
Federation (Matrix): 8448
TURN (TCP/TLS/UDP): 3478, 5349
TURN UDP диапазон: 49152–65535
Synapse (локальный проксируемый порт): 8008
Конфигурации Synapse: /etc/matrix-synapse/conf.d/
Certbot (Let’s Encrypt) хранит сертификаты в /etc/letsencrypt/live//

Краткий глоссарий (1‑строчные определения)

Synapse — серверная реализация Matrix homeserver.
Element — веб/десктоп/мобильный клиент для Matrix.
Coturn — реализация TURN сервера (Traversal Using Relays around NAT).
TURN — протокол ретрансляции медиа для обхода NAT/файрволов.
Federation — связь между разными Matrix‑сервером для обмена сообщениями.

Шаблон сравнения подходов (коротко)

SQLite (тест/локально): просто, но не подходит для нагрузки.
PostgreSQL (production): надёжно, поддерживает пул соединений и высокий трафик.
nginx: рекомендуемый прокси и точка SSL‑терминации.
Caddy: альтернативный web‑сервер с встроенным автоматическим TLS (если предпочитаете упрощённую настройку).

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

В руководстве показано, как шаг за шагом развернуть Synapse на Debian 12, подключить PostgreSQL, настроить nginx и SSL, опционально установить Coturn для звонков и развернуть Element как веб‑клиент. Приведены контрольные списки, рекомендации по безопасности и отладке.

Если возникнут вопросы — опишите вашу конфигурацию (логи, версии пакетов, шаг, на котором возникла ошибка) — это ускорит диагностику.

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

Спасибо за внимание.