Skip to content

architecture.md

Latest commit

 

History

History
460 lines (389 loc) · 35.4 KB

architecture.md

File metadata and controls

460 lines (389 loc) · 35.4 KB

Архитектура проекта: Менеджер Systemd-сервисов с Webhook Автоматизацией

Общая структура проекта

services-create-curl/
├── service.sh              # Основной скрипт менеджера сервисов
├── webhook.sh              # Скрипт автоматизации CI/CD с webhook
├── setup_mail.sh           # Скрипт установки и управления почтовым сервером
├── README.md               # Документация пользователя
├── README_cert_https.md    # Документация по HTTPS сертификатам
├── example.png             # Скриншот примера использования
└── architecture.md         # Архитектурная документация

Основные компоненты

service.sh - Главный исполняемый файл

Bash-скрипт для создания и управления systemd-сервисами с графическим интерфейсом в терминале.

setup_mail.sh - Установка и управление почтовым сервером

Bash-скрипт для установки и управления почтовым сервером на базе Postfix, Dovecot, MariaDB и OpenDKIM с интерактивным интерфейсом.

Основные функции:

Инициализация и конфигурация:

  • init_mail_config() - создание директорий и файлов для хранения конфигурации почтового сервера
  • check_packages_installed() - проверка установленных пакетов почтового сервера

Установка почтового сервера:

  • input_mail_server_config() - интерактивный ввод данных для настройки почтового сервера (домен, hostname, пользователь, пароль)
  • install_mail_server() - установка и настройка почтового сервера (Postfix, Dovecot, MariaDB, OpenDKIM, firewall)
  • show_dns_records() - вывод DNS записей для настройки в панели управления DNS (A, MX, SPF, DMARC, DKIM)

Управление доменами и почтовыми ящиками:

  • add_domain_mailbox() - меню добавления нового домена или почтового ящика
  • add_mailbox_to_existing_domain() - добавление почтового ящика к существующему домену
  • view_domains_mailboxes() - просмотр списка зарегистрированных доменов и почтовых ящиков с возможностью выбора домена для детальной информации
  • show_domain_details() - отображение детальной информации о домене: DNS настройки (A, MX, SPF, DMARC, DKIM) и параметры подключения для каждого почтового ящика (SMTP/IMAP: сервер, порт, шифрование, логин, пароль) с адаптивной таблицей, автоматически подстраивающейся под длину значений, с возможностью отправки тестового письма
  • send_test_email() - отправка тестового письма с выбранного почтового ящика домена на указанный адрес получателя для проверки работы почтового сервера с меню просмотра логов после отправки
  • view_email_logs() - просмотр логов отправленного сообщения из Postfix через journalctl и файловых логов с фильтрацией по отправителю и получателю с автоматическим определением проблем (например, SMTPUTF8) и предложением решений
  • fix_smtputf8_issue() - исправление проблемы SMTPUTF8 путем отключения требования SMTPUTF8 в Postfix для совместимости с серверами, не поддерживающими эту функцию (например, Yandex)

Endpoint для отправки писем:

  • create_python_mail_endpoint_server() - создание Python HTTP сервера скрипта для обработки POST запросов на отправку писем с поддержкой автоматического определения HTML контента
  • create_mail_endpoint() - создание HTTP endpoint для отправки писем: запрос порта, генерация/ввод API ключа, создание Python скрипта сервера, создание systemd сервиса, сохранение конфигурации
  • manage_mail_endpoints() - управление созданными endpoint'ами: просмотр списка, запуск/остановка/перезапуск, просмотр логов, удаление, показ примеров использования
  • is_html_content() (в Python сервере) - функция определения типа контента сообщения (HTML или plain text) по наличию HTML тегов для автоматической установки правильного Content-Type заголовка

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

  • show_main_menu() - главное меню управления почтовым сервером
  • clear_screen() - очистка экрана
  • strip_ansi() - удаление ANSI-кодов для корректного расчета длины строк
  • vislen() - вычисление видимой длины строки без учета ANSI-кодов
  • print_hr() - печать горизонтальной линии таблицы с адаптивными ширинами столбцов
  • print_row() - печать строки таблицы с учетом ANSI-цветов и корректным выравниванием

