Документация Glass Mail

Полная техническая документация по почтовому клиенту Glass Mail — версия 0.0.6, ООО «АйТи-Изи»

1. Общая информация

2. Архитектура

Glass Mail представляет собой клиент-серверное веб-приложение, состоящее из трёх уровней:

2.1. Компоненты ПО

2.2. Сетевые протоколы

3. Работа с электронной почтой

3.1. Приём писем (IMAP)

• Подключение к почтовому серверу по протоколу IMAP (порт 993, TLS)
• Автоматическая и ручная синхронизация папок
• Поддержка стандартных папок: Входящие, Отправленные, Черновики, Архив, Спам, Корзина
• Поддержка пользовательских (IMAP) папок сервера
• Пакетная загрузка писем с пагинацией (по 100 штук)
• Полная синхронизация по запросу (Shift+Обновить)
• Отложенная синхронизация (snooze)

3.2. Отправка писем (SMTP)

• Отправка писем по протоколу SMTP (порт 465, TLS)
• Поддержка вложенных файлов (attachments)
• Поля Кому (To), Копия (CC), Скрытая копия (BCC)
• Шаблоны писем, сохранение черновиков
• Запланированная отправка писем

3.3. Обработка писем

• Чтение писем с отображением HTML в изолированном iframe (sandbox)
• Санитизация HTML от вредоносного кода (XSS-защита)
• Пометка прочитано/непрочитано, избранное (звёздочка), важное (флаг)
• Перемещение между папками, архивирование, отложенное письмо (snooze)
• Пометка как спам, удаление, массовые операции
• Быстрый ответ (quick reply)

4. Поиск

• Полнотекстовый поиск по содержимому писем (FTS5 — SQLite)
• Поиск по теме, отправителю, содержимому
• Расширенный поиск: по отправителю (from), по теме (subject), по дате (с/по), только с вложениями
• Мгновенный поиск с задержкой 300мс (debounce)

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

5.1. Аутентификация

• Регистрация пользователей с проверкой через IMAP
• Аутентификация по JWT-токену (7 дней)
• Двухфакторная аутентификация (2FA TOTP — совместимо с Google Authenticator)
• Генерация QR-кода для настройки 2FA
• Защита от подбора пароля (Rate Limiting: 5 регистраций/час, 500 запросов/15 мин)
• CAPTCHA при 3 неудачных попытках входа

5.2. Шифрование

• Шифрование паролей IMAP — AES-256-CBC
• Хеширование паролей пользователей — bcrypt
• HTTPS/TLS для всех соединений
• Заголовки безопасности (Helmet.js): X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security

5.3. Авторизация

• Проверка JWT-токена для всех API-запросов
• Изоляция данных пользователей — каждый пользователь видит только свои данные
• История входов (IP, User-Agent, дата/время)

6. Контакты

• Адресная книга с хранением контактов
• Автоматическое создание контактов из входящих/исходящих писем
• Ручное добавление и редактирование контактов
• Поиск по контактам с автодополнением при вводе адреса
• Экспорт/импорт контактов (vCard, CSV)

7. Календарь

• Встроенный календарь в боковой панели
• Создание событий и напоминаний
• Просмотр событий по дням
• Уведомления о предстоящих событиях

8. Автоматизация

• Настраиваемые правила фильтрации писем
• Условия фильтрации: по отправителю, теме, наличию вложений
• Действия: перемещение в папку, пометка прочитанным, пометка важным
• Автоответчик (с указанием периода и текста)
• Подписи писем (автоматическое добавление)

9. Пользовательский интерфейс

• Адаптивный (responsive) дизайн — desktop и мобильные устройства
• Тёмная и светлая темы
• Анимированный стеклянный интерфейс (glassmorphism)
• Пагинация писем (бесконечная прокрутка)
• Мастер первоначальной настройки (onboarding wizard)
• Уведомления об обновлениях (What's New)
• Состояние подключения (online/offline)

10. Системные требования

10.1. Серверная часть

10.2. Клиентская часть (браузер)

10.3. Совместимость с российскими ОС

• ✅ ОС «Альт» (BaseALT) — через Docker
• ✅ РЕД ОС — через Docker
• ✅ Astra Linux — через Docker
• ✅ ОС «ГосЛинукс» — через Docker
• ✅ Linux (Ubuntu, Debian, CentOS)
• ✅ Windows Server — через Docker

11. Установка

11.1. Предварительные требования

Для установки Glass Mail на сервере должны быть установлены:

• Docker 20.10+ и Docker Compose 2.0+
• Операционная система Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+)
• Не менее 512 МБ оперативной памяти (рекомендуется 2 ГБ)
• Не менее 1 ГБ дискового пространства + объём для почты
• Доступ к IMAP (порт 993) и SMTP (порт 465) серверу

11.2. Установка с Docker Compose (рекомендуемый способ)

Шаг 1. Скачивание и распаковка

Скачайте установочный архив на сервер и распакуйте его:

# Скачивание архива прямо на сервер
wget https://айти-изи.рф/files/glass-mail-source.zip -O /tmp/glass-mail-source.zip

# Распаковка
unzip /tmp/glass-mail-source.zip -d /opt/glass-mail
cd /opt/glass-mail

