База знаний (кластер NBICS)

Admin

Создаём и запускаем службу NodeBB в SystemD

1. Создаём пользователя

NodeBB (как и любой Node.js-сервис) никогда не должен работать от root. Поэтому нужно создать непривелегированного пользователя.

adduser --disabled-password --gecos "" nodebb

Эта команда создает минимальную, непривилегированную и неинтерактивную учетную запись с именем nodebb, которая идеально подходит для безопасного запуска веб-приложений.

2. Меняем владельца каталога nodebb

Допустим, вы работаете в LXC-контейнере, и каталог nodebb находится в корневом каталоге виртуальной системы.
Заходим туда, и сначала останавливаем форум:

cd /nodebb
./nodebb stop

Далее меняем владельца каталога

chown -R nodebb:nodebb /nodebb

chown: Изменить владельца.
-R: Рекурсивно (применить ко всем файлам и подкаталогам внутри /nodebb).
nodebb:nodebb: Новый владелец (пользователь:группа).
/nodebb: Директория форума NodeBB.

После этого пользователь nodebb сможет безопасно запускать приложение, и вы сможете правильно указать его в вашем файле Systemd-службы (например, в директивах User=nodebb и Group=nodebb).

3. Создание файла для systemd

Заходим в каталог

cd /etc/systemd/system/

Создаём файл

touch nodebb.service

Вносим в этот файл следующий текст:

# /etc/systemd/system/nodebb.service
[Unit]
Description=NodeBB Forum
Documentation=https://docs.nodebb.org
After=network.target mongod.service
Wants=mongod.service

[Service]
Type=simple
User=nodebb
Group=nodebb
WorkingDirectory=/nodebb
Environment=NODE_ENV=production

# Это самый важный момент — запускаем напрямую loader.js
ExecStart=/usr/bin/node /nodebb/loader.js --no-silent --no-daemon
ExecStop=/usr/bin/node /nodebb/app.js --stop   # или просто kill, но так аккуратнее

Restart=always
RestartSec=10

# Логи
StandardOutput=journal
StandardError=journal

# Ограничения (по желанию)
MemoryMax=600M
CPUQuota=90%

[Install]
WantedBy=multi-user.target

4. Запуск сервиса

sudo systemctl daemon-reload
sudo systemctl enable nodebb
sudo systemctl start nodebb

Admin

Управление NodeBB

️ Основные команды NodeBB

Команда	Описание
`./nodebb start`	Запуск экземпляра NodeBB (в фоновом режиме).
`./nodebb stop`	Остановка запущенного экземпляра NodeBB.
`./nodebb restart`	Перезапуск экземпляра NodeBB.
`./nodebb log`	Просмотр логов в реальном времени (с использованием `tail -f`).
`./nodebb status`	Проверка статуса запущенного процесса NodeBB.

️ Команды для разработки и обслуживания

Команда	Описание
`./nodebb dev`	Запуск NodeBB в режиме разработки. Включает горячую перезагрузку шаблонов и логов.
`./nodebb setup`	Настройка NodeBB (первоначальная установка или изменение конфигурации).
`./nodebb upgrade`	Выполнение обновления базы данных и файлов NodeBB до последней версии.
`./nodebb reset`	Сброс конфигурации NodeBB (не рекомендуется без необходимости).
`./nodebb build`	Пересборка клиентских скриптов и стилей (обычно требуется после обновления или установки плагинов).
`./nodebb activate plugin-name`	Активация указанного плагина.
`./nodebb deactivate plugin-name`	Деактивация указанного плагина.

Команды для базы данных

Команда	Описание
`./nodebb backup`	Создание резервной копии базы данных (требует дополнительной настройки или внешних утилит в зависимости от используемой БД).
`./nodebb restore`	Восстановление базы данных из резервной копии.

Примечание: Все эти команды должны выполняться из корневой директории установки NodeBB.

Admin

5. Создание конфига для NGINX и сертификата

Внимание!
Работа с Nginx производится вне контейнера, на хостовой системе

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

cd /etc/nginx/sites-available
sudo touch nodebb.conf
sudo nano nodebb.conf

Вписываем в конфиг примитив, сохраняем

server {
    listen 80;
    server_name my_domain.tld;  # Замените на ваш домен

    location / {
        root /var/www/html;
    }
}

Создаём линк

sudo ln -s /etc/nginx/sites-available/nodebb.conf /etc/nginx/sites-enabled/

Устанавливаем certbot, если ещё не установлен

sudo apt install certbot python3-certbot-nginx -y

Создаём сертификат для домена

sudo certbot --nginx -d my_domain.tld

Заходим сюда /etc/nginx/sites-available/nodebb.conf и меняем текст конфига таком образом:

server {

    server_name my_domain.tld; # Подставляем свой домен

    location / {
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;
        proxy_set_header X-NginX-Proxy true;

        proxy_pass http://10.0.3.180:4567;  # Меняем на айпи своего контейнера с форумом
        proxy_redirect off;

        # Socket.IO Support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/my_domain.tld/fullchain.pem; # Сюда тоже свой домен
    ssl_certificate_key /etc/letsencrypt/live/my_domain.tld/privkey.pem; # И сюда свой домен                                                                                                                
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot                                                                                                                                         
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot                                                                                                                                           

}server {
    if ($host = my_domain.tld) {    # Ещё раз прописываем свой домен
        return 301 https://$host$request_uri;
    } # managed by Certbot


    listen 80;

    server_name my_domain.tld;   #  И снова свой домен вписываем
    return 404; # managed by Certbot
}

Проверка и перезагрузка

sudo nginx -t
sudo systemctl reload nginx

Admin

4. Настройка и запуск NodeBB

Внимание!
Операции по настройке и запуску форума NodeBB осуществляем без входа в режим sudo

cd nodebb

1. Запуск настройки

Заходим через файловый менеджер mc
Выбираем каталог install (получится nodebb/install)
Копируем оттуда файл package.json на уровень выше, то есть в каталог nodebb
Выходим из mc

2. Запуск настройки

./nodebb setup

Ответы на вопросы:

URL сайта: http://ваш-домен.ру (точно так, как будете открывать)
Порт: 4567 (по умолчанию)
База данных: mongo
Хост MongoDB: localhost
Порт MongoDB: 27017
Имя пользователя: nodebb
Пароль: ВАШ_ПАРОЛЬ_NODEBB (из шага выше)
Создание администратора: заполните логин, email, пароль

ПРИМЕР

Welcome to NodeBB v4.7.0!

This looks like a new installation, so you'll have to answer a few questions about your environment before we can proceed.
Press enter to accept the default setting (shown in brackets).
URL used to access this NodeBB (http://localhost:4567) https://pixelfed.nbics.net
Please enter a NodeBB secret (90a569b2-f42b-4be2-b36b-35606094bfea) 
Would you like to submit anonymous plugin usage to nbbpm? (yes) no
Which database to use (mongo) 
2025-12-05T20:15:09.594Z [5423] - info: 
Now configuring mongo database:
MongoDB connection URI: (leave blank if you wish to specify host, port, username/password and database individually)
Format: mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]] 
Host IP or address of your MongoDB instance (127.0.0.1) 
Host port of your MongoDB instance (27017) 
MongoDB username nodebb
Password of your MongoDB database 
MongoDB database name (nodebb) nodebb
2025-12-05T20:16:31.596Z [5423] - info: [database] Checking database indices.
2025-12-05T20:16:32.210Z [5423] - info: [database] Checking database indices done!
2025-12-05T20:16:33.290Z [5423] - verbose: [minifier] utilizing a maximum of 7 additional threads
Configuration Saved OK
Populating database with default configs, if not already set...
2025-12-05T20:16:33.348Z [5423] - warn: [cache-buster] could not read cache buster ENOENT: no such file or directory, open '/nodebb/build/cache-buster' {"code":"ENOENT","errno":-2,"path":"/nodebb/build/cache-buster","stack":"Error: ENOENT: no such file or directory, open '/nodebb/build/cache-buster'\n    at async open (node:internal/fs/promises:641:25)\n    at async Object.readFile (node:internal/fs/promises:1245:14)\n    at async read (/nodebb/src/meta/cacheBuster.js:31:18)\n    at async Configs.init (/nodebb/src/meta/configs.js:90:17)\n    at async setupDefaultConfigs (/nodebb/src/install.js:249:2)\n    at async install.setup (/nodebb/src/install.js:617:3)\n    at async Object.setup (/nodebb/src/cli/setup.js:30:15)","syscall":"open"}
Enabling default theme: nodebb-theme-harmony
No categories found, populating instance with default categories
2025-12-05T20:16:33.760Z [5423] - warn: No administrators have been detected, running initial user setup

Administrator username Admin
Administrator email address oleg75@mail.nbics.net
Password 
Confirm Password

После завершения появится: NodeBB Setup Completed.

3. Запуск NodeBB

./nodebb start

Проверьте: http://ваш-ip:4567 — должен открыться форум.

Управление NodeBB

Команда	Описание
`./nodebb start`	Запуск
`./nodebb stop`	Остановка
`./nodebb restart`	Перезапуск
`./nodebb log`	Просмотр логов в реальном времени

Admin

3. Настраиваем базу данных

Настройка MongoDB (с авторизацией)

1. Подключение к MongoDB Shell

mongosh

2. Создание администратора (в базе `admin`)

use admin
db.createUser({
  user: "admin",
  pwd: "ВАШ_НАДЁЖНЫЙ_ПАРОЛЬ",
  roles: [ { role: "root", db: "admin" } ]
})

Замените ВАШ_НАДЁЖНЫЙ_ПАРОЛЬ на сложный пароль (без <>).

3. Создание базы и пользователя для NodeBB

use nodebb
db.createUser({
  user: "nodebb",
  pwd: "ВАШ_ПАРОЛЬ_NODEBB",
  roles: [
    { role: "readWrite", db: "nodebb" },
    { role: "clusterMonitor", db: "admin" }
  ]
})

4. Выход

quit()

5. Включение авторизации

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

sudo nano /etc/mongod.conf

Добавьте в конец:

security:
  authorization: enabled

6. Перезапуск MongoDB

sudo systemctl restart mongod

7. Проверка подключения с авторизацией

mongosh "mongodb://localhost:27017" --username admin --authenticationDatabase admin

(Вас попросят ввести пароль admin. Выйдите через quit().)

Admin

2. Устанавливаем компоненты форума

Заходим в контейнер

incus exec incus-forum -- bash

Заходим под созданным ранее пользователем

su - forumuser

Установка Node.js (версия 22 LTS)

NodeBB требует Node.js 22.x (LTS на ноябрь 2025 года). Устанавливаем из репозитория NodeSource.

1. Импорт GPG-ключа NodeSource

sudo apt-get install -y ca-certificates curl gnupg
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

2. Добавление репозитория Node.js 22.x

echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list

3. Установка

sudo apt update
sudo apt install nodejs -y

Проверка

node -v    # должно быть v22.x.x
npm -v     # должно быть 10.x.x

Установка MongoDB 8.0

MongoDB 8.0 — официально поддерживаемая версия. Используем репозиторий MongoDB для Debian 12 (bookworm).

1. Импорт GPG-ключа MongoDB

sudo apt-get install -y gnupg curl
curl -fsSL https://pgp.mongodb.com/server-8.0.asc | \
   sudo gpg -o /usr/share/keyrings/mongodb-server-8.0.gpg --dearmor

2. Добавление репозитория

echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] http://repo.mongodb.org/apt/debian bookworm/mongodb-org/8.0 main" | sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list

3. Установка

sudo apt update
sudo apt install -y mongodb-org

Проверка

mongod --version
# db version v8.0.x

Запуск и проверка службы

sudo systemctl start mongod
sudo systemctl enable mongod
sudo systemctl status mongod

Установка NodeBB

1. Установка Git

sudo apt install -y git