webhook.sh - Система автоматизации CI/CD

Bash-скрипт для автоматического выполнения действий при получении уведомлений от GitHub webhook'ов.

Основные функции:

Инициализация и конфигурация:

  • init_services_list() - создает директории и файлы для хранения списка сервисов
  • check_sudo() - проверяет наличие прав суперпользователя
  • check_command() - проверяет наличие команд в системе

Управление уведомлениями:

  • send_notification() - отправка уведомлений через Telegram API
  • manage_notifications() - интерфейс настройки уведомлений

Создание сервисов:

  • select_runtime() - выбор режима запуска (Python, UV, Poetry, PHP, Shell)
  • select_file() - выбор файла для создания сервиса
  • create_service() - создание systemd-сервиса и скриптов уведомлений

Управление сервисами:

  • manage_services() - просмотр списка созданных сервисов
  • service_control() - управление конкретным сервисом
  • view_service_logs() - просмотр журналов сервиса
  • edit_service_file() - редактирование конфигурации сервиса

Управление Nginx:

  • list_nginx_configs() - получение списка всех конфигураций nginx из /etc/nginx/sites-available/
  • show_nginx_config_info() - отображение детальной информации о конфигурации nginx с указанием wildcard доменов и типа проксирования
  • manage_nginx_configs() - главное меню управления конфигурациями nginx с выбором конфигурации
  • check_nginx_ports() - проверка портов в конфигурациях nginx (вызывает manage_nginx_configs)
  • create_nginx_config() - создание конфигурации nginx с поддержкой обычных и wildcard доменов, выбор типа проксирования (локальный/внешний), опциональная поддержка WebSocket проксирования, активация через симлинк, опциональный выпуск SSL сертификата
  • edit_nginx_config() - редактирование конфигурации nginx через текстовый редактор с валидацией
  • delete_nginx_config() - удаление конфигурации nginx с подтверждением и автоматическим отключением
  • toggle_nginx_config() - включение/отключение конфигурации nginx через управление симлинками
  • issue_ssl_certificate() - выпуск SSL сертификата для конфигурации с автоматическим определением типа (обычный/wildcard) и вызовом соответствующей функции
  • issue_wildcard_certificate() - выпуск wildcard SSL сертификата через DNS challenge с интерактивным процессом добавления DNS TXT записи и автоматической настройкой nginx с сохранением поддержки WebSocket

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

  • show_main_menu() - главное меню приложения
  • clear_screen() - очистка экрана

Функции webhook.sh:

Инициализация webhook системы:

  • init_webhook_system() - создание директорий и файлов конфигурации
  • fix_automations_format() - миграция старых форматов данных автоматизаций

Обработка webhook событий:

  • handle_ping_event() - обработка ping событий от GitHub для проверки подключения
  • handle_push_event() - обработка push событий и запуск автоматизаций
  • log_event() - централизованное логирование всех событий

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

  • create_automation() - создание новой автоматизации с настройкой команд
  • manage_automations() - интерфейс управления существующими автоматизациями
  • test_automation_manual() - принудительное тестирование автоматизации
  • simulate_push_event() - эмуляция push события для отладки

Webhook сервер:

  • start_webhook_server() - запуск HTTP сервера для приема webhook'ов
  • Поддержка Python, socat и netcat в качестве сервера

Система уведомлений:

  • send_notification() - отправка уведомлений через Telegram
  • Интеграция с системой логирования

Управление данными:

  • cleanup_corrupted_data() - очистка поврежденных данных автоматизаций
  • view_logs() - просмотр журналов событий
  • system_settings() - настройки порта и уведомлений

