vault backup: 2025-08-04 15:31:52
This commit is contained in:
Andrey Epifancev
@@ -0,0 +1,299 @@
|
|||||||
|
# Единое приложение 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 с ограниченными ресурсами) единое приложение является оптимальным решением.
|
||||||
Reference in New Issue
Block a user