awatch-rus/AWatch-rus
1
0
Fork 0
Code Issues Pull Requests Actions 100 Packages Projects Releases Wiki Activity
Files
66dc0a09b1f46bf83389e3f8a2b6e1b7971b9ee0
AWatch-rus/docs/FULL_DEPLOYMENT_MANUAL_RU.md
T

21 KiB
Executable File
Raw Blame History

Полная инструкция по развёртыванию и поддержке AWatch-rus

Статус документа

Этот документ описывает актуальный **Rust-fiWindows/PowerShell deployment flow больше не считается основным способом развёртывания, патчинга или эксплуатации. Если в репозитории остаются старые ".ps1"-файлы, они рассматриваются как legacy/history или как будущий provider-слой, но не как production runtime.

  1. Назначение

AWatch-rus — программный комплекс операционного контроля, технического аудита, оценки трудоотдачи сотрудников и мониторинга корпоративной ИТ-инфраструктуры на базе:

  • Rust backend/runtime;
  • Rust Agent;
  • Rust server-rendered HTML + HTMX-compatible JSON API;
  • Grafana/Prometheus-витрин;
  • модулей Workforce, Security и Forensics;
  • evidence/reporting tooling;
  • ActivityWatch-compatible источников данных, где это применимо.

Проект не позиционируется как сертифицированная DLP/SIEM/EDR/XDR/СЗИ. DLP, evidence, UEBA и расследовательские функции используются как внутренние аналитические и операционные модули.

  1. Актуальная архитектура

1.1 Основной runtime

Основной production runtime AWatch-rus — Rust-first:

  • backend/runtime — Rust;
  • agent — Rust;
  • portal — Rust server-rendered HTML + HTMX-compatible JSON API;
  • operational status/check — Rust;
  • DLP server-side helpers — Rust;
  • worktime helpers/exporters/prewarm — Rust;
  • SLO/health/readiness helpers — Rust;
  • evidence/install-kit tooling — Rust;
  • auto-heal helpers — Rust, только в безопасном режиме.

1.2 Что не является основным runtime

Не считать основным production deployment flow:

  • PowerShell deployment;
  • старые Windows ".ps1" rollout scripts;
  • ручное исправление production-файлов без release/backup;
  • прямое редактирование Web UI в "/opt" без воспроизводимого патча;
  • Python/shell как основной operational runtime, если для компонента уже есть Rust-аналог.

Python, shell, Ansible или PowerShell могут оставаться в проекте только как:

  • legacy compatibility;
  • вспомогательные dev/test tools;
  • миграционные сценарии;
  • будущие provider-слои;
  • Telegram/OCR/AI/ETL/MCP helpers, если они явно не входят в Rust-first core.
  1. Типовые роли узлов

2.1 Server node

Серверный узел содержит:

  • AWatch-rus backend/runtime;
  • portal;
  • API;
  • exporters;
  • health/readiness/status tooling;
  • systemd units/timers;
  • Grafana/Prometheus integration;
  • evidence/reporting storage.

2.2 Agent node

Agent node содержит:

  • Rust Agent;
  • локальную конфигурацию агента;
  • systemd service или другой штатный supervisor;
  • локальные логи;
  • буфер/очередь, если предусмотрено конфигурацией;
  • сетевой доступ до backend/API.

2.3 Monitoring node

Monitoring node может содержать:

  • Prometheus;
  • Grafana;
  • dashboards;
  • alerting rules;
  • external logs/metrics storage.

Monitoring node может совпадать с server node в пилотной установке.

  1. Требования

3.1 Базовые требования

  • Linux-сервер или LXC/VM.
  • Доступ администратора к systemd.
  • Rust toolchain для сборочного узла.
  • Сетевой доступ между agent node и server node.
  • Закрытый доступ к API и порталу через VPN, reverse proxy или внутренний контур.
  • Backup/snapshot перед любым production patch.

3.2 Рекомендуемый production-подход

Для production не собирать проект прямо на боевом сервере, если есть отдельный build host.

Рекомендуемый поток:

git checkout нужного commit/tag → cargo fmt / clippy / test / build → упаковка release artifacts → перенос artifacts на сервер → backup/snapshot → остановка/перезапуск нужных services → smoke tests → фиксация версии

  1. Основные пути

Рекомендуемая структура на сервере:

/opt/awatch-rus/ bin/ etc/ portal/ releases/ evidence/ reports/ logs/

/etc/awatch-rus/ awatch-rus.env agent.env portal.env

/var/lib/awatch-rus/ data/ state/ cache/ evidence/ reports/

/var/log/awatch-rus/ backend.log agent.log portal.log exporter.log

Рекомендуемые runtime binaries:

/usr/local/bin/detmir-status /usr/local/bin/detmir-check /usr/local/bin/detmir-dlp /usr/local/bin/detmir-auto /usr/local/bin/detmir-heal-safe /usr/local/bin/aw-rus-healthd

Имена конкретных бинарников должны соответствовать текущему "Cargo.toml" и фактически собранным artifacts. Если имя binary изменено, документация и systemd unit должны обновляться в том же commit.

  1. Конфигурация

5.1 Общие правила

  • Не хранить production secrets в публичном репозитории.
  • Не коммитить реальные hostnames, IP, логины, ФИО, токены, пароли.
  • Для production использовать "/etc/awatch-rus/*.env".
  • Для demo использовать только обезличенные fixtures.
  • Все параметры, влияющие на runtime, должны быть описаны в документации.

5.2 Пример server env

AWATCH_ENV=production AWATCH_BIND_ADDR=127.0.0.1 AWATCH_PORT=5600 AWATCH_DATA_DIR=/var/lib/awatch-rus/data AWATCH_LOG_DIR=/var/log/awatch-rus AWATCH_EVIDENCE_DIR=/var/lib/awatch-rus/evidence AWATCH_REPORTS_DIR=/var/lib/awatch-rus/reports RUST_LOG=info

5.3 Пример agent env

AWATCH_AGENT_ENV=production AWATCH_SERVER_URL=https://awatch.example.local AWATCH_AGENT_HOST_ID=HOSTNAME_OR_NODE_ID AWATCH_AGENT_DATA_DIR=/var/lib/awatch-rus/agent AWATCH_AGENT_LOG_DIR=/var/log/awatch-rus RUST_LOG=info

  1. Сборка

6.1 Проверки перед сборкой

На build host:

cd /path/to/AWatch-rus

git status --short cargo fmt --all -- --check cargo clippy --workspace --all-targets -- -D warnings cargo test --workspace

Если в репозитории есть проектные quality gates, выполнить их обязательно:

bash scripts/check_private_config_guard.sh bash scripts/quality-gate.sh

Если какой-то скрипт отсутствует в текущей ветке, не создавать фиктивную замену. Зафиксировать это в release notes.

6.2 Release build

cargo build --release --workspace

Проверить artifacts:

find target/release -maxdepth 1 -type f -executable -print

6.3 Упаковка artifacts

Рекомендуемый вариант:

mkdir -p dist/awatch-rus-release/bin cp target/release/detmir-status dist/awatch-rus-release/bin/ 2>/dev/null || true cp target/release/detmir-check dist/awatch-rus-release/bin/ 2>/dev/null || true cp target/release/detmir-dlp dist/awatch-rus-release/bin/ 2>/dev/null || true cp target/release/detmir-auto dist/awatch-rus-release/bin/ 2>/dev/null || true cp target/release/detmir-heal-safe dist/awatch-rus-release/bin/ 2>/dev/null || true cp target/release/aw-rus-healthd dist/awatch-rus-release/bin/ 2>/dev/null || true

tar -C dist -czf awatch-rus-release.tar.gz awatch-rus-release sha256sum awatch-rus-release.tar.gz > awatch-rus-release.tar.gz.sha256

Не использовать "cp ... || true" в CI без последующей проверки обязательных binaries. Для ручного production release список обязательных binaries должен быть проверен явно.

  1. Первичное развёртывание server node

