**МИНИСТЕРСТВО НАУКИ И ВЫСШЕГО ОБРАЗОВАНИЯ РОССИЙСКОЙ ФЕДЕРАЦИИ**
**Новгородский государственный университет имени Ярослава Мудрого**
**Политехнический институт**
**Кафедра Информационных Технологий и Систем**

ОТЧЕТ ПО ЛАБОРАТОРНОЙ РАБОТЕ №14
Разработка распределенной системы обмена сообщениями реального времени (аналог Discord) Minor для кафедры Программного Обеспечения и Вычислительной Техники НовГУ
Версия v0.1

**Выполнили:**
* Студент Ильин Д.А. группы № 3093
* Студент Распопов С.И. группы № 3093

Великий Новгород 2026 г.

---
# Аннотация

В данном документе представлено подробное руководство пользователя распределенной системы обмена сообщениями реального времени **«Minor»** (версия 0.1). Система разработана для оптимизации информационного обмена на кафедре Информационных Технологий и Систем (ИТИС) НовГУ. Она представляет собой суверенный аналог коммуникационных платформ Discord и Slack, функционирующий на базе микросервисной архитектуры с использованием технологий Go, Cassandra, PostgreSQL, Redis и NATS JetStream.

Руководство пользователя составлено в строгом соответствии с требованиями межгосударственного стандарта **ГОСТ 19.502-90** (Единая система программной документации. Описание применения) и регламентирует структуру, системные требования, процессы установки, тестирования и повседневной эксплуатации системы как в десктопной (веб-клиент), так и в мобильной версиях.

---

# Содержание