Инициализация и конфигурация:

  • init_webhook_system() - создание директорий и файлов конфигурации
  • save_config() - сохранение настроек системы

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

  • create_automation() - создание новой автоматизации CI/CD
  • manage_automations() - управление существующими автоматизациями
  • view_automation_details() - просмотр деталей автоматизации
  • delete_automation() - удаление автоматизации
  • test_automation() - тестирование автоматизации

Webhook сервер:

  • start_webhook_server() - запуск/остановка/перезапуск webhook сервера
  • webhook_server() - основная функция HTTP сервера
  • handle_webhook_request() - обработка входящих webhook запросов

Система мониторинга:

  • log_event() - логирование событий с временными метками
  • view_logs() - просмотр журнала событий
  • send_notification() - отправка уведомлений через Telegram

Интеграция с service.sh:

  • get_services_list() - получение списка созданных сервисов из service.sh

Поддерживаемые режимы запуска

  1. Python (python3) - запуск Python-скриптов через системный интерпретатор
  2. UV Manager (uv run) - запуск через UV менеджер пакетов
  3. Poetry (poetry run python) - запуск через Poetry менеджер зависимостей
  4. PHP Server (php -S) - запуск PHP-файлов как веб-сервер
  5. Shell Script (bash) - запуск shell-скриптов через bash интерпретатор

Структура данных

Файлы конфигурации service.sh:

  • /var/lib/service-creator/created_services.list - список созданных сервисов
  • /var/lib/service-creator/notifications/config - настройки уведомлений
  • /var/lib/service-creator/notifications/{service_name}_notify.sh - скрипты уведомлений для каждого сервиса

Файлы конфигурации webhook.sh:

  • /var/lib/webhook-automation/config - основная конфигурация webhook системы
  • /var/lib/webhook-automation/automations.list - список созданных автоматизаций (ID|название|репозиторий|путь|ветка|команды|дата_создания|приватный|учетные_данные_зашифрованы)
  • /var/lib/webhook-automation/logs/webhook.log - журнал событий автоматизации

Файлы конфигурации setup_mail.sh:

  • /var/lib/mail-server/domains.list - список зарегистрированных доменов (домен:hostname:дата_создания)
  • /var/lib/mail-server/mailboxes.list - список почтовых ящиков (email:домен:пароль:дата_создания)
  • /var/lib/mail-server/endpoints.list - список созданных endpoint для отправки писем (порт:api_ключ:имя_сервиса:дата_создания)
  • /var/lib/mail-server/logs/endpoint.log - журнал работы endpoint серверов
  • /tmp/mail_endpoint_{PORT}.py - Python скрипты HTTP серверов для каждого endpoint

Системные файлы:

  • /etc/systemd/system/{service_name}.service - файлы конфигурации systemd
  • /etc/systemd/system/mail-endpoint-{PORT}.service - файлы конфигурации systemd для endpoint отправки писем
  • /etc/nginx/sites-available/{domain}.conf - конфигурации nginx
  • /etc/nginx/sites-enabled/{domain}.conf - активированные конфигурации nginx (симлинки)
  • /etc/postfix/mysql-virtual-*.cf - конфигурационные файлы Postfix для работы с MySQL
  • /etc/dovecot/dovecot-sql.conf.ext - конфигурация Dovecot для работы с MySQL
  • /etc/opendkim/keys/{domain}/dkim.private - приватные ключи DKIM для доменов
  • /etc/opendkim/keys/{domain}/dkim.txt - публичные ключи DKIM для DNS записей

Интеграции

Telegram API

  • Отправка уведомлений о статусе сервисов (service.sh)
  • Отправка файлов логов (service.sh)
  • Уведомления о событиях автоматизации (webhook.sh)
  • Тестирование уведомлений

GitHub Webhooks

  • Получение уведомлений о push в репозиторий
  • Фильтрация по веткам
  • Автоматический запуск команд при обновлении кода

