222 lines
7.9 KiB
Markdown
222 lines
7.9 KiB
Markdown
# План переезда с Quartz на Hugo
|
||
|
||
## 1. Обоснование переезда
|
||
|
||
### 1.1 Проблемы текущего решения (Quartz)
|
||
- **Высокое потребление ресурсов**: Node.js + множество зависимостей
|
||
- **Медленная сборка**: Особенно при большом количестве заметок
|
||
- **Сложность настройки**: Множество конфигурационных файлов
|
||
- **Ограниченная кастомизация**: Зависимость от готовых компонентов
|
||
- **Проблемы с производительностью**: На VPS с ограниченными ресурсами
|
||
|
||
### 1.2 Преимущества Hugo
|
||
- **Быстрая сборка**: Написан на Go, компилируется в бинарник
|
||
- **Низкое потребление ресурсов**: Минимальные требования к CPU/RAM
|
||
- **Простота развертывания**: Один бинарник + статические файлы
|
||
- **Гибкость**: Полный контроль над шаблонами и стилями
|
||
- **SEO-оптимизация**: Встроенные возможности для SEO
|
||
- **Богатая экосистема**: Множество готовых тем и плагинов
|
||
|
||
## 2. Архитектура нового решения
|
||
|
||
### 2.1 Общая схема
|
||
|
||
```mermaid
|
||
graph TB
|
||
A[Git Repository] --> B[Webhook Server Go]
|
||
B --> C[Hugo Builder]
|
||
C --> D[Static Files]
|
||
D --> E[Nginx Server]
|
||
F[Traefik Proxy] --> E
|
||
F --> B
|
||
|
||
subgraph "Second Mind Container"
|
||
B
|
||
C
|
||
end
|
||
|
||
subgraph "External Services"
|
||
A
|
||
F
|
||
end
|
||
```
|
||
|
||
### 2.2 Компоненты системы
|
||
|
||
**Webhook Server (Go)**
|
||
- Обработка webhook от Git
|
||
- Запуск Hugo сборки
|
||
- Управление процессом деплоя
|
||
- Логирование и мониторинг
|
||
|
||
**Hugo Builder**
|
||
- Генерация статических файлов
|
||
- Обработка Markdown
|
||
- Применение темы и стилей
|
||
- Оптимизация ресурсов
|
||
|
||
**Nginx Server**
|
||
- Раздача статических файлов
|
||
- Кэширование
|
||
- Gzip сжатие
|
||
- SSL/TLS терминация
|
||
|
||
## 3. Техническая реализация
|
||
|
||
### 3.1 Webhook Server на Go
|
||
|
||
**Структура проекта:**
|
||
```
|
||
webhook-server/
|
||
├── cmd/
|
||
│ └── server/
|
||
│ └── main.go
|
||
├── internal/
|
||
│ ├── handler/
|
||
│ │ └── webhook.go
|
||
│ ├── builder/
|
||
│ │ └── hugo.go
|
||
│ └── config/
|
||
│ └── config.go
|
||
├── pkg/
|
||
│ └── git/
|
||
│ └── client.go
|
||
├── go.mod
|
||
├── go.sum
|
||
└── Dockerfile
|
||
```
|
||
|
||
**Основные функции:**
|
||
- Валидация webhook payload
|
||
- Клонирование/обновление репозитория
|
||
- Запуск Hugo сборки
|
||
- Обработка ошибок и retry логика
|
||
- Метрики и логирование
|
||
|
||
### 3.2 Hugo конфигурация
|
||
|
||
**Структура Hugo проекта:**
|
||
```
|
||
hugo-site/
|
||
├── config.toml
|
||
├── content/
|
||
│ ├── notes/
|
||
│ ├── daily/
|
||
│ └── templates/
|
||
├── layouts/
|
||
│ ├── _default/
|
||
│ ├── partials/
|
||
│ └── shortcodes/
|
||
├── static/
|
||
│ ├── css/
|
||
│ ├── js/
|
||
│ └── images/
|
||
└── themes/
|
||
└── custom-theme/
|
||
```
|
||
|
||
**Оптимизации:**
|
||
- Минификация CSS/JS
|
||
- Оптимизация изображений
|
||
- Кэширование статических ресурсов
|
||
- Lazy loading для изображений
|
||
|
||
### 3.3 Docker контейнеризация
|
||
|
||
**Dockerfile для webhook сервера:**
|
||
```dockerfile
|
||
FROM golang:1.21-alpine AS builder
|
||
WORKDIR /app
|
||
COPY go.mod go.sum ./
|
||
RUN go mod download
|
||
COPY . .
|
||
RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o main ./cmd/server
|
||
|
||
FROM alpine:latest
|
||
RUN apk --no-cache add ca-certificates hugo
|
||
WORKDIR /root/
|
||
COPY --from=builder /app/main .
|
||
EXPOSE 8080
|
||
CMD ["./main"]
|
||
```
|
||
|
||
## 4. План миграции
|
||
|
||
### 4.1 Этап 1: Подготовка (1-2 дня)
|
||
- [ ] Создание Hugo проекта
|
||
- [ ] Настройка базовой темы
|
||
- [ ] Миграция контента из Quartz
|
||
- [ ] Настройка URL структуры
|
||
|
||
### 4.2 Этап 2: Webhook Server (2-3 дня)
|
||
- [ ] Разработка Go webhook сервера
|
||
- [ ] Интеграция с Git API
|
||
- [ ] Настройка Hugo сборки
|
||
- [ ] Тестирование в dev окружении
|
||
|
||
### 4.3 Этап 3: Развертывание (1 день)
|
||
- [ ] Настройка Docker контейнеров
|
||
- [ ] Конфигурация Nginx
|
||
- [ ] Настройка SSL сертификатов
|
||
- [ ] Тестирование production окружения
|
||
|
||
### 4.4 Этап 4: Переключение (1 день)
|
||
- [ ] Обновление DNS записей
|
||
- [ ] Мониторинг производительности
|
||
- [ ] Резервное копирование старого решения
|
||
- [ ] Документирование изменений
|
||
|
||
## 5. Ожидаемые улучшения
|
||
|
||
### 5.1 Производительность
|
||
- **Время сборки**: С 30-60 секунд до 5-10 секунд
|
||
- **Потребление памяти**: С 512MB до 128MB
|
||
- **CPU нагрузка**: Снижение на 70-80%
|
||
- **Время загрузки страниц**: Улучшение на 40-60%
|
||
|
||
### 5.2 Операционные улучшения
|
||
- **Простота развертывания**: Один контейнер вместо множества сервисов
|
||
- **Мониторинг**: Встроенные метрики Go приложения
|
||
- **Безопасность**: Меньше зависимостей = меньше уязвимостей
|
||
- **Масштабируемость**: Легкое горизонтальное масштабирование
|
||
|
||
## 6. Риски и митигация
|
||
|
||
### 6.1 Технические риски
|
||
- **Потеря функциональности**: Тщательное тестирование всех компонентов
|
||
- **Проблемы с темой**: Создание собственной темы на основе существующей
|
||
- **SEO регрессия**: Сохранение URL структуры и метаданных
|
||
|
||
### 6.2 Операционные риски
|
||
- **Downtime при переключении**: Использование blue-green deployment
|
||
- **Проблемы с контентом**: Полное резервное копирование
|
||
- **Производительность**: Мониторинг и оптимизация
|
||
|
||
## 7. Мониторинг и метрики
|
||
|
||
### 7.1 Ключевые метрики
|
||
- Время сборки Hugo
|
||
- Размер генерируемых файлов
|
||
- Время ответа webhook сервера
|
||
- Потребление ресурсов контейнеров
|
||
- Время загрузки страниц
|
||
|
||
### 7.2 Алерты
|
||
- Сборка не завершилась в течение 60 секунд
|
||
- Ошибки webhook сервера
|
||
- Высокое потребление ресурсов
|
||
- Недоступность сайта
|
||
|
||
## 8. Документация и обучение
|
||
|
||
### 8.1 Техническая документация
|
||
- Архитектура системы
|
||
- Конфигурация компонентов
|
||
- Процедуры развертывания
|
||
- Troubleshooting guide
|
||
|
||
### 8.2 Операционная документация
|
||
- Процедуры мониторинга
|
||
- План аварийного восстановления
|
||
- Процедуры обновления
|
||
- Контакты ответственных лиц |