From cc92c44b65f33c990bf2b878270e015950dc19ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A5=D0=B0=D0=BB=D0=B8=D0=BC=D0=BE=D0=B2=20=D0=A0=D1=83?= =?UTF-8?q?=D1=81=D1=82=D0=B0=D0=BC?= Date: Mon, 16 Mar 2026 14:54:23 +0300 Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=BF=D0=BE=D0=BB=D0=BD=D0=B5?= =?UTF-8?q?=D0=BD=D0=B8=D0=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 141 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 82 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index 9daa3a1..20fe891 100644 --- a/README.md +++ b/README.md @@ -1,88 +1,112 @@ -# SelfHost Messenger +# Knot Messenger -SelfHost Messenger — это современный, безопасный и многофункциональный мессенджер с открытым исходным кодом, предназначенный для самостоятельного развертывания на собственных серверах (self-hosted). Проект разработан на стеке **React + TypeScript + Vite** для фронтенда и **.NET (C#) 8/10 + PostgreSQL + MinIO + SignalR** для бэкенда. +Knot Messenger — это современный, безопасный и высокопроизводительный мессенджер с открытым исходным кодом, созданный для самостоятельного развертывания (self-hosted). Проект разработан на стеке **React + TypeScript + Vite** для фронтенда и **.NET (C#) 8/10 + PostgreSQL + MinIO + SignalR** для бэкенда. ## 🚀 Основной функционал -Мессенджер обладает всеми функциями полноценной современной платформы для общения и командной работы: +Knot Messenger обладает всеми функциями полноценной современной платформы для общения: -### Чаты и группы -* **Личные сообщения (P2P):** Обмен сообщениями в реальном времени (SignalR). Текстовые сообщения, статусы отправки, доставки и прочитанности, индикаторы набора текста (typing). -* **Групповые чаты:** Создание групп. Настройки группы (название, описание, аватар). Добавление и удаление участников администратором. В админ-панели можно установить лимит участников. -* **Закрепление чатов (Pin/Unpin):** Важные чаты всегда под рукой вверху списка. -* **Вложения и медиа:** Отправка фото, видео, голосовых сообщений (с генерацией waveform-волны), аудиофайлов и обычных документов. Плавный просмотр изображений и видео во встроенном полноэкранном лайтбоксе (галерее). -* **Интеграция GIF (Klipy):** Встроенный поиск и отправка GIF-анимаций через Klipy. Ключи и ID клиента(Customer ID) настраиваются прямо из панели администратора. -* **Реакции и действия с сообщениями:** Реакции на сообщения (эмодзи), редактирование, пересылка (Forward), ответы (Reply c цитатами), удаление (только для себя или для всех). -* **Отложенные сообщения:** Возможность запланировать отправку сообщения на определенную дату и время. +### Сообщения и чаты +* **Личные и групповые чаты:** Мгновенный обмен сообщениями через веб-сокеты (SignalR). Добавление и удаление участников, роли администраторов. +* **Статусы сообщений:** Гарантированная доставка, статусы "Отправлено", "Доставлено", "Прочитано" (Double Check) и индикаторы набора текста (Typing). +* **Богатое взаимодействие:** Эмодзи-реакции, ответы (Reply c цитатами), пересылка сообщений (Forward) и возможность закреплять важные чаты (Pin). +* **Редактирование и удаление:** Редактирование текста, а также удаление сообщений (только у себя или у всех участников). +* **Отложенные сообщения:** Встроенный планировщик, позволяющий отправить сообщение в назначенную дату и время. -### Конференц-связь (WebRTC) -* **Аудио и видеозвонки:** Интеграция WebRTC для личных звонков P2P. -* **Групповые звонки:** Аудио-конференции внутри групповых чатов со всеми участниками беседы. -* **Демонстрация экрана (Screen Sharing):** Возможность поделиться экраном или окном. -* Управление микрофоном, камерой, отображение статусов звонка прямо в чате. *Для стабильной работы необходим внешний TURN-сервер.* +### Медиа и файлы +* **Отправка файлов:** Поддержка документов, изображений, видео файлов. +* **Голосовые сообщения:** Запись голоса прямо из браузера с красивой генерацией и отрисовкой waveform-волны в интерфейсе чата. +* **Интеграция Klipy (GIF):** Встроенный и быстрый поиск трендовых GIF-анимаций (ключи API управляются "на лету" из админ-панели). +* **Полноэкранная галерея (Lightbox):** Удобный просмотр отправленных фото и видео без необходимости скачивания. -### Социальные функции -* **Истории (Stories):** Публикация фото/видео историй. Просмотр списка посмотревших (Viewer List). Истории автоматически удаляются через установленное время. -* **Друзья (Friends):** Гибкая система отправки заявок в друзья, подтверждения и удаления из друзей. -* **Продвинутый профиль пользователя:** Настройка никнейма, информации "о себе", даты рождения. Клиентский редактор аватарок (Crop/Zoom) с идеальной обрезкой прямо в браузере. -* **Онлайн-статусы:** Индикация того, кто находится онлайн в данный момент (с точным временем "Был(а) в сети..."). +### Конференц-связь и Звонки +* **Личные (P2P) звонки:** Качественные аудио- и видеозвонки благодаря WebRTC. +* **Групповые аудиоконференции:** Возможность подключиться к голосовому каналу непосредственно внутри группы со всеми участниками. +* **Демонстрация экрана:** Захват и расшаривание экрана или конкретного окна в режиме реального времени. +* *Все медиаконфигурации работают в закрытых NAT сетях благодаря внешнему TURN-серверу.* -### Интерфейс и Панель Управления -* **Премиальный дизайн:** Эффект стекла (glassmorphism), плавные анимации (Framer Motion), кастомизация тем на лету (Ocean, Nebula, Midnight, Forest и д.р.). -* **Админ-панель (Dashboard):** Динамическое управление настройками системы "на лету" без перезагрузки сервера: - * Включение/выключение звонков. - * Настройка ключей Klipy API. - * Установка максимального размера загружаемого файла. - * Лимиты на количество участников в группах. - * Управление пользователями системы. +### Социализация и Профиль +* **Истории (Stories):** Публикация временных (на 24 часа) фото и видео историй с просмотром списка зрителей (Viewer List). +* **Система друзей:** Отправка заявок в друзья, список контактов, онлайн/офлайн статусы ("Был в сети..."). +* **Продвинутый профиль:** Редактор "О себе", даты рождения, установка и смена кастомного никнейма. +* **Умный кроп изображений:** Идеальная клиентская обрезка и масштабирование (Zoom) аватарок (квадрат/круг) еще до отправки на сервер. + +### Премиальный UI и Админ-панель +* **Современный дизайн:** Эффект матового стекла (Glassmorphism), плавные переходы (Framer Motion) и темы оформления (Ocean, Nebula, Midnight, Forest и др., меняющиеся "на лету"). +* **Панель управления (Admin Dashboard):** Динамическое управление системой без перезагрузок сервера: + * Настройки Klipy API (Customer ID, ключи). + * Управление лимитами загрузки файлов (File Size Limits). + * Ограничения на максимальное количество участников в группе. + * Глобальное отключение звонков (Toggle Calls). + * Управление пользователями, блокировка (Бан), статистика. + +--- + +## 🛡 Безопасность и Шифрование + +Безопасность является одним из приоритетов Knot Messenger: +* **Аутентификация:** Безопасные JWT-токены с механизмом ротации Refresh-токенов. +* **Шифрование трафика (Transport Security):** Все данные между клиентом и сервером передаются поверх TLS (HTTPS и WSS/WebSockets Secure). +* **Безопасность звонков (WebRTC):** Весь аудио/видео трафик и демонстрация экрана **обязательно шифруется** встроенными протоколами DTLS (Datagram Transport Layer Security) и SRTP (Secure Real-time Transport Protocol), что исключает возможность перехвата медиа-данных (Man-in-the-Middle) даже на стороне TURN-сервера. +* **Хранение секретов:** Изолированное управление секретами через переменные окружения `.env` (ключи, пароли БД, credentials MinIO). +* **Система прав:** Строгое разграничение на уровне ролей (Admin/User) и проверки участия пользователя в конкретном чате перед выдачей контента через CQRS (MediatR Behaviours/Policies). --- ## 🛠 Архитектура -* **Бэкенд:** C# .NET (ASP.NET Core), Entity Framework Core (PostgreSQL). Паттерн CQRS (MediatR). Механизм SignalR для доставки событий и сообщений в реальном времени. -* **Фронтенд:** React 18, Zustand (стейт-менеджер и кэширование параметров коннекта), TailwindCSS, lucide-react (векторные иконки), framer-motion (анимации), react-easy-crop, WebRTC APIs. -* **База данных и S3:** - * `PostgreSQL Server` — надежное и быстрое хранение реляционных данных. - * `MinIO` (S3) — масштабируемое и независимое объектное хранилище для медиафайлов (аватарки, файлы, вложения). +Проект построен как масштабируемая система с раздельными фронтендом, бэкендом и сервисами: + +* **Backend (.NET 8/10):** + * Построен на архитектурном паттерне **CQRS** с использованием **MediatR**. Логика работы с чатами, пользователями и вызовами изолирована по модулям. + * Работа в реальном времени осуществляется через **SignalR Hub**, с умным учетом подключений и распределением сообщений по группам (Groups). + * Выделенные background-сервисы (потоки Worker) очищают устаревшие данные (например, удаление "Stories" спустя 24 часа). +* **Database (PostgreSQL) + Entity Framework Core:** + * Хранение реляционных связей, чатов, истории сообщений и метаданных. Применяются строгие миграции. +* **Object Retrieval (MinIO S3):** + * Полноценное объектное S3-совместимое хранилище (MinIO) отвечает за отдачу и хранение всех медиа (изображений, файлов, аудио, аватарок). Снимает нагрузку с основного бэкенда и позволяет гибко масштабировать файловое пространство. +* **Frontend (React 18):** + * SPA-приложение, сборка происходит через быстрый бандлер **Vite**. + * Стилизация компонентов осуществлена через **TailwindCSS**. + * Глобальное и легковесное управление состоянием конфигураций, чатов и профилей реализовано через **Zustand**. --- ## ⚙️ Установка и развертывание (Docker Compose) -Проект изначально готов к `production` развертыванию через `docker-compose`. +Мессенджер спроектирован для моментального локального запуска или `production` развертывания через `docker-compose`. 1. Клонируйте репозиторий. -2. В корневой директории найдите файл `.env`. Там задаются секреты (пароль к базе данных, ключи JWT, доступы MinIO, ключи TURN). -3. Запустите стек: +2. В корневой директории найдите файл `.env`. Задайте там собственные секреты (пароли к Postgres, JWT-ключи, доступы MinIO/S3, ключи TURN). +3. Запустите все необходимые компоненты одной командой: ```bash docker compose build --no-cache docker compose up -d ``` В результате поднимутся 4 контейнера: -* `knot-db` — База данных PostgreSQL. -* `knot-minio` — S3 хранилище файлов MinIO. -* `knot-server` — Основной бэкенд на порту `:5034` / `:5059` -* `knot-web` — Фронтенд (Nginx + React) на порту `:9090` (или на 80/443 при использовании Traefik/Dokploy). +* `knot-db` — Реляционная база данных PostgreSQL. +* `knot-minio` — S3-хранилище файлов (с UI интерфейсом для менеджмента бакетов). +* `knot-server` — Основной API и SignalR-сервер (`:5034` / `:5059`). +* `knot-web` — Фронтенд (Nginx + распределение статики) на порту `:9090`. -*Для продакшена (Dokploy / Coolify) можно использовать стандартный подход публикации через Docker Compose, указав SSL сертификаты и настроив домены.* +*Для продакшена (Dokploy / Coolify / Traefik) вы можете экспонировать фронтенд на порты 80/443 и подключить самоподписные или Let's Encrypt SSL-сертификаты для безупречной работы HTTPS и WSS.* --- -## 🌐 Настройка TURN-сервера (для стабильности звонков) +## 🌐 Настройка TURN-сервера (для звонков без сбоев) -Механизм аудио и видео звонков, а также демонстрации экрана основан на технологии **WebRTC**. -Чтобы пользователи могли свободно общаться вне зависимости от локальных ограничений сети (NAT/Firewall/мобильные вышки), необходим внешний TURN сервер-ретранслятор. +Аудио, видео и демонстрация экрана используют технологию **WebRTC**. +Чтобы пользователи могли свободно устанавливать P2P-соединения вне зависимости от NAT (4G/LTE вышки, роутеры, корпоративные брэндмауэры), серверу звонков **необходим внешний TURN (Relay) сервер**. ### Требования к TURN -1. Вам нужен **отдельный сервер с белым (публичным) IP адресом**. -2. В файрволе этого сервера должны быть открыты порты: +1. VPS-сервер с **белым публичным IP-адресом**. +2. Открытые порты на файрволе: * `3478` (TCP/UDP) - * `5349` (TCP/UDP, если настроен TLS) - * Диапазон портов `49152 - 65535` (UDP) для прохода медиа-трафика. + * `5349` (TCP/UDP для TLS) + * Диапазон портов `49152 - 65535` (UDP) под сквозной медиа-трафик. -### Развертывание Coturn -Быстрое развертывание при помощи Docker на отдельном VPS: +### Запуск Coturn +Самый быстрый способ развернуть Coturn через Docker: ```bash docker run -d \ --network=host \ @@ -91,16 +115,15 @@ docker run -d \ -n --log-file=stdout \ --min-port=49152 \ --max-port=65535 \ - --user=USER_NAME:SECRET_PASSWORD \ + --user=ВАШ_ЛОГИН:ВАШ_ПАРОЛЬ \ --realm=yourdomain.com ``` -*Замените `USER_NAME` и `SECRET_PASSWORD` на собственные логин и пароль.* -### Подключение к приложению -После установки Coturn, перейдите в файл `.env` корневого проекта SelfHost Messenger и укажите реквизиты: +### Настройка в Knot +После запуска TURN-ретранслятора откройте файл `.env` в корне проекта (или укажите это прямо в Variables вашего CI/CD) и добавьте: ```env -TURN_URL=turn:ВАШ_БЕЛЫЙ_IP_ТУТ:3478 -TURN_USERNAME=USER_NAME -TURN_PASSWORD=SECRET_PASSWORD +TURN_URL=turn:ОТКРЫТЫЙ_IP_ТУТ:3478 +TURN_USERNAME=ВАШ_ЛОГИН +TURN_PASSWORD=ВАШ_ПАРОЛЬ ``` -(Также эти параметры можно переопределить через админ-панель в будущих версиях). После этого WebRTC звонки будут работать практически в 100% клиентских конфигураций. +После ввода этих данных клиенты Knot будут получать настройки TURN через бэкенд, и звонки (включая демонстрацию экрана) будут проходить со 100% вероятностью, шифруясь через DTLS.