1. Архитектура
Каждая AploMatrix нода — это автономный Matrix-сервер с полным набором компонентов. После развёртывания нода работает независимо от центральной панели.
┌─────────────────────────────────────────┐ │ Ваш сервер │ │ │ │ ┌──────────┐ ┌──────────────────────┐ │ │ │ Synapse │ │ Node Agent │ │ │ │ (Matrix) │ │ Управление, API, │ │ │ │ :8008 │ │ heartbeat, бэкапы │ │ │ └──────────┘ │ :9091 │ │ │ └──────────────────────┘ │ │ ┌──────────┐ ┌──────────────────────┐ │ │ │PostgreSQL│ │ Node Panel │ │ │ │ :5432 │ │ Веб-панель (/_admin) │ │ │ │ :5433 │ │ :3001 │ │ │ └──────────┘ └──────────────────────┘ │ │ │ │ ┌──────────┐ ┌──────────────────────┐ │ │ │ Nginx │ │ Element Web (опц.) │ │ │ │ :80/443 │ │ :8080 │ │ │ └──────────┘ └──────────────────────┘ │ └─────────────────────────────────────────┘
Synapse
Matrix homeserver. Хранит пользователей, комнаты, историю сообщений, ключи шифрования.
Node Agent
Go-сервис. REST API для панели, heartbeat в CP, бэкапы, OTA обновления, управление модулями.
Node Panel
Next.js веб-панель по адресу /_admin. Управление сервером через браузер.
PostgreSQL
Две базы: Synapse DB (пользователи, чаты) и Agent DB (роли, инвайты, аудит).
2. Первый вход
- Откройте
https://ваш-домен/_admin - Введите логин и пароль администратора, указанные при деплое
- Вы попадёте на страницу Обзор с информацией о сервере
- Рекомендуется сразу создать пространства и комнаты, затем пользователей
3. Управление пользователями
Раздел Пользователи в панели.
Создание
Кнопка «Создать» → укажите имя, логин (латиница, точки, дефисы), пароль (мин. 8 символов). Пользователь появится в Synapse и сможет войти через любой Matrix-клиент.
Действия
🔑 Сброс пароля
Задаёт новый пароль. Старый становится недействительным.
🛡️ Назначение роли
Админ ноды, Админ пространства, Пользователь с ЛС, Пользователь.
📁 Доступ
Добавить/убрать из пространств и комнат.
🚫 Деактивация
Блокирует вход. Данные сохраняются.
Массовый импорт
Загрузите CSV-файл с колонками username,password,displayname. Пользователи создаются пакетно.
4. Роли и доступ
| Роль | Уровень | Возможности |
|---|---|---|
| Админ ноды | 95 | Полный доступ: пользователи, комнаты, бэкапы, система, конфигурация |
| Админ пространства | 50 | Управление пространством: комнаты, участники, инвайты. Доступ к панели (только инвайты) |
| Пользователь с ЛС | 5 | Может создавать личные чаты (DM). Не может создавать комнаты и пространства |
| Пользователь | 0 | Только чтение в назначенных комнатах. Не может создавать ничего |
Роли назначаются через кнопку 🛡️ в списке пользователей. Роль определяет как права в панели, так и power level в Matrix (влияет на возможности в клиенте).
5. Пространства и комнаты
Пространство — это папка для комнат (аналог «сервера» в Discord). Комната — это чат (текстовый канал).
Создание
Раздел «Пространства» → «Создать». Укажите название и алиас. Затем добавьте комнаты внутрь пространства.
Управление доступом
В разделе «Пользователи» → кнопка 📁 (Доступ) — добавляйте/убирайте пользователя из пространств и комнат. Пользователь мгновенно получает или теряет доступ (force join/leave через Admin API).
6. Приглашения
Раздел «Приглашения» позволяет генерировать ссылки для саморегистрации новых пользователей.
- Нажмите «Создать приглашение»
- Укажите имя (для удобства), выберите пространство
- Опционально: выберите комнаты, ограничение по количеству использований, срок действия
- Скопируйте ссылку или покажите QR-код
При переходе по ссылке пользователь заполняет имя, автоматически получает логин (транслитерация), задаёт пароль и сразу попадает в назначенные пространства/комнаты.
7. Element Web
Element Web — веб-клиент Matrix, встроенный в ноду. Доступен по адресу https://ваш-домен/.
Установка через модули
CP Dashboard → сервер → вкладка «Модули» → Element Web → «Установить». Укажите бренд и язык. Docker-контейнер развернётся автоматически, nginx перенастроится.
Что кастомизировано
- Тёмная тема по умолчанию
- Русский язык
- Скрыты кнопки создания комнат/пространств (только для админов)
- Отключена регистрация, экспорт чата, гостевой доступ
- Кастомный бренд на странице входа
8. Бэкапы
Раздел «Бэкапы» в панели или через CP Dashboard → сервер → «Бэкапы».
Что входит в бэкап
Agent DB
Роли иерархии, инвайт-ссылки, аудит-лог, доступы пользователей.
Synapse DB
Пользователи, комнаты, история сообщений, ключи шифрования, участники.
Восстановление
Нажмите «Восстановить» рядом с бэкапом. Введите имя файла для подтверждения. Текущие данные будут перезаписаны данными из бэкапа.
9. Обновления (OTA)
Агент и панель обновляются через CP Dashboard → сервер → вкладка «Обновления».
Процесс обновления
- CP показывает текущую и последнюю доступную версию
- Администратор читает changelog и нажимает «Обновить»
- CP ставит команду в очередь → агент получает её через heartbeat
- Агент скачивает новый бинарник, делает бэкап текущего
- Заменяет бинарник, перезапускает сервис через systemd
- Health check — если новая версия не отвечает, откат к бэкапу
Что НЕ затрагивается
- Конфигурация (env vars, systemd, токены)
- Данные в базе (пользователи, роли, аудит)
- SSL-сертификаты
- Docker volumes (Synapse data, PostgreSQL)
- homeserver.yaml
10. Модули
CP Dashboard → сервер → вкладка «Модули». Опциональные компоненты, которые можно установить или удалить без влияния на основной сервер.
Element Web
Веб-клиент Matrix. При установке: создаётся Docker-контейнер vectorim/element-web, генерируется config.json с привязкой к домену сервера, nginx перенастраивается для проксирования.
11. Безопасность
Сквозное шифрование (E2EE)
Все приватные комнаты шифруются по умолчанию. Сервер не имеет доступа к содержимому сообщений.
Контроль создания комнат
Nginx проксирует createRoom через агент. Агент проверяет роль пользователя: DM — для dm_user+, публичные — только admin.
JWT аутентификация
Панель использует JWT с 4-часовым сроком жизни. Пароли хешируются bcrypt.
Автономная работа
После деплоя сервер можно отключить от интернета. Всё управление — через локальную панель /_admin.
12. Решение проблем
Не могу войти в панель
Проверьте, что сервис запущен: sudo systemctl status aplomatrix-agent. Если упал — sudo systemctl restart aplomatrix-agent.
502 Bad Gateway на /_admin
Panel сервис не запущен или путь к server.js неверный. Проверьте: sudo journalctl -u aplomatrix-panel -n 20.
Пользователь не видит комнату после добавления
Панель использует JoinRoom (Synapse Admin API). Если Synapse отдаёт ошибку — проверьте SYNAPSE_ACCESS_TOKEN в /etc/systemd/system/aplomatrix-agent.service.
Бэкап с ошибкой
Проверьте, что Docker-контейнеры PostgreSQL запущены: docker ps | grep postgres. Бэкап использует docker run для pg_dump.
Обновление не приходит
Убедитесь, что heartbeat работает: journalctl -u aplomatrix-agent | grep heartbeat. Agent ID должен совпадать с зарегистрированным в CP.
Полезные команды
# Статус сервисов
sudo systemctl status aplomatrix-agent aplomatrix-panel nginx
# Логи агента
sudo journalctl -u aplomatrix-agent -f
# Перезапуск
sudo systemctl restart aplomatrix-agent aplomatrix-panel
# Docker контейнеры
sudo docker ps --format "{{.Names}} {{.Status}}"
# Synapse логи
sudo docker logs aplomatrix-synapse --tail 50
13. История версий
- Система модулей: установка/удаление Element Web через панель
- OTA обновления: версионирование агента, скачивание бинарника, автобэкап, откат
- Pending commands: CP отправляет команды через heartbeat
- KickUser через Synapse state event API
- Исправлено удаление пользователей из комнат
- Force-join при добавлении в комнаты/пространства (вместо invite)
- Уникальные Agent ID по домену
- Heartbeat с версиями агента/панели
- Инфраструктура pending commands
- Иерархия ролей: server_admin, space_admin, dm_user, user
- createRoom proxy с проверкой ролей
- Бэкапы: Agent DB + Synapse DB
- Инвайты с QR-кодами и авторегистрацией
- Let's Encrypt автонастройка при деплое
- Поддержка SSH-ключей и non-root пользователей
- space_admin: доступ к панели (только инвайты)