Systemd

  • Создание и управление службами
  • Автозапуск сервисов
  • Журналирование
  • Интеграция с автоматизацией (перезапуск сервисов)

Nginx

  • Проверка портов в существующих конфигурациях
  • Создание новых конфигураций reverse proxy
  • Автоматическая активация конфигураций через симлинки
  • Интеграция с certbot для выпуска SSL сертификатов
  • Валидация конфигураций перед применением

Почтовый сервер (setup_mail.sh)

  • Установка и настройка Postfix для отправки почты
  • Установка и настройка Dovecot для приема почты (IMAP/IMAPS)
  • Настройка MariaDB для хранения виртуальных доменов и пользователей
  • Настройка OpenDKIM для подписи исходящей почты
  • Настройка firewall (порты 25, 587, 993)
  • Автоматическая генерация DNS записей (A, MX, SPF, DMARC, DKIM)
  • Управление множественными доменами и почтовыми ящиками

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

  • Требует прав суперпользователя для управления системными сервисами
  • Проверка корректности ввода пользователя
  • Подтверждение критических операций (удаление сервисов/автоматизаций)
  • Безопасное редактирование конфигурационных файлов
  • Webhook secret для защиты от несанкционированных запросов
  • Валидация входящих webhook данных
  • Изоляция выполнения команд автоматизации

Цветовая схема интерфейса

  • GREEN - успешные операции и активные элементы
  • RED - ошибки и неактивные элементы
  • YELLOW - предупреждения и информационные сообщения
  • CYAN - пункты меню и заголовки
  • BLUE - дополнительная информация
  • BOLD - выделение важных элементов

Функциональные возможности webhook.sh

Создание автоматизаций

  • Настройка Git репозитория и целевой ветки
  • Выбор между использованием существующих сервисов и ручным вводом команд
  • Интеграция с созданными в service.sh сервисами
  • Автоматическое формирование команд перезапуска сервисов

Webhook сервер

  • HTTP сервер на настраиваемом порту (по умолчанию 9000)
  • Обработка POST запросов от GitHub
  • Парсинг JSON payload для определения ветки и репозитория
  • Автоматический запуск соответствующих автоматизаций

Система мониторинга

  • Подробное логирование всех событий с временными метками
  • Отправка уведомлений в Telegram о статусе выполнения
  • Просмотр журналов через интерфейс
  • Тестирование автоматизаций вручную

Типы автоматизаций

  1. Интеграция с service.sh - автоматический git pull и перезапуск systemd сервиса
  2. Пользовательские команды - выполнение произвольных bash команд
  3. Комбинированные сценарии - объединение нескольких операций

Настройки безопасности

  • Webhook secret для аутентификации GitHub запросов
  • Настраиваемый порт для webhook сервера
  • Изоляция выполнения команд
  • Валидация входящих данных
  • Шифрование учетных данных для приватных репозиториев (base64 + rot13)
  • Поддержка Personal Access Token и username/password аутентификации

Функциональные возможности Nginx (service.sh)

Управление конфигурациями nginx

  • Просмотр списка всех конфигураций в /etc/nginx/sites-available/
  • Отображение детальной информации о каждой конфигурации:
    • Домены (server_name) с указанием wildcard доменов
    • Порты прослушивания (listen)
    • Цели проксирования (proxy_pass)
    • Тип проксирования (локальный/внешний сервер)
    • Статус SSL сертификата
    • Статус активации конфигурации (sites-enabled)
  • Цветная визуализация информации с выделением wildcard доменов

Редактирование конфигураций nginx

  • Выбор конфигурации из списка для редактирования
  • Открытие конфигурации в текстовом редакторе (vim/vi/nano)
  • Автоматическая валидация конфигурации после редактирования (nginx -t)
  • Автоматическая перезагрузка nginx при успешной валидации
  • Откат изменений при обнаружении ошибок в конфигурации

