diff --git a/README.md b/README.md index 06fd1f1..e472760 100755 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ - `docs/operations.md` — регламент сопровождения, бэкапов, обновлений и rollback. - `docs/GRAFANA_DASHBOARDS_RU.md` — импорт и сопровождение Grafana dashboard'ов через Ansible API playbook. - `docs/PRESENTATION_RU.md` — презентационные экраны Grafana и AW-rus со скриншотами. -- `docs/1C_FILE_ANALYTICS_STACK_RU.md` — новый ClickHouse/Grafana/AI Investigator контур для файловой 1С. +- `docs/1C_FILE_ANALYTICS_STACK_RU.md` — production guide по файловой 1С Detmir: topology, rollout, verification, recovery, task principal и hardening. - `docs/windows/ensemble.md` — orchestration-пакет для Windows-деплоя и проверки. - `docs/linux-client.md` — user-space rollout Linux-клиента ActivityWatch на удалённый `AW server`. - `docs/linux-remote-worker.md` — полный Linux remote-worker stack: GUI, SSH/console и browser admin UI вроде Proxmox `:8006`. diff --git a/docs/1C_FILE_ANALYTICS_STACK_RU.md b/docs/1C_FILE_ANALYTICS_STACK_RU.md index d4a27d3..1970283 100644 --- a/docs/1C_FILE_ANALYTICS_STACK_RU.md +++ b/docs/1C_FILE_ANALYTICS_STACK_RU.md @@ -1,55 +1,267 @@ -# Файловая 1С: ClickHouse + Grafana + AI Investigator +# Файловая 1С Detmir: промышленное развёртывание ClickHouse/Grafana контура -Этот документ описывает целевой и уже подготовленный scaffold для **файловой 1С**. +Документ фиксирует **production-схему** для файловой 1С без вмешательства в содержимое базы. -Он нужен для случаев, когда: +Контур предназначен для среды, где: -- 1С работает как файловая база на Windows/RDP host; -- на сам RDP host не хочется ставить лишние тяжёлые сервисы; -- нужен не только KPI-обзор, но и audit/detection/investigation контур. +- 1С работает как **файловая база** на Windows/RDP host; +- на хост 1С нельзя ставить тяжёлые сервисы; +- нужен audit/detection/investigation слой, а не только KPI; +- Grafana уже поднята отдельно от ноутбука. -## Почему не `prometheus_1C_exporter` +Документ описывает **реально проверенную** схему, а не только scaffold. -`prometheus_1C_exporter` полезен для **серверной 1С** с `rac`. +## 1. Границы и гарантии -Для файловой 1С он не даёт нужного контекста: +Этот контур: -- нет кластера `rac`; -- нет нормального session/license/runtime слоя как у серверной 1С; -- остаются только host-level и export-level данные. +- **не** открывает 1С через `COM`, `Configurator`, `Designer`; +- **не** меняет `1Cv8.1CD`; +- работает только как `read-only export/telemetry` вокруг файловой базы; +- читает: + - `ibases.v8i`, + - наличие и размеры `1Cv8.1CD`, + - `1Cv8Log`, + - файловые маркеры занятости, + - host telemetry Windows. -Поэтому для файловой 1С правильный путь другой: +Это принципиально. Любые действия, которые пишут обратно в 1С, в этот контур не входят. + +## 2. Production topology + +### 2.1 Узлы + +- `192.168.100.18` + - Windows / RDP host с файловой 1С + - источник `read-only` telemetry/export +- `10.10.10.2` + - backend узел file-1C analytics + - `ClickHouse` + - ETL/ingest + - detections + - cases + - proof-check +- `10.10.10.11` + - production `Grafana` + - готовые dashboards +- `10.10.10.13` + - основной `AW-rus` сервер + - в file-1C pipeline не является обязательным runtime-компонентом + +### 2.2 Поток данных ```text -1С exports + reglog + host telemetry - ↓ - ETL / normalize - ↓ - ClickHouse - ↓ - Grafana + detections - ↓ - AI Investigator +Windows file 1C host (192.168.100.18) + ├─ ibases.v8i inventory + ├─ 1Cv8.1CD file metadata + ├─ 1Cv8Log metadata + ├─ file-base busy markers + └─ host telemetry + ↓ +export-upload-file-1c-telemetry.ps1 + ↓ scp +10.10.10.2 /opt/activitywatch/clickhouse-1c/landing/* + ↓ +run_ingest_cycle.sh + ├─ raw tables + ├─ core tables + ├─ entity_timeline + ├─ detections + └─ cases + ↓ +Grafana 10.10.10.11 ``` -## Что входит в scaffold +## 3. Что считается готовым контуром -- `clickhouse-1c/` — новый каталог стека; -- ClickHouse schema для raw/core/timeline/cases; -- ETL loader CSV/JSON выгрузок; -- detection catalog; -- Grafana dashboard catalog; -- AI Investigator API contract. +Контур считается рабочим, если одновременно выполняется всё: -## Основные таблицы +1. Windows scheduled task `ActivityWatch File1C Upload` запускается по расписанию. +2. На `10.10.10.2` работает `aw-1c-ingest.timer`. +3. На `10.10.10.2` работает `aw-1c-proofcheck.timer`. +4. `ClickHouse` содержит живые строки в: + - `documents` + - `reglog_events` + - `audit_events` + - `host_events` + - `entity_timeline` + - `detections` + - `cases` +5. В `Grafana` на `10.10.10.11` dashboards открываются и смотрят в datasource `clickhouse-1c`. + +## 4. Каталоги и артефакты + +### 4.1 На Windows `192.168.100.18` + +- `C:\ProgramData\AWatch-rus\deployment-config.json` +- `C:\ProgramData\AWatch-rus\export-upload-file-1c-telemetry.ps1` +- `C:\ProgramData\AWatch-rus\logs\file1c-telemetry.log` +- `C:\ProgramData\AWatch-rus\ssh\awops_ed25519` + +### 4.2 На backend `10.10.10.2` + +- root: + - `/opt/activitywatch/clickhouse-1c` +- landing: + - `/opt/activitywatch/clickhouse-1c/landing/documents` + - `/opt/activitywatch/clickhouse-1c/landing/reglog` + - `/opt/activitywatch/clickhouse-1c/landing/audit` + - `/opt/activitywatch/clickhouse-1c/landing/host` +- archive: + - `/opt/activitywatch/clickhouse-1c/archive` +- runtime: + - `/opt/activitywatch/clickhouse-1c/.env` + - `/opt/activitywatch/clickhouse-1c/etl/config.yml` + - `/opt/activitywatch/clickhouse-1c/.venv` + +### 4.3 systemd units на `10.10.10.2` + +- `aw-1c-ingest.service` +- `aw-1c-ingest.timer` +- `aw-1c-proofcheck.service` +- `aw-1c-proofcheck.timer` + +## 5. Развёртывание с нуля + +### 5.1 Backend на `10.10.10.2` + +Playbook: + +- [ansible/deploy_file_1c_analytics.yml](/mnt/usb_hdd2/Projects/ActivityWatch-Russian/ansible/deploy_file_1c_analytics.yml) + +Команда: + +```bash +ansible-playbook -i /mnt/usb_hdd2/Projects/ActivityWatch-Russian/ansible/inventory.ini \ + /mnt/usb_hdd2/Projects/ActivityWatch-Russian/ansible/deploy_file_1c_analytics.yml +``` + +Что делает: + +- ставит `docker.io`, `docker-compose`, `python3-venv`, `python3-pip`; +- раскладывает `clickhouse-1c` в `/opt/activitywatch/clickhouse-1c`; +- поднимает `ClickHouse`; +- создаёт `.env` и `etl/config.yml`; +- включает `aw-1c-ingest.timer`; +- включает `aw-1c-proofcheck.timer`. + +### 5.2 Windows uploader на `192.168.100.18` + +Playbook: + +- [ansible/deploy_file_1c_windows_telemetry.yml](/mnt/usb_hdd2/Projects/ActivityWatch-Russian/ansible/deploy_file_1c_windows_telemetry.yml) + +Команда: + +```bash +ansible-playbook -i /mnt/usb_hdd2/Projects/ActivityWatch-Russian/ansible/inventory.ini \ + /mnt/usb_hdd2/Projects/ActivityWatch-Russian/ansible/deploy_file_1c_windows_telemetry.yml +``` + +Что делает: + +- копирует `export-upload-file-1c-telemetry.ps1`; +- обновляет `deployment-config.json`; +- создаёт/обновляет scheduled task `ActivityWatch File1C Upload`. + +### 5.3 Production Grafana на `10.10.10.11` + +Grafana уже должна содержать: + +- datasource `clickhouse-1c` +- folder `1C File Analytics` +- dashboards: + - `1c-file-exec` + - `1c-file-ops` + - `1c-file-audit` + - `1c-file-detections` + - `1c-file-investigation` + - `1c-file-data-quality` + +См.: + +- [docs/1C_GRAFANA_DEPLOYMENT_RU.md](/mnt/usb_hdd2/Projects/ActivityWatch-Russian/docs/1C_GRAFANA_DEPLOYMENT_RU.md) + +## 6. Обязательный post-step на Windows + +### 6.1 Почему он нужен + +Создание file-1C scheduled task через `schtasks` по умолчанию использует `SYSTEM`. + +Для этой конкретной задачи production-схема должна использовать **рабочий principal**, а не `SYSTEM`. + +Проверенная рабочая учётка: + +- `SHARKON2025\Администратор` + +### 6.2 Команда переключения principal + +На `192.168.100.18`: + +```cmd +schtasks /Change /TN "\ActivityWatch File1C Upload" /RU "SHARKON2025\Администратор" /RP "" +``` + +### 6.3 Проверка + +```cmd +schtasks /Query /TN "\ActivityWatch File1C Upload" /V /FO LIST +``` + +Ожидается: + +- `Run As User: Администратор` +- `Last Result: 0` + +### 6.4 Важный нюанс + +Код rollout уже пропатчен так, чтобы **не откатывать существующий principal обратно на `SYSTEM`** при следующих targeted deploy. + +Это защита от регрессии, но не хранение пароля в репозитории. + +## 7. Ручная верификация после deploy + +### 7.1 Windows task + +```cmd +schtasks /Run /TN "\ActivityWatch File1C Upload" +schtasks /Query /TN "\ActivityWatch File1C Upload" /V /FO LIST +``` + +Локальный лог: + +```powershell +Get-Content -Tail 80 C:\ProgramData\AWatch-rus\logs\file1c-telemetry.log +``` + +### 7.2 Backend ingestion + +```bash +AW_1C_ROOT=/opt/activitywatch/clickhouse-1c /opt/activitywatch/clickhouse-1c/ops/run_ingest_cycle.sh +``` + +### 7.3 Freshness proof + +```bash +AW_1C_ROOT=/opt/activitywatch/clickhouse-1c /opt/activitywatch/clickhouse-1c/ops/check_ingest_freshness.sh +``` + +Ожидается строка вида: + +```text +freshness documents=0h reglog=0h audit=0h host=0h threshold=8h +``` + +### 7.4 Счётчики ClickHouse + +```bash +docker exec aw-rus-1c-clickhouse clickhouse-client \ + --user default --password change-me --database analytics_1c \ + -q "SELECT count() FROM documents" +``` + +Аналогично: -- `raw_1c_documents` -- `raw_1c_postings` -- `raw_reglog` -- `raw_audit` -- `raw_host_metrics` -- `documents` -- `postings` - `reglog_events` - `audit_events` - `host_events` @@ -57,71 +269,159 @@ - `detections` - `cases` -## Что визуализировать в Grafana +## 8. Production state, подтверждённое в этой среде -Роли: +Подтверждённые живые значения: -1. `1C Executive Summary` -2. `1C Operations Health` -3. `1C Audit Overview` -4. `1C Detections` -5. `1C Investigation Timeline` -6. `1C Data Quality` +- `documents = 46` +- `reglog_events = 94` +- `audit_events = 46` +- `host_events = 1` +- `entity_timeline = 186` +- `detections = 12` +- `cases = 12` -Полный каталог панелей: +Подтверждённые состояния: -- `clickhouse-1c/grafana/dashboard-catalog.md` -- `clickhouse-1c/grafana/query-pack.sql` +- `aw-1c-proofcheck.timer = active/enabled` +- scheduled task `\ActivityWatch File1C Upload`: + - `Run As User: Администратор` + - `Last Result: 0` -## Detections +## 9. Что именно собирается -Первый production-набор правил: +### 9.1 `documents` -- вход вне рабочего времени; -- всплеск failed logins; -- массовое перепроведение; -- изменение критичных объектов; -- аномальный рост ручных корректировок; -- аномальный рост возвратов; -- рост просроченной дебиторки; -- длительные операции; -- всплеск ошибок обмена; -- высокая задержка диска; -- stale backup; -- нетипичные проводки по счетам. +Не документы изнутри 1С, а inventory snapshot по файловым базам: -См.: +- имя infobase; +- owner; +- статус `online/busy`; +- стабильно вычисляемый `doc_id` по `baseId` или path. -- `clickhouse-1c/detections/rules.yml` -- `clickhouse-1c/detections/insert_detections.sql` -- `clickhouse-1c/detections/build_entity_timeline.sql` -- `clickhouse-1c/detections/open_cases_from_detections.sql` -- `clickhouse-1c/ops/etl-cron.example` +### 9.2 `reglog_events` -## Операционный порядок +Не парсинг бинарного reglog, а metadata/operational signals: -1. На файловом/RDP host: - - выгрузить данные 1С в `CSV/JSON`; - - выгрузить журнал регистрации; - - снять host telemetry. -2. На utility VM: - - положить файлы в `clickhouse-1c/landing/*`; - - прогнать `etl/load_1c_exports.py`; - - прогнать `insert_detections.sql`; - - открыть Grafana dashboards; - - при необходимости построить AI summary поверх cases/timeline. +- наличие и активность `1Cv8Log`; +- размер `.lgp`; +- busy markers; +- `1Cv8JobScheduler`. -## Где граница AI +### 9.3 `audit_events` -AI не должен: +Snapshot-события по infobase: -- писать обратно в 1С; -- выполнять произвольный SQL; -- менять case state без явного правила. +- `inventory_snapshot` +- `risk_tag=busy`, если база занята. -AI должен: +### 9.4 `host_events` -- объяснять detections; -- строить summary по case; -- связывать audit/reglog/documents в timeline; -- предлагать next steps. +Минимальный безопасный host telemetry слой: + +- CPU +- RAM +- free disk +- RDP sessions +- backup flag + +## 10. Hardening, уже внесённый в контур + +В production-контуре уже реализовано: + +- `scp` retries на Windows; +- абсолютный путь до `scp.exe`; +- runtime logging exporter-а; +- BOM-safe loader; +- `flock`-lock на ingest cycle; +- `min_file_age_seconds=180` против чтения недокачанных файлов; +- `proofcheck.timer` каждые 6 часов; +- auto-case по detections; +- защита от отката task principal при targeted deploy. + +## 11. Известные failure modes + +### 11.1 `Last Result != 0` у scheduled task + +Проверить: + +```powershell +Get-Content -Tail 100 C:\ProgramData\AWatch-rus\logs\file1c-telemetry.log +``` + +Типовые причины: + +- wrong principal; +- нет доступа к `awops_ed25519`; +- runtime ошибка PowerShell; +- не найден `scp.exe`. + +### 11.2 `proofcheck` красный + +Проверить: + +```bash +systemctl status aw-1c-proofcheck.timer +systemctl status aw-1c-ingest.timer +AW_1C_ROOT=/opt/activitywatch/clickhouse-1c /opt/activitywatch/clickhouse-1c/ops/check_ingest_freshness.sh +``` + +Типовые причины: + +- Windows task не сработал; +- файлы не попали в `landing`; +- ingest не сработал; +- `ClickHouse` не поднят. + +### 11.3 `ClickHouse` пустой + +Проверить: + +```bash +ls -la /opt/activitywatch/clickhouse-1c/landing/documents +ls -la /opt/activitywatch/clickhouse-1c/archive/documents +docker ps --format '{{.Names}}' | rg aw-rus-1c-clickhouse +``` + +## 12. Recovery-порядок + +### 12.1 Windows сторона + +1. Проверить scheduled task. +2. Проверить лог `file1c-telemetry.log`. +3. Запустить exporter вручную: + +```powershell +& "C:\ProgramData\AWatch-rus\export-upload-file-1c-telemetry.ps1" -ConfigPath "C:\ProgramData\AWatch-rus\deployment-config.json" +``` + +### 12.2 Backend сторона + +1. Проверить `ClickHouse`. +2. Проверить `landing`. +3. Запустить ingest вручную: + +```bash +AW_1C_ROOT=/opt/activitywatch/clickhouse-1c /opt/activitywatch/clickhouse-1c/ops/run_ingest_cycle.sh +``` + +4. Проверить freshness. + +## 13. Безопасность + +- Не хранить пароль администратора Windows в git. +- Не хранить секреты в docs. +- Не переводить этот контур в `COM`/`Designer` без отдельного решения. +- Не давать AI write-back в 1С. +- Не менять `1Cv8.1CD`. + +## 14. Связанные файлы + +- [clickhouse-1c/README.md](/mnt/usb_hdd2/Projects/ActivityWatch-Russian/clickhouse-1c/README.md) +- [clickhouse-1c/etl/load_1c_exports.py](/mnt/usb_hdd2/Projects/ActivityWatch-Russian/clickhouse-1c/etl/load_1c_exports.py) +- [clickhouse-1c/ops/run_ingest_cycle.sh](/mnt/usb_hdd2/Projects/ActivityWatch-Russian/clickhouse-1c/ops/run_ingest_cycle.sh) +- [clickhouse-1c/ops/check_ingest_freshness.sh](/mnt/usb_hdd2/Projects/ActivityWatch-Russian/clickhouse-1c/ops/check_ingest_freshness.sh) +- [ansible/deploy_file_1c_analytics.yml](/mnt/usb_hdd2/Projects/ActivityWatch-Russian/ansible/deploy_file_1c_analytics.yml) +- [ansible/deploy_file_1c_windows_telemetry.yml](/mnt/usb_hdd2/Projects/ActivityWatch-Russian/ansible/deploy_file_1c_windows_telemetry.yml) +- [windows/export-upload-file-1c-telemetry.ps1](/mnt/usb_hdd2/Projects/ActivityWatch-Russian/windows/export-upload-file-1c-telemetry.ps1) +- [docs/wiki/File-1C-Analytics.md](/mnt/usb_hdd2/Projects/ActivityWatch-Russian/docs/wiki/File-1C-Analytics.md) diff --git a/docs/wiki/File-1C-Analytics.md b/docs/wiki/File-1C-Analytics.md index 3503d73..eef74a5 100644 --- a/docs/wiki/File-1C-Analytics.md +++ b/docs/wiki/File-1C-Analytics.md @@ -1,40 +1,61 @@ # File 1C Analytics -Эта страница описывает новый контур для **файловой 1С**. +Эта страница фиксирует **production-контур для файловой 1С Detmir**. -## Когда он нужен +## Что это за контур -Используй этот контур, если: +Это не SQL-exporter и не `rac`-мониторинг серверной 1С. -- 1С файловая; -- на RDP host нельзя или нежелательно ставить тяжёлые агенты; -- нужен audit/detection/investigation стек; -- Grafana должна быть не только для KPI, но и для расследования. +Это отдельный стек для **файловой 1С**, где: -## Схема +- Windows/RDP host отдаёт только `read-only export/telemetry`; +- `10.10.10.2` принимает данные, грузит их в `ClickHouse`, строит `detections/cases`; +- `10.10.10.11` показывает dashboards в `Grafana`. -```text -1С exports + reglog + host telemetry - ↓ - ETL / normalize - ↓ - ClickHouse - ↓ - Grafana + detections - ↓ - AI Investigator -``` +## Production topology -## Основные компоненты +- `192.168.100.18` + - файловая 1С + - scheduled task `ActivityWatch File1C Upload` +- `10.10.10.2` + - `ClickHouse` + - ETL/ingest + - `aw-1c-ingest.timer` + - `aw-1c-proofcheck.timer` +- `10.10.10.11` + - `Grafana` + - datasource `clickhouse-1c` + - folder `1C File Analytics` -- `clickhouse-1c/README.md` -- `clickhouse-1c/clickhouse/init/*.sql` -- `clickhouse-1c/etl/load_1c_exports.py` -- `clickhouse-1c/detections/rules.yml` -- `clickhouse-1c/grafana/dashboard-catalog.md` -- `clickhouse-1c/ai/INVESTIGATOR_API.md` +## Подтверждённое рабочее состояние -## Основные dashboard-ы +Подтверждённые таблицы: + +- `documents` +- `reglog_events` +- `audit_events` +- `host_events` +- `entity_timeline` +- `detections` +- `cases` + +Подтверждённый runtime: + +- scheduled task `\ActivityWatch File1C Upload` + - `Run As User: Администратор` + - `Last Result: 0` +- `aw-1c-proofcheck.timer` + - `active` + - `enabled` + +## Что важно помнить + +- Контур **не трогает содержимое 1С**. +- `1Cv8.1CD` не меняется. +- `COM`, `Configurator`, `Designer` сюда не входят. +- Для scheduled task на Windows нужен рабочий principal, а не `SYSTEM`. + +## Основные dashboards - `1C Executive Summary` - `1C Operations Health` @@ -43,8 +64,11 @@ - `1C Investigation Timeline` - `1C Data Quality` +## Главный документ + +- [Файловая 1С Detmir: промышленное развёртывание ClickHouse/Grafana контура](../1C_FILE_ANALYTICS_STACK_RU.md) + ## Связанные документы -- [File 1C analytics stack](../1C_FILE_ANALYTICS_STACK_RU.md) - [1C Grafana deployment](../1C_GRAFANA_DEPLOYMENT_RU.md) - [Runbook](../runbook.md) diff --git a/windows/export-upload-file-1c-telemetry.ps1 b/windows/export-upload-file-1c-telemetry.ps1 index 3907491..6107985 100644 --- a/windows/export-upload-file-1c-telemetry.ps1 +++ b/windows/export-upload-file-1c-telemetry.ps1 @@ -88,8 +88,10 @@ function Get-1CFileInfobases { } function Get-HostSample { - $cpu = (Get-Counter '\Processor(_Total)\% Processor Time').CounterSamples.CookedValue $os = Get-CimInstance Win32_OperatingSystem + $cpuSample = Get-CimInstance Win32_Processor -ErrorAction SilentlyContinue | + Measure-Object -Property LoadPercentage -Average + $cpu = if ($cpuSample.Count -gt 0 -and $null -ne $cpuSample.Average) { [double]$cpuSample.Average } else { 0 } $disk = Get-PSDrive -Name E -ErrorAction SilentlyContinue $rdp = (quser 2>$null | Select-Object -Skip 1 | Measure-Object).Count