Шаг 2. Создание файла конфигурации

cp .env.example .env

Шаг 3. Настройка переменных окружения

Отредактируйте файл .env:

# Сервер
PORT=3000
NODE_ENV=production

# Безопасность (ОБЯЗАТЕЛЬНО ЗАМЕНИТЬ!)
# Генерация: node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
JWT_SECRET=<сгенерировать-уникальный-ключ>

# Шифрование паролей (64 hex символа)
# Генерация: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
ENCRYPTION_KEY=<сгенерировать-64-hex-ключ>

# Почтовый сервер
IMAP_HOST=mail.example.com
IMAP_PORT=993
SMTP_HOST=mail.example.com
SMTP_PORT=465

# CORS (разрешённые домены)
ALLOWED_ORIGINS=https://mail.example.com

Шаг 4. Сборка и запуск

# Сборка Docker-образов
docker compose build

# Запуск в фоновом режиме
docker compose up -d

Шаг 5. Проверка работоспособности

# Проверка статуса контейнеров
docker compose ps

# Проверка логов
docker compose logs -f

# Health check
curl http://localhost:3000/health
# Ожидаемый ответ: {"status":"ok"}

Приложение будет доступно по адресу http://localhost:8833.

11.3. Установка без Docker (для разработки)

# Установка Node.js 20+
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Клонирование и установка зависимостей
cd backend
npm install --omit=dev

# Настройка окружения
cp ../.env.example ../.env
# Отредактируйте .env

# Запуск
NODE_ENV=production node server.js

Для продакшена рекомендуется использовать Nginx в качестве обратного прокси.

12. Настройка SSL/TLS

12.1. Получение сертификата Let's Encrypt

# Установка certbot
sudo apt install certbot python3-certbot-nginx

# Получение сертификата
sudo certbot certonly --standalone -d mail.example.com

# Копирование сертификатов
cp /etc/letsencrypt/live/mail.example.com/fullchain.pem ssl/
cp /etc/letsencrypt/live/mail.example.com/privkey.pem ssl/

12.2. Автообновление сертификатов

# Добавить в crontab
0 0 1 * * certbot renew --quiet && docker compose restart nginx

13. Резервное копирование

13.1. Ручное резервное копирование

scripts/backup-db.bat

Скрипт создаёт копию базы данных SQLite с меткой даты/времени в директории backups/.

13.2. Автоматическое резервное копирование

# Добавить в crontab (ежедневно в 02:00)
0 2 * * * /opt/glass-mail/scripts/auto-backup.sh

13.3. Восстановление из резервной копии

# Остановка сервиса
docker compose down

# Восстановление
scripts/restore-db.bat

# Запуск сервиса
docker compose up -d

14. Мониторинг и журналирование

14.1. Логи приложения

# Просмотр логов в реальном времени
docker compose logs -f

# Логи только backend
docker compose logs -f backend

# Логи за последние 100 строк
docker compose logs --tail=100

14.2. Мониторинг ресурсов

# Использование ресурсов контейнерами
docker stats

# Использование диска
du -sh /var/lib/docker/volumes/mail-client-data

14.3. Health Check

curl http://localhost:3000/health
# Ожидаемый ответ: {"status":"ok"}

Docker Compose автоматически проверяет здоровье контейнера каждые 30 секунд.

15. Обновление

15.1. Процедура обновления

# 1. Резервное копирование
scripts/backup-db.bat

# 2. Получение новой версии
git pull origin main

# 3. Пересборка и перезапуск
docker compose build
docker compose up -d

# 4. Проверка
docker compose ps
docker compose logs -f --tail=50

15.2. Откат версии

# 1. Остановка
docker compose down

# 2. Восстановление базы данных
scripts/restore-db.bat

# 3. Переключение на предыдущую версию
git checkout 
docker compose build
docker compose up -d

16. Устранение неисправностей

17. REST API

17.1. Аутентификация

17.2. Почта

17.3. IMAP синхронизация

17.4. Контакты, календарь, черновики

18. Лицензии и соответствие 152-ФЗ

18.1. Открытые компоненты

Все используемые библиотеки и компоненты имеют открытые лицензии (MIT, BSD, Apache 2.0, Public Domain), не содержат ограничений на использование в РФ и не подпадают под экспортный контроль.

18.2. Соответствие 152-ФЗ

ПО Glass Mail может использоваться в качестве оператора персональных данных при соответствующей настройке:

• Разграничение доступа пользователей
• Шифрование персональных данных (AES-256-CBC)
• Ведение журнала доступа (IP, User-Agent, дата/время)
• Возможность удаления данных по запросу субъекта
• Данные хранятся локально на сервере организации — не покидают территорию РФ

→ Политика обработки персональных данных

18.3. Ограничения

• Подключение к одному IMAP/SMTP серверу одновременно на пользователя
• Максимальный размер вложения: 10 МБ (настраивается)
• Хранение данных: локальная база данных SQLite (без облачного хранилища)
• Количество пользователей: не ограничено (зависит от ресурсов сервера, рекомендуется до 100 одновременно)

19. Бесплатное программное обеспечение