awatch-rus/AWatch-rus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(1c): add production deployment guide

Browse Source
This commit is contained in:
igor04091968
2026-05-22 09:06:39 +03:00
parent 1e23d5acb6
commit 172d113536
4 changed files with 445 additions and 119 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/1C_FILE_ANALYTICS_STACK_RU.md
+389 -89
View File
@@ -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 "<LOCAL_ADMIN_PASSWORD>"
```
### 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)