Удаление конфигураций nginx

  • Выбор конфигурации для удаления
  • Отображение информации о конфигурации перед удалением
  • Подтверждение удаления (защита от случайного удаления)
  • Автоматическое отключение конфигурации перед удалением
  • Валидация и перезагрузка nginx после удаления

Включение/отключение конфигураций nginx

  • Активация конфигурации через создание симлинка в /etc/nginx/sites-enabled/
  • Деактивация конфигурации через удаление симлинка
  • Автоматическая валидация конфигурации перед активацией
  • Автоматическая перезагрузка nginx после изменений
  • Откат активации при обнаружении ошибок в конфигурации

Выпуск SSL сертификата с автообновлением

  • Автоматическое определение домена из конфигурации
  • Автоматическое определение типа сертификата (обычный/wildcard)
  • Выпуск обычных SSL сертификатов через certbot --nginx (HTTP challenge)
  • Выпуск wildcard SSL сертификатов через certbot certonly --manual --preferred-challenges dns (DNS challenge)
  • Интерактивный процесс выпуска wildcard сертификатов:
    • Инструкции по добавлению DNS TXT записи
    • Ожидание подтверждения добавления записи
    • Автоматическая настройка nginx после получения сертификата
  • Автоматическая настройка HTTPS в конфигурации nginx
  • Настройка автообновления через systemd timer (certbot.timer)
  • Резервный вариант с рекомендацией настройки cron для автообновления
  • Проверка наличия certbot перед выпуском сертификата
  • Информирование о необходимых требованиях для успешного выпуска SSL
  • Автоматическая активация конфигурации перед выпуском сертификата

Создание конфигурации nginx

  • Интерактивный запрос домена с поддержкой форматов:
    • Обычный домен (example.com)
    • Поддомен (subdomain.example.com)
    • Wildcard домен (*.example.com)
  • Выбор типа проксирования:
    • Локальный сервер (localhost:port) - проксирование на локальные сервисы
    • Внешний сервер (host:port или IP:port) - проксирование на внешние серверы
  • Опциональная поддержка WebSocket проксирования:
    • Интерактивный выбор включения поддержки WebSocket при создании конфигурации
    • Автоматическое добавление директив nginx для WebSocket (proxy_http_version 1.1, Upgrade, Connection)
    • Сохранение поддержки WebSocket при выпуске wildcard SSL сертификатов
  • Валидация введенных данных (корректность порта 1-65535, формат адреса)
  • Автоматическое определение типа домена (wildcard/обычный)
  • Создание reverse proxy конфигурации с учетом типа проксирования и поддержки WebSocket
  • Поддержка wildcard доменов в server_name (*.example.com example.com)
  • Автоматическое создание файла в /etc/nginx/sites-available/{domain}.conf
  • Проверка существования конфигурации с подтверждением перезаписи
  • Активация конфигурации через создание симлинка в /etc/nginx/sites-enabled/
  • Валидация конфигурации nginx перед применением (nginx -t)
  • Автоматическая перезагрузка nginx после создания конфигурации
  • Опциональный выпуск SSL сертификата с автоматическим определением типа (обычный/wildcard)
  • Проверка наличия certbot перед выпуском сертификата
  • Информирование о необходимых требованиях для успешного выпуска SSL

Интеграция с SSL/TLS

  • Использование certbot для автоматического выпуска Let's Encrypt сертификатов
  • Поддержка двух типов сертификатов:
    • Обычные сертификаты через HTTP challenge (certbot --nginx)
    • Wildcard сертификаты через DNS challenge (certbot certonly --manual --preferred-challenges dns)
  • Автоматическое определение типа сертификата на основе конфигурации домена
  • Интерактивный процесс выпуска wildcard сертификатов:
    • Получение DNS TXT записи от certbot
    • Инструкции пользователю для добавления записи в DNS зону
    • Ожидание подтверждения добавления записи
    • Автоматическая настройка nginx после получения сертификата
    • Автоматическое сохранение поддержки WebSocket при выпуске wildcard сертификатов (проверка наличия WebSocket директив в исходной конфигурации)
  • Автоматическая настройка HTTPS в конфигурации nginx
  • Поддержка редиректа HTTP -> HTTPS для wildcard доменов
  • Проверка доступности домена перед выпуском сертификата
  • Информирование о требованиях (DNS настройка, открытые порты 80/443)
  • Настройка автообновления сертификатов через systemd timer
  • Резервное копирование конфигурации перед изменением для wildcard сертификатов

