diff --git a/docs/INDEX.md b/docs/INDEX.md index ae7218e..3a8576c 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -15,6 +15,8 @@ | [ssl-certificate.md](ssl-certificate.md) | Wildcard TLS: формат, scp, пути `/etc/ssl/sac/` | | [deployment.md](deployment.md) | Эксплуатация, backup, TLS, `sac-deploy.sh` | | [operations-prod-status.md](operations-prod-status.md) | **Статус prod** и следующие шаги | +| [seaca-mobile.md](seaca-mobile.md) | **Seaca**: коды, устройства, сессия, API | +| [seaca-fcm.md](seaca-fcm.md) | **Seaca push**: Firebase и `SAC_FCM_*` | | [workspace-three-repos.md](workspace-three-repos.md) | Multi-root workspace (три репо) | ## Порядок чтения diff --git a/docs/runbook-ops.md b/docs/runbook-ops.md index 9d4ead3..9699b7b 100644 --- a/docs/runbook-ops.md +++ b/docs/runbook-ops.md @@ -18,6 +18,12 @@ curl -sS https://sac.kalinamall.ru/health | jq . Ожидается `status: ok`, `database: ok`. При устаревших heartbeat агентов — `status: degraded`, поле `hosts_stale` > 0. +## Мобильные устройства (Seaca) + +См. [seaca-mobile.md](seaca-mobile.md) и [seaca-fcm.md](seaca-fcm.md). + +После деплоя 0.9.0+: в веб-SAC включить мобильные устройства, выдать код оператору. Push — после настройки FCM и сборки APK с `google-services.json`. + ## Резервное копирование PostgreSQL ```bash diff --git a/docs/seaca-fcm.md b/docs/seaca-fcm.md new file mode 100644 index 0000000..019fd8a --- /dev/null +++ b/docs/seaca-fcm.md @@ -0,0 +1,49 @@ +# FCM (push) для Seaca + +Настраивается **только на сервере SAC** и в **Firebase**; в веб-UI — индикатор и тест push на устройство. + +## 1. Firebase + +1. [Firebase Console](https://console.firebase.google.com/) → создать проект (или использовать существующий). +2. Добавить Android-приложение с package name **`ru.kalinamall.seaca`** (как в APK Seaca). +3. Скачать `google-services.json` — файл для **сборки Seaca**, в git не коммитить. +4. **Project settings → Service accounts → Generate new private key** — JSON для **сервера SAC**. + +## 2. Сервер SAC + +```bash +sudo install -o sac -g sac -m 600 /path/to/firebase-key.json \ + /etc/security-alert-center/fcm-service-account.json +``` + +В `/opt/security-alert-center/config/sac-api.env`: + +```ini +SAC_FCM_ENABLED=true +SAC_FCM_PROJECT_ID=your-firebase-project-id +SAC_FCM_SERVICE_ACCOUNT_JSON=/etc/security-alert-center/fcm-service-account.json +``` + +Перезапуск API: + +```bash +sudo systemctl restart sac-api +``` + +## 3. Политика оповещений + +**Настройки → Правило оповещений** → канал **Seaca (push)**. + +Действуют те же `min_severity`, cooldown и dedup, что для Telegram/email. + +## 4. Проверка + +1. Телефон привязан (enroll), в списке устройств **FCM: да**. +2. **Настройки → Мобильные устройства → Тест push** на строке устройства. +3. Либо сгенерировать событие с severity выше порога policy. + +## 5. Ограничения + +- FCM доставляет через инфраструктуру Google; payload формирует SAC (заголовок, id, deep link). +- Без `SAC_FCM_ENABLED=true` push не отправляется; приложение и REST API работают. +- `google-services.json` нужен приложению; service account JSON — только серверу. diff --git a/docs/seaca-mobile.md b/docs/seaca-mobile.md new file mode 100644 index 0000000..aa91e93 --- /dev/null +++ b/docs/seaca-mobile.md @@ -0,0 +1,102 @@ +# Seaca — мобильный клиент SAC + +Репозиторий приложения: [seaca](https://git.kalinamall.ru/PapaTramp/seaca). +Требуется SAC **≥ 0.9.0** с применённой миграцией `014`. + +--- + +## Роли + +| Где | Кто | +|-----|-----| +| Веб-SAC | Админ: мобильные устройства, коды, отзыв, FCM на сервере | +| Seaca (Android) | Оператор: обзор, события, проблемы, хосты, отчёты; ack/resolve | +| Веб-SAC | Пользователи SAC, Telegram/SMTP — **не** в приложении | + +--- + +## Включение мобильных устройств (админ) + +1. **Настройки → Мобильные устройства (Seaca)** +2. Включить **«Разрешать мобильным устройствам подключаться»** → **Сохранить мобильные** +3. В **Правило оповещений** при необходимости включить канал **Seaca (push)** (для push после настройки FCM) + +### «Сохранить мобильные» + +Сохраняет в БД: + +- разрешение подключения новых устройств; +- максимум активных устройств на одного пользователя SAC; +- минимальную версию приложения (опционально). + +Не настраивает FCM и не выдаёт коды. + +### Коды регистрации + +| Поле | Смысл | +|------|--------| +| Метка | Произвольная подпись для админа | +| Пользователь | Если выбран — enroll только для этого пользователя | +| Способ входа | **Логин и пароль + код** — в приложении нужны учётные данные SAC; **Только код** — пароль не нужен, пользователь должен быть выбран в форме | +| Срок (часов) | Код перестаёт принимать **новые** привязки; уже подключённые телефоны не отключаются | + +Код показывается **один раз** после «Выдать код». Передайте оператору: URL сервера (`https://sac.example.com`), код `sacmob_…`, при режиме password — логин/пароль SAC. + +### Подключённые устройства + +- **Отключить** — отзыв устройства и refresh-токенов; приложение получит 401 при следующем запросе +- **Тест push** — только если FCM настроен на сервере и у устройства есть FCM-токен + +--- + +## Сессия после привязки + +1. Оператор один раз выполняет enroll (`POST /api/v1/mobile/enroll`). +2. Приложение хранит **access_token** (JWT, ~24 ч) и **refresh_token** (по умолчанию **90 дней**, `SAC_MOBILE_REFRESH_EXPIRE_DAYS` в `sac-api.env`). +3. Код регистрации после успешного enroll больше не нужен. + +Для долгой работы без повторной привязки увеличьте `SAC_MOBILE_REFRESH_EXPIRE_DAYS` (например `3650`). Отзыв устройства в вебе обнуляет доступ немедленно. + +--- + +## Push (FCM) на сервере + +Подробно: [seaca-fcm.md](seaca-fcm.md). + +Кратко в `config/sac-api.env`: + +```ini +SAC_FCM_ENABLED=true +SAC_FCM_PROJECT_ID=ваш-firebase-project-id +SAC_FCM_SERVICE_ACCOUNT_JSON=/etc/security-alert-center/fcm-service-account.json +``` + +После изменений: `sudo systemctl restart sac-api` или `sudo /opt/sac-deploy.sh`. + +В UI индикатор **FCM: настроен / не настроен** читает эти переменные; править их через веб нельзя. + +--- + +## API (для разработчиков Seaca) + +| Метод | Путь | +|-------|------| +| GET | `/health` | +| POST | `/api/v1/mobile/enroll` | +| POST | `/api/v1/mobile/auth/refresh` | +| PUT | `/api/v1/mobile/devices/me/fcm` | +| GET | `/api/v1/dashboards/summary` | +| GET | `/api/v1/events`, `/api/v1/events/{id}` | +| GET | `/api/v1/problems`, `/api/v1/problems/{id}` | +| POST | `/api/v1/problems/{id}/ack`, `/resolve` | +| GET | `/api/v1/hosts`, `/api/v1/hosts/{id}` | + +JWT с мобильного устройства содержит claim `device_id`. + +--- + +## См. также + +- [seaca-fcm.md](seaca-fcm.md) — Firebase и push +- [deployment.md](deployment.md) — деплой SAC +- [runbook-ops.md](runbook-ops.md) — эксплуатация