149 lines
11 KiB
Markdown
149 lines
11 KiB
Markdown
# Архитектура API Sync
|
||
|
||
## Обзор
|
||
|
||
API Sync — однопроходная утилита (не демон), запускаемая по cron. При каждом запуске выполняет три последовательных этапа: синхронизацию данных из API в PostgreSQL, очистку устаревших записей и обновление whitelist-файла в Git-репозитории.
|
||
|
||
---
|
||
|
||
## Поток выполнения
|
||
|
||
```
|
||
main()
|
||
│
|
||
├─ 1. Подключение к PostgreSQL
|
||
│
|
||
├─ 2. Загрузка списка клиентов (client_info)
|
||
│
|
||
├─ 3. Сбор SID (apps_settings WHERE mode = 'auto')
|
||
│
|
||
├─ 4. Параллельная обработка SID (worker pool)
|
||
│ └─ processSID() для каждого SID
|
||
│ ├─ GET /l7/resource/{sid}/global → whois
|
||
│ ├─ GET /l7/origin/global?l7ResourceId={sid} → origins
|
||
│ ├─ GET /l7/alias/global?l7ResourceId={sid} → aliases
|
||
│ ├─ DNS резолв домена → проверка AntiDDOS
|
||
│ └─ upsertAPIInfo() → сравнение + запись в API_info + алерты
|
||
│
|
||
├─ 5. Очистка устаревших SID из API_info (cleanupRemovedSIDs)
|
||
│
|
||
└─ 6. Обновление WAF whitelist (updateWAFWhitelist)
|
||
├─ git pull
|
||
├─ Загрузка IP из API_info (auto)
|
||
├─ Загрузка IP из manual_info (ручные)
|
||
├─ Фильтрация WAF-сетей (таблица ips)
|
||
├─ Сравнение с текущим whitelist-файлом
|
||
├─ Запись файла + git commit + git push
|
||
└─ Отправка алерта об изменениях
|
||
```
|
||
|
||
---
|
||
|
||
## Модули
|
||
|
||
### main.go — точка входа и worker pool
|
||
|
||
Инициализирует подключение к БД, собирает все SID для обработки и запускает пул горутин. Количество воркеров задаётся через `MAX_CONCURRENT_WORKERS` (по умолчанию 5). SID передаются воркерам через буферизированный канал.
|
||
|
||
После завершения всех воркеров последовательно запускаются очистка устаревших записей и обновление whitelist.
|
||
|
||
### config.go — конфигурация
|
||
|
||
Загружает переменные окружения из `/etc/API_sync/API_sync.env` через `godotenv`. Если файл недоступен — использует системные переменные окружения. Все переменные инициализируются в `init()` до старта `main()`.
|
||
|
||
### api.go — HTTP-клиент и структуры API
|
||
|
||
Содержит единственный HTTP-клиент с таймаутом 20 секунд и функцию `apiGet()`, которая выполняет GET-запрос к API API с Bearer-авторизацией и десериализует JSON-ответ в переданную структуру.
|
||
|
||
Определены структуры ответов API: `originItem`, `aliasItem`, `whoisReAPIonse`, `apiList`.
|
||
|
||
### database.go — работа с PostgreSQL
|
||
|
||
**`loadClients()`** — загружает список клиентов из `client_info`.
|
||
|
||
**`loadL7IDs()`** — загружает SID из `apps_settings` для конкретного клиента с `mode = 'auto'`.
|
||
|
||
**`processSID()`** — оркестрирует обработку одного SID: делает три запроса к API, резолвит домен для проверки AntiDDOS, вызывает `upsertAPIInfo()`.
|
||
|
||
**`upsertAPIInfo()`** — сравнивает новые данные со старыми из БД и при наличии изменений формирует алерты:
|
||
- изменение домена → алерт + флаг необходимости обновления PT AF
|
||
- изменение origins (IP, mode, weight) — через `compareOrigins()`
|
||
- изменение aliases — через `compareAliases()`
|
||
- изменение WAF-настроек (vendor, instance, enabled) — отдельный алерт
|
||
|
||
Сохранение выполняется через `INSERT ... ON CONFLICT DO UPDATE` (upsert по `sid`).
|
||
|
||
**`cleanupRemovedSIDs()`** — сравнивает все SID в `API_info` с актуальным списком активных SID. Записи, которых нет в активном списке (ресурс удалён из `apps_settings` или сменил `mode`), удаляются из `API_info`. По каждому удалённому ресурсу отправляется алерт с указанием WAF-вендора (берётся из `apps_settings` через LEFT JOIN).
|
||
|
||
**`wafVendorWarning()`** — формирует строку предупреждения в зависимости от вендора: `ptaf` → PT AF, `sw` → SW, `wmx` → WMX.
|
||
|
||
### compare.go — функции сравнения
|
||
|
||
**`compareOrigins()`** — сравнивает два списка origins по IP-адресу. Определяет добавленные, удалённые и изменённые (mode/weight) записи. Возвращает отформатированную строку для алерта с текущим состоянием origins.
|
||
|
||
**`compareAliases()`** — сравнивает два отсортированных списка доменов. Возвращает строку с изменениями и булев флаг наличия изменений.
|
||
|
||
### dns.go — DNS-резолвер
|
||
|
||
Функция `resolveDomain()` возвращает первый IPv4-адрес для заданного домена. Используется в `processSID()` для проверки AntiDDOS: если resolvedIP совпадает с protectedIP из API — AntiDDOS активен.
|
||
|
||
### notify.go — система уведомлений
|
||
|
||
**`sendAlert()`** — единая точка отправки алертов. Последовательно отправляет сообщение во все настроенные каналы. Ошибка одного канала не блокирует остальные.
|
||
|
||
**Telegram** — `buildTelegramClient()` при каждой отправке выбирает транспорт в порядке приоритета:
|
||
1. HTTP-прокси (`TELEGRAM_HTTP_PROXY`) — если задан и доступен
|
||
2. SOCKS5-прокси (`TELEGRAM_SOCKS5_PROXY`) — если задан и доступен
|
||
3. Прямое подключение — fallback
|
||
|
||
Доступность проверяется реальным GET-запросом на `api.telegram.org`. Сообщения отправляются в формате HTML (`parse_mode: HTML`).
|
||
|
||
**Mattermost** — POST на `/api/v4/posts` с Bearer-токеном. HTML-теги Telegram конвертируются в Markdown через `htmlToMarkdown()`. Отправляется только если заполнены все три переменные: `MATTERMOST_URL`, `MATTERMOST_BOT_TOKEN`, `MATTERMOST_CHANNEL_ID`.
|
||
|
||
**Email** — через стандартный `net/smtp`. Поддерживает несколько адресов получателей через запятую в `EMAIL_TO`. Авторизация опциональна — если `EMAIL_SMTP_USER` пуст, отправка идёт без аутентификации (relay). HTML-теги Telegram удаляются через `stripHTMLTags()`. Отправляется только если заполнены `EMAIL_SMTP_HOST`, `EMAIL_FROM`, `EMAIL_TO`.
|
||
|
||
### git.go — Git-операции
|
||
|
||
**`syncGitRepo()`** — если репозиторий не существует локально — клонирует (`git clone`), иначе обновляет (`git pull`). Автоматически настраивает `user.email` и `user.name` для коммитов.
|
||
|
||
**`gitCommitAndPush()`** — выполняет `git add <whitelist_file>`, `git commit -m <message>`, `git push`. Если нечего коммитить (`nothing to commit`) — завершается без ошибки.
|
||
|
||
### whitelist.go — управление whitelist
|
||
|
||
**`updateWAFWhitelist()`** — основная функция обновления whitelist:
|
||
1. Синхронизирует Git-репозиторий
|
||
2. Загружает WAF-сети из таблицы `ips`
|
||
3. Загружает origin IP из `API_info` (`loadAllOrigins`) и `manual_info` (`loadManualOrigins`), объединяет и дедуплицирует
|
||
4. Фильтрует IP попадающие в WAF-сети (`filterNonWAFOrigins`)
|
||
5. Сравнивает с текущим содержимым файла (`compareWhitelists`)
|
||
6. При наличии изменений — перезаписывает файл, коммитит и пушит, отправляет алерт
|
||
|
||
**`loadManualOrigins()`** — загружает все записи из `manual_info` как есть, без дополнительных условий. Таблица заполняется администратором вручную и программой не изменяется.
|
||
|
||
**`filterNonWAFOrigins()`** — исключает из списка IP-адреса, которые принадлежат WAF-сетям из таблицы `ips`. Такие адреса являются узлами самого WAF и не должны попадать в whitelist.
|
||
|
||
---
|
||
|
||
## Алерты
|
||
|
||
Все алерты отправляются через единую функцию `sendAlert()`. Типы алертов:
|
||
|
||
| Событие | Содержание |
|
||
|---|---|
|
||
| Изменение origins | Добавленные/удалённые/изменённые backend IP + текущее состояние |
|
||
| Изменение aliases | Добавленные/удалённые домены |
|
||
| Изменение домена | Старое и новое значение + предупреждение об обновлении WAF |
|
||
| Изменение WAF-настроек | Изменения waf_enabled, waf_vendor, waf_instance |
|
||
| Удаление ресурса | SID, домен, предупреждение с указанием конкретного WAF-вендора |
|
||
| Обновление whitelist | Добавленные/удалённые IP с привязкой к SID и домену, итоговое количество |
|
||
|
||
---
|
||
|
||
## Зависимости
|
||
|
||
| Пакет | Назначение |
|
||
|---|---|
|
||
| `github.com/lib/pq` | PostgreSQL драйвер |
|
||
| `github.com/joho/godotenv` | Загрузка `.env` файла |
|
||
| `golang.org/x/net` | SOCKS5 прокси для Telegram |
|
||
| `net/smtp` | Отправка email (стандартная библиотека) |
|