Функциональные возможности setup_mail.sh

Установка почтового сервера

  • Интерактивный ввод данных (домен, hostname, пользователь, пароль)
  • Автоматическая установка необходимых пакетов (Postfix, Dovecot, MariaDB, OpenDKIM)
  • Настройка firewall для почтовых портов
  • Создание базы данных и таблиц для виртуальных доменов и пользователей
  • Настройка Postfix для работы с MySQL
  • Настройка Dovecot для работы с MySQL
  • Генерация DKIM ключей для домена
  • Автоматический вывод DNS записей для настройки

Управление доменами

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

DNS записи

  • A-запись для hostname почтового сервера
  • MX-запись для приема почты
  • SPF-запись для защиты от спама
  • DMARC-запись для политики обработки почты
  • DKIM-запись с автоматически извлеченным публичным ключом

Функциональные возможности endpoint для отправки писем (setup_mail.sh)

Создание HTTP endpoint

  • Интерактивный запрос порта для HTTP сервера (1-65535)
  • Проверка доступности порта перед созданием
  • Генерация или ручной ввод API ключа для аутентификации (автогенерация через openssl rand)
  • Создание Python HTTP сервера с использованием http.server
  • Валидация входящих данных (subject, message, from, to)
  • Валидация email адресов через регулярные выражения
  • Автоматическое определение типа контента (HTML или plain text) по наличию HTML тегов
  • Формирование писем в формате RFC 2822 с автоматической установкой Content-Type (text/html или text/plain)
  • Отправка писем через /usr/sbin/sendmail
  • Создание systemd unit файла для автозапуска
  • Сохранение конфигурации в endpoints.list

HTTP API endpoint

  • URL: http://localhost:{PORT}/send
  • Метод: POST
  • Аутентификация: Заголовок X-API-Key с API ключом
  • Content-Type: application/json
  • Тело запроса (JSON): 
    {
  "from": "sender@example.com",
  "to": "recipient@example.com",
  "subject": "Тема письма",
  "message": "Текст сообщения или HTML контент"
}
  • Поддержка HTML: Поле message может содержать как обычный текст, так и HTML разметку. Система автоматически определяет тип контента по наличию HTML тегов и устанавливает соответствующий Content-Type заголовок (text/html или text/plain)
  • Ответ при успехе (200): 
    {
  "status": "success",
  "message": "Email sent successfully",
  "from": "sender@example.com",
  "to": "recipient@example.com",
  "subject": "Тема письма"
}
  • Ответ при ошибке (400/401/500): 
    {
  "status": "error",
  "error": "Описание ошибки"
}
  • Health check: GET http://localhost:{PORT}/health возвращает статус сервиса

Управление endpoint'ами

  • Просмотр списка всех созданных endpoint с информацией о порте, статусе, API ключе, дате создания
  • Запуск/остановка/перезапуск endpoint через systemctl
  • Просмотр журналов endpoint через journalctl
  • Показ примеров использования с curl
  • Удаление endpoint с остановкой сервиса и очисткой файлов
  • Автоматическое удаление endpoint'ов при полной очистке данных почтового сервера

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

  • Аутентификация через API ключ в заголовке X-API-Key
  • Валидация email адресов перед отправкой
  • Проверка обязательных полей в запросе
  • Логирование всех операций отправки писем
  • Изоляция выполнения через systemd сервис