chore: initial private ActivityWatch Russian deployment project

2026-04-25 15:24:04 +03:00
commit 0821de0964
26 changed files with 2915 additions and 0 deletions
@@ -0,0 +1,111 @@
+# Windows deployment
+
+## Состав пакета
+
+- `windows/deploy-single-user.ps1` — развёртывание для одного пользователя.
+- `windows/deploy-domain-users.ps1` — массовое развёртывание по списку пользователей.
+- `windows/hardening-recovery.ps1` — повторная регистрация задач, ACL и recovery-loop.
+- `windows/browser-domains-native-collector.ps1` — native collector доменов браузера с категоризацией.
+- `windows/web-category-rules.example.json` — пример кастомных правил категоризации.
+
+## Что делает пакет
+
+- Ставит `aw-watcher-afk` и `aw-watcher-window` из официального Windows ZIP ActivityWatch.
+- Копирует browser-domain collector в `C:\ProgramData\ActivityWatch`.
+- Создаёт per-user задачи `ActivityWatch Launch [...]` с запуском при логоне.
+- Создаёт системную задачу `ActivityWatch Recovery`, которая циклически перезапускает per-user launch tasks.
+- Применяет ACL к `C:\Program Files\ActivityWatch`, `C:\ProgramData\ActivityWatch` и каталогу логов.
+- Не содержит хардкодов инфраструктуры: сервер, домен, список пользователей и правила передаются параметрами.
+
+## Предпосылки
+
+- Windows 10/11 или Windows Server с PowerShell 5.1+.
+- Запуск из elevated PowerShell.
+- Доступ до ActivityWatch Server по `host:port`.
+- Пользователи домена должны реально входить на хост интерактивно.
+- Если интернет недоступен, заранее скачайте ActivityWatch ZIP и передайте `-PackageZipPath`.
+
+## Single-user deploy
+
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
+
+.\windows\deploy-single-user.ps1 `
+  -ServerHost aw.example.local `
+  -ServerPort 5600 `
+  -TargetUser 'CONTOSO\svc.activity.user01' `
+  -CustomRulesPath .\windows\web-category-rules.example.json
+```
+
+Локальный пользователь:
+
+```powershell
+.\windows\deploy-single-user.ps1 `
+  -ServerHost aw-gateway.internal `
+  -ServerPort 5600 `
+  -TargetUser '.\operator01'
+```
+
+Оффлайн-установка из локального ZIP:
+
+```powershell
+.\windows\deploy-single-user.ps1 `
+  -ServerHost aw.example.local `
+  -TargetUser 'CONTOSO\user01' `
+  -PackageZipPath C:\Temp\activitywatch-v0.13.2-windows-x86_64.zip
+```
+
+## Multi-user / domain deploy
+
+Поддерживаются:
+
+- `-Users user1,user2`
+- `-Users 'CONTOSO\user1','CONTOSO\user2'`
+- `-UserListPath .\users.txt`
+- `-UserListPath .\users.csv`
+
+TXT-формат:
+
+```text
+# comments are ignored
+user01
+user02
+user03
+```
+
+CSV-формат: колонка `User`, `Username`, `SamAccountName` или `Login`.
+
+Пример:
+
+```powershell
+.\windows\deploy-domain-users.ps1 `
+  -ServerHost aw.example.local `
+  -ServerPort 5600 `
+  -Domain CONTOSO `
+  -UserListPath C:\Temp\aw-users.txt `
+  -CustomRulesPath C:\Temp\web-category-rules.json
+```
+
+Если список уже содержит `DOMAIN\user`, параметр `-Domain` не нужен.
+
+## Категоризация доменов
+
+- Встроенные категории покрывают базовые рабочие, нейтральные и личные домены.
+- Для кастомизации скопируйте `windows/web-category-rules.example.json` и отредактируйте домены.
+- Передайте файл через `-CustomRulesPath`; он будет сохранён как `C:\ProgramData\ActivityWatch\web-category-rules.json`.
+- Пользовательские правила имеют приоритет над встроенными.
+
+## Структура после установки
+
+- `C:\Program Files\ActivityWatch` — бинарники watcher'ов.
+- `C:\ProgramData\ActivityWatch\deployment-config.json` — итоговая конфигурация.
+- `C:\ProgramData\ActivityWatch\launch-watchers.ps1` — per-user launcher.
+- `C:\ProgramData\ActivityWatch\recovery-loop.ps1` — system recovery loop.
+- `C:\ProgramData\ActivityWatch\browser-domains-native-collector.ps1` — runtime collector.
+- `C:\ProgramData\ActivityWatch\logs\` — логи collector'а.
+
+## Повторный прогон
+
+- Скрипты идемпотентны: переустанавливают задачи и обновляют runtime-файлы.
+- Предыдущая установка ActivityWatch бэкапится в `C:\ProgramData\ActivityWatch\backups\install-YYYYMMDD-HHMMSS`.
+- Для жёсткого восстановления запускайте `windows/hardening-recovery.ps1`.
@@ -0,0 +1,102 @@
+# Windows troubleshooting
+
+## Частые проблемы
+
+### `Run this script from an elevated PowerShell session`
+
+- Откройте PowerShell через `Run as administrator`.
+- Проверьте, что UAC не понизил токен.
+
+### Задачи созданы, но watcher'ы не стартуют
+
+- Убедитесь, что пользователь реально вошёл в интерактивную сессию.
+- Проверьте задачу `ActivityWatch Launch [...]` в Task Scheduler.
+- Запустите вручную:
+
+```powershell
+Start-ScheduledTask -TaskName 'ActivityWatch Launch [CONTOSO_user01]'
+```
+
+- Если доменный логон ещё ни разу не происходил на хосте, сначала выполните вход этим пользователем.
+
+### Collector не видит URL
+
+- Скрипт работает через UI Automation и foreground window.
+- Некоторые браузеры/страницы могут скрывать адресную строку или блокировать UIA.
+- Проверьте лог `C:\ProgramData\ActivityWatch\logs\browser-domains-<user>.log`.
+- Убедитесь, что активное окно — поддерживаемый браузер: Edge, Chrome, Brave, Vivaldi, Opera, Firefox.
+
+### Сервер недоступен
+
+- Проверьте TCP-доступ:
+
+```powershell
+Test-NetConnection aw.example.local -Port 5600
+```
+
+- Проверьте локально API:
+
+```powershell
+Invoke-WebRequest http://aw.example.local:5600/api/0/info
+```
+
+- Если нужен HTTPS reverse proxy, задайте `-ServerScheme https`.
+
+### Неправильная категоризация домена
+
+- Проверьте содержимое `C:\ProgramData\ActivityWatch\web-category-rules.json`.
+- Пользовательские правила должны быть валидным JSON.
+- Один и тот же домен лучше определять только в одной категории.
+- После изменения правил достаточно перезапустить collector или задачу пользователя:
+
+```powershell
+Stop-Process -Name powershell -ErrorAction SilentlyContinue
+Start-ScheduledTask -TaskName 'ActivityWatch Launch [CONTOSO_user01]'
+```
+
+### ACL сломаны или пользователи удалили runtime-файлы
+
+- Запустите:
+
+```powershell
+.\windows\hardening-recovery.ps1 -RepairPackage
+```
+
+- Если сервер и пользователи уже есть в `deployment-config.json`, дополнительные параметры не нужны.
+
+## Диагностика
+
+Проверить задачи:
+
+```powershell
+Get-ScheduledTask -TaskName 'ActivityWatch*' | Select-Object TaskName, State
+```
+
+Проверить процессы в пользовательской сессии:
+
+```powershell
+Get-Process aw-watcher-afk, aw-watcher-window -ErrorAction SilentlyContinue |
+  Select-Object ProcessName, Id, SessionId, StartTime
+```
+
+Проверить collector:
+
+```powershell
+Get-CimInstance Win32_Process |
+  Where-Object { $_.Name -in 'powershell.exe', 'pwsh.exe' -and $_.CommandLine -match 'browser-domains-native-collector.ps1' } |
+  Select-Object ProcessId, SessionId, CommandLine
+```
+
+Проверить конфиг:
+
+```powershell
+Get-Content C:\ProgramData\ActivityWatch\deployment-config.json -Raw
+```
+
+## Когда запускать hardening/recovery
+
+- После ручной чистки задач.
+- После неудачного обновления ActivityWatch.
+- После переноса сервера на другой host/port.
+- После обновления списка пользователей.
+- После изменения кастомных правил, если нужен централизованный repair pass.
@@ -0,0 +1,109 @@
+# Windows validation
+
+## Базовая проверка после развёртывания
+
+### 1. Проверить установленные файлы
+
+```powershell
+Test-Path 'C:\Program Files\ActivityWatch\aw-watcher-afk\aw-watcher-afk.exe'
+Test-Path 'C:\Program Files\ActivityWatch\aw-watcher-window\aw-watcher-window.exe'
+Test-Path 'C:\ProgramData\ActivityWatch\browser-domains-native-collector.ps1'
+Test-Path 'C:\ProgramData\ActivityWatch\deployment-config.json'
+```
+
+Ожидаемый результат — везде `True`.
+
+### 2. Проверить задачи
+
+```powershell
+Get-ScheduledTask -TaskName 'ActivityWatch*' |
+  Select-Object TaskName, Author, State
+```
+
+Ожидаемо:
+
+- по одной задаче `ActivityWatch Launch [...]` на пользователя;
+- одна задача `ActivityWatch Recovery`.
+
+### 3. Проверить процессы после логина пользователя
+
+```powershell
+Get-Process aw-watcher-afk, aw-watcher-window -ErrorAction SilentlyContinue |
+  Select-Object ProcessName, SessionId, StartTime
+```
+
+И collector:
+
+```powershell
+Get-CimInstance Win32_Process |
+  Where-Object { $_.Name -in 'powershell.exe', 'pwsh.exe' -and $_.CommandLine -match 'browser-domains-native-collector.ps1' } |
+  Select-Object ProcessId, SessionId, CommandLine
+```
+
+### 4. Проверить сетевую связность
+
+```powershell
+Test-NetConnection aw.example.local -Port 5600
+Invoke-WebRequest http://aw.example.local:5600/api/0/info
+```
+
+Если используется HTTPS:
+
+```powershell
+Invoke-WebRequest https://aw.example.local/api/0/info
+```
+
+### 5. Проверить buckets на сервере
+
+После открытия нескольких сайтов в браузере на сервере должны появиться:
+
+- `aw-watcher-window_<hostname>`
+- `aw-watcher-web-edge_<hostname>` или другой browser bucket
+- `aw-watcher-web-category_<hostname>`
+
+Проверка через API:
+
+```powershell
+Invoke-WebRequest http://aw.example.local:5600/api/0/buckets | Select-Object -ExpandProperty Content
+```
+
+## Проверка категоризации
+
+1. Откройте сайт из кастомного правила.
+2. Подождите `PollSeconds + PulseSeconds`.
+3. Проверьте category bucket на сервере.
+4. Убедитесь, что поля `domain`, `rootDomain`, `category`, `categoryGroup`, `categoryRule` заполнены.
+
+## Проверка восстановления
+
+1. Завершите `aw-watcher-afk.exe` и `aw-watcher-window.exe` у тестового пользователя.
+2. Подождите до `RecoveryIntervalSeconds`.
+3. Убедитесь, что per-user launch task стартовала процессы заново.
+
+Ручной запуск recovery:
+
+```powershell
+Start-ScheduledTask -TaskName 'ActivityWatch Recovery'
+```
+
+## Проверка ACL
+
+```powershell
+icacls 'C:\Program Files\ActivityWatch'
+icacls 'C:\ProgramData\ActivityWatch'
+icacls 'C:\ProgramData\ActivityWatch\logs'
+```
+
+Ожидаемо:
+
+- `SYSTEM` и `Administrators` имеют `F`;
+- `Users` имеет `RX` на install/state;
+- `Users` имеет `M` на `logs`.
+
+## Критерий готовности к массовому развёртыванию
+
+- Установка проходит без ручного редактирования скриптов.
+- Все параметры инфраструктуры передаются снаружи.
+- Повторный запуск не ломает текущую установку.
+- Recovery восстанавливает запуск watcher'ов после остановки.
+- Collector пишет domain/category события без расширений браузера.