Files
AWatch-rus/docs/FULL_DEPLOYMENT_MANUAL_RU.md
T

668 lines
21 KiB
Markdown
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Полная инструкция по развёртыванию и поддержке AWatch-rus
Статус документа
Этот документ описывает актуальный **Rust-fiWindows/PowerShell deployment flow больше не считается основным способом развёртывания, патчинга или эксплуатации. Если в репозитории остаются старые ".ps1"-файлы, они рассматриваются как legacy/history или как будущий provider-слой, но не как production runtime.
0. Назначение
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.
2. Типовые роли узлов
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 в пилотной установке.
3. Требования
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
→ фиксация версии
4. Основные пути
Рекомендуемая структура на сервере:
/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.
5. Конфигурация
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
6. Сборка
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 должен быть проверен явно.
7. Первичное развёртывание 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
8. 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.
9. Развёртывание 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
10. Развёртывание портала
Портальный слой 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.
11. Патчи в развернутой среде
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.
12. 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 открываются
13. 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
14. 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 наружу.
15. Security hardening
Обязательные правила:
- не публиковать API напрямую в интернет;
- использовать VPN/reverse proxy/access control;
- закрыть лишние порты;
- хранить secrets вне git;
- ограничить права systemd services;
- использовать отдельного service user, если это поддерживается текущей установкой;
- включить backup;
- проверять логи после каждого патча;
- не использовать demo fixtures как production data;
- не смешивать реальные ФИО/IP/hostname с публичными demo screenshots.
16. Проверка перед вводом в эксплуатацию
Минимальный 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/оператор зафиксированы
17. Что больше не использовать как основной путь
Не использовать как основной 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-путь.
18. Короткий 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/<binary> /opt/awatch-rus/bin/<binary>
sudo systemctl daemon-reload
sudo systemctl restart <service>.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>.service
19. Правило актуализации этого документа
Если меняется:
- имя binary;
- имя systemd unit;
- порт;
- endpoint;
- путь хранения данных;
- способ сборки;
- способ доставки artifacts;
- smoke-test;
- rollback procedure;
то этот файл должен обновляться в том же commit, что и изменение кода или deployment-конфигурации.