299 lines
10 KiB
Markdown
299 lines
10 KiB
Markdown
# Единое приложение Hugo + Webhook
|
||
|
||
## 1. Концепция
|
||
|
||
### 1.1 Общая идея
|
||
Объединение webhook сервера и Hugo в одно приложение на Go, которое обрабатывает Git webhook и автоматически пересобирает сайт при изменениях.
|
||
|
||
### 1.2 Преимущества единого приложения
|
||
- **Простота развертывания**: Один контейнер вместо нескольких
|
||
- **Эффективность ресурсов**: Меньше накладных расходов
|
||
- **Простота мониторинга**: Единая точка наблюдения
|
||
- **Атомарность операций**: Все операции в одном процессе
|
||
- **Простота отладки**: Единый лог и контекст
|
||
|
||
## 2. Архитектура
|
||
|
||
### 2.1 Компонентная диаграмма
|
||
|
||
```mermaid
|
||
graph TB
|
||
A[Git Webhook] --> B[HTTP Server]
|
||
B --> C[Webhook Handler]
|
||
C --> D[Git Manager]
|
||
D --> E[Hugo Builder]
|
||
E --> F[File System]
|
||
F --> G[Nginx Reload]
|
||
|
||
subgraph "Единое приложение"
|
||
B
|
||
C
|
||
D
|
||
E
|
||
end
|
||
|
||
subgraph "Внешние сервисы"
|
||
A
|
||
F
|
||
G
|
||
end
|
||
```
|
||
|
||
### 2.2 Структура приложения
|
||
|
||
**Основные модули:**
|
||
- **HTTP Server**: Обработка входящих запросов
|
||
- **Webhook Handler**: Валидация и обработка webhook
|
||
- **Git Manager**: Клонирование и обновление репозитория
|
||
- **Hugo Builder**: Сборка статического сайта
|
||
- **File Manager**: Управление файловой системой
|
||
- **Nginx Controller**: Перезагрузка веб-сервера
|
||
|
||
## 3. Флоу обработки
|
||
|
||
### 3.1 Основной флоу
|
||
|
||
```mermaid
|
||
graph TB
|
||
A[Получение webhook] --> B[Валидация подписи]
|
||
B --> C[Проверка ветки]
|
||
C --> D[Обновление репозитория]
|
||
D --> E[Проверка изменений]
|
||
E --> F[Сборка Hugo]
|
||
F --> G[Копирование файлов]
|
||
G --> H[Перезагрузка Nginx]
|
||
H --> I[Отправка уведомления]
|
||
|
||
subgraph "Обработка ошибок"
|
||
J[Retry логика]
|
||
K[Fallback механизмы]
|
||
L[Логирование ошибок]
|
||
end
|
||
|
||
E --> J
|
||
F --> K
|
||
H --> L
|
||
```
|
||
|
||
### 3.2 Детальный флоу
|
||
|
||
**Этап 1: Получение и валидация**
|
||
- Получение webhook от Git (GitHub, GitLab, Gitea)
|
||
- Валидация подписи webhook
|
||
- Проверка типа события (push, merge)
|
||
- Проверка целевой ветки
|
||
|
||
**Этап 2: Работа с репозиторием**
|
||
- Клонирование репозитория (если первый раз)
|
||
- Pull последних изменений
|
||
- Проверка наличия изменений в контенте
|
||
- Очистка временных файлов
|
||
|
||
**Этап 3: Сборка сайта**
|
||
- Проверка конфигурации Hugo
|
||
- Запуск Hugo сборки
|
||
- Обработка ошибок сборки
|
||
- Оптимизация статических файлов
|
||
|
||
**Этап 4: Развертывание**
|
||
- Резервное копирование текущего сайта
|
||
- Копирование новых файлов
|
||
- Проверка целостности файлов
|
||
- Перезагрузка Nginx
|
||
|
||
**Этап 5: Уведомления**
|
||
- Отправка статуса в Telegram
|
||
- Логирование результата
|
||
- Обновление метрик
|
||
|
||
## 4. Конфигурация
|
||
|
||
### 4.1 Основные параметры
|
||
|
||
**Git настройки:**
|
||
- URL репозитория
|
||
- Ветка для отслеживания
|
||
- SSH ключи или токены
|
||
- Webhook секрет
|
||
|
||
**Hugo настройки:**
|
||
- Путь к исходникам
|
||
- Путь для сборки
|
||
- Конфигурационный файл
|
||
- Параметры оптимизации
|
||
|
||
**Системные настройки:**
|
||
- Путь к Nginx конфигурации
|
||
- Команда перезагрузки
|
||
- Пути для статических файлов
|
||
- Настройки логирования
|
||
|
||
### 4.2 Переменные окружения
|
||
|
||
**Обязательные:**
|
||
- GIT_REPOSITORY_URL
|
||
- GIT_WEBHOOK_SECRET
|
||
- HUGO_SOURCE_PATH
|
||
- HUGO_OUTPUT_PATH
|
||
- NGINX_RELOAD_COMMAND
|
||
|
||
**Опциональные:**
|
||
- TELEGRAM_BOT_TOKEN
|
||
- TELEGRAM_CHAT_ID
|
||
- LOG_LEVEL
|
||
- METRICS_PORT
|
||
|
||
## 5. Обработка ошибок
|
||
|
||
### 5.1 Типы ошибок
|
||
|
||
**Git ошибки:**
|
||
- Недоступность репозитория
|
||
- Конфликты при merge
|
||
- Проблемы с аутентификацией
|
||
- Отсутствие изменений
|
||
|
||
**Hugo ошибки:**
|
||
- Ошибки в конфигурации
|
||
- Проблемы с шаблонами
|
||
- Ошибки в Markdown файлах
|
||
- Недостаток ресурсов
|
||
|
||
**Системные ошибки:**
|
||
- Проблемы с файловой системой
|
||
- Ошибки Nginx
|
||
- Проблемы с сетью
|
||
- Недостаток места на диске
|
||
|
||
### 5.2 Стратегии восстановления
|
||
|
||
**Retry логика:**
|
||
- Автоматические повторные попытки
|
||
- Экспоненциальная задержка
|
||
- Максимальное количество попыток
|
||
- Graceful degradation
|
||
|
||
**Fallback механизмы:**
|
||
- Использование последней успешной сборки
|
||
- Откат к предыдущей версии
|
||
- Уведомления администратора
|
||
- Логирование для анализа
|
||
|
||
## 6. Мониторинг и метрики
|
||
|
||
### 6.1 Ключевые метрики
|
||
|
||
**Производительность:**
|
||
- Время обработки webhook
|
||
- Время сборки Hugo
|
||
- Размер генерируемых файлов
|
||
- Частота обновлений
|
||
|
||
**Надежность:**
|
||
- Количество успешных сборок
|
||
- Количество ошибок по типам
|
||
- Время восстановления
|
||
- Доступность сервиса
|
||
|
||
**Ресурсы:**
|
||
- Использование CPU
|
||
- Использование памяти
|
||
- Использование диска
|
||
- Сетевой трафик
|
||
|
||
### 6.2 Алерты
|
||
|
||
**Критические:**
|
||
- Сборка не завершилась в течение 5 минут
|
||
- Ошибки webhook валидации
|
||
- Проблемы с файловой системой
|
||
- Недоступность сайта
|
||
|
||
**Предупреждения:**
|
||
- Высокое время сборки
|
||
- Большой размер файлов
|
||
- Частые ошибки
|
||
- Низкое место на диске
|
||
|
||
## 7. Безопасность
|
||
|
||
### 7.1 Webhook безопасность
|
||
- Валидация подписи webhook
|
||
- Проверка IP адресов
|
||
- Rate limiting
|
||
- Логирование подозрительной активности
|
||
|
||
### 7.2 Системная безопасность
|
||
- Запуск от непривилегированного пользователя
|
||
- Ограничение доступа к файлам
|
||
- Шифрование чувствительных данных
|
||
- Регулярные обновления
|
||
|
||
### 7.3 Git безопасность
|
||
- Использование SSH ключей
|
||
- Проверка подписи коммитов
|
||
- Ограничение доступа к репозиторию
|
||
- Мониторинг изменений
|
||
|
||
## 8. Развертывание
|
||
|
||
### 8.1 Docker контейнер
|
||
- Многоэтапная сборка
|
||
- Минимальный образ на Alpine
|
||
- Включение Hugo и Git
|
||
- Оптимизация размера
|
||
|
||
### 8.2 Конфигурация
|
||
- Environment variables
|
||
- Конфигурационные файлы
|
||
- Volume mounts для данных
|
||
- Health checks
|
||
|
||
### 8.3 Orchestration
|
||
- Docker Compose для разработки
|
||
- Kubernetes для production
|
||
- Автоматическое масштабирование
|
||
- Rolling updates
|
||
|
||
## 9. Преимущества единого приложения
|
||
|
||
### 9.1 Операционные преимущества
|
||
- **Простота развертывания**: Один контейнер
|
||
- **Упрощенный мониторинг**: Единая точка наблюдения
|
||
- **Атомарность**: Все операции в одном процессе
|
||
- **Отладка**: Единый лог и контекст
|
||
|
||
### 9.2 Технические преимущества
|
||
- **Эффективность ресурсов**: Меньше накладных расходов
|
||
- **Производительность**: Прямая связь между компонентами
|
||
- **Надежность**: Меньше точек отказа
|
||
- **Безопасность**: Единая точка контроля
|
||
|
||
### 9.3 Преимущества разработки
|
||
- **Простота кода**: Единая кодовая база
|
||
- **Тестирование**: Интеграционные тесты
|
||
- **Версионирование**: Единая версия приложения
|
||
- **Документация**: Единая документация
|
||
|
||
## 10. Сравнение с раздельными сервисами
|
||
|
||
### 10.1 Единое приложение vs Микросервисы
|
||
|
||
**Единое приложение:**
|
||
- ✅ Простота развертывания
|
||
- ✅ Эффективность ресурсов
|
||
- ✅ Простота отладки
|
||
- ✅ Атомарность операций
|
||
- ❌ Менее гибкое масштабирование
|
||
- ❌ Сложность при росте функциональности
|
||
|
||
**Микросервисы:**
|
||
- ✅ Гибкое масштабирование
|
||
- ✅ Независимое развитие
|
||
- ✅ Отказоустойчивость
|
||
- ❌ Сложность развертывания
|
||
- ❌ Накладные расходы
|
||
- ❌ Сложность отладки
|
||
|
||
### 10.2 Рекомендация
|
||
Для текущих потребностей (один пользователь, VPS с ограниченными ресурсами) единое приложение является оптимальным решением. |