Added database_schema

DATABASE_SCHEMA.md

@@ -0,0 +1,151 @@
+# Auspex — Схема базы данных
+
+## Общее
+
+Auspex подключается к PostgreSQL базе данных `waf_info`. Используется в двух модулях: `-l` (logcheck) и `-p` (portcheck). Подключение реализовано с автоматическим failover: сначала пробуется primary-хост, при недоступности — secondary.
+
+**Параметры подключения** задаются в `/etc/auspex/auspex.env`:
+
+```
+DB_USER=
+DB_PASSWORD=
+DB_NAME=waf_info
+DB_PORT=5432
+PRIMARY_DB_HOST=10.100.10.8
+SECONDARY_DB_HOST=10.100.13.5
+```
+
+Соединение устанавливается без TLS (`sslmode=disable`).
+
+---
+
+## Таблицы
+
+### `instances_new`
+
+Используется в: **`-l` (logcheck)**
+
+Содержит информацию о том, какие WAF-инстансы развёрнуты на каких хостах. Logcheck использует эту таблицу как первый шаг — определяет инстансы текущего хоста по его hostname.
+
+**Запрос:**
+```sql
+SELECT hostname, instance
+FROM instances_new
+WHERE hostname = $1
+```
+
+**Используемые столбцы:**
+
+| Столбец | Тип | Описание |
+|---------|-----|----------|
+| `hostname` | text | FQDN или короткое имя хоста (совпадает с `os.Hostname()`) |
+| `instance` | text | Имя инстанса WAF (передаётся в следующий запрос к `client_info`) |
+
+---
+
+### `client_info`
+
+Используется в: **`-l` (logcheck)**
+
+Содержит привязку клиентов к WAF-инстансам. Logcheck получает список клиентов для инстансов найденных на текущем хосте.
+
+**Запрос:**
+```sql
+SELECT DISTINCT client_title, waf_instance
+FROM client_info
+WHERE waf_instance IN ($1, $2, ...)
+```
+
+**Используемые столбцы:**
+
+| Столбец | Тип | Описание |
+|---------|-----|----------|
+| `client_title` | text | Название клиента (передаётся в следующий запрос к `apps_settings`) |
+| `waf_instance` | text | Имя инстанса WAF (используется для фильтрации по IN) |
+
+---
+
+### `apps_settings`
+
+Используется в: **`-l` (logcheck)** и **`-p` (portcheck)**
+
+Центральная таблица настроек приложений. Каждая строка — одно L7-приложение с его параметрами мониторинга.
+
+#### Запрос из logcheck (`-l`):
+```sql
+SELECT l7resourceid, client_title, COALESCE(check_write_logs, false)
+FROM apps_settings
+WHERE client_title IN ($1, $2, ...)
+```
+
+#### Запрос из portcheck (`-p`):
+```sql
+SELECT l7resourceid, COALESCE(check_ports, false)
+FROM apps_settings
+```
+
+**Используемые столбцы:**
+
+| Столбец | Тип | Описание |
+|---------|-----|----------|
+| `l7resourceid` | text | Идентификатор L7-ресурса. В logcheck используется для поиска файлов логов по паттерну `{LOG_DIR}/*/*/{l7resourceid}*_access.log`. В portcheck извлекается из имени конфига (`Client_17822.conf` → `17822`) |
+| `client_title` | text | Название клиента — используется для группировки в алертах |
+| `check_write_logs` | boolean / null | Флаг включения проверки логов. `true` — файлы логов этого приложения проверяются. `null` обрабатывается как `false` через `COALESCE` |
+| `check_ports` | boolean / null | Флаг включения проверки портов. `true` — nginx upstream конфиг этого приложения проверяется. `null` обрабатывается как `false` через `COALESCE` |
+
+---
+
+## Цепочка запросов в logcheck
+
+Logcheck выполняет запросы последовательно, передавая результаты каждого шага в следующий:
+
+```
+os.Hostname()
+      │
+      ▼
+instances_new (WHERE hostname = ?)
+      │  → []instance
+      ▼
+client_info (WHERE waf_instance IN (...))
+      │  → []client_title
+      ▼
+apps_settings (WHERE client_title IN (...) AND check_write_logs = true)
+      │  → []l7resourceid
+      ▼
+Файловая система: /var/log/ptaf_nginx/*/*/{l7resourceid}*_access.log
+      │  → ModTime → сравнение с порогом
+      ▼
+Алерт если файл устарел
+```
+
+Если на любом шаге результат пустой — выполнение прекращается с информационным сообщением в лог.
+
+---
+
+## Использование `l7resourceid` в portcheck
+
+В portcheck `l7resourceid` не запрашивается напрямую — он извлекается из имени nginx конфига функцией `pcExtractL7ResourceID`:
+
+```
+/home/install/conf/ptaf-nginx/client/env/conf/Client_Name_17822.conf
+                                                              └─────┘
+                                                           l7resourceid = "17822"
+```
+
+Логика: берётся часть имени файла после последнего символа `_` без расширения. Затем по этому ID делается запрос к `apps_settings` для проверки флага `check_ports`.
+
+Если `check_ports = false` — конфиг пропускается, его upstream-серверы не проверяются. Если записи в БД нет — конфиг тоже пропускается (поведение по умолчанию безопасное).
+
+---
+
+## Минимально необходимые права пользователя БД
+
+Для работы Auspex достаточно прав только на чтение:
+
+```sql
+GRANT CONNECT ON DATABASE waf_info TO auspex_user;
+GRANT USAGE ON SCHEMA public TO auspex_user;
+GRANT SELECT ON instances_new TO auspex_user;
+GRANT SELECT ON client_info TO auspex_user;
+GRANT SELECT ON apps_settings TO auspex_user;
+```