- [1. Введение](#1-введение)
  - [1.1. Область применения](#11-область-применения)
  - [1.2. Краткое описание возможностей](#12-краткое-описание-возможностей)
  - [1.3. Уровень подготовки пользователя](#13-уровень-подготовки-пользователя)
  - [1.4. Перечень эксплуатационной документации](#14-перечень-эксплуатационной-документации)
- [2. Назначение и условия применения](#2-назначение-и-условия-применения)
  - [2.1. Назначение программы](#21-назначение-программы)
  - [2.2. Системные требования и условия применения](#22-системные-требования-и-условия-применения)
- [3. Подготовка к работе](#3-подготовка-к-работе)
  - [3.1. Состав и содержание дистрибутивного носителя](#31-состав-и-содержание-дистрибутивного-носителя)
  - [3.2. Порядок загрузки данных и программ](#32-порядок-загрузки-данных-и-программ)
  - [3.3. Порядок проверки работоспособности](#33-порядок-проверки-работоспособности)
- [4. Описание операций](#4-описание-операций)
  - [4.1. Регистрация и аутентификация пользователя](#41-регистрация-и-аутентификация-пользователя)
  - [4.2. Главное меню программы](#42-главное-меню-программы)
  - [4.3. Управление профилем и настройки](#43-управление-профилем-и-настройки)
  - [4.4. Навигация по серверам и создание каналов](#44-навигация-по-серверам-и-создание-каналов)
  - [4.5. Обмен сообщениями](#45-обмен-сообщениями)
  - [4.6. Завершение работы с программой](#46-завершение-работы-с-программой)
- [5. Аварийные ситуации](#5-аварийные-ситуации)
- [6. Рекомендации по освоению](#6-рекомендации-по-освоению)
- [7. Термины и сокращения](#7-термины-и-сокращения)
- [Лист регистрации изменений](#лист-регистрации-изменений)

---
# 1. Введение

## 1.1. Область применения

Распределенная информационная система реального времени **Minor** предназначена для использования на кафедре Информационных Технологий и Систем НовГУ имени Ярослава Мудрого. Основными пользователями системы являются:

- Студенты бакалавриата и магистратуры, координирующие выполнение групповых проектов и лабораторных работ.
- Преподавательский состав кафедры, использующий систему для проведения консультаций, выдачи заданий и контроля успеваемости.
- Администраторы кафедры, управляющие распределением прав и доступом к учебным ресурсам.

Программа функционирует в корпоративной сети университета с возможностью внешнего доступа через защищенные каналы связи. Внедрение Minor позволяет исключить риски потери данных в облачных зарубежных сервисах и перевести внутреннее взаимодействие на суверенную инфраструктуру.

## 1.2. Краткое описание возможностей

Программный продукт предоставляет пользователям следующий набор функциональных возможностей:

- **Аутентификация и авторизация:** безопасный вход в систему по корпоративным учетным записям, защита сессий при помощи токенов JWT (Access и Refresh).
- **Управление серверами:** организация изолированных пространств для различных академических дисциплин, курсов или проектных групп.
- **Каналы коммуникации:** деление серверов на текстовые каналы (для обсуждений, публикации учебных материалов и файлов) и голосовые каналы (для проведения онлайн-семинаров и аудиосвязи в реальном времени с минимальной задержкой).
- **Обмен мгновенными сообщениями:** отправка текстовой информации (длиной до 2000 символов) по протоколу WebSocket с задержкой доставки менее 100 мс.
- **Профили пользователей:** кастомизация личных данных (ФИО, академическая группа, аватар) и системных настроек (звуки, уведомления, выбор темы оформления).
- **Уведомления и статусы:** автоматическое отслеживание статуса присутствия участников ("В сети" / "Не в сети") и индикация непрочитанных сообщений в каналах.

## 1.3. Уровень подготовки пользователя

Для работы с пользовательскими интерфейсами системы Minor (веб-клиент, мобильное приложение) от пользователя не требуется специальной технической подготовки. Достаточно обладать базовыми навыками работы на персональном компьютере или смартфоне под управлением Android/iOS и уметь использовать стандартные интернет-браузеры.

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

- Системное администрирование операционных систем семейства Linux (Ubuntu Server).
- Навыки контейнеризации приложений с использованием Docker и оркестрации через Docker Compose.
- Базовые знания языков запросов SQL (для PostgreSQL) и CQL (для Apache Cassandra).
- Опыт конфигурирования брокеров сообщений (NATS) и шлюзов API (Traefik).

## 1.4. Перечень эксплуатационной документации

В состав пакета эксплуатационной документации программного продукта Minor входят следующие документы:

- **Техническое задание** ([ТЗ-Minor.docx](file:///Users/odner/Desktop/morkin/ТЗ-Minor.docx)): определяет исходные цели разработки и технические рамки.
- **Спецификация требований к программному обеспечению** ([LAB7-Minor.docx](file:///Users/odner/Desktop/morkin/LAB7-Minor.docx)): детально описывает логику работы микросервисов и схемы баз данных.
- **Руководство пользователя** ([LR14-Minor.docx](file:///Users/odner/Desktop/morkin/LR14-Minor.docx)): текущий документ, содержащий руководство по установке и эксплуатации.

---
# 2. Назначение и условия применения

## 2.1. Назначение программы

Программа Minor предназначена для автоматизации процессов обмена сообщениями, координации совместной проектной деятельности студентов и проведения оперативных онлайн-консультаций преподавателями в рамках образовательного процесса кафедры ИТИС НовГУ.

## 2.2. Системные требования и условия применения

Для стабильного функционирования серверной части распределенной системы Minor в условиях средней нагрузки (до 500 активных WebSocket-соединений одновременно) должны быть обеспечены следующие минимальные параметры окружения:

**Аппаратные требования к серверу:**
- **Процессор:** x86_64 или ARM64 с тактовой частотой не менее 2.5 ГГц, количество ядер — не менее 4.
- **Оперативная память:** не менее 8 Гб (рекомендуется 16 Гб для стабильной работы СУБД Cassandra в Java Virtual Machine).
- **Дисковая подсистема:** твердотельный накопитель SSD объемом не менее 50 Гб со скоростью чтения/записи не ниже 500 Мб/с.
- **Сетевой интерфейс:** гигабитный сетевой адаптер (1 Gbps Ethernet).

**Программные требования к серверу:**
- **Операционная система:** Ubuntu Server 22.04 LTS или аналогичный Linux-дистрибутив (ядро версии 5.15 и выше).
- **Платформа контейнеризации:** Docker Engine версии 24.0.0 и выше.
- **Инструмент оркестрации:** Docker Compose v2.20.0 и выше.

**Требования к клиентским устройствам:**
- **Персональный компьютер:** ОС Windows 10/11, macOS 12+ или Linux; установленный браузер Google Chrome 110+, Mozilla Firefox 100+, Apple Safari 15+ с поддержкой HTML5 и WebSockets.
- **Мобильное устройство:** смартфон под управлением Android 10.0+ или iOS 15.0+; стабильное подключение к сети Интернет или интрасети НовГУ (Wi-Fi/4G).

---
# 3. Подготовка к работе

## 3.1. Состав и содержание дистрибутивного носителя

Программное обеспечение Minor поставляется в виде Git-репозитория. В соответствии со структурой проекта, состав дистрибутивного пакета содержит следующие компоненты:

| Путь в репозитории | Описание | Тип |
| :--- | :--- | :--- |
| `/backend/` | Корневая директория бэкенд-компонентов системы. | Каталог |
| `/backend/services/` | Каталог микросервисов системы (`api_gateway`, `auth_service`, `chat_service`, `gateway_service`, `guild_service`, `notification_service`, `presence_service`, `sfu_service`, `signal_service`, `upload_service`, `user_service`). | Каталог |
| `/backend/shared/` | Общие библиотеки (`pkg`) и protobuf-определения API (`api`). | Каталог |
| `/deploy/` | Скрипты и файлы для развертывания инфраструктуры. | Каталог |
| `/deploy/docker-compose.yaml` | Конфигурация Docker Compose для запуска всех сервисов и баз данных. | YAML-файл |
| `/docs/` | Техническая документация проекта. | Каталог |
| `/frontend/` | Исходный код клиентской веб-панели (React/Vite). | Каталог |

## 3.2. Порядок загрузки данных и программ

Развертывание программного продукта на сервере производится в соответствии со следующим пошаговым алгоритмом:

1. **Шаг 1. Получение дистрибутива:**  
   Склонируйте репозиторий с исходным кодом в локальную директорию на сервере:
   ```bash
   git clone http://172.20.7.4:3000/minor-chat/minor.git /opt/minor
   ```

2. **Шаг 2. Конфигурирование системы:**  
   Перейдите в каталог нужного сервиса бэкенда (например, `chat_service`) и создайте рабочий файл конфигурации окружения `.env` на основе шаблона:
   ```bash
   cd /opt/minor/backend/services/chat_service && cp .env.example .env
   ```
   Отредактируйте параметры подключения к БД, секретный ключ JWT для шифрования токенов и порты.

3. **Шаг 3. Подготовка баз данных:**  
   Перейдите в каталог развертывания `deploy`, запустите контейнеры баз данных (PostgreSQL и Cassandra) и примените файлы миграций схем данных:
   ```bash
   cd /opt/minor/deploy && docker-compose up -d postgres cassandra
   ```
   Убедитесь, что порты доступны, и выполните:
   ```bash
   migrate -path ../backend/services/chat_service/migrations -database "postgres://postgres:secret@localhost:5432/minor?sslmode=disable" up
   ```

4. **Шаг 4. Запуск всех компонентов:**  
   Запустите сборку образов микросервисов и разверните всю распределенную систему Minor:
   ```bash
   cd /opt/minor/deploy && docker-compose up --build -d
   ```

## 3.3. Порядок проверки работоспособности

Для верификации корректности развертывания распределенной системы выполните следующие действия:

1. Выполните HTTP-запрос к эндпоинту проверки состояния микросервиса авторизации:
   ```bash
   curl -i http://localhost:8080/api/v1/auth/health
   ```
   Сервер должен вернуть статус `200 OK` и JSON-тело `{"status": "healthy"}`.

2. Проверьте логи шлюза API Traefik на отсутствие критических ошибок маршрутизации:
   ```bash
   cd /opt/minor/deploy && docker-compose logs | grep -E "(ERROR|FATAL)"
   ```

3. Убедитесь в активности очередей в брокере сообщений NATS JetStream, выполнив команду в контейнере:
   ```bash
   cd /opt/minor/deploy && docker-compose exec nats nats stream info server_messages
   ```

4. Откройте веб-браузер на клиентском компьютере, перейдите по настроенному доменному адресу (например, `http://minor.novsu.ru`) и убедитесь в отображении стартовой страницы авторизации.

---

# 4. Описание операций

## 4.1. Регистрация и аутентификация пользователя

При первом обращении к системе пользователь видит экран авторизации.

- Если учетная запись еще не создана, необходимо нажать на ссылку **«Регистрация»** и ввести адрес корпоративной почты, имя пользователя и надежный пароль.
- Для входа в систему введите e-mail и пароль в соответствующие поля ввода формы (Рисунок 1).
- После успешной аутентификации Auth Service сгенерирует токен, который запишется в защищенные cookie браузера, и клиент будет автоматически перенаправлен на главный рабочий экран.

|           *Рисунок 1 – Авторизация*            |
| :----------------------------------------------: |
| ![Рисунок 4 – Главный экран](./media/image1.png) |

## 4.2. Главное меню программы

Главный интерфейс Minor разделен на несколько функциональных зон (Рисунок 2):

- В нижней части мобильного приложения (или в левой части веб-версии) отображаются круглые иконки доступных серверов (гильдий), а также кнопка быстрого перехода к личным сообщениям.
- В центральной области выводится текущий выбранный чат.
- Панель поиска сверху позволяет выполнять полнотекстовый поиск по истории личных сообщений (Рисунок 3).

|           *Рисунок 2 – Главный экран*            |           *Рисунок 3 – Поиск в главном меню*            |
| :----------------------------------------------: | :-----------------------------------------------------: |
| ![Рисунок 2 – Главный экран](./media/image2.png) | ![Рисунок 3 – Поиск в главном меню](./media/image3.png) |

## 4.3. Управление профилем и настройки

Нажав на иконку настроек профиля, пользователь попадает в меню конфигурации (Рисунок 4). В данном разделе доступны:

- Настройка приватности и доступа.
- Управление системными звуковыми уведомлениями.
- Переключение цветового оформления интерфейса (Светлая тема / Темная тема).

|           *Рисунок 4 – Настройки*            |
| :----------------------------------------------: |
| ![Рисунок 4 – Главный экран](./media/image4.png) |

## 4.4. Навигация по серверам и создание каналов

При переходе на один из серверов в левой панели отображается список доступных каналов (Рисунок 5):

- **Текстовые каналы** (помечаются знаком `#`) используются для обмена сообщениями и учебными файлами.
- **Голосовые каналы** (помечаются значком динамика) служат для мгновенного подключения к голосовой связи. Достаточно кликнуть на канал для начала аудиообщения.

|           *Рисунок 5 – Экран сервера*            |
| :----------------------------------------------: |
| ![Рисунок 5 – Экран сервера](./media/image5.png) |

## 4.5. Обмен сообщениями

Для отправки сообщения выберите нужный текстовый канал, введите текст в поле ввода внизу экрана и нажмите клавишу **Enter** (или кнопку **«Отправить»**).

- Для отправки файлов воспользуйтесь кнопкой со скрепкой.
- Для записи голосового сообщения удерживайте кнопку с изображением микрофона.
- Интерфейс личной переписки с другим пользователем представлен на Рисунке 6. Окно чата в текстовом канале сервера представлено на Рисунке 7.

| *Рисунок 6 – Личная переписка* | *Рисунок 7 – Переписка в канале* |
| :---: | :---: |
| ![Рисунок 6 – Личная переписка](./media/image6.png) | ![Рисунок 7 – Переписка в канале](./media/image7.png) |

## 4.6. Завершение работы с программой

Для корректного выхода из системы и предотвращения несанкционированного доступа к аккаунту с текущего устройства откройте настройки профиля и нажмите на кнопку **«Logout»** (Рисунок 4). В результате сессия будет аннулирована, а авторизационные токены удалены из памяти устройства.

---

# 5. Аварийные ситуации

В процессе эксплуатации распределенной системы Minor возможны сбои программного и аппаратного характера. Ниже представлены сценарии реагирования на нештатные ситуации:

**Временная потеря сетевого соединения клиентом:**
- *Поведение системы:* Пользовательский веб-клиент автоматически переходит в режим ожидания. На экране отображается сообщение *«Соединение потеряно. Попытка переподключения...»*.
- *Действия пользователя:* Проверить физическое подключение к сети Интернет или интрасети НовГУ. При восстановлении связи клиентское приложение восстановит WebSocket-сессию автоматически без потери истории сообщений.

**Отказ базы данных истории сообщений (Apache Cassandra):**
- *Поведение системы:* При попытке отправки или получения старых сообщений интерфейс выдает ошибку *«Не удалось загрузить сообщения. Пожалуйста, попробуйте позже»* (HTTP-статус 500). Работа авторизации и голосовых каналов при этом сохраняется (отказоустойчивость).
- *Действия администратора:* Подключиться к серверу по SSH, проверить логи контейнера базы данных:
  ```bash
  docker-compose logs cassandra
  ```
  В случае необходимости выполнить перезапуск службы:
  ```bash
  docker-compose restart cassandra
  ```

**Истечение времени действия сессии (JWT токена):**
- *Поведение системы:* При выполнении любого действия (отправка сообщения, переход в канал) система перенаправляет пользователя на форму входа.
- *Действия пользователя:* Повторно пройти процедуру авторизации, введя логин и пароль.

**Сбой брокера сообщений NATS JetStream:**
- *Поведение системы:* Сообщения сохраняются в БД, но перестают приходить другим участникам в реальном времени до момента ручного обновления страницы.
- *Действия администратора:* Проверить статус контейнера NATS и очистить зависшие сообщения в очереди при переполнении диска.

---

# 6. Рекомендации по освоению

Для быстрого и эффективного начала работы с системой Minor рекомендуется придерживаться следующих шагов:

- **Изучение интерфейса:** Основное расположение элементов управления (серверы, каналы, настройки) аналогично популярным мессенджерам Discord и Slack. Освоение базового функционала занимает у среднего пользователя не более 10–15 минут.
- **Групповая координация:** Рекомендуется создавать отдельные серверы для каждой учебной дисциплины, а внутри них группировать каналы по типам заданий (например, текстовые каналы `#лекции`, `#лабораторные` и голосовой канал `Консультации` для созвонов с преподавателем).

---

# 7. Термины и сокращения

Таблица 2 – Термины и сокращения

| Термин / Сокращение | Расшифровка | Описание |
| :--- | :--- | :--- |
| **БД** | База Данных | Организованная структура для хранения системной информации. |
| **СУБД** | Система Управления Базами Данных | Специализированное ПО для управления реляционными и нереляционными данными. |
| **JWT** | JSON Web Token | Стандарт токенов для безопасной передачи claims (утверждений) между сторонами. |
| **NATS JetStream** | Брокер сообщений | Распределенная система обмена сообщениями, обеспечивающая доставку событий в реальном времени. |
| **UUIDv7** | Universally Unique Identifier | Уникальный 128-битный идентификатор, генерируемый с использованием временной метки (timestamp-first). |
| **API** | Application Programming Interface | Программный интерфейс взаимодействия между клиентами и бэкенд-службами. |
| **gRPC** | Google Remote Procedure Call | Фреймворк для быстрого межсервисного взаимодействия с использованием Protocol Buffers. |
| **WebSocket** | Протокол связи | Протокол двусторонней полнодуплексной связи поверх TCP-соединения для Real-time обмена. |
| **Гильдия / Сервер** | Тематическое сообщество | Изолированное коммуникационное пространство внутри Minor, содержащее каналы и участников. |


---

# Лист регистрации изменений

| Номер изменения |   Тип изменения    | Дата изменения | Описание внесенных изменений                                            | Автор изменения             |
| :-------------: | :----------------: | :------------: | :---------------------------------------------------------------------- | :-------------------------- |
|     **0.1**     | Создание документа |   20.05.2026   | Разработка первичной версии руководства пользователя по ГОСТ 19.502-90. | Ильин Д. А., Распопов С. И. |