vault backup: 2025-08-04 16:10:16
This commit is contained in:
Andrey Epifancev
@@ -1,292 +0,0 @@
|
||||
# Единое приложение Hugo + Webhook
|
||||
|
||||
## 1. Концепция
|
||||
|
||||
### 1.1 Общая идея
|
||||
Создание единого приложения на Go, которое объединяет webhook сервер и Hugo генератор статического сайта. Приложение обрабатывает Git webhook и автоматически пересобирает сайт при изменениях в репозитории.
|
||||
|
||||
### 1.2 Преимущества единого приложения
|
||||
- **Простота развертывания**: Один контейнер вместо нескольких
|
||||
- **Эффективность ресурсов**: Меньше накладных расходов
|
||||
- **Простота мониторинга**: Единая точка наблюдения
|
||||
- **Атомарность операций**: Все операции в одном процессе
|
||||
- **Простота отладки**: Единый лог и контекст
|
||||
|
||||
### 1.3 Недостатки единого приложения
|
||||
- **Менее гибкое масштабирование**: Сложность горизонтального масштабирования
|
||||
- **Сложность при росте функциональности**: Монолитная архитектура
|
||||
- **Единая точка отказа**: Все компоненты в одном процессе
|
||||
- **Сложность обновлений**: Необходимость пересборки всего приложения
|
||||
|
||||
## 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[Shared Volume]
|
||||
F --> G[Nginx]
|
||||
|
||||
subgraph "Единое приложение"
|
||||
B
|
||||
C
|
||||
D
|
||||
E
|
||||
end
|
||||
|
||||
subgraph "Внешние сервисы"
|
||||
A
|
||||
F
|
||||
G
|
||||
end
|
||||
```
|
||||
|
||||
### 2.2 Структура приложения
|
||||
|
||||
**Основные модули:**
|
||||
- **HTTP Server**: Обработка входящих запросов
|
||||
- **Webhook Handler**: Валидация и обработка webhook
|
||||
- **Git Manager**: Клонирование и обновление репозитория
|
||||
- **Hugo Builder**: Сборка статического сайта
|
||||
- **File Manager**: Управление файловой системой
|
||||
|
||||
## 3. Флоу обработки
|
||||
|
||||
### 3.1 Основной флоу
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A[Получение webhook] --> B[Валидация подписи]
|
||||
B --> C[Проверка ветки]
|
||||
C --> D[Обновление репозитория]
|
||||
D --> E[Проверка изменений]
|
||||
E --> F[Сборка Hugo]
|
||||
F --> G[Автоматическое обновление статики]
|
||||
G --> H[Отправка уведомления]
|
||||
|
||||
subgraph "Обработка ошибок"
|
||||
I[Retry логика]
|
||||
J[Fallback механизмы]
|
||||
K[Логирование ошибок]
|
||||
end
|
||||
|
||||
E --> I
|
||||
F --> J
|
||||
G --> K
|
||||
```
|
||||
|
||||
### 3.2 Детальный флоу
|
||||
|
||||
**Этап 1: Получение и валидация**
|
||||
- Получение webhook от Git (GitHub, GitLab, Gitea)
|
||||
- Валидация подписи webhook
|
||||
- Проверка типа события (push, merge)
|
||||
- Проверка целевой ветки
|
||||
|
||||
**Этап 2: Работа с репозиторием**
|
||||
- Клонирование репозитория (если первый раз)
|
||||
- Pull последних изменений
|
||||
- Проверка наличия изменений в контенте
|
||||
- Очистка временных файлов
|
||||
|
||||
**Этап 3: Сборка сайта**
|
||||
- Проверка конфигурации Hugo
|
||||
- Запуск Hugo сборки
|
||||
- Обработка ошибок сборки
|
||||
- Оптимизация статических файлов
|
||||
|
||||
**Этап 4: Развертывание**
|
||||
- Автоматическое обновление файлов в общем volume
|
||||
- Проверка целостности файлов
|
||||
- Nginx автоматически раздает обновленный контент
|
||||
|
||||
**Этап 5: Уведомления**
|
||||
- Отправка статуса в Telegram
|
||||
- Логирование результата
|
||||
- Обновление метрик
|
||||
|
||||
## 4. Конфигурация
|
||||
|
||||
### 4.1 Основные параметры
|
||||
|
||||
**Git настройки:**
|
||||
- URL репозитория
|
||||
- Ветка для отслеживания
|
||||
- SSH ключи или токены
|
||||
- Webhook секрет
|
||||
|
||||
**Hugo настройки:**
|
||||
- Путь к исходникам
|
||||
- Путь для сборки (общий volume)
|
||||
- Конфигурационный файл
|
||||
- Параметры оптимизации
|
||||
|
||||
**Системные настройки:**
|
||||
- Пути для статических файлов
|
||||
- Настройки логирования
|
||||
- Общий volume для Hugo и Nginx
|
||||
|
||||
### 4.2 Переменные окружения
|
||||
|
||||
**Обязательные:**
|
||||
- GIT_REPOSITORY_URL
|
||||
- GIT_WEBHOOK_SECRET
|
||||
- HUGO_SOURCE_PATH
|
||||
- HUGO_OUTPUT_PATH
|
||||
- SHARED_VOLUME_PATH
|
||||
|
||||
**Опциональные:**
|
||||
- TELEGRAM_BOT_TOKEN
|
||||
- TELEGRAM_CHAT_ID
|
||||
- LOG_LEVEL
|
||||
- METRICS_PORT
|
||||
|
||||
## 5. Обработка ошибок
|
||||
|
||||
### 5.1 Типы ошибок
|
||||
|
||||
**Git ошибки:**
|
||||
- Недоступность репозитория
|
||||
- Конфликты при merge
|
||||
- Проблемы с аутентификацией
|
||||
- Отсутствие изменений
|
||||
|
||||
**Hugo ошибки:**
|
||||
- Ошибки в конфигурации
|
||||
- Проблемы с шаблонами
|
||||
- Ошибки в Markdown файлах
|
||||
- Недостаток ресурсов
|
||||
|
||||
**Системные ошибки:**
|
||||
- Проблемы с файловой системой
|
||||
- Проблемы с общим volume
|
||||
- Проблемы с сетью
|
||||
- Недостаток места на диске
|
||||
|
||||
### 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 Идеальные сценарии
|
||||
- Один пользователь или небольшая команда
|
||||
- VPS с ограниченными ресурсами
|
||||
- Простота развертывания важнее масштабируемости
|
||||
- Быстрая итерация и отладка
|
||||
|
||||
### 10.2 Неподходящие сценарии
|
||||
- Большие команды разработчиков
|
||||
- Высокие требования к масштабируемости
|
||||
- Сложная микросервисная архитектура
|
||||
- Критически важные production системы
|
||||
@@ -1,322 +0,0 @@
|
||||
# Миграция контента на Hugo
|
||||
|
||||
## 1. Понимание архитектуры
|
||||
|
||||
### 1.1 Флоу работы
|
||||
```
|
||||
Obsidian Vault → Hugo → Static Site → Nginx (в Docker)
|
||||
```
|
||||
|
||||
**Компоненты:**
|
||||
- **Obsidian Vault**: Исходные Markdown документы
|
||||
- **Hugo**: Генератор статического сайта на Go
|
||||
- **Static Site**: Оптимизированные HTML/CSS/JS файлы
|
||||
- **Nginx**: Веб-сервер в Docker контейнере
|
||||
|
||||
## 2. Сохранение структуры каталогов
|
||||
|
||||
### 2.1 Принцип "не трогать структуру"
|
||||
|
||||
**Ключевое правило:** Структура каталогов в Git остается неизменной, Hugo адаптируется под неё.
|
||||
|
||||
**Преимущества:**
|
||||
- Сохранение удобной навигации в Obsidian
|
||||
- Отсутствие необходимости переименовывать файлы
|
||||
- Сохранение существующих ссылок
|
||||
- Простота миграции
|
||||
|
||||
### 2.2 Адаптация Hugo под существующую структуру
|
||||
|
||||
**Текущая структура (остается неизменной):**
|
||||
```
|
||||
Second Mind/
|
||||
├── index.md
|
||||
├── Идеи/
|
||||
│ ├── Obsidian телеграм бот/
|
||||
│ │ ├── MVP Telegram бота для Obsidian.md
|
||||
│ │ └── Telegram бот для Obsidian.md
|
||||
│ └── Оптимизация ресурсов VPS/
|
||||
│ ├── Единое приложение Hugo + Webhook.md
|
||||
│ └── Миграция контента на Hugo.md
|
||||
├── Мой сервер/
|
||||
│ ├── Authelia Authentication/
|
||||
│ ├── Git Service/
|
||||
│ ├── Second Mind Setup/
|
||||
│ └── Traefik Reverse Proxy/
|
||||
└── Документация сервера aepif.ru.md
|
||||
```
|
||||
|
||||
**Hugo конфигурация для работы с существующей структурой:**
|
||||
- Настройки для работы с существующей структурой
|
||||
- Поддержка Obsidian-специфичных элементов
|
||||
- Сохранение кириллических имен
|
||||
|
||||
### 2.3 Обработка имен файлов и каталогов
|
||||
|
||||
**Стратегия Hugo:**
|
||||
- Использование оригинальных имен файлов и каталогов
|
||||
- Автоматическое создание slug из имен файлов
|
||||
- Сохранение кириллических имен
|
||||
- Обработка пробелов и специальных символов
|
||||
|
||||
**URL структура:**
|
||||
- `/идеи/obsidian-телеграм-бот/mvp-telegram-бота-для-obsidian/`
|
||||
- `/мой-сервер/authelia-authentication/`
|
||||
- Сохранение читаемости URL
|
||||
|
||||
## 3. Граф записей (Graph View)
|
||||
|
||||
### 3.1 Аналоги Obsidian/Quartz графа
|
||||
|
||||
**Доступные решения для Hugo:**
|
||||
|
||||
**Встроенные возможности Hugo:**
|
||||
- Автоматическое создание графа связей между страницами
|
||||
- Визуализация внутренних ссылок
|
||||
- Отображение связанных страниц
|
||||
- Интерактивная карта знаний
|
||||
|
||||
**Сторонние библиотеки:**
|
||||
- D3.js для интерактивной визуализации
|
||||
- Vis.js для сетевых графов
|
||||
- Cytoscape.js для сложных графов
|
||||
- Sigma.js для больших сетей
|
||||
|
||||
### 3.2 Функциональность графа
|
||||
|
||||
**Визуализация связей:**
|
||||
- Отображение всех внутренних ссылок между страницами
|
||||
- Размер узлов в зависимости от количества связей
|
||||
- Цветовая кодировка по категориям/тегам
|
||||
- Интерактивная навигация по графу
|
||||
|
||||
**Интерактивность:**
|
||||
- Клик по узлу для перехода к странице
|
||||
- Зум и панорамирование графа
|
||||
- Фильтрация по тегам или категориям
|
||||
- Поиск по названиям страниц
|
||||
|
||||
**Аналитика:**
|
||||
- Центральные страницы (много связей)
|
||||
- Изолированные страницы (мало связей)
|
||||
- Кластеры связанных тем
|
||||
- Пути между страницами
|
||||
|
||||
### 3.3 Интеграция с существующей структурой
|
||||
|
||||
**Автоматическое создание графа:**
|
||||
- Анализ всех Markdown файлов
|
||||
- Извлечение внутренних ссылок
|
||||
- Создание JSON данных для графа
|
||||
- Генерация интерактивной визуализации
|
||||
|
||||
**Сохранение Obsidian-стиля:**
|
||||
- Похожий интерфейс на Obsidian Graph View
|
||||
- Те же принципы навигации
|
||||
- Совместимость с существующими ссылками
|
||||
- Поддержка кириллических названий
|
||||
|
||||
## 4. Миграция контента
|
||||
|
||||
### 4.1 Основные изменения при миграции
|
||||
|
||||
**Frontmatter преобразования:**
|
||||
- Сохранение существующих полей
|
||||
- Добавление Hugo-специфичных полей (title, date, draft)
|
||||
- Автоматическое извлечение заголовка из имени файла
|
||||
- Преобразование дат в стандартный формат
|
||||
|
||||
**Внутренние ссылки:**
|
||||
- `[[wiki links]]` → `{{< ref "path" >}}`
|
||||
- Сохранение относительных путей
|
||||
- Обработка Obsidian-специфичных ссылок
|
||||
- Автоматическое обновление ссылок при изменении структуры
|
||||
|
||||
**Изображения и вложения:**
|
||||
- Сохранение в той же структуре каталогов
|
||||
- Обновление путей в контенте
|
||||
- Оптимизация размера файлов без изменения структуры
|
||||
|
||||
### 4.2 Автоматизация миграции
|
||||
|
||||
**Скрипт миграции:**
|
||||
- Анализ существующей структуры
|
||||
- Автоматическое создание Hugo конфигурации
|
||||
- Преобразование frontmatter
|
||||
- Обновление внутренних ссылок
|
||||
- Сохранение структуры каталогов
|
||||
|
||||
## 5. Docker развертывание
|
||||
|
||||
### 5.1 Архитектура контейнеров
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A[Git Repository] --> B[Hugo + Webhook Container]
|
||||
B --> C[Shared Volume]
|
||||
C --> D[Nginx Container]
|
||||
D --> E[Internet]
|
||||
|
||||
subgraph "Docker Host"
|
||||
B
|
||||
C
|
||||
D
|
||||
end
|
||||
```
|
||||
|
||||
### 5.2 Структура Docker
|
||||
|
||||
**Docker Compose:**
|
||||
- Hugo + Webhook контейнер с прямым монтированием существующей структуры
|
||||
- Nginx контейнер для раздачи статики
|
||||
- Общий volume для статических файлов
|
||||
- Автоматическое обновление контента без перезагрузки
|
||||
|
||||
### 5.3 Преимущества общего volume
|
||||
|
||||
**Для пользователя:**
|
||||
- Знакомая навигация в Obsidian
|
||||
- Отсутствие необходимости переучиваться
|
||||
- Сохранение всех существующих ссылок
|
||||
- Простота поиска файлов
|
||||
|
||||
**Для системы:**
|
||||
- Минимальные изменения в Git репозитории
|
||||
- Простота отката к предыдущей версии
|
||||
- Сохранение истории изменений
|
||||
- Совместимость с существующими инструментами
|
||||
- Автоматическое обновление без перезагрузки сервисов
|
||||
|
||||
## 6. Интеграция с Obsidian
|
||||
|
||||
### 6.1 Рабочий флоу
|
||||
|
||||
**Разработка (без изменений):**
|
||||
1. Редактирование в Obsidian
|
||||
2. Коммит в Git репозиторий
|
||||
3. Webhook автоматически запускает сборку
|
||||
4. Hugo генерирует новый сайт
|
||||
5. Nginx автоматически раздает обновленный контент
|
||||
|
||||
**Синхронизация:**
|
||||
- Obsidian Vault → Git Repository (без изменений)
|
||||
- Git Repository → Hugo Content (прямое использование)
|
||||
- Hugo Content → Static Site (с сохранением структуры)
|
||||
- Static Site → Nginx (через общий volume)
|
||||
|
||||
### 6.2 Автоматизация
|
||||
|
||||
**Git Hooks (без изменений):**
|
||||
- Автоматический коммит при изменениях в Obsidian
|
||||
- Push в удаленный репозиторий
|
||||
- Webhook уведомление
|
||||
|
||||
**Webhook обработка:**
|
||||
- Валидация изменений
|
||||
- Клонирование/обновление репозитория
|
||||
- Сборка Hugo с сохранением структуры
|
||||
- Автоматическое обновление в общем volume
|
||||
|
||||
## 7. Конфигурация Hugo
|
||||
|
||||
### 7.1 Базовая конфигурация
|
||||
|
||||
**Основные параметры:**
|
||||
- Настройки для сохранения структуры
|
||||
- Поддержка оригинальных имен файлов
|
||||
- Включение поиска и навигации
|
||||
- Настройки для графа записей
|
||||
|
||||
### 7.2 Оптимизации для VPS
|
||||
|
||||
**Производительность:**
|
||||
- Минификация всех ресурсов
|
||||
- Оптимизация изображений
|
||||
- Gzip сжатие
|
||||
- Кэширование статических файлов
|
||||
|
||||
**Ресурсы:**
|
||||
- Ограничение использования памяти
|
||||
- Оптимизация времени сборки
|
||||
- Эффективное использование диска
|
||||
|
||||
## 8. Сравнение Hugo vs Quartz
|
||||
|
||||
### 8.1 Преимущества Hugo перед Quartz
|
||||
|
||||
**Производительность:**
|
||||
- **Время сборки**: Hugo в 5-10 раз быстрее
|
||||
- **Потребление памяти**: Снижение на 70-80%
|
||||
- **CPU нагрузка**: Минимальная нагрузка
|
||||
- **Время загрузки**: Улучшение на 40-60%
|
||||
|
||||
**Технические:**
|
||||
- **Язык**: Go vs Node.js (более эффективный)
|
||||
- **Зависимости**: Минимальные vs множество npm пакетов
|
||||
- **Размер**: Один бинарник vs множество файлов
|
||||
- **Сборка**: Компиляция vs интерпретация
|
||||
|
||||
**Операционные:**
|
||||
- **Развертывание**: Простое Docker развертывание
|
||||
- **Мониторинг**: Встроенные метрики
|
||||
- **Безопасность**: Меньше уязвимостей
|
||||
- **Стабильность**: Более предсказуемое поведение
|
||||
|
||||
### 8.2 Недостатки Hugo перед Quartz
|
||||
|
||||
**Функциональность:**
|
||||
- **Готовые компоненты**: Меньше готовых решений
|
||||
- **Экосистема**: Меньше плагинов и тем
|
||||
- **Гибкость**: Менее гибкая настройка
|
||||
- **Сообщество**: Меньше готовых решений для Obsidian
|
||||
|
||||
**Разработка:**
|
||||
- **Кривая обучения**: Сложнее для новичков
|
||||
- **Документация**: Меньше примеров для Obsidian
|
||||
- **Отладка**: Сложнее отладка шаблонов
|
||||
- **Кастомизация**: Требует больше знаний
|
||||
|
||||
**Интеграция:**
|
||||
- **Obsidian специфика**: Меньше готовых решений
|
||||
- **Wiki ссылки**: Требует дополнительной обработки
|
||||
- **Frontmatter**: Другой формат
|
||||
- **Плагины**: Ограниченная совместимость
|
||||
|
||||
## 9. Преимущества миграции
|
||||
|
||||
### 9.1 Производительность
|
||||
- **Время сборки**: С 30-60 секунд до 5-10 секунд
|
||||
- **Потребление памяти**: С 512MB до 128MB
|
||||
- **CPU нагрузка**: Снижение на 70-80%
|
||||
- **Время загрузки**: Улучшение на 40-60%
|
||||
|
||||
### 9.2 Операционные
|
||||
- **Простота развертывания**: Docker Compose
|
||||
- **Изоляция**: Контейнеры
|
||||
- **Автоматическое обновление**: Без перезагрузки сервисов
|
||||
- **Масштабируемость**: Легкое горизонтальное масштабирование
|
||||
- **Мониторинг**: Встроенные метрики
|
||||
|
||||
### 9.3 Интеграция
|
||||
- **Сохранение рабочего флоу**: Obsidian → Git → Hugo
|
||||
- **Сохранение структуры**: Без изменений в организации файлов
|
||||
- **Граф записей**: Интерактивная визуализация связей
|
||||
- **Автоматизация**: Webhook → Сборка → Деплой
|
||||
- **Консистентность**: Один источник истины
|
||||
- **Простота отладки**: Единый лог и контекст
|
||||
|
||||
## 10. Применимость
|
||||
|
||||
### 10.1 Идеальные сценарии
|
||||
- Один пользователь или небольшая команда
|
||||
- VPS с ограниченными ресурсами
|
||||
- Простота развертывания важнее сложной функциональности
|
||||
- Быстрая итерация и отладка
|
||||
- Готовность к дополнительной настройке
|
||||
|
||||
### 10.2 Неподходящие сценарии
|
||||
- Большие команды разработчиков
|
||||
- Критически важные production системы
|
||||
- Сложные требования к кастомизации
|
||||
- Необходимость готовых решений "из коробки"
|
||||
- Ограниченное время на настройку
|
||||
Reference in New Issue
Block a user