B22: прикладное логирование vector.* + администрирование в доках (по образцу РВС)
- backend/logging_setup.py: setup_logging() (stdout INFO + файл /tmp/vector/vector.log,
ротация 5×2 МБ, VectorLOGLEVEL/VectorLOGFILE/VectorLOGDIR), get_logger('vector.*')
- события: vector.analyze (матрасчёт с длительностью), vector.auth (login_ok/failed/
lockout), vector.audit (каждая запись), vector.contour (ok/failed/rejected),
vector.operations (operation_complete), vector.geocode (успех/timeout/ошибка)
- существующие логгеры переведены в namespace vector.* (geo, geo.osm, rules, water, admin)
- README §13а: таблица наблюдаемых событий + правила (без ПДн/секретов)
- SETUP_GUIDE: §15 RPO/RTO + backup≠restore, §16 grep по vector.*, §17 диагностика
по цепочкам (БД, 500, fallback-зоны, вход), §17а чек-лист передачи проекта
- DEPLOY.md: вместо устаревшего дубля — ссылка на актуальные доки + шпаргалка стенда
- тесты: 239 passed
This commit is contained in:
+143
-4
@@ -2,7 +2,7 @@
|
||||
|
||||
**Пошаговое руководство для IT-специалистов МЧС Республики Беларусь по развёртыванию системы определения приоритетных направлений поиска (ВЕКТОР) на серверах организации.**
|
||||
|
||||
> **Версия документа:** 1.0 от 9 сентября 2026 г.
|
||||
> **Версия документа:** 1.1 от 25 сентября 2026 г.
|
||||
> **Репозиторий:** [`Sadmin/vector`](http://192.168.0.106:3000/Sadmin/vector)
|
||||
|
||||
---
|
||||
@@ -23,9 +23,10 @@
|
||||
12. [Настройка интеграции с КОНТУР](#12-настройка-интеграции-с-контуром)
|
||||
13. [Обратный прокси и HTTPS](#13-обратный-прокси-и-https)
|
||||
14. [Обновление проекта](#14-обновление-проекта)
|
||||
15. [Резервное копирование](#15-резервное-копирование)
|
||||
15. [Резервное копирование (RPO/RTO)](#15-резервное-копирование)
|
||||
16. [Мониторинг и логи](#16-мониторинг-и-логи)
|
||||
17. [Диагностика проблем](#17-диагностика-проблем)
|
||||
17а. [Чек-лист передачи проекта](#17а-чек-лист-передачи-проекта)
|
||||
18. [Чек-лист развёртывания](#18-чек-лист-развёртывания)
|
||||
|
||||
---
|
||||
@@ -329,23 +330,73 @@ docker exec vector-postgres pg_dump -U postgres -d vector_mchs \
|
||||
|
||||
Рекомендация: ежедневный cron прикладного дампа (он небольшой) + еженедельный полный. Хранить копии вне сервера.
|
||||
|
||||
**Docker volume — не backup.** Если сервер умер вместе с диском, volume умер вместе с ним. Что подлежит резервному копированию:
|
||||
|
||||
```text
|
||||
БД (прикладные таблицы + OSM)
|
||||
+ .env (JWT_SECRET, пароль БД, CONTOUR_TOKEN)
|
||||
+ конфигурация compose
|
||||
```
|
||||
|
||||
**Backup ≠ восстановление.** Копия проверяется периодическим restore на отдельном стенде:
|
||||
файл читается → БД восстанавливается → backend подключается → расчёт выполняется. Непроверенный restore — это не стратегия, а файл с именем «backup».
|
||||
|
||||
### RPO и RTO
|
||||
|
||||
| Величина | Вопрос | Рекомендация для пилота |
|
||||
|----------|--------|------------------------|
|
||||
| **RPO** | Сколько данных допустимо потерять | Ежедневный дамп → RPO ≤ 24 ч. Потеря последних суток карточек; активная операция восстановляется из бумажного журнала смены |
|
||||
| **RTO** | Сколько времени допустимо восстанавливать | Развернуть compose + restore дампа на новом LXC ≈ 30–60 мин (без импорта OSM — прикладной дамп + повторный импорт по необходимости; расчёт временно fallback'ится на Overpass) |
|
||||
|
||||
---
|
||||
|
||||
## 16. Мониторинг и логи
|
||||
|
||||
```bash
|
||||
docker compose logs -f # все сервисы
|
||||
docker compose logs -f backend # API + аудит-сообщения
|
||||
docker compose logs -f backend # API + прикладные логи vector.*
|
||||
docker compose logs -f frontend # сборка CRA / ошибки компиляции
|
||||
docker stats # потребление контейнеров
|
||||
tail -f /tmp/vector/vector.log # файл-лог внутри контейнера (ротация 5×2 МБ)
|
||||
```
|
||||
|
||||
Ключевые события в логах backend: `admin closed case ... операция(ий) завершены` (синхронизация закрытия), ошибки расчёта (полный traceback uvicorn).
|
||||
Прикладные события (B22, `backend/logging_setup.py`) — префикс `vector.<модуль>`:
|
||||
|
||||
```bash
|
||||
# Все матрасчёты с длительностью
|
||||
docker compose logs backend | grep 'vector.analyze'
|
||||
|
||||
# Входы и блокировки
|
||||
docker compose logs backend | grep -E 'vector\.auth'
|
||||
|
||||
# Отправки в КОНТУР (ok/failed/rejected)
|
||||
docker compose logs backend | grep 'vector.contour'
|
||||
|
||||
# Аудит-записи (операционный след; юридический — в БД audit_events)
|
||||
docker compose logs backend | grep 'vector.audit'
|
||||
```
|
||||
|
||||
Ключевые события: `анализ case=… радиус=… время=…мс` (каждый расчёт),
|
||||
`login_ok/login_failed/lockout` (безопасность), `contour_send_ok/failed` (связь с КОНТУРом),
|
||||
`operation_complete op=… исход=…` (завершение поиска), `admin closed case …` (синхронизация закрытия),
|
||||
`Overpass … недоступен` / `OSM PostGIS недоступен` (геослой ушёл в fallback).
|
||||
|
||||
Уровень детализации: `VectorLOGLEVEL=debug` в `.env` + `docker compose up -d backend` (restart не перечитывает env). Файл-лог отключается `VectorLOGFILE=0`.
|
||||
|
||||
---
|
||||
|
||||
## 17. Диагностика проблем
|
||||
|
||||
### Быстрые проверки
|
||||
|
||||
```bash
|
||||
docker compose ps # 4 контейнера Up/healthy
|
||||
curl -s http://localhost:8000/api/v1/health # {"status":"ok"}
|
||||
df -h && free -h # диск/память
|
||||
```
|
||||
|
||||
### Типовые симптомы
|
||||
|
||||
| Симптом | Причина | Решение |
|
||||
|---------|---------|---------|
|
||||
| Логин даёт 422 | JSON вместо form-urlencoded | Логин строго `application/x-www-form-urlencoded` |
|
||||
@@ -359,6 +410,94 @@ docker stats # потребление контейне
|
||||
| КОНТУР недоступен при отправке зон | Нет связи/токена | curl до CONTOUR_API_URL; проверить CONTOUR_TOKEN; после правки env — up -d |
|
||||
| Тайлы карты не грузятся | Нет интернета у браузера | Для полного offline — локальный tile-сервер (в планах) |
|
||||
|
||||
### Диагностика по цепочке (начинать с места проблемы, не с перезапусков)
|
||||
|
||||
**Бэкенд не подключается к БД** — цепочка `backend → docker network → postgres:5432 → authentication → vector_mchs`:
|
||||
|
||||
```bash
|
||||
docker compose logs backend | grep -iE 'error|failed|refused'
|
||||
docker exec vector-backend python -c "from services.osm_local import osm_available; print(osm_available())"
|
||||
docker exec vector-postgres pg_isready -U postgres
|
||||
```
|
||||
|
||||
Проверить: `DATABASE_URL` (хост `postgres`, пароль совпадает с POSTGRES_PASSWORD), общую compose-сеть, состояние БД.
|
||||
|
||||
**500 Internal Server Error** — «500» это результат, а не диагноз. Сначала traceback:
|
||||
|
||||
```bash
|
||||
docker compose logs backend --tail 100
|
||||
```
|
||||
|
||||
Затем определить слой: FastAPI / SQLAlchemy / БД / данные / конфигурация. Прикладной контекст ищется по `vector.*` в логах.
|
||||
|
||||
**Расчёт отдал fallback-зоны («Ближняя зона N / Средняя E»)** — геослой не ответил:
|
||||
|
||||
```bash
|
||||
docker compose logs backend | grep -E 'vector\.(rules|geo)'
|
||||
```
|
||||
|
||||
`Geo/scoring service error` → смотреть причину выше по стеку (PostGIS? Overpass breaker?). При работе на локальном OSM — проверить таблицы:
|
||||
|
||||
```bash
|
||||
docker exec vector-postgres psql -U postgres -d vector_mchs -t -c \
|
||||
"SELECT count(*) FROM planet_osm_line;"
|
||||
```
|
||||
|
||||
**Пользователь не входит** — цепочка `login → bcrypt → lockout → session → JWT`:
|
||||
|
||||
```bash
|
||||
docker compose logs backend | grep 'vector.auth'
|
||||
docker exec vector-postgres psql -U postgres -d vector_mchs -c \
|
||||
"SELECT username, is_active, status, failed_login_count, locked_until FROM users WHERE username='<логин>';"
|
||||
```
|
||||
|
||||
401 после смены JWT_SECRET — все сессии инвалидны, ожидаемо: перелогин. 403 при валидном входе — проверить роль/юнит пользователя (скоуп).
|
||||
|
||||
---
|
||||
|
||||
## 17а. Чек-лист передачи проекта (по образцу РВС)
|
||||
|
||||
### Код
|
||||
|
||||
- [ ] код в Git (Gitea, `Sadmin/vector`), история коммитов осмысленная
|
||||
- [ ] production-конфигурация без паролей в репо (`.env.example` вместо `.env`)
|
||||
- [ ] README актуален (архитектура, API, БД, логирование §13а)
|
||||
- [ ] SETUP_GUIDE актуален (развертывание, диагностика)
|
||||
- [ ] тесты зелёные: `pytest` (239 passed)
|
||||
|
||||
### База
|
||||
|
||||
- [ ] известен production-сервер PostgreSQL и БД `vector_mchs`
|
||||
- [ ] схема актуальна: `alembic current` = `009_e3_operations`
|
||||
- [ ] понятны таблицы OSM (planet_osm_*) и способ их восстановления (дамп + b16-import.sh)
|
||||
- [ ] сиды (users, units) воспроизводимы
|
||||
|
||||
### Docker
|
||||
|
||||
- [ ] понятны compose-файлы, volumes, сети
|
||||
- [ ] понятно, что можно пересоздавать (backend/frontend/adminer), а что содержит данные (postgres volume)
|
||||
- [ ] известен порядок обновления (§14) и отката
|
||||
|
||||
### Security
|
||||
|
||||
- [ ] `JWT_SECRET` не дефолтный; пароль БД сменён
|
||||
- [ ] пароль admin сменён; `must_change_password` для созданных пользователей работает
|
||||
- [ ] `.env` защищён (chmod 600, не в репо)
|
||||
- [ ] внешних ИИ/API-ключей нет (политика закрытого контура, тест `TestNoLLM`)
|
||||
- [ ] Adminer и порты БД не торчат наружу без необходимости
|
||||
|
||||
### Логи и аудит
|
||||
|
||||
- [ ] прикладные логи `vector.*` доступны (`docker compose logs backend`, файл в контейнере)
|
||||
- [ ] аудит 90 дней читается (вкладка «Аудит», право `view_audit`)
|
||||
- [ ] ретенция настроена в `security_settings`
|
||||
|
||||
### Backup
|
||||
|
||||
- [ ] cron прикладного дампа настроен, копии вне сервера
|
||||
- [ ] restore проверен на стенде
|
||||
- [ ] RPO/RTO осознаны и приняты (§15)
|
||||
|
||||
---
|
||||
|
||||
## 18. Чек-лист развёртывания
|
||||
|
||||
Reference in New Issue
Block a user