Важно: Для следующей операции НЕ используйте sudo!

2. Клонирование репозитория (ветка v4.x — стабильная)

git clone -b v4.x https://github.com/NodeBB/NodeBB.git nodebb

3. Переходим в каталог nodebb и копируем туда файл package.json

cd nodebb
cp install/package.json ./     # Тоже без sudo

Или:

Заходим через файловый менеджер mc
Выбираем каталог install (получится nodebb/install)
Копируем оттуда файл package.json на уровень выше, то есть в каталог nodebb
Выходим из mc

Admin

Подразумевается, что установка форума происходит в Incus-контейнере

1. Настраиваем систему в контейнере

Заходим в контейнер

incus exec incus-forum -- bash     # Имя контейнера incus-forum, но можете задать другое имя

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

apt update
apt install mc nano curl wget htop lynx lsof openssh-server

Задаём пароль для суперпользователя (root)

passwd root

И два раза вводим придуманный пароль

Создаём нового пользователя и включаем его в группу sudo

sudo adduser forumuser  # Вместо newuser можете задать другое имя пользователя

Система попросит вас:

Ввести пароль (символы при вводе не отображаются).
Повторить пароль.
Ввести данные пользователя (ФИО, номер комнаты и т.д.) — это можно пропустить, просто нажимая Enter.
Далее будет предложено подтвердить настройки, выбираем Y и жмём Enter

Добавляем пользователя в группу sudo

sudo usermod -aG sudo forumuser

-a (append) — добавить.
-G (groups) — в группу.

Чтобы убедиться, что всё прошло успешно, переключитесь на нового пользователя:

su - forumuser

Затем попробуйте выполнить любую команду с sudo, например, обновить список пакетов:

sudo apt update

Если система приняла пароль и начала обновление — пользователь успешно настроен.

Выходим из режима пользователя

exit

Выходим из контейнера

exit

Admin

Содержание

Admin

Увеличение размера файла подкачки (виртуальная память, Swap)

# Пример создания swap-файла 2 ГБ (если нет раздела)
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Admin

Теория JWT-аутентификации

JWT (JSON Web Token) — это безопасный и удобный способ передачи данных между разными системами. JWT часто используется для аутентификации пользователей или передачи информации о правах доступа.

Это как пропуск на мероприятие. Когда вы заходите на концерт, вам дают билет с уникальным кодом, который подтверждает, что вы купили билет и имеете право зайти. JWT выполняет ту же роль, только для систем.

Создание токена

Когда вы или ваше приложение авторизуетесь, сервер создаёт токен (то есть «пропуск»), в котором хранится информация, например:

- Кто вы (имя пользователя или ID).
- Какие у вас права (например, "может записывать звонки").
- Когда истекает срок действия этого токена (чтобы нельзя было использовать его вечно).

Эта информация кодируется в виде строки (набора символов) и подписывается с помощью специального "секретного ключа". Подпись нужна, чтобы никто не мог подделать токен.

Использование токена

Когда вы хотите что-то сделать на сервере (например, войти в конференцию в Jitsi), ваше приложение отправляет этот токен серверу. Сервер проверяет токен:

- Не изменён ли он.
- Действителен ли он.
- Есть ли у вас право делать то, что вы хотите.

Почему JWT удобен?

Не нужно хранить сессии на сервере. Всё, что нужно, — это проверить подпись токена. Это облегчает работу сервера.
Токен — это всего лишь текстовая строка, которую можно легко передавать через Интернет.

Как выглядит JWT?

JWT состоит из трёх частей, разделённых точками (.):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImpvaG4iLCJyb2xlIjoiYWRtaW4iLCJleHBpcmUiOjE2MzAxMzc2MDB9.N9RXgZG8ghJDU4Zfbl9h7syNDcKXoZVgCkKb-Pouhyo

Заголовок (Header): Указывает тип токена и метод шифрования.

{
  "alg": "HS256",
  "typ": "JWT"
}

Полезная нагрузка (Payload): Содержит данные, например имя пользователя, роль и срок действия.

{
  "username": "sidorov",
  "role": "admin",
  "expire": 1630137600
}

Подпись (Signature): Гарантирует, что токен не был изменён.

Как это используется в Jitsi?

Создание токена: Система управления, например Jitsi Admin, создаёт токен, когда пользователь пытается подключиться. В токене прописываются его права: например, кто он и может ли он создавать конференции.

Проверка токена: Jitsi Meet сервер проверяет токен, прежде чем впустить пользователя или разрешить ему выполнять действия.

Admin

Разные вопросы и нюансы

1. Как часто серверы «опрашивают» основной?

FRP работает не совсем как «опрос» (poll), а как постоянное TCP-соединение.

Принцип: Клиент (frpc) устанавливает соединение с сервером (frps) при старте и удерживает его открытым. Это не «запрос-ответ», а «труба», которая всегда открыта.
Heartbeat (пульс): Чтобы соединение не разрывалось из-за бездействия или NAT-таймаутов, внутри FRP есть механизм heartbeat. По умолчанию он отправляет маленькие контрольные пакеты примерно каждые 30 секунд. Это минимальная нагрузка на сеть — доли килобайт.
Настройка: Вы можете регулировать это в frpc.toml параметром heartbeatInterval (в секундах). Если сеть очень нестабильная, можно поставить меньше, если всё хорошо — оставить по умолчанию.

2. Сколько серверов можно «повесить» на один основной?

Здесь всё зависит от ресурсов Сервера Б (Стабильного). FRP крайне эффективен, так как написан на Go.

Оперативная память (RAM): Один клиент frpc потребляет очень мало (от 5 до 20 МБ в зависимости от количества прокси). Если у вас 1 ГБ ОЗУ на Сервере Б, вы легко можете держать сотни (200–500+) подключенных серверов.
Процессор (CPU): Пока туннели простаивают, нагрузка близка к нулю. Она вырастает только тогда, когда по туннелю идет реальный трафик (например, вы копируете файлы через SSH или передаёте данные).
Сетевой канал (Bandwidth): Это узкое место. Если 50 серверов начнут одновременно качать гигабайты данных через Сервер Б, он станет "бутылочным горлышком".

Есть ли предел?

Технического лимита внутри FRP практически нет, но есть ограничения операционной системы (Linux):

Лимит файлов (File Descriptors): Каждое соединение — это открытый файл. В Linux по умолчанию лимит обычно 1024, но его легко поднять в настройках ulimit или через системные настройки sysctl.
Суммарная пропускная способность: Один мощный сервер (например, с 2–4 ядрами и 4 ГБ ОЗУ) легко "переварит" 1000+ туннелей в режиме ожидания.

Итого:

Нагрузка на сеть: Мизерная (контрольные пакеты раз в 30 секунд).
Масштабирование: Можно цеплять сотни клиентов.
Совет: Если планируете более 50–100 серверов, обязательно добавьте в настройки [common] параметр maxPoolCount на Сервере Б, чтобы управлять пулом соединений и не забить все порты.

Если планируете подключать целую «ферму» из десятков серверов, лучше заранее выделить отдельный конфиг для каждого или использовать динамическую конфигурацию (когда frps берет настройки из БД или отдельной папки), чтобы не раздувать один файл до бесконечности.

Admin

Пошаговая инструкция по установке и настройке FRP.

Шаг 1: Скачивание (на обоих серверах)

Внимание!
SSH-сервер должен быть установлен на всех серверах, если его нет, устанавливаем:

sudo apt install openssh-server

Далее, скачиваем FRP.

FRP — это один архив с двумя файлами: frps (server) и frpc (client).

Зайдите на страницу релизов GitHub.
Скопируйте ссылку на актуальную версию для Linux (обычно _linux_amd64.tar.gz).
Скачайте и распакуйте на обоих серверах.

Пример:

# Переходим в домашнюю папку
cd ~
# Скачиваем архив (версия 0.61.1 актуальна на текущий момент)
wget https://github.com/fatedier/frp/releases/download/v0.61.1/frp_0.61.1_linux_amd64.tar.gz
tar -xvzf frp_0.61.1_linux_amd64.tar.gz
# Для удобства переименуем папку
mv frp_0.61.1_linux_amd64 frp

Шаг 2: Настройка сервера "Сервер Б" (Стабильный) — FRPS

Здесь нам нужен файл конфигурации frps.toml (Server).

Отредактируйте конфиг: mcedit frps.toml
Вставь следующее:

bindPort = 7000       # Порт, по которому "Сервер А1" будет стучаться к "Сервер Б"

[auth]
token = "<секретный_токен_связи>"
                                                                                                                                                                                                                  
[webServer]                                                                                                                                                                                                       
addr = "0.0.0.0"                                                                                                                                                                                                  
port = 7500
user = "admin"
password = "<пароль_админа>"

Секретный токен связи можно создать командой

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

Запуск:

./frps -c frps.toml

(Если всё ок, панель будет доступна по адресу http://IP_SERVER_B:7500).

Шаг 3: Настройка "Сервер А1" (Проблемный) — FRPC

Здесь нам нужен файл frpc.toml (Client).

Отредактируйте конфиг: mcedit frpc.toml
Вставьте следующее:

serverAddr = "<IP_SERVER_B>"
serverPort = 7000

[auth]
token = "секретный_токен_связи"   # Должен совпадать с тем, что на "Сервер Б"

[[proxies]]
name = "ssh-tunnel"   # Имя выбирайте любое, чтобы отличать по именам сервера
type = "tcp"
localIP = "127.0.0.1"
localPort = 22                # Локальный SSH
remotePort = 2222        # Порт, который откроется на "Сервер Б" для входа

Внимание!

localPort = 22 Это для стандартных случаев.
Посмотрите, на каком порту работает ssh вашего сервера, и вставьте нужный номер порта.

Запуск:

./frpc -c frpc.toml

Шаг 4: Автоматизация (Systemd)

Чтобы всё работало само после перезагрузки, создадим сервисы.

На Сервере Б (Server):
Создай файл /etc/systemd/system/frps.service:

[Unit]
Description=FRP Server
After=network.target

[Service]
Type=simple
User=USER
Restart=on-failure
RestartSec=5s
ExecStart=/home/USER/frp/frps -c /home/USER/frp/frps.toml

[Install]
WantedBy=multi-user.target

Вместо USER вставьте имя пользователя, от которого запускается FRPS

На Сервере А1 (Client):
Создайте файл /etc/systemd/system/frpc.service:

[Unit]
Description=FRP Client
After=network-online.target

[Service]
Type=simple
User=USER
ExecStart=/home/USER/frp/frpc -c /home/USER/frp/frpc.toml
Restart=always
RestartSec=10s

[Install]
WantedBy=multi-user.target

Вместо USER вставьте имя пользователя, от которого запускается FRPC

Не забудьте прописать полные пути к бинарникам и конфигам! После этого:

sudo systemctl daemon-reload
sudo systemctl enable --now frps  # На сервере "Сервер Б"

sudo systemctl daemon-reload
sudo systemctl enable --now frpc  # На сервере "Сервер А1"

Как пользоваться?

Теперь, чтобы попасть на Сервер А1, вам достаточно подключиться к Серверу Б на порт 2222:

ssh user_A1@IP_SERVER_B -p 2222

Внимание!
Вводите пароль именно для сервера "Сервер А1"

Почему FRP лучше Autossh в данном конкретном случае?

Авто-переподключение: FRP гораздо «умнее» восстанавливает сессии при смене IP.
Веб-панель: Вы всегда видите в браузере, подключен ли "Сервер А1" прямо сейчас.
Масштабируемость: Захотите пробросить веб-сайт или базу данных — просто добавляете пару строк в frpc.toml без перезапуска SSH-процессов.

Чтобы зайти в веб-интерфейс:
Откройте в браузере http://<IP_СЕРВЕРА_Б>:7500. Вы увидите в разделе "Proxies -> TCP", что туннель ssh-tunnel активен (Online).

Admin

Задача - сделать обратный туннель наподобие autossh, чтобы был постоянный доступ к серверу, у которого временно "слетел" внешний ip-адрес, или случайно заблокированы файрволом порты, необходимые для прямого доступа к серверу извне. При этом, исходящий трафик не заблокирован, то есть доступ в интернет у сервера есть.
Назовём этот сервер "Сервер А1".

Для этого нужен второй сервер, не имеющий проблем с прямым доступом. Этот сервер обозначим как "Сервер Б".
К серверу "Сервер Б" можно подключать не только "Сервер А1", но и "Сервер А2", "Сервер А3", и так далее.

Важный нюанс:
Когда вы подключаетесь через FRP, вы фактически идете по цепочке:

Ваш компьютер -> Сервер Б -> Туннель FRP -> Сервер А1 (порт 22).

Admin

FRP — это быстрый обратный прокси-сервер, позволяющий сделать локальный сервер, расположенный за NAT или брандмауэром, доступным из интернета. В настоящее время он поддерживает протоколы TCP и UDP, а также HTTP и HTTPS, что позволяет перенаправлять запросы к внутренним сервисам через доменное имя.

Что умеет: Пробрасывает TCP, UDP, HTTP и HTTPS.
Веб-интерфейс: У него есть встроенный Dashboard (на порту 7500 по умолчанию), где можно смотреть состояние всех туннелей, трафик и ошибки.
Плюс: Очень легкий, работает на одном конфиг-файле (.toml).
Сложность: Низкая (похоже на настройку SSH, но удобнее).

Admin

Справочник по Matrix Synapse (Пункты 301–374)

Сборный: сетевые проблемы в контейнерах, продвинутая диагностика, API, сравнение установок и практические советы

Incus/LXD, Docker и Сетевые Конфликты

Incus/LXD создает изолированную сеть для контейнеров, что приводит к двойному NAT (Double NAT) и усложняет прохождение WebRTC-трафика.
В отличие от нативной установки, в контейнере Incus сервис (Synapse/Coturn) видит только свой внутренний IP (например, 10.214.97.46), а не реальный внешний IP хоста.
Это требует обязательной настройки external-ip в Coturn в формате external-ip=ВНЕШНИЙ_IP/ВНУТРЕННИЙ_IP (например, external-ip=91.221.70.18/10.214.97.46).
Docker и Incus на одном хосте часто конфликтуют, так как оба активно управляют цепочками iptables, вставляя свои правила в самый верх.
Конфликт с Jitsi — частая проблема, так как Jitsi Videobridge по умолчанию использует порт 10000 UDP и может перехватывать трафик, предназначенный для Matrix.
Проверить, какие UDP-порты заняты Docker-контейнерами, можно командой: sudo ss -lupn | grep docker-proxy.
Чтобы избежать конфликтов, необходимо разносить диапазоны портов для разных сервисов (например, Jitsi — 10000, Matrix — 49152-65535).
При использовании Incus стандартные пробросы портов через incus config device add неэффективны для больших диапазонов UDP, требуется прямое вмешательство в iptables на хосте.
Правила iptables, добавленные вручную, живут только в памяти и исчезают после перезагрузки, если их не сохранить.
Команда для сохранения правил iptables: sudo netfilter-persistent save (требуется пакет iptables-persistent).
Просмотр сохраненных правил: cat /etc/iptables/rules.v4.

Глубокая Диагностика Сети и Пакетов

Если tcpdump внутри контейнера показывает входящие пакеты от клиента, а Coturn в логах молчит — значит, Coturn отклоняет пакеты на уровне приложения.
Самая частая причина такого молчания — блокировка подсети клиента через директиву denied-peer-ip в turnserver.conf.
Для контейнеров с IP в диапазоне 10.x.x.x критически важно закомментировать строку denied-peer-ip=10.0.0.0-10.255.255.255.
Пакеты могут "стучаться" в порт 3478, но Coturn не считает их валидными STUN-запросами из-за несовпадения realm или отсутствия fingerprint.
Ошибка "401 Unauthorized" в логах Coturn при попытке звонка — явный признак несовпадения static-auth-secret в Coturn и turn_shared_secret в Synapse.
Для детальной диагностики WebRTC-соединения в браузере (Element) нужно открыть инструменты разработчика (F12) и изучить вкладку "Network" и "Console".
Поиск в консоли по словам "ICE", "TURN", "STUN" покажет, какие серверы пытается использовать клиент.
Если в консоли нет упоминаний вашего TURN-сервера, значит Synapse не отдал клиенту его настройки (проблема в секции turn_uris).
Команда для проверки, что Synapse "видит" свой TURN-сервер изнутри контейнера: curl http://localhost:8008/_matrix/client/versions (это не проверит TURN, но проверит работу Synapse).

API Администратора (Практические Примеры)

Получение короткого токена администратора одной строкой (замените admin и password
TOKEN=$(curl -s -X POST "http://localhost:8008/_matrix/client/r0/login" -H "Content-Type: application/json" -d '{"type":"m.login.password","user":"admin","password":"ПАРОЛЬ"}' | jq -r '.access_token')
Создание алиаса для удобного получения токена:
alias matrix-token='curl -s -X POST http://localhost:8008/_matrix/client/r0/login -d '\''{"type":"m.login.password","user":"admin","password":"ваш_пароль"}'\'' | jq -r .access_token'
Получение списка всех комнат на сервере (осторожно, может быть много):
curl -s "http://localhost:8008/_synapse/admin/v1/rooms?limit=100" -H "Authorization: Bearer $TOKEN" | jq '.rooms[].room_id'
Удаление комнаты (очистка данных):
curl -X DELETE "http://localhost:8008/_synapse/admin/v1/rooms/!room_id:domain" -H "Authorization: Bearer $TOKEN"
Получение статистики по медиафайлам:
curl -s "http://localhost:8008/_synapse/admin/v1/statistics" -H "Authorization: Bearer $TOKEN" | jq .
Просмотр активных сессий пользователя:
curl -s "http://localhost:8008/_synapse/admin/v1/whois/@user:domain" -H "Authorization: Bearer $TOKEN" | jq .devices
Блокировка сервера на уровне федерации (Server ACL) через API — сложная задача, проще через интерфейс комнаты.
Сброс пароля пользователя через API одной командой (функция оболочки):

```
matrix-passwd() {
  TOKEN=$(matrix-token)
  curl -X PUT "http://localhost:8008/_synapse/admin/v2/users/$1" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d "{\"password\": \"$2\"}"
}
```

Сравнение Способов Установки

Нативная установка (Debian/Ubuntu) — максимальная простота, лучшая производительность, легкая интеграция с Coturn, но "засоряет" систему и сложнее в изоляции.
Установка в Docker — хорошая изоляция, легкие обновления, но сложнее с пробросом UDP-портов и работой WebRTC.
Установка в Incus/LXD — отличная изоляция, удобные снапшоты, но самые большие проблемы с WebRTC из-за двойного NAT.
YunoHost — максимальная простота для новичков, все работает "из коробки", включая звонки, но меньше гибкости и контроля.
Вывод: для продакшена с видео/звонками лучше всего подходит нативная установка на хост. Контейнеры хороши для тестов и изолированных сред без VoIP.

Проблемы с PostgreSQL и Базами Данных

Проверить, использует ли Synapse PostgreSQL, можно командой ss -antp | grep 5432 | grep python. Наличие ESTAB соединений — признак использования PostgreSQL.
Если в логах нет ошибок, но база данных не растет, возможно, Synapse все еще пишет в SQLite. Проверьте дату изменения файла /var/lib/matrix-synapse/homeserver.db.
Конфликт между настройками БД в homeserver.yaml и conf.d/ может привести к тому, что Synapse не запустится с ошибкой Duplicate key.
При миграции с SQLite на PostgreSQL дамп SQLite требует ручной корректировки (удаление команд, специфичных для SQLite, например, BEGIN TRANSACTION может дублироваться).
Параметр cp_min и cp_max в конфиге БД управляют размером пула соединений. Для больших серверов cp_max можно увеличить до 20-30.

Практические Команды Администратора (Продолжение)

Быстрый просмотр последних ошибок в логах Synapse:
journalctl -u matrix-synapse -n 50 -f | grep -i error
Проверка, слушает ли Coturn нужные порты внутри контейнера:
ss -ulnp | grep 3478 (UDP) и ss -tlnp | grep 3478 (TCP).
Проверка версии Synapse из командной строки:
dpkg -l | grep matrix-synapse (для пакетной установки) или docker exec synapse pip show matrix-synapse.
Просмотр переменных окружения внутри контейнера Docker:
docker exec synapse env.
Интерактивный вход в контейнер Docker:
docker exec -it synapse /bin/bash.
Просмотр логов конкретного контейнера Docker с временными метками:
docker logs -t synapse.
Остановка всех контейнеров Docker разом (для теста конфликтов):
docker stop $(docker ps -q).
Поиск файлов конфигурации Coturn:
find / -name "turnserver.conf" 2>/dev/null.
Просмотр открытых файлов процессом Coturn:
lsof -p $(pgrep turnserver).

Теория NAT и WebRTC (Почему это сложно)

STUN позволяет клиенту узнать свой внешний IP и порт, чтобы сообщить их собеседнику для прямого соединения.
TURN используется, когда прямое соединение невозможно (симметричный NAT, корпоративные файерволы). Сервер ретранслирует трафик.
ICE — это протокол, который собирает все возможные кандидаты (STUN, TURN, локальные адреса) и пытается установить соединение, перебирая их.
В контейнере Incus Coturn видит только свой внутренний IP (10.214.97.46). Без external-ip он сообщит клиенту именно его, и клиент не сможет подключиться.
Эффект "пробитого NAT" (UDP Hole Punching) — когда после успешного прохождения одного пакета NAT "запоминает" маршрут и временно открывает его для обратного трафика.
Именно поэтому иногда "вчера не работало, а сегодня работает": таблица трансляции адресов (conntrack) могла очиститься или, наоборот, зафиксировать успешный проход.

Разное Важное

При использовании внешнего реверс-прокси (Nginx) в конфиге Synapse обязателен параметр x_forwarded: true в секции listeners.
Для корректной работы федерации server_name в Synapse должен быть именно доменом, а не поддоменом (если вы хотите короткие ID @user:domain.com). Иначе используйте .well-known делегирование.
Параметр max_upload_size измеряется в байтах. 50M = 50 * 1024 * 1024 = 52428800.
При изменении server_name на уже работающем сервере все существующие пользователи и комнаты "сломаются", так как их ID привязаны к старому имени.
Synapse поддерживает ротацию логов. Настройки ротации находятся в /etc/logrotate.d/matrix-synapse.
Для мониторинга можно использовать готовый дашборд Grafana для Synapse (например, из официального репозитория).
Ошибка "Connection refused" при попытке curl с хоста в контейнер почти всегда означает, что сервис внутри контейнера слушает только 127.0.0.1, а не 0.0.0.0.
Команда для изменения bind_addresses в Synapse внутри контейнера: отредактировать файл в /conf.d/ или изменить основной конфиг.
Файл /etc/matrix-synapse/conf.d/server_name.yaml создается автоматически при установке из пакета и содержит только server_name: "ваш.домен".
Не рекомендуется редактировать этот файл, если вы уже указали домен при установке. Для изменения домена проще переустановить сервер.
Параметр enable_registration_captcha включает капчу при регистрации. Требует настройки ReCaptcha от Google.
Для использования капчи нужно получить ключи на сайте Google ReCaptcha и указать их в конфиге.
Модули Synapse (spam checker, 3pid providers) расширяют функциональность сервера и настраиваются в секции modules.
Официальная документация Synapse — лучший источник информации: https://element-hq.github.io/synapse/latest/.
Сообщество Matrix в Telegram (@matrix_ru) — отличное место для получения помощи на русском языке.

Итоговые проверки работоспособности

Финальная проверка федерации без внешних тестеров: с одного сервера пригласить пользователя с другого сервера и отправить сообщение.
Финальная проверка звонков: позвонить с пользователя на одном сервере пользователю на другом сервере.
Проверка логирования: убедиться, что логи пишутся и не забивают диск.
Проверка автоматического запуска: systemctl is-enabled matrix-synapse и systemctl is-enabled coturn.
Проверка открытых портов снаружи: использовать онлайн-сервисы вроде yougetsignal.com или portchecker.co.
Проверка валидности SSL-сертификата: openssl s_client -connect matrix.domain.com:443 -servername matrix.domain.com < /dev/null 2>/dev/null | openssl x509 -text | grep -A2 Validity.

Admin

Справочник по Matrix Synapse (Пункты 201–300)

Глубокая настройка федерации

Для федерации через порт 443 (вместо 8448) используется делегирование через .well-known/matrix/server.
Альтернативный метод делегирования — SRV-запись в DNS: _matrix._tcp.domain.com. 3600 IN SRV 10 0 443 matrix.domain.com.
SRV-запись имеет приоритет перед .well-known, но сложнее в настройке.
Если федерация не работает, проверьте, что порт 443 открыт для входящих соединений из любых IP-адресов.
Другие серверы Matrix подключаются к вашему серверу по протоколу HTTPS и ожидают валидный SSL-сертификат.
Ошибка "Certificate signed by unknown authority" означает, что сертификат не доверенный (самоподписанный).
Ошибка "Connection refused" означает, что порт 443 закрыт файерволом или сервис не слушает.
Ошибка "401 Unauthorized" при федерации возникает из-за проблем с подписью ключей или неверным server_name.
Параметр federation_verify_dns (по умолчанию true) заставляет Synapse проверять SRV-записи при федерации.
federation_client_minimum_version позволяет задать минимальную версию протокола для федерации.
Для отладки федерации включите логирование на уровень DEBUG в log.yaml для модуля synapse.federation.

Мосты (Bridges)

Мосты позволяют подключать к Matrix другие мессенджеры: Telegram, WhatsApp, Signal, Slack, Discord и др.
Мосты обычно запускаются как отдельные сервисы (часто в Docker) и подключаются к Synapse через API.
Самый популярный мост для Telegram — mautrix-telegram.
Для установки моста требуется отдельный домен (обычно telegram.domain.com или bridge.domain.com).
Мосты часто используют собственные базы данных (SQLite/PostgreSQL) и могут потреблять много ресурсов.
При настройке моста необходимо создать в Synapse специального пользователя для моста (например, @telegrambot:domain.com).
В конфиге Synapse может потребоваться добавление моста в federation_domain_whitelist, если он настроен на отдельном домене.
Логи мостов обычно хранятся отдельно и помогают диагностировать проблемы с доставкой сообщений.
После настройки моста пользователи могут приглашать контакт моста в комнату для связи с внешним мессенджером.

Интеграция с SSO (OIDC/LDAP)

Synapse поддерживает Single Sign-On (SSO) через OpenID Connect (OIDC).
Это позволяет входить в Matrix, используя учетные записи Google, GitHub, Keycloak или корпоративного провайдера.
Настройка OIDC производится в секции oidc_providers конфигурации Synapse.
Пример настройки для Keycloak:

```yaml
oidc_providers:
  - idp_id: keycloak
    idp_name: "Keycloak"
    issuer: "https://keycloak.domain.com/realms/myrealm"
    client_id: "matrix-client"
    client_secret: "secret"
    scopes: ["openid", "profile", "email"]
    user_mapping_provider:
      config:
        localpart_template: "{{ user.preferred_username }}"
        display_name_template: "{{ user.name }}"
        email_template: "{{ user.email }}"
```

При использовании SSO регистрация новых пользователей происходит автоматически при первом входе (если включена).
LDAP-аутентификация также поддерживается через модуль matrix-synapse-ldap3.
Установка модуля LDAP: pip install matrix-synapse-ldap3 или через пакетный менеджер (если доступен).
Настройка LDAP требует указания URI сервера, базы поиска (base DN) и фильтров для поиска пользователей.
При использовании LDAP пароли не хранятся в Synapse, а проверяются напрямую у LDAP-сервера.

Пространства (Spaces)

Spaces (пространства) — это способ организации комнат в иерархические структуры (аналог серверов в Discord).
Spaces v2 поддерживаются начиная с Synapse 1.121+.
Пространства могут быть публичными (видны всем) или приватными.
Для создания пространства используется клиент Element (или другой, поддерживающий Spaces).
API для управления пространствами доступно администраторам для массового создания/удаления.
Пространства могут содержать другие пространства, создавая древовидную структуру.

Голосовые и видеозвонки (WebRTC)

WebRTC использует ICE (Interactive Connectivity Establishment) для поиска пути между клиентами.
STUN-сервер помогает клиентам узнать свой внешний IP-адрес.
TURN-сервер ретранслирует трафик, если прямое соединение невозможно.
В конфиге Synapse для TURN указывается несколько URI для разных протоколов (UDP, TCP, TLS).
Параметр turn_uris должен содержать полные URI: turn:turn.domain.com:3478?transport=udp.
TURN-сервер Coturn может использовать TLS на порту 5349 для защищенного соединения.
Для этого в конфиге Coturn нужно указать cert и pkey (пути к SSL-сертификатам) и tls-listening-port=5349.
Клиенты автоматически выбирают наиболее эффективный путь (P2P если возможно, иначе через TURN).
WebRTC требует открытого диапазона UDP-портов для медиа-трафика (обычно 49152-65535).
Если звонки не работают, проверьте, что клиенты получают правильные turn_uris (через F12 в Element).
Для тестирования TURN/STUN можно использовать сайт https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/.

Шифрование (E2EE)

Matrix поддерживает сквозное шифрование (E2EE) по умолчанию для приватных комнат.
Шифрование основано на протоколе Olm и Megolm.
Ключи шифрования хранятся на клиентах пользователей, сервер не имеет доступа к содержимому сообщений.
Для восстановления доступа к зашифрованным сообщениям используется механизм "key backup" (резервное копирование ключей).
Резервное копирование ключей может быть защищено парольной фразой или храниться на сервере в зашифрованном виде.
При первом входе в Element клиент предложит настроить резервное копирование ключей.
Администратор не может расшифровать сообщения пользователей без их ключей.
Шифрование может быть отключено для публичных комнат, но не рекомендуется.

Модерация и управление комнатами

Администраторы комнат могут назначать модераторов (power level 50) и администраторов (power level 100).
Команды модерации в Element:
- /kick @user:domain — исключить пользователя
- /ban @user:domain — забанить пользователя
- /unban @user:domain — разбанить
- /redact <event_id> — удалить сообщение
Можно устанавливать правила комнаты (server ACLs) для блокировки определенных серверов.
Server ACLs настраиваются в конфигурации комнаты (в Element: Настройки комнаты -> Безопасность).
Для массовой модерации используется модуль Mjolnir (бота-модератора).
Mjolnir позволяет синхронизировать списки заблокированных пользователей и серверов между комнатами.
Установка Mjolnir требует отдельного сервера или контейнера и доступа к API Synapse.

Масштабирование и производительность

При росте числа пользователей (сотни и тысячи) SQLite перестает справляться — PostgreSQL обязателен.
Synapse поддерживает горизонтальное масштабирование через разделение компонентов (worker-архитектура).
Воркеры (workers) позволяют вынести обработку разных типов запросов на отдельные процессы.
Типы воркеров:
- synapse.app.generic_worker — общий воркер
- synapse.app.federation_sender — отправка федеративных событий
- synapse.app.media_repository — обслуживание медиафайлов
- synapse.app.pusher — отправка push-уведомлений
Настройка воркеров сложна и требует изменений в конфигурации Nginx и Synapse.
Для небольших установок (до 1000 пользователей) одного процесса Synapse достаточно.
Медиафайлы можно вынести на отдельное хранилище (NFS, S3) при масштабировании.
Synapse поддерживает хранение медиа в S3-совместимых хранилищах (через модуль s3-storage-provider).
Кэширование в Redis (начиная с Synapse 1.113+) значительно улучшает производительность.
Настройка Redis: указать параметры в секции redis конфигурации.

Резервное копирование и восстановление

Критически важные данные для бэкапа: база данных (PostgreSQL) и папка с медиафайлами.
Для PostgreSQL используется pg_dump:
sudo -u postgres pg_dump synapse > /backup/synapse_$(date +%Y%m%d).sql
Для восстановления: sudo -u postgres psql -d synapse < backup.sql.
Медиафайлы можно копировать через rsync или tar:
tar -czf /backup/media_$(date +%Y%m%d).tar.gz /var/lib/matrix-synapse/media
Ключ подписи сервера (homeserver.signing.key) также необходимо сохранить, иначе федерация сломается.
Автоматизацию бэкапов лучше настроить через cron.
Для инкрементального бэкапа больших медиа-хранилищ используйте rsync.
При восстановлении убедитесь, что версия Synapse совпадает с той, на которой был сделан бэкап (из-за миграций БД).
Тестируйте восстановление на тестовом сервере, чтобы убедиться в целостности бэкапов.

Мониторинг и алертинг

Synapse предоставляет метрики в формате Prometheus на порту 9000 (если включено).
Включение метрик: добавить enable_metrics: true и открыть порт в listeners.
Пример listeners для метрик:

```yaml
listeners:
  - port: 9000
    type: metrics
    bind_addresses: ['127.0.0.1']
```

Метрики доступны по URL: http://localhost:9000/_synapse/metrics.
Prometheus может собирать эти метрики, а Grafana — отображать дашборды.
Ключевые метрики для мониторинга:
- Количество активных пользователей
- Количество отправленных сообщений
- Время отклика API
- Использование памяти и CPU
- Размер базы данных
Для мониторинга логов можно использовать Loki или Elasticsearch.
Алертинг можно настроить в Prometheus Alertmanager для отправки уведомлений в Telegram/Slack.

Ограничения и лимиты

Максимальный размер одного сообщения (текст + вложения) ограничен max_request_size (по умолчанию 50M).
Максимальный размер загружаемого файла — max_upload_size (по умолчанию 10M, рекомендуется увеличить до 100M+).
Количество пользователей в комнате технически не ограничено, но производительность падает при тысячах участников.
Для больших комнат рекомендуется использовать архитектуру с выделенными воркерами.
Количество одновременных подключений к базе данных ограничено параметром cp_max в настройках БД.
Скорость отправки сообщений может быть ограничена параметрами rc_message, rc_login и другими.
При превышении лимитов Synape возвращает ошибки с кодом 429 (Too Many Requests).

Устаревшие настройки и миграции

Ранее Synapse использовал /opt/venvs/matrix-synapse для виртуального окружения Python. Сейчас пакеты устанавливаются системно.
Если вы видите старые пути в инструкциях (до 2024 года), они могут быть неактуальны.
Миграция со старой версии на новую обычно описывается в официальном блоге Matrix.org.
Перед обновлением всегда читайте release notes и проверяйте наличие обязательных миграций БД.
При обновлении с пропуском нескольких версий могут потребоваться промежуточные обновления.

Admin

Справочник по Matrix Synapse (Пункты 101–200)

Глубокая настройка Synapse

Параметр public_baseurl в homeserver.yaml должен быть полным URL-адресом вашего сервера (например, https://matrix.nbics.net/).
Он используется для генерации ссылок в уведомлениях по электронной почте и для других сервисов.
max_upload_size задает максимальный размер загружаемого файла (например, 100M или 2000M).
enable_registration: false отключает публичную регистрацию, позволяя создавать аккаунты только через административную утилиту.
enable_registration_without_verification: true позволяет регистрироваться без подтверждения email (опасно для публичных серверов).
registration_shared_secret — секретный ключ, используемый для регистрации новых пользователей через утилиту register_new_matrix_user.
Его нужно генерировать случайным образом (например, cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1).
Параметр rc_message позволяет ограничить скорость отправки сообщений для борьбы со спамом.

```yaml
rc_message:
  per_second: 0.2
  burst_count: 10
```

media_store_path указывает путь к хранилищу медиафайлов (обычно /var/lib/matrix-synapse/media).
signing_key_path — путь к ключу подписи сервера, используемому для федерации (/etc/matrix-synapse/homeserver.signing.key).
Ключ подписи генерируется автоматически при первой установке и НИКОГДА не должен быть скомпрометирован.
pid_file указывает путь к PID-файлу процесса Synapse (/var/run/matrix-synapse.pid).

Настройка слушателей (listeners)

Секция listeners определяет, на каких портах и интерфейсах Synapse принимает соединения.
Пример настройки для работы через reverse proxy (слушать только localhost):

```yaml
listeners:
  - port: 8008
    tls: false
    type: http
    x_forwarded: true
    bind_addresses: ['127.0.0.1', '::1']
    resources:
      - names: [client, federation]
        compress: false
```

x_forwarded: true указывает Synapse доверять заголовкам X-Forwarded-For от прокси.
Если сервер должен принимать соединения извне напрямую, bind_addresses нужно изменить на ['0.0.0.0'].
Ресурс client обслуживает клиентские запросы (логин, отправка сообщений, синхронизация).
Ресурс federation обслуживает запросы от других серверов Matrix.

Безопасность и изоляция

federation_ip_range_blacklist — список IP-диапазонов, к которым серверу запрещено подключаться (защита от SSRF-атак).
Включает приватные диапазоны (10.0.0.0/8, 192.168.0.0/16, 172.16.0.0/12 и IPv6 аналоги).
trusted_key_servers: [] делает сервер независимым от внешних серверов ключей (полезно при блокировке matrix.org).
Без списка доверенных серверов федерация работает напрямую: серверы обмениваются ключами друг с другом.
suppress_key_server_warning: true отключает предупреждение об отсутствии доверенных серверов ключей.
enable_room_list_search: false отключает публичный каталог комнат, если он не нужен.
limit_usage_by_membership позволяет ограничить использование ресурсов в зависимости от членства в комнатах.
require_auth_for_profile_requests: true требует аутентификации для запросов профиля пользователя.

Установка из пакетов Debian/Ubuntu (детали)

Пакет называется matrix-synapse-py3 (а не просто matrix-synapse).
После установки создается системный пользователь matrix-synapse, от которого запускается сервис.
Файлы конфигурации по умолчанию находятся в /etc/matrix-synapse.
Логи по умолчанию пишутся в /var/log/matrix-synapse/homeserver.log.
Настройки логирования управляются файлом /etc/matrix-synapse/log.yaml.
Для изменения уровня логирования (например, на DEBUG для отладки) нужно отредактировать log.yaml.
Встроенная команда проверки конфигурации: python3 -m synapse.app.homeserver --config-path /etc/matrix-synapse/homeserver.yaml --config-path /etc/matrix-synapse/conf.d/ --check-config.
Python для пакета может находиться в системном окружении или в виртуальном окружении по пути /opt/venvs/matrix-synapse/bin/python.

Установка в Docker (детали)

При использовании Docker данные Synapse хранятся в Docker-томе (volume) synapse-data.
Файлы конфигурации внутри контейнера находятся в /data.
Чтобы отредактировать homeserver.yaml, нужно зайти в контейнер: docker exec -it synapse /bin/bash.
Переменная окружения SYNAPSE_CONFIG_PATH указывает путь к конфигурационному файлу.
Для проброса портов при запуске используются ключи -p 8008:8008 (клиентский API) и -p 8448:8448 (федерация).
Логи Docker-контейнера смотрят командой docker logs -f synapse.
Обновление Synapse в Docker: docker pull matrixdotorg/synapse:latest && docker stop synapse && docker rm synapse && (запустить контейнер заново).
Преимущество Docker — изоляция и простота обновления (не нужно чистить конфиги).

Продвинутая диагностика

Команда для проверки, какие соединения с БД держит Synapse: ss -antp | grep python.*5432.
Множество соединений в состоянии ESTAB — это нормально (пул соединений).
Проверка версии Synapse: dpkg -l | grep matrix-synapse или docker exec synapse pip show matrix-synapse.
Проверка, какие правила iptables активны для Matrix: sudo iptables -L FORWARD -v -n | grep 10.214.97.46.
Просмотр статистики по пакетам в iptables (колонка pkts показывает, сколько пакетов прошло).
Если счетчики пакетов в iptables растут, а звонка нет — проблема внутри контейнера (Coturn).
Если счетчики не растут — проблема на хосте (Firewall, проброс портов).
Для диагностики конфликтов портов используется sudo ss -lupn | grep <порт>.

Решение проблем с конфигурацией (conf.d)

При использовании conf.d/ важно помнить, что файлы загружаются в алфавитном порядке.
Позже загруженные настройки могут переопределить более ранние.
Если в основном homeserver.yaml и в conf.d/ есть одинаковые секции, сервер может не запуститься с ошибкой Duplicate key.
Правильный подход: в основном файле оставлять только то, что нужно, а специфичные настройки выносить в conf.d/.
Для отключения какой-либо опции лучше закомментировать её во всех местах.
Файлы в conf.d/ должны иметь права на чтение для пользователя matrix-synapse.
Проверить, какие файлы из conf.d/ загружаются, можно в логах при запуске сервера (уровень INFO).

Интеграция с Coturn и WebRTC

Параметр turn_user_lifetime определяет время жизни учетных данных TURN (например, 86400000 мс или 1h).
turn_allow_guests: true разрешает гостевым пользователям использовать TURN-сервер.
В конфиге Coturn listening-ip можно указать как 0.0.0.0, чтобы слушать на всех интерфейсах.
min-port и max-port должны точно совпадать с диапазоном, проброшенным в iptables.
fingerprint в Coturn включает добавление отпечатка в пакеты STUN, что требуется некоторыми WebRTC-клиентами.
lt-cred-mech включает механизм долговременных учетных данных.
Для отладки звонков полезно включить verbose в Coturn и смотреть логи.
Если в логах Coturn появляется 401 Unauthorized, значит не совпадает static-auth-secret с turn_shared_secret в Synapse.
Если в логах пусто, а пакеты в iptables есть, скорее всего, Coturn блокирует подсеть клиента (проверить denied-peer-ip).

Настройка Element Web

Element можно разместить на отдельном поддомене (например, element.nbics.net) или на том же, что и Synapse.
Скачать последнюю версию Element: wget https://github.com/vector-im/element-web/releases/latest/download/element.tar.gz.
Распаковать архив в веб-директорию: tar -xzf element.tar.gz -C /var/www/element.
Конфигурационный файл Element — config.json в корне веб-директории.
В config.json обязательно указать base_url вашего Synapse:

```json
{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.nbics.net",
      "server_name": "nbics.net"
    }
  }
}
```

Можно отключить гостевой доступ: "disable_guests": true.
Для изменения названия бренда используется параметр "brand": "Мой Мессенджер".
Element лучше проксировать через тот же Nginx, что и Synapse, с отдельным server_name.
Для кэширования статических файлов Element в Nginx можно добавить заголовки expires 1y; add_header Cache-Control "public, immutable";.

Управление медиафайлами

Медиафайлы (изображения, видео, документы) хранятся в директории media_store_path.
Synapse автоматически создает хэш-директории внутри этой папки для хранения файлов.
Просмотр занятого места под медиа: du -sh /var/lib/matrix-synapse/media.
Удаление старых или неиспользуемых медиафайлов можно делать через API администратора.
max_image_pixels: 32M ограничивает максимальный размер изображения (в пикселях) для предотвращения DoS-атак.

API администратора (примеры)

Для использования API администратора нужен access_token пользователя с правами администратора.
Получение списка пользователей (с пагинацией):
curl -s "http://localhost:8008/_synapse/admin/v2/users?from=0&limit=100" -H "Authorization: Bearer ТОКЕН" | jq .
Получение информации о конкретном пользователе:
curl -s "http://localhost:8008/_synapse/admin/v2/users/@user:domain" -H "Authorization: Bearer ТОКЕН"
Деактивация пользователя (мягкое удаление):
curl -X PUT -H "Authorization: Bearer ТОКЕН" "http://localhost:8008/_synapse/admin/v2/users/@user:domain" -d '{"deactivated": true}'
Удаление пользователя (без возможности восстановления):
curl -X DELETE -H "Authorization: Bearer ТОКЕН" "http://localhost:8008/_synapse/admin/v1/deactivate/@user:domain"
Очистка медиафайлов пользователя:
curl -X POST -H "Authorization: Bearer ТОКЕН" "http://localhost:8008/_synapse/admin/v1/media/@user:domain/delete" -d '{"delete_profiles": true}'

Интеграция с почтой (необязательно)

Synapse может отправлять email-уведомления (например, для сброса пароля).
Для этого нужно настроить секцию email в homeserver.yaml:

```yaml
email:
  smtp_host: mail.nbics.net
  smtp_port: 587
  smtp_user: noreply@nbics.net
  smtp_pass: "пароль"
  notif_from: "Matrix <noreply@nbics.net>"
```

Email используется только для системных уведомлений, а не для регистрации (если она отключена).

Миграция с SQLite на PostgreSQL

Если изначально использовался SQLite, можно перенести данные в PostgreSQL.
Остановить Synapse: systemctl stop matrix-synapse.
Сделать дамп SQLite: sqlite3 /var/lib/matrix-synapse/homeserver.db .dump > synapse_dump.sql.
Создать базу и пользователя в PostgreSQL (как описано выше).
Импортировать дамп в PostgreSQL: sudo -u postgres psql -d synapse < synapse_dump.sql.
Важно: дамп SQLite может потребовать ручной правки (удаление строк, специфичных для SQLite).
После импорта настроить Synapse на использование PostgreSQL и перезапустить.

Безопасность и мониторинг

Регулярно обновляйте Synapse: apt update && apt upgrade matrix-synapse-py3.
Подпишитесь на рассылку безопасности Matrix.org.
Следите за логами на предмет подозрительной активности (попытки брутфорса, спам-регистрации).
Настройте автоматическое резервное копирование базы данных и папки с медиафайлами.

Admin

Справочник по Matrix Synapse (Пункты 1–100)

Основные понятия и архитектура

Matrix — это открытый, децентрализованный протокол для обмена сообщениями в реальном времени (альтернатива Telegram, Discord).
Synapse — это эталонная реализация сервера Matrix на Python, самая популярная и распространенная.
Федерация (Federation) — возможность общаться с пользователями на других серверах Matrix.
Домашний сервер (Homeserver) — сервер, на котором зарегистрирован пользователь и где хранятся его данные.
Element — самый популярный клиент (веб, мобильный, десктоп) для работы с сетью Matrix.
Coturn — TURN/STUN сервер, необходимый для голосовых и видеозвонков (WebRTC) в Matrix.

Установка Synapse (Основные способы)

Synapse можно установить из официального репозитория Matrix.org для Debian/Ubuntu.
Команда добавления ключа репозитория: 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" | tee /etc/apt/sources.list.d/matrix-org.list.
Установка Synapse из репозитория: apt install matrix-synapse-py3.
Во время установки пакет запросит server_name (домен сервера) и согласие на отправку статистики.
После установки Synapse запускается как системная служба: systemctl start matrix-synapse.
Включение автозапуска Synapse: systemctl enable matrix-synapse.
Основной конфигурационный файл Synapse: /etc/matrix-synapse/homeserver.yaml.
Для установки в Docker используется образ matrixdotorg/synapse:latest.
Генерация конфигурации для Docker: docker run -it --rm --mount type=volume,src=synapse-data,dst=/data -e SYNAPSE_SERVER_NAME=example.com matrixdotorg/synapse:latest generate.
Запуск Synapse в Docker: docker run -d --name synapse --restart unless-stopped --mount type=volume,src=synapse-data,dst=/data -p 8008:8008 matrixdotorg/synapse:latest run.

PostgreSQL вместо SQLite

Для продакшена настоятельно рекомендуется использовать PostgreSQL вместо встроенной SQLite.
Установка PostgreSQL: apt install postgresql postgresql-contrib -y.
Создание пользователя БД: sudo -u postgres psql -c "CREATE USER synapse_user WITH PASSWORD 'secure_password';".
Создание базы данных: sudo -u postgres psql -c "CREATE DATABASE synapse ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE=template0 OWNER synapse_user;".
Настройки базы данных в Synapse лучше выносить в отдельный файл в /etc/matrix-synapse/conf.d/database.yaml.

Пример конфигурации для PostgreSQL:

database:
  name: psycopg2
  args:
    user: synapse_user
    password: secure_password
    database: synapse
    host: localhost
    cp_min: 5
    cp_max: 10

Подключение Synapse к PostgreSQL можно проверить командой ss -antp | grep 5432 — должны быть ESTAB соединения с процессом python.
Проверить, что Synapse использует PostgreSQL, можно SQL-запросом: sudo -u postgres psql -d synapse -c "SELECT count(*) FROM users;".

Структура конфигурации (conf.d)

В Debian/Ubuntu пакет Synapse поддерживает модульную конфигурацию через папку /etc/matrix-synapse/conf.d/.
Все файлы с расширением .yaml в этой папке автоматически загружаются и применяются поверх основного homeserver.yaml.
Использование conf.d/ — лучшая практика, так как при обновлении пакета основной файл может быть перезаписан.
В conf.d/ рекомендуется хранить настройки базы данных, регистрации, TURN-сервера, федерации и другие специфические параметры.
Файл /etc/matrix-synapse/conf.d/server_name.yaml обычно содержит только одну строку: server_name: "ваш.домен".

Настройка Nginx в качестве Reverse Proxy

Matrix Synapse не должен быть напрямую доступен из интернета. Его проксируют через Nginx или Apache.
Synapse по умолчанию слушает на порту 8008 (localhost).
Конфигурация Nginx для проксирования должна включать передачу заголовков X-Forwarded-For и X-Forwarded-Proto.

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

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

Для работы больших файлов (вложения) нужно увеличить client_max_body_size (например, до 50M или 2000M).
Важно: в конфиге Synapse в секции listeners должен быть параметр x_forwarded: true.

SSL-сертификаты (Let's Encrypt)

Для работы федерации и безопасных клиентов обязателен валидный SSL-сертификат.
Установка Certbot для Nginx: apt install certbot python3-certbot-nginx -y.
Получение сертификата: certbot --nginx -d matrix.ваш-домен.ru.
Certbot автоматически обновляет конфигурацию Nginx, добавляя пути к сертификатам и настраивая редирект с HTTP на HTTPS.
При использовании федерации сертификат должен быть доверенным (самоподписанный не подойдет).

Настройка федерации (.well-known)

Федерация позволяет серверам Matrix обмениваться сообщениями.
Для работы федерации сервер должен корректно отвечать на запросы к /.well-known/matrix/server.
Правильный ответ должен быть JSON: {"m.server": "matrix.ваш-домен.ru:443"}.

В Nginx это настраивается через location:

location /.well-known/matrix/server {
    default_type application/json;
    return 200 '{"m.server": "matrix.ваш-домен.ru:443"}';
}

Аналогично для клиентов настраивается /.well-known/matrix/client с base_url.
Проверить федерацию можно через инструмент Matrix Federation Tester.
Если matrix.org заблокирован, можно обойтись без внешних доверенных серверов ключей, установив trusted_key_servers: [].
Для изоляции сервера (только свои домены) используется параметр federation_domain_whitelist.

Управление пользователями и паролями

Создание нового пользователя через командную строку: register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://localhost:8008.
Утилита запросит имя, пароль и подтверждение администратора.
Если утилита не видит registration_shared_secret, нужно указать путь к конфигу из conf.d/ дополнительным флагом -c.
Получение списка всех пользователей из SQLite: sudo sqlite3 /var/lib/matrix-synapse/homeserver.db "SELECT name, creation_ts FROM users;".
Получение списка пользователей из PostgreSQL: sudo -u postgres psql -d synapse -c "SELECT name, admin FROM users;".

Сброс пароля пользователя через curl (с админским токеном):

curl -X PUT -H "Authorization: Bearer ТОКЕН" "http://localhost:8008/_synapse/admin/v2/users/@user:domain" -d '{"password": "новый_пароль"}'

Получение access_token администратора:

curl -X POST "http://localhost:8008/_matrix/client/r0/login" -d '{"type":"m.login.password","user":"admin","password":"пароль"}'

Назначение пользователя администратором через API: curl -X PUT -H "Authorization: Bearer ТОКЕН" "http://localhost:8008/_synapse/admin/v2/users/@user:domain" -d '{"admin": true}'.
Деактивация пользователя: curl -X PUT -H "Authorization: Bearer ТОКЕН" "http://localhost:8008/_synapse/admin/v2/users/@user:domain" -d '{"deactivated": true}'.

Настройка TURN-сервера (Coturn) для звонков

Для голосовых и видеозвонков необходим TURN-сервер (Coturn), так как клиенты часто находятся за NAT.
Установка Coturn: apt install coturn -y.
Основной конфигурационный файл Coturn: /etc/turnserver.conf.
Генерация секретного ключа (static-auth-secret) для аутентификации: echo "static-auth-secret=$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1)" | tee /etc/turnserver.conf.

В конфиге обязательно указать:

listening-port=3478
external-ip=ВНЕШНИЙ_IP_СЕРВЕРА
realm=ваш-домен.ru

Если сервер находится в контейнере, для external-ip используется формат: external-ip=ВНЕШНИЙ_IP/ВНУТРЕННИЙ_IP.
Включение авторизации: use-auth-secret.
Важно: Не блокировать подсеть сервера. Если сервер в сети 10.x.x.x, нужно закомментировать или удалить строку denied-peer-ip=10.0.0.0-10.255.255.255.
Запрет на использование TCP-релея (no-tcp-relay) лучше отключить (закомментировать) для надежности.
Указание диапазона портов для медиа-трафика: min-port=49152 и max-port=65535.
Включение подробного логирования: verbose и fingerprint.

Настройка в Synapse (homeserver.yaml):

turn_uris:
  - "turn:ваш-домен.ru:3478?transport=udp"
  - "turn:ваш-домен.ru:3478?transport=tcp"
turn_shared_secret: "ВАШ_СЕКРЕТ"
turn_user_lifetime: 1h
turn_allow_guests: true

Для работы звонков в контейнере Incus/LXD необходим проброс UDP-портов через iptables на хосте.

Команды для проброса портов (на хосте):

iptables -t nat -I PREROUTING -p udp --dport 3478 -j DNAT --to-destination IP_КОНТЕЙНЕРА:3478
iptables -t nat -I PREROUTING -p udp --dport 49152:65535 -j DNAT --to-destination IP_КОНТЕЙНЕРА
iptables -I FORWARD -p udp -d IP_КОНТЕЙНЕРА --dport 3478 -j ACCEPT
iptables -I FORWARD -p udp -d IP_КОНТЕЙНЕРА --dport 49152:65535 -j ACCEPT

Сохранение правил iptables после перезагрузки: apt install iptables-persistent и netfilter-persistent save.

Диагностика и логи

Просмотр логов Synapse: journalctl -u matrix-synapse -f.
Поиск ошибок в логах: journalctl -u matrix-synapse -n 100 | grep -i error.
Проверка статуса сервера: systemctl status matrix-synapse.
Проверка, на каких интерфейсах и портах слушает Synapse: ss -tlnp | grep 8008.
Проверка, слушает ли Coturn: ss -ulnp | grep 3478.
Просмотр логов Coturn: journalctl -u coturn -f.
В логах Coturn при успешном звонке должны появляться записи allocate request или success.
Мониторинг трафика в реальном времени на хосте: tcpdump -n -i any udp port 3478.
Проверка активных соединений к PostgreSQL: ss -antp | grep 5432.
Проверка валидности конфигурации Synapse без запуска: /usr/bin/python3 -m synapse.app.homeserver --config-path /etc/matrix-synapse/homeserver.yaml --config-path /etc/matrix-synapse/conf.d/ --check-config.
Проверка доступности TURN-сервера извне через онлайн-инструменты (например, Trickle ICE).

Решение проблем

Ошибка [] is not of type 'string': возникает при неверном синтаксисе trusted_key_servers: []. Нужно закомментировать всю секцию.
Нет звука/видео: 90% проблема в неработающем TURN-сервере или закрытых UDP-портах (3478, 49152-65535).
Приглашение висит, но чат не создается: проблема в федерации, проверьте .well-known и открытый порт 443.
Ошибка Unable to connect to server при curl с хоста в контейнер: сервис слушает только 127.0.0.1, нужно изменить bind_addresses на 0.0.0.0.
Дублирование ключей (Duplicate key) в конфиге: настройка прописана и в основном файле, и в conf.d/. Оставить только в одном месте.
Конфликт с Jitsi или другими сервисами: используют общие UDP-порты, нужно разносить диапазоны (Jitsi — 10000, Matrix — 49152+).
Пакеты в iptables есть, но Coturn молчит: Coturn блокирует подсеть через denied-peer-ip (особенно 10.x.x.x).
Сервер не запускается после изменения конфига: проверьте синтаксис YAML (отступы важен!).
Бесконечное «Устанавливается соединение» при звонке: TURN-сервер не отвечает или ключи не совпадают.
Регистрация не работает: проверьте enable_registration и наличие registration_shared_secret.
Федерация не работает с matrix.org (блокировка): удалите matrix.org из trusted_key_servers и оставьте пустой список [].

Полезные команды и алиасы

Просмотр всех пользователей с датой регистрации:
sudo sqlite3 /var/lib/matrix-synapse/homeserver.db "SELECT name, datetime(creation_ts,'unixepoch') FROM users WHERE is_deactivated = 0;".
Количество активных пользователей: alias matrix-count="sudo sqlite3 /var/lib/matrix-synapse/homeserver.db \"SELECT count(*) FROM users WHERE is_deactivated = 0;\"".
Список администраторов: alias matrix-admins="sudo sqlite3 /var/lib/matrix-synapse/homeserver.db \"SELECT name FROM users WHERE is_admin = 1;\"".
Быстрая проверка логов звонков: journalctl -u coturn -f | grep -E "success|error|allocate".
Путь к основным каталогам Synapse:
* Конфигурация: /etc/matrix-synapse/
* База данных SQLite: /var/lib/matrix-synapse/homeserver.db
* Медиафайлы: /var/lib/matrix-synapse/media/
* Логи: /var/log/matrix-synapse/homeserver.log

Admin

Справочник по установке, настройке и эксплуатации Mailcow (Пункты 101–200)

Docker и управление контейнерами

docker compose exec <имя_контейнера> <команда> позволяет выполнить команду внутри работающего контейнера.
Пример: sudo docker compose exec mysql-mailcow mysql -u${DBUSER} -p${DBPASS} ${DBNAME} проверяет подключение к базе данных.
Контейнер nginx-mailcow выступает в роли обратного прокси внутри стека Mailcow для всех веб-сервисов.
Контейнер php-fpm-mailcow обрабатывает PHP-логику веб-интерфейса Mailcow.
Контейнер mysql-mailcow (MariaDB) хранит все настройки, домены, пользователей и пароли.
Контейнер dovecot-mailcow отвечает за доставку писем в ящики пользователей (IMAP/POP3).
Контейнер postfix-mailcow — это MTA (Mail Transfer Agent), принимающий и отправляющий почту.
Контейнер rspamd-mailcow — мощная система фильтрации спама и проверки писем.
Контейнер clamd-mailcow — антивирус, проверяющий вложения на вредоносный код.
Контейнер unbound-mailcow — локальный DNS-резолвер для повышения производительности и безопасности.
Контейнер redis-mailcow используется для кэширования и очередей задач.
Контейнер sogo-mailcow предоставляет веб-почту (Roundcube) и CalDAV/CardDAV функционал.
Контейнер acme-mailcow автоматически получает и обновляет SSL-сертификаты Let's Encrypt.
Контейнер watchdog-mailcow отслеживает состояние других контейнеров и перезапускает упавшие.
Контейнер netfilter-mailcow управляет правилами файервола внутри Docker-сети.

Проблемы с сетью и портами

Ошибка failed to bind host port for 0.0.0.0:443: address already in use означает, что порт 443 занят.
Для освобождения порта 443 нужно остановить сервис, который его занимает (nginx, apache, другой Docker-контейнер).
При использовании внешнего прокси порты 80 и 443 на хосте должны принадлежать прокси, а не Mailcow.
В этом случае в файле .env нужно указать альтернативные порты для Mailcow, например HTTP_PORT=8080 и HTTPS_PORT=8443.
Команда sudo ss -tulpn | grep 443 показывает все процессы, использующие порт 443 с их PID.
Если порт занят процессом с PID 1 (systemd), значит служба настроена на системном уровне.
После изменения портов в .env может потребоваться полный перезапуск: docker compose down && docker compose up -d.
Конфликт портов может возникнуть не только с внешними сервисами, но и с другими контейнерами Docker.
Для просмотра всех Docker-сетей используется команда docker network ls.
Для детальной информации о сети: docker network inspect <имя_сети>.
Стандартная сеть Docker bridge использует подсеть 172.17.0.0/16, что может конфликтовать с Mailcow.
Если несколько проектов Docker Compose используют одинаковые подсети, возникает конфликт.
Решение конфликта сетей — изменить IPV4_NETWORK в .env на уникальный диапазон.

Настройка внешнего Nginx (Reverse Proxy)

Внешний Nginx должен быть настроен на проксирование трафика на внутренние порты Mailcow.
Для HTTP-трафика: proxy_pass http://127.0.0.1:8080; (если HTTP_PORT=8080).
Для HTTPS-трафика: proxy_pass http://127.0.0.1:8080; также, так как SSL терминируется на внешнем Nginx.
Заголовок proxy_set_header X-Forwarded-Proto https; критически важен для правильной работы Mailcow за прокси.
Без этого заголовка Mailcow будет думать, что все запросы идут по HTTP, и пытаться редиректить на HTTPS.
Заголовок proxy_set_header Host $host; сохраняет оригинальное имя хоста при проксировании.
Заголовок proxy_set_header X-Real-IP $remote_addr; передает реальный IP-адрес клиента.
Для поддержки WebSocket (нужен SOGo для уведомлений) необходимы настройки:
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
Директива client_max_body_size 0; отключает ограничение на размер загружаемых файлов (важно для вложений).
В конфиге внешнего Nginx должен быть отдельный блок server для порта 80 с редиректом на HTTPS.
Редирект делается директивой return 301 https://$host$request_uri;.
Без этого редиректа пользователи, заходящие по HTTP, будут видеть ошибки или страницу Mailcow без стилей.

Certbot и SSL-сертификаты

Certbot — это клиент Let's Encrypt для автоматического получения и обновления SSL-сертификатов.
Команда sudo certbot --nginx автоматически получает сертификат и настраивает Nginx.
При первом запуске Certbot создает временный файл в /.well-known/acme-challenge/ для проверки домена.
Для этого порт 80 должен быть открыт и доступен из интернета.
Если Certbot находит существующий сертификат, он предлагает опции: переустановить или обновить.
Выбор 2: Renew & replace the certificate гарантирует получение свежего сертификата и обновление конфига.
Certbot автоматически добавляет в конфиг Nginx строки ssl_certificate и ssl_certificate_key.
Также добавляются include /etc/letsencrypt/options-ssl-nginx.conf; и ssl_dhparam....
Ошибка "We were unable to restart web server" означает, что Certbot не смог перезапустить Nginx из-за ошибок в конфиге.
В этом случае нужно исправить конфиг Nginx вручную и выполнить sudo certbot install --cert-name <домен>.
Сертификаты Let's Encrypt действительны 90 дней, Certbot автоматически их обновляет через cron/systemd timer.
После обновления сертификата Nginx перезагружается для применения новых сертификатов.

Диагностика и отладка

sudo docker compose logs -f <контейнер> позволяет следить за логами в реальном времени (аналог tail -f).
sudo docker compose logs --tail=50 mysql-mailcow показывает последние 50 строк логов MySQL.
Лог-сообщение mariadbd: ready for connections. означает, что MySQL готов к работе.
Циклическое повторение Waiting for SQL... в логах PHP-FPM указывает на проблемы с подключением к MySQL.
Ошибка connect() failed (111: Connection refused) в логах Nginx означает, что бэкенд (PHP-FPM) не отвечает.
Команда sudo docker compose restart <контейнер> перезапускает конкретный контейнер.
sudo docker compose restart nginx-mailcow перезапускает только Nginx, что полезно после изменения конфигов.
Проверка доступности порта изнутри контейнера: docker exec -it <контейнер> nc -zv 127.0.0.1 <порт>.
Для проверки DNS внутри контейнера: docker exec -it <контейнер> dig google.com.
Логирование ошибок PHP можно включить в конфигурации PHP-FPM, монтируя файл логов.
Все контейнеры Mailcow используют один и тот же внутренний часовой пояс из переменной TZ.

Настройка DNS и почтовые протоколы

Помимо веб-интерфейса, Mailcow использует стандартные почтовые порты: 25 (SMTP), 465 (SMTPS), 587 (Submission).
IMAP (для чтения почты) работает на портах 143 (STARTTLS) и 993 (SSL/TLS).
POP3 (устаревший протокол) работает на портах 110 и 995.
Sieve (для фильтрации почты) работает на порту 4190.
Для нормальной работы почты эти порты должны быть открыты в файерволе сервера.
Проверить доступность порта извне можно на mxtoolbox.com (Diagnostics -> SMTP Test).
При использовании внешнего прокси, почтовые порты должны быть открыты напрямую на сервере (прокси их не трогает).
SUBMISSION_PORT=587 в .env позволяет изменить стандартный порт для отправки почты клиентами.
SMTPS_PORT=465 — порт для устаревшего SMTPS (не путать с STARTTLS на порту 587).
IMAPS_PORT=993 и POP3S_PORT=995 — защищенные версии протоколов доступа к почте.
Для каждого добавленного почтового домена нужно настроить отдельные DNS-записи (MX, SPF, DKIM, DMARC).
DKIM-ключи генерируются отдельно для каждого домена в панели Mailcow.
Селектор DKIM по умолчанию в Mailcow — dkim (запись выглядит как dkim._domainkey.domain.tld).
DMARC-политика p=quarantine рекомендована для начальной настройки, p=reject — для полной защиты.
Адрес для DMARC-отчетов (rua=mailto:...) должен существовать и быть доступным.

Безопасность

Встроенный watchdog (USE_WATCHDOG=y) автоматически перезапускает упавшие контейнеры.
WATCHDOG_NOTIFY_EMAIL позволяет настроить отправку уведомлений о проблемах на email.
WATCHDOG_NOTIFY_BAN включает уведомления о забаненных IP-адресах.
WATCHDOG_EXTERNAL_CHECKS=n отключает внешние проверки на open relay (по умолчанию выключено).
Переменная SKIP_CLAMD=n включает антивирус ClamAV (рекомендуется, но требует ресурсов).
SKIP_SOGO=n включает веб-почту SOGo (рекомендуется оставить включенным).
SKIP_FTS=n включает полнотекстовый поиск в Dovecot (полезно, но нагружает сервер).
FTS_HEAP=128 ограничивает память для индексации писем (можно увеличить при наличии ресурсов).
FTS_PROCS=1 ограничивает количество процессов индексации (можно увеличить на мощных серверах).
ALLOW_ADMIN_EMAIL_LOGIN=n запрещает администраторам входить в почтовые ящики пользователей без пароля.
ACL_ANYONE=disallow запрещает создание общих папок для всех аутентифицированных пользователей.
ENABLE_SSL_SNI=n отключает поддержку отдельных сертификатов для разных доменов (если не нужно).
ENABLE_IPV6=false отключает IPv6 (если не настроен на сервере).

Почтовые ящики и квоты

MAILDIR_GC_TIME=7200 определяет время (в минутах) хранения удаленных ящиков в корзине (здесь 5 дней).
MAILDIR_SUB=Maildir — стандартное имя директории для хранения писем в формате Maildir.
SOGO_EXPIRE_SESSION=480 — время сессии в веб-почте SOGo в минутах (480 = 8 часов).
SOGO_URL_ENCRYPTION_KEY — ключ шифрования для URL в SOGo (генерируется автоматически).
DOVECOT_MASTER_USER и DOVECOT_MASTER_PASS — мастер-аккаунт для доступа к любым ящикам (использовать осторожно).
LOG_LINES=9999 — количество сохраняемых строк логов в Redis для каждого сервиса.
SPAMHAUS_DQS_KEY — ключ для Spamhaus Data Query Service (если ваш IP в заблокированной ASN).

API и автоматизация

Mailcow имеет полноценный REST API для управления доменами, ящиками, алиасами и настройками.
Для использования API нужно создать ключ в разделе Access → API и разрешить доступ с нужных IP (API_ALLOW_FROM).

Admin

Справочник по установке, настройке и эксплуатации Mailcow (Пункты 1–100)

Установка и Docker

Команда sudo docker compose pull скачивает все необходимые Docker-образы, указанные в файле docker-compose.yml, без запуска контейнеров.
Команда sudo docker compose up -d скачивает образы (если их нет), создает и запускает все контейнеры Mailcow в фоновом режиме.
Команда sudo docker compose down останавливает и удаляет все контейнеры и сети Mailcow, но сохраняет тома с данными.
Команда sudo docker compose down -v полностью удаляет все контейнеры, сети и тома (включая все письма и базу данных).
sudo docker compose ps показывает статус всех контейнеров Mailcow (работает/остановлен).
sudo docker compose logs --tail=200 <имя_контейнера> показывает последние 200 строк логов указанного контейнера (например, nginx-mailcow, php-fpm-mailcow).
Конфликт портов — самая частая проблема при запуске Mailcow, когда порт уже занят другим сервисом (nginx, apache).
Ошибка address already in use означает, что порт, который пытается занять контейнер, уже используется другим процессом на хосте.
Для тестового запуска Mailcow можно временно остановить системный Nginx командой sudo systemctl stop nginx.
Чтобы Nginx не запускался автоматически, используется команда sudo systemctl disable nginx.
Статус контейнера Healthy означает, что он не просто запущен, но и успешно прошел внутренние проверки работоспособности.
Статус Started / Running означает, что процесс контейнера запущен, но его функциональность может быть еще не готова (например, база данных инициализируется).
Конфликт Docker-сетей возникает, когда подсеть, которую пытается создать Mailcow, уже используется другой сетью Docker.
Ошибка Pool overlaps with other one on this address space решается изменением подсети в переменной IPV4_NETWORK в файле .env.
Для смены подсети Mailcow нужно изменить третий октет в IPV4_NETWORK (например, с 172.22.1 на 172.22.2).
В качестве гарантированно свободной подсети можно использовать диапазон 10.0.0.0/24 (установив IPV4_NETWORK=10.0.0).
Файл .env в директории /opt/mailcow-dockerized является основным конфигурационным файлом Mailcow.
MAILCOW_HOSTNAME в файле .env — это полное доменное имя (FQDN) вашего почтового сервера (например, mail.domain.tld).
Переменная HTTP_PORT в .env задает порт на хосте, который будет слушать веб-интерфейс Mailcow по HTTP.
Переменная HTTPS_PORT в .env задает порт на хосте для HTTPS-интерфейса Mailcow.
Если HTTPS_PORT закомментирован, Mailcow использует стандартный порт 443.
SKIP_LETS_ENCRYPT=y в .env отключает встроенный ACME-клиент Mailcow, что необходимо при использовании внешнего прокси и Certbot.
HTTP_REDIRECT=y заставляет Mailcow принудительно перенаправлять все HTTP-запросы на HTTPS.
Переменная ADDITIONAL_SERVER_NAMES указывает дополнительные доменные имена, на которые должен отвечать веб-интерфейс Mailcow.
TZ=Europe/Moscow задает часовой пояс для контейнеров Mailcow.
DBPASS и DBROOT — автоматически сгенерированные пароли к базе данных MySQL/MariaDB.
При изменении файла .env необходимо перезапустить Mailcow: sudo docker compose down && sudo docker compose up -d.

Обратный прокси (Reverse Proxy)

При использовании внешнего обратного прокси (например, Nginx) Mailcow должен слушать на нестандартных портах (например, 8080 и 8443).
Внешний Nginx принимает трафик на стандартных портах 80 и 443 и перенаправляет его на внутренние порты Mailcow.
Ключевой заголовок для Mailcow при работе за прокси: proxy_set_header X-Forwarded-Proto https;.
Он сообщает Mailcow, что исходный запрос был по HTTPS, даже если внутри он идет по HTTP.
Для работы с Certbot в конфиге Nginx обязательно должен быть блок server для порта 80.
Certbot для проверки домена использует временную директорию location /.well-known/acme-challenge/.
После успешного получения сертификата Certbot автоматически модифицирует конфиг Nginx, добавляя настройки SSL.
Ошибка "if directive is not allowed here" возникает, когда Certbot добавляет неправильный редирект в конфиг Nginx.
Правильный редирект HTTP -> HTTPS в Nginx выглядит так: return 301 https://$host$request_uri;.
Для проксирования HTTPS-трафика внешний Nginx должен иметь свой собственный валидный SSL-сертификат (от Certbot).
Конфиг внешнего Nginx должен быть разделен на два блока server: для порта 80 (редирект) и для порта 443 (прокси).
В блоке для порта 443 обязательно должна быть директива proxy_pass http://127.0.0.1:8087; (или ваш внутренний порт).
При использовании внешнего прокси встроенный HTTPS-порт Mailcow (например, 8443) остается неиспользуемым для внешнего трафика.

Решение проблем с запуском и подключением

Ошибка "Waiting for SQL..." в логах php-fpm-mailcow означает, что контейнер ждет готовности базы данных MySQL.
Это нормально для первого запуска и может длиться несколько минут, пока MySQL инициализируется.
Логи mysql-mailcow показывают прогресс инициализации базы данных и момент, когда она готова к подключениям (ready for connections).
Ошибка HTTP 502 Bad Gateway от Nginx означает, что Nginx не может связаться с бэкендом (PHP-FPM).
Самоподписанный сертификат вызывает предупреждение браузера "Недействительный сертификат" или "Ваше соединение не защищено".
Ошибка "Циклическое перенаправление" в Firefox при доступе по HTTP возникает из-за принудительного редиректа Mailcow на HTTPS.
Ошибка в Chrome "Этот сайт не может обеспечить безопасное подключение" возникает из-за проблем с SSL/TLS рукопожатием.
Команда sudo nginx -t проверяет синтаксис конфигурационных файлов Nginx и указывает на ошибки.
Ошибка "conflicting server name" в логах Nginx означает, что одно и то же доменное имя объявлено в двух разных конфигурационных файлах.
Ошибка "protocol options redefined" возникает, когда настройки SSL определены в нескольких блоках server для одного порта.
Ошибка "duplicate extension" в mime.types означает, что одно расширение файла определено дважды и не критична.
Для диагностики занятости порта используется команда sudo ss -tuln | grep <порт>.
Для определения процесса, занимающего порт, используется sudo lsof -i :<порт>.
Устаревший синтаксис listen ... http2 в Nginx рекомендуется заменить на отдельную директиву http2 on;.
Если после изменения портов в .env контейнер не запускается, нужно проверить, свободны ли эти порты.
При ручном исправлении конфига Nginx после Certbot, все настройки SSL должны быть только в блоке для порта 443.
Доступ к веб-интерфейсу по http://домен:8087 приведет к редиректу на HTTPS и может вызвать циклическую ошибку.
Доступ по https://домен:8443 работает напрямую к Mailcow, но с предупреждением о самоподписанном сертификате.
Прямой доступ к внутренним портам Mailcow следует использовать только для отладки.

PTR, DNS и репутация

PTR-запись связывает IP-адрес с доменным именем и критически важна для репутации почтового сервера.
PTR-запись настраивается у хостинг-провайдера, а не в DNS-зоне домена у регистратора.
Стандартные PTR от провайдера (например, 95-31-38-30.broadband.corbina.ru) вредят репутации почтового сервера.
Правильный PTR должен указывать на почтовый хостнейм (например, mail.other5.nbics.net).
Для идеальной работы необходима связка FCrDNS: PTR и A-запись должны указывать друг на друга.
Отсутствие правильного PTR — одна из главных причин попадания писем в спам.
Проверить PTR можно командой dig -x <IP-адрес> или на сайте mxtoolbox.com.
Если провайдер не дает настроить PTR, необходимо использовать внешний SMTP-релей или сменить хостера.
MX-запись должна указывать на почтовый хост (например, mail.other5.nbics.net), у которого есть A-запись.
Ошибка {No A Record} для MX-хоста — критична. Почта не будет доставляться.
SPF-запись (TXT) определяет, какие серверы имеют право отправлять почту от имени домена.
Проверить SPF можно на mxtoolbox.com или с помощью dig TXT домен.tld.
Пример правильной SPF-записи: v=spf1 mx a ip4:ВАШ_IP -all.
DKIM-запись — это цифровая подпись писем. Ключ генерируется в Mailcow и добавляется как TXT-запись.
DMARC-запись (TXT для _dmarc.домен.tld) определяет политику обработки писем, не прошедших SPF/DKIM.
Отсутствие DMARC-записи снижает доверие к домену и мешает внедрению BIMI.
Отчеты mxtoolbox показывают, что ваш IP не находится в черных списках (RBL) — это хороший знак.
Статус "Ok OK" для всех RBL означает чистую репутацию IP-адреса.
Домашние IP-адреса (из пулов Билайна, Ростелекома) непригодны для серьезного почтового сервера из-за PTR и блокировок портов.
IP от специализированных дата-центров (как dedic-center.ru) имеют лучшую исходную репутацию.

Управление и функциональность

В Mailcow по умолчанию нет самостоятельной регистрации пользователей.
Новые почтовые ящики создаются администратором в веб-интерфейсе (Mail Setup → Mailboxes).
Логин администратора по умолчанию: admin, пароль: moohoo.
При первом входе необходимо сменить пароль администратора.
Mailcow можно использовать как SMTP-сервер для внешних приложений (например, Element/Synapse).
Для этого создается специальный почтовый ящик (например, noreply@domain.tld), чьи данные указываются в настройках приложения.
При регистрации пользователя в стороннем сервисе, письмо подтверждения отправляется с этого спец-ящика на личную почту пользователя.
Такие транзакционные письма не считаются спамом при правильной настройке аутентификации домена (SPF, DKIM, DMARC).

Общие вопросы и сравнения

Установка почтового сервера — сложная задача, требующая знаний Linux, DNS и сетевых технологий.
Настройка правильных DNS-записей (A, MX, PTR, SPF, DKIM, DMARC) — самый важный и сложный этап.
Почтовый сервер состоит из нескольких компонентов: MTA (Postfix), MDA/IMAP (Dovecot), антиспам (Rspamd), веб-интерфейс (SOGo).
YunoHost — это простая платформа для хостинга приложений (включая почту), идеальна для новичков.
Mailcow — это профессиональное, мощное Docker-решение, сфокусированное только на почте.
Помимо Mailcow и YunoHost, существуют другие open-source решения: iRedMail, Mail-in-a-Box, Modoboa.
iRedMail — один из старейших и проверенных почтовых дистрибутивов.
Mail-in-a-Box нацелен на максимальную простоту и автоматизацию.
Modoboa — это гибкая панель управления для Postfix и Dovecot.
Выбор решения зависит от опыта и целей: YunoHost для хобби, Mailcow/iRedMail для бизнеса.
Для надежной корпоративной почты "из коробки" проще использовать Google Workspace или Microsoft 365.
Свой сервер требует постоянного мониторинга, обновлений и борьбы со спамом.
Самостоятельный почтовый сервер дает полный контроль над данными, но требует значительных временных затрат на поддержку.

База знаний (кластер NBICS)

Admin

Сообщения

Создаём и запускаем службу NodeBB в SystemD

1. Создаём пользователя

2. Меняем владельца каталога nodebb

3. Создание файла для systemd

4. Запуск сервиса

Управление NodeBB

️ Основные команды NodeBB

️ Команды для разработки и обслуживания

Команды для базы данных

5. Создание конфига для NGINX и сертификата

4. Настройка и запуск NodeBB

1. Запуск настройки

2. Запуск настройки

ПРИМЕР

3. Запуск NodeBB

Управление NodeBB

3. Настраиваем базу данных

Настройка MongoDB (с авторизацией)

1. Подключение к MongoDB Shell

2. Создание администратора (в базе admin)

3. Создание базы и пользователя для NodeBB

4. Выход

5. Включение авторизации

6. Перезапуск MongoDB

7. Проверка подключения с авторизацией

2. Устанавливаем компоненты форума

Установка Node.js (версия 22 LTS)

1. Импорт GPG-ключа NodeSource

2. Добавление репозитория Node.js 22.x

3. Установка

Проверка

Установка MongoDB 8.0

1. Импорт GPG-ключа MongoDB

2. Добавление репозитория

3. Установка

Проверка

Запуск и проверка службы

Установка NodeBB

1. Установка Git

2. Клонирование репозитория (ветка v4.x — стабильная)

3. Переходим в каталог nodebb и копируем туда файл package.json

Подразумевается, что установка форума происходит в Incus-контейнере

1. Настраиваем систему в контейнере

Увеличение размера файла подкачки (виртуальная память, Swap)

Теория JWT-аутентификации

Создание токена

Использование токена

Почему JWT удобен?

Как выглядит JWT?

Как это используется в Jitsi?

Разные вопросы и нюансы

1. Как часто серверы «опрашивают» основной?

2. Сколько серверов можно «повесить» на один основной?

Есть ли предел?

Итого:

Шаг 1: Скачивание (на обоих серверах)

Шаг 2: Настройка сервера "Сервер Б" (Стабильный) — FRPS

Шаг 3: Настройка "Сервер А1" (Проблемный) — FRPC

Шаг 4: Автоматизация (Systemd)

Как пользоваться?

Почему FRP лучше Autossh в данном конкретном случае?

Справочник по Matrix Synapse (Пункты 301–374)

Incus/LXD, Docker и Сетевые Конфликты

Глубокая Диагностика Сети и Пакетов

API Администратора (Практические Примеры)

Сравнение Способов Установки

Проблемы с PostgreSQL и Базами Данных

Практические Команды Администратора (Продолжение)

Теория NAT и WebRTC (Почему это сложно)

Разное Важное

Итоговые проверки работоспособности

Справочник по Matrix Synapse (Пункты 201–300)

Глубокая настройка федерации

Мосты (Bridges)

Интеграция с SSO (OIDC/LDAP)

Пространства (Spaces)

Голосовые и видеозвонки (WebRTC)

2. Создание администратора (в базе `admin`)