7.1 Создание каталогов

sudo mkdir -p /opt/awatch-rus/bin sudo mkdir -p /opt/awatch-rus/releases sudo mkdir -p /etc/awatch-rus sudo mkdir -p /var/lib/awatch-rus/data sudo mkdir -p /var/lib/awatch-rus/state sudo mkdir -p /var/lib/awatch-rus/evidence sudo mkdir -p /var/lib/awatch-rus/reports sudo mkdir -p /var/log/awatch-rus

7.2 Установка binaries

sudo install -m 0755 dist/awatch-rus-release/bin/* /opt/awatch-rus/bin/

Создать symlink для удобства:

sudo ln -sf /opt/awatch-rus/bin/detmir-status /usr/local/bin/detmir-status sudo ln -sf /opt/awatch-rus/bin/detmir-check /usr/local/bin/detmir-check sudo ln -sf /opt/awatch-rus/bin/detmir-dlp /usr/local/bin/detmir-dlp

Если binary отсутствует, не создавать пустой symlink. Сначала проверить фактический состав release artifact.

7.3 Конфигурация

sudo install -m 0640 awatch-rus.env /etc/awatch-rus/awatch-rus.env

Проверить права:

sudo chown root:root /etc/awatch-rus/awatch-rus.env sudo chmod 0640 /etc/awatch-rus/awatch-rus.env

  1. systemd units

8.1 Пример backend service

[Unit] Description=AWatch-rus backend/runtime After=network-online.target Wants=network-online.target

[Service] Type=simple EnvironmentFile=/etc/awatch-rus/awatch-rus.env ExecStart=/opt/awatch-rus/bin/awatch-rus-backend Restart=on-failure RestartSec=5 WorkingDirectory=/opt/awatch-rus NoNewPrivileges=true PrivateTmp=true ProtectSystem=full ProtectHome=true ReadWritePaths=/var/lib/awatch-rus /var/log/awatch-rus

[Install] WantedBy=multi-user.target

Если фактическое имя backend binary отличается, заменить "awatch-rus-backend" на актуальное имя из release artifact.

8.2 Пример health service

[Unit] Description=AWatch-rus health daemon After=network-online.target Wants=network-online.target

[Service] Type=simple EnvironmentFile=/etc/awatch-rus/awatch-rus.env ExecStart=/opt/awatch-rus/bin/aw-rus-healthd Restart=on-failure RestartSec=5 WorkingDirectory=/opt/awatch-rus NoNewPrivileges=true PrivateTmp=true ProtectSystem=full ProtectHome=true ReadWritePaths=/var/lib/awatch-rus /var/log/awatch-rus

[Install] WantedBy=multi-user.target

8.3 Применение unit files

sudo systemctl daemon-reload sudo systemctl enable --now awatch-rus-backend.service sudo systemctl enable --now aw-rus-healthd.service

Если конкретный unit не используется в текущей инсталляции, не создавать фиктивный сервис. Документировать фактический набор services.

  1. Развёртывание Rust Agent

9.1 Установка agent binary

sudo mkdir -p /opt/awatch-rus/bin sudo mkdir -p /etc/awatch-rus sudo mkdir -p /var/lib/awatch-rus/agent sudo mkdir -p /var/log/awatch-rus

sudo install -m 0755 awatch-rus-agent /opt/awatch-rus/bin/awatch-rus-agent sudo install -m 0640 agent.env /etc/awatch-rus/agent.env

9.2 Пример agent service

[Unit] Description=AWatch-rus Rust Agent After=network-online.target Wants=network-online.target

[Service] Type=simple EnvironmentFile=/etc/awatch-rus/agent.env ExecStart=/opt/awatch-rus/bin/awatch-rus-agent Restart=on-failure RestartSec=5 WorkingDirectory=/opt/awatch-rus NoNewPrivileges=true PrivateTmp=true ProtectSystem=full ProtectHome=true ReadWritePaths=/var/lib/awatch-rus /var/log/awatch-rus

[Install] WantedBy=multi-user.target

9.3 Запуск agent

sudo systemctl daemon-reload sudo systemctl enable --now awatch-rus-agent.service sudo systemctl status awatch-rus-agent.service --no-pager

  1. Развёртывание портала

Портальный слой AWatch-rus зафиксирован как Rust server-rendered HTML + HTMX-compatible JSON API.

10.1 Общий порядок

build portal/backend binary → install binary → install templates/static assets, если они выделены отдельно → update portal env → restart portal service → smoke check HTTP/API routes

10.2 Проверка портала

curl -fsS http://127.0.0.1:5600/healthz curl -fsS http://127.0.0.1:5600/readyz curl -fsS http://127.0.0.1:5600/version

Если конкретные endpoints в текущей версии отличаются, использовать фактически реализованные health/readiness/version endpoints и обновить этот документ в том же commit.

  1. Патчи в развернутой среде

11.1 Правило

Любой production patch применяется только через контролируемый цикл:

определить commit/tag → собрать release artifact → выполнить локальные проверки → сделать backup/snapshot → установить новые binaries/configs → restart/reload services → smoke tests → зафиксировать результат → сохранить rollback path

11.2 Перед патчем

git rev-parse HEAD git status --short

Сохранить:

дата/время commit/tag кто применяет какие services затрагиваются какой rollback path

11.3 Backup перед патчем

Если используется Proxmox/LXC:

vzdump <CT_ID> --mode snapshot --compress zstd --storage <BACKUP_STORAGE>

Внутри сервера:

sudo tar -C / -czf /root/awatch-rus-backup-$(date +%Y%m%d-%H%M%S).tgz
etc/awatch-rus
opt/awatch-rus
var/lib/awatch-rus
var/log/awatch-rus

Если данные большие, backup "/var/lib/awatch-rus" выполнять отдельной процедурой согласно backup policy.

11.4 Установка нового binary

Сохранить предыдущую версию:

sudo mkdir -p /opt/awatch-rus/releases/previous sudo cp -a /opt/awatch-rus/bin /opt/awatch-rus/releases/previous/bin-$(date +%Y%m%d-%H%M%S)

Установить новый artifact:

sudo install -m 0755 dist/awatch-rus-release/bin/* /opt/awatch-rus/bin/

11.5 Restart services

sudo systemctl daemon-reload sudo systemctl restart awatch-rus-backend.service sudo systemctl restart aw-rus-healthd.service

Если патч касается только agent:

sudo systemctl restart awatch-rus-agent.service

Если сервис в текущем контуре называется иначе, использовать фактическое имя systemd unit.

  1. Smoke-тесты после патча

12.1 Systemd

systemctl --failed --no-pager systemctl status awatch-rus-backend.service --no-pager systemctl status aw-rus-healthd.service --no-pager

12.2 Rust operational checks

detmir-status --json detmir-check --json detmir-dlp --json

Если отдельная команда не установлена в данном контуре, это не считается ошибкой только при наличии документированного исключения.

12.3 HTTP/API

curl -fsS http://127.0.0.1:5600/healthz curl -fsS http://127.0.0.1:5600/readyz curl -fsS http://127.0.0.1:5600/version

12.4 Portal smoke

Проверить в браузере:

/portal /portal/reports /portal/architecture

Для Pilot v1 проверить роли:

executive manager security forensics admin

12.5 Data freshness

Проверить, что витрины и отчёты не пустые из-за сбоя сбора:

последние события поступают worktime reports обновляются DLP/security events отображаются, если включены evidence/reporting не падает Grafana dashboards открываются

  1. Rollback

13.1 Быстрый rollback binary

Найти предыдущий backup:

ls -lah /opt/awatch-rus/releases/previous/

Восстановить:

sudo rsync -a --delete /opt/awatch-rus/releases/previous/bin-YYYYMMDD-HHMMSS/ /opt/awatch-rus/bin/ sudo systemctl restart awatch-rus-backend.service sudo systemctl restart aw-rus-healthd.service

13.2 Rollback конфигурации

sudo cp /etc/awatch-rus/awatch-rus.env.bak /etc/awatch-rus/awatch-rus.env sudo systemctl restart awatch-rus-backend.service

13.3 Rollback CT/VM

Если повреждение затрагивает runtime, данные или systemd-конфигурацию:

остановить сервисы восстановить snapshot/backup проверить health/readiness/version проверить портал проверить поступление данных зафиксировать incident note

  1. Monitoring

14.1 Что должно контролироваться

  • service status;
  • process uptime;
  • API health/readiness;
  • latency;
  • error rate;
  • freshness данных;
  • заполненность диска;
  • размер логов;
  • успешность exporters;
  • SLO status;
  • agent coverage;
  • отсутствие failed systemd units.

14.2 Grafana

В Grafana должны быть разделены витрины:

  • executive dashboard;
  • security dashboard;
  • operations dashboard;
  • RDP/user activity dashboard;
  • data quality/freshness dashboard;
  • DLP/evidence dashboard, если модуль включён.

14.3 Prometheus

Prometheus scrape должен быть доступен только из внутреннего контура мониторинга. Не открывать metrics endpoints наружу.

  1. Security hardening

Обязательные правила:

  • не публиковать API напрямую в интернет;
  • использовать VPN/reverse proxy/access control;
  • закрыть лишние порты;
  • хранить secrets вне git;
  • ограничить права systemd services;
  • использовать отдельного service user, если это поддерживается текущей установкой;
  • включить backup;
  • проверять логи после каждого патча;
  • не использовать demo fixtures как production data;
  • не смешивать реальные ФИО/IP/hostname с публичными demo screenshots.
  1. Проверка перед вводом в эксплуатацию

Минимальный checklist:

[ ] выбран commit/tag release [ ] cargo fmt прошёл [ ] cargo clippy прошёл [ ] cargo test прошёл [ ] cargo build --release прошёл [ ] private config guard прошёл [ ] backup/snapshot создан [ ] binaries установлены [ ] systemd services запущены [ ] health/readiness/version отвечают [ ] detmir-status/check/dlp работают [ ] portal открывается [ ] роли Pilot v1 проверены [ ] Grafana dashboards открываются [ ] данные поступают [ ] rollback path известен [ ] дата/commit/оператор зафиксированы

  1. Что больше не использовать как основной путь

Не использовать как основной production flow:

windows/deploy-single-user.ps1 windows/deploy-domain-users.ps1 windows/deploy-ensemble.ps1 windows/validate-deployment.ps1 windows/hardening-recovery.ps1 windows/browser-domains-native-collector.ps1 windows/dlp-endpoint-signals-collector.ps1

Если эти файлы физически остаются в репозитории, они должны быть явно помечены как:

legacy planned provider migration-only dev/test helper

Они не должны описываться в основном deployment manual как обязательный production-путь.

  1. Короткий production runbook

18.1 Развернуть

cargo fmt --all -- --check cargo clippy --workspace --all-targets -- -D warnings cargo test --workspace cargo build --release --workspace

sudo install -m 0755 target/release/ /opt/awatch-rus/bin/ sudo systemctl daemon-reload sudo systemctl restart .service

18.2 Проверить

systemctl --failed --no-pager detmir-status --json detmir-check --json curl -fsS http://127.0.0.1:5600/healthz curl -fsS http://127.0.0.1:5600/readyz curl -fsS http://127.0.0.1:5600/version

18.3 Откатить

sudo rsync -a --delete /opt/awatch-rus/releases/previous/bin-YYYYMMDD-HHMMSS/ /opt/awatch-rus/bin/ sudo systemctl restart .service

  1. Правило актуализации этого документа

Если меняется:

  • имя binary;
  • имя systemd unit;
  • порт;
  • endpoint;
  • путь хранения данных;
  • способ сборки;
  • способ доставки artifacts;
  • smoke-test;
  • rollback procedure;

то этот файл должен обновляться в том же commit, что и изменение кода или deployment-конфигурации.

Reference in New Issue View Git Blame Copy Permalink