153 lines
5.4 KiB
Markdown
153 lines
5.4 KiB
Markdown
# Go Webhook Server
|
||
|
||
Go-версия webhook сервиса для автоматической пересборки Quartz сайта при получении webhook'а.
|
||
|
||
## Особенности
|
||
|
||
- **Написан на Go** - быстрый и эффективный
|
||
- **Использует Gin** - легковесный веб-фреймворк
|
||
- **Интеграция с Git** - автоматическое обновление репозитория
|
||
- **Асинхронная обработка** - webhook'и обрабатываются в фоне
|
||
- **Graceful shutdown** - корректное завершение работы
|
||
- **Структурированное логирование** - с использованием logrus
|
||
- **Конфигурируемость** - через переменные окружения
|
||
|
||
## Архитектура
|
||
|
||
Сервис состоит из следующих компонентов:
|
||
|
||
1. **HTTP сервер** на Gin с эндпоинтами:
|
||
- `POST /webhook` - основной webhook для пересборки
|
||
- `GET /health` - проверка состояния сервиса
|
||
|
||
2. **Git интеграция** - автоматическое обновление репозитория Obsidian
|
||
3. **Quartz сборка** - запуск процесса сборки статического сайта
|
||
4. **Файловые операции** - копирование собранных файлов в публичную директорию
|
||
|
||
## Конфигурация
|
||
|
||
Сервис настраивается через переменные окружения:
|
||
|
||
| Переменная | Описание | По умолчанию |
|
||
|------------|----------|--------------|
|
||
| `PORT` | Порт для HTTP сервера | `3000` |
|
||
| `OBSIDIAN_PATH` | Путь к репозиторию Obsidian | `/obsidian` |
|
||
| `QUARTZ_PATH` | Путь к директории Quartz | `/quartz` |
|
||
| `PUBLIC_PATH` | Путь к публичной директории | `/public` |
|
||
| `GIT_BRANCH` | Ветка Git для обновления | `main` |
|
||
| `GIT_REMOTE` | Имя удаленного репозитория | `origin` |
|
||
|
||
## Запуск
|
||
|
||
### Локально
|
||
|
||
1. Установите Go 1.21+
|
||
2. Скачайте зависимости:
|
||
```bash
|
||
go mod download
|
||
```
|
||
3. Запустите сервис:
|
||
```bash
|
||
go run main.go
|
||
```
|
||
|
||
### В Docker
|
||
|
||
1. Соберите образ:
|
||
```bash
|
||
docker build -t go-webhook-server .
|
||
```
|
||
|
||
2. Запустите контейнер:
|
||
```bash
|
||
docker run -d \
|
||
--name go-webhook-server \
|
||
-p 3000:3000 \
|
||
-v obsidian_repo:/obsidian:ro \
|
||
-v quartz_repo:/quartz:ro \
|
||
-v public_site:/public \
|
||
go-webhook-server
|
||
```
|
||
|
||
### С Docker Compose
|
||
|
||
1. Запустите сервис:
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
## Использование
|
||
|
||
### Отправка webhook'а
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3000/webhook
|
||
```
|
||
|
||
### Проверка состояния
|
||
|
||
```bash
|
||
curl http://localhost:3000/health
|
||
```
|
||
|
||
## Процесс сборки
|
||
|
||
При получении webhook'а сервис выполняет:
|
||
|
||
1. **Проверка репозитория** - убеждается что Git репозиторий существует
|
||
2. **Обновление кода** - выполняет `git pull` для получения последних изменений
|
||
3. **Установка зависимостей** - запускает `npm install` если необходимо
|
||
4. **Сборка сайта** - запускает `npm run quartz build` с указанием директории Obsidian
|
||
5. **Копирование файлов** - копирует собранные файлы в публичную директорию
|
||
|
||
## Логирование
|
||
|
||
Сервис использует структурированное логирование с помощью logrus:
|
||
|
||
- **Info** - информационные сообщения о процессе сборки
|
||
- **Error** - ошибки, возникающие в процессе
|
||
- **HTTP логи** - все HTTP запросы с деталями
|
||
|
||
## Безопасность
|
||
|
||
- Контейнер запускается от непривилегированного пользователя
|
||
- Используется Alpine Linux для минимального attack surface
|
||
- Graceful shutdown для корректного завершения работы
|
||
|
||
## Мониторинг
|
||
|
||
Сервис предоставляет health check эндпоинт для мониторинга:
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"timestamp": "2025-01-27T10:30:00Z",
|
||
"service": "go-webhook-server",
|
||
"version": "1.0.0"
|
||
}
|
||
```
|
||
|
||
## Разработка
|
||
|
||
### Структура проекта
|
||
|
||
```
|
||
go-webhook-server/
|
||
├── main.go # Основной файл приложения
|
||
├── go.mod # Go модуль
|
||
├── go.sum # Хеши зависимостей
|
||
├── Dockerfile # Docker образ
|
||
├── docker-compose.yml # Docker Compose конфигурация
|
||
└── README.md # Документация
|
||
```
|
||
|
||
### Зависимости
|
||
|
||
- `github.com/gin-gonic/gin` - веб-фреймворк
|
||
- `github.com/go-git/go-git/v5` - Git клиент
|
||
- `github.com/sirupsen/logrus` - логирование
|
||
|
||
## Лицензия
|
||
|
||
MIT
|