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,308 @@
+# Полная инструкция по развёртыванию и поддержке ActivityWatch-Russian
+
+Документ описывает полный цикл: Proxmox/LXC сервер, установка ActivityWatch Server, RU Web UI patch, развёртывание Windows-клиентов в другом AD-домене, валидация, сопровождение и rollback.
+
+---
+
+## 0) Структура проекта (полные пути)
+
+- `/mnt/usb_hdd2/Projects/ActivityWatch-Russian/secrets/deploy.secrets.env`
+- `/mnt/usb_hdd2/Projects/ActivityWatch-Russian/proxmox/create-ct.sh`
+- `/mnt/usb_hdd2/Projects/ActivityWatch-Russian/proxmox/push-aw-artifacts.sh`
+- `/mnt/usb_hdd2/Projects/ActivityWatch-Russian/aw-server/install_aw_server.sh`
+- `/mnt/usb_hdd2/Projects/ActivityWatch-Russian/aw-server/apply_webui_ru_patch.sh`
+- `/mnt/usb_hdd2/Projects/ActivityWatch-Russian/windows/deploy-single-user.ps1`
+- `/mnt/usb_hdd2/Projects/ActivityWatch-Russian/windows/deploy-domain-users.ps1`
+- `/mnt/usb_hdd2/Projects/ActivityWatch-Russian/windows/hardening-recovery.ps1`
+- `/mnt/usb_hdd2/Projects/ActivityWatch-Russian/windows/browser-domains-native-collector.ps1`
+
+---
+
+## 1) Подготовка
+
+### 1.1 Требования
+
+- Proxmox VE 8/9, доступ root (или sudo с правами на `pct`).
+- Шаблон Debian 12 LXC на хосте Proxmox.
+- Windows хост(ы) с PowerShell 5.1+ и правами локального администратора.
+- Сетевой доступ Windows-клиентов до ActivityWatch Server (`5600/tcp`).
+
+### 1.2 Подготовка единого файла секретов
+
+Скопируйте шаблон:
+
+```bash
+cp /mnt/usb_hdd2/Projects/ActivityWatch-Russian/secrets/deploy.secrets.env.example \
+   /mnt/usb_hdd2/Projects/ActivityWatch-Russian/secrets/deploy.secrets.env
+```
+
+Заполните в файле `/mnt/usb_hdd2/Projects/ActivityWatch-Russian/secrets/deploy.secrets.env`:
+
+- все `CT_*` параметры контейнера;
+- все `AW_SERVER_*` параметры сервера;
+- `CT_PASSWORD` (реальный пароль).
+
+Важно: этот файл подхватывается автоматически скриптами Proxmox.
+
+---
+
+## 2) Развёртывание сервера в Proxmox
+
+### 2.1 Создать LXC контейнер
+
+На узле Proxmox:
+
+```bash
+cd /mnt/usb_hdd2/Projects/ActivityWatch-Russian
+/mnt/usb_hdd2/Projects/ActivityWatch-Russian/proxmox/create-ct.sh
+```
+
+По умолчанию читается:
+
+- `/mnt/usb_hdd2/Projects/ActivityWatch-Russian/secrets/deploy.secrets.env`
+
+При необходимости можно передать другой путь:
+
+```bash
+/mnt/usb_hdd2/Projects/ActivityWatch-Russian/proxmox/create-ct.sh /absolute/path/to/deploy.secrets.env
+```
+
+### 2.2 Загрузить bootstrap-артефакты и env внутрь CT
+
+```bash
+cd /mnt/usb_hdd2/Projects/ActivityWatch-Russian
+/mnt/usb_hdd2/Projects/ActivityWatch-Russian/proxmox/push-aw-artifacts.sh
+```
+
+Скрипт загружает в CT:
+
+- `/root/bootstrap/install_aw_server.sh`
+- `/root/bootstrap/apply_webui_ru_patch.sh`
+- `/root/bootstrap/activitywatch-server.service`
+- `/root/bootstrap/aw-ru-patch.js`
+- `/root/bootstrap/aw-sw-cleanup.js`
+- `/etc/activitywatch/aw-server.env` (из `AW_SERVER_*`)
+
+### 2.3 Установить ActivityWatch Server внутри CT
+
+```bash
+pct enter <CT_ID>
+bash /root/bootstrap/install_aw_server.sh
+```
+
+### 2.4 Применить RU patch Web UI
+
+```bash
+bash /root/bootstrap/apply_webui_ru_patch.sh
+systemctl restart activitywatch-server.service
+```
+
+### 2.5 Проверка сервера
+
+В CT:
+
+```bash
+systemctl status activitywatch-server.service --no-pager
+curl -fsS http://127.0.0.1:5600/api/0/info
+ss -ltnp | grep 5600
+grep -n 'aw-ru-patch\|aw-sw-cleanup' /opt/activitywatch/webui-ru/index.html
+```
+
+Ожидается:
+
+- сервис `active (running)`;
+- API отвечает JSON;
+- порт 5600 слушается;
+- в `index.html` присутствуют оба скрипта.
+
+---
+
+## 3) Развёртывание Windows-клиентов (другой AD-домен)
+
+### 3.1 Подготовка на Windows-хосте
+
+Скопируйте каталог:
+
+- `/mnt/usb_hdd2/Projects/ActivityWatch-Russian/windows`
+
+например в:
+
+- `C:\Deploy\ActivityWatch-Russian\windows`
+
+Откройте **elevated PowerShell**:
+
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
+```
+
+### 3.2 Массовое доменное развёртывание (рекомендуется)
+
+Пример со списком пользователей:
+
+```powershell
+C:\Deploy\ActivityWatch-Russian\windows\deploy-domain-users.ps1 `
+  -ServerHost aw.example.local `
+  -ServerPort 5600 `
+  -Domain CONTOSO `
+  -UserListPath C:\Deploy\aw-users.txt `
+  -CustomRulesPath C:\Deploy\ActivityWatch-Russian\windows\web-category-rules.example.json
+```
+
+Поддерживаемые варианты:
+
+- `-Users user01,user02`
+- `-Users 'CONTOSO\user01','CONTOSO\user02'`
+- `-UserListPath <txt|csv>`
+
+### 3.3 Single-user развёртывание
+
+```powershell
+C:\Deploy\ActivityWatch-Russian\windows\deploy-single-user.ps1 `
+  -ServerHost aw.example.local `
+  -ServerPort 5600 `
+  -TargetUser 'CONTOSO\user01' `
+  -CustomRulesPath C:\Deploy\ActivityWatch-Russian\windows\web-category-rules.example.json
+```
+
+### 3.4 Recovery / hardening
+
+```powershell
+C:\Deploy\ActivityWatch-Russian\windows\hardening-recovery.ps1 `
+  -ConfigPath C:\ProgramData\ActivityWatch\deployment-config.json
+```
+
+---
+
+## 4) Что должно появиться на Windows после установки
+
+- `C:\Program Files\ActivityWatch`
+- `C:\ProgramData\ActivityWatch\deployment-config.json`
+- `C:\ProgramData\ActivityWatch\launch-watchers.ps1`
+- `C:\ProgramData\ActivityWatch\recovery-loop.ps1`
+- `C:\ProgramData\ActivityWatch\browser-domains-native-collector.ps1`
+- `C:\ProgramData\ActivityWatch\web-category-rules.json`
+- `C:\ProgramData\ActivityWatch\logs\`
+
+Задачи планировщика:
+
+- `ActivityWatch Launch [<user>]` (per-user, при логоне)
+- `ActivityWatch Recovery` (system-level recovery)
+
+---
+
+## 5) Полная валидация потока данных
+
+### 5.1 На Windows-хосте
+
+Проверить процессы:
+
+```powershell
+Get-Process aw-watcher-afk,aw-watcher-window -ErrorAction SilentlyContinue
+Get-CimInstance Win32_Process | ? { $_.CommandLine -like '*browser-domains-native-collector.ps1*' } | select ProcessId,SessionId,CommandLine
+```
+
+Проверить задачи:
+
+```powershell
+Get-ScheduledTask | ? { $_.TaskName -like 'ActivityWatch*' } | select TaskName,State
+```
+
+### 5.2 На сервере ActivityWatch API
+
+```bash
+curl -sS http://127.0.0.1:5600/api/0/buckets | jq 'keys'
+```
+
+Ожидаемые bucket'ы:
+
+- `aw-watcher-afk_<HOST>`
+- `aw-watcher-window_<HOST>`
+- `aw-watcher-web-<browser>_<HOST>`
+- `aw-detmir-web-category_<HOST>` (категоризованный поток)
+
+Проверка событий браузера:
+
+```bash
+curl -sS "http://127.0.0.1:5600/api/0/buckets/aw-watcher-web-edge_<HOST>/events?limit=5" | jq
+```
+
+Проверка категоризации:
+
+```bash
+curl -sS "http://127.0.0.1:5600/api/0/buckets/aw-detmir-web-category_<HOST>/events?limit=5" | jq
+```
+
+---
+
+## 6) Сопровождение (обязательно)
+
+### 6.1 Backup перед любыми изменениями
+
+На Proxmox:
+
+```bash
+vzdump <CT_ID> --mode snapshot --compress zstd --storage <BACKUP_STORAGE>
+```
+
+Конфиги внутри CT:
+
+```bash
+pct exec <CT_ID> -- tar -C / -czf /root/activitywatch-config-backup.tgz \
+  etc/activitywatch \
+  etc/systemd/system/activitywatch-server.service \
+  opt/activitywatch/webui-ru \
+  opt/activitywatch/releases
+```
+
+### 6.2 Обновление сервера
+
+1. Обновить `AW_SERVER_VERSION` и `AW_SERVER_DOWNLOAD_URL` в  
+   `/mnt/usb_hdd2/Projects/ActivityWatch-Russian/secrets/deploy.secrets.env`
+2. Выполнить:
+
+```bash
+/mnt/usb_hdd2/Projects/ActivityWatch-Russian/proxmox/push-aw-artifacts.sh
+pct enter <CT_ID>
+bash /root/bootstrap/install_aw_server.sh
+bash /root/bootstrap/apply_webui_ru_patch.sh
+systemctl restart activitywatch-server.service
+```
+
+3. Повторить валидацию API/UI.
+
+### 6.3 Rollback
+
+RU patch rollback:
+
+```bash
+cp /opt/activitywatch/webui-ru/index.html.bak.<timestamp> /opt/activitywatch/webui-ru/index.html
+systemctl restart activitywatch-server.service
+```
+
+Полный rollback:
+
+- восстановить CT из snapshot/backup;
+- проверить API и Web UI;
+- проверить доступность для Windows-клиентов.
+
+---
+
+## 7) Безопасность
+
+- Не хранить реальные секреты вне `/mnt/usb_hdd2/Projects/ActivityWatch-Russian/secrets/deploy.secrets.env`.
+- Не открывать `5600/tcp` в интернет напрямую.
+- Публиковать через VPN или reverse proxy с ограничением доступа.
+- Перед изменениями всегда делать backup.
+
+---
+
+## 8) Короткий чек-лист ввода в эксплуатацию
+
+1. Заполнен `/mnt/usb_hdd2/Projects/ActivityWatch-Russian/secrets/deploy.secrets.env`.
+2. Выполнен `/mnt/usb_hdd2/Projects/ActivityWatch-Russian/proxmox/create-ct.sh`.
+3. Выполнен `/mnt/usb_hdd2/Projects/ActivityWatch-Russian/proxmox/push-aw-artifacts.sh`.
+4. В CT выполнены `/root/bootstrap/install_aw_server.sh` и `/root/bootstrap/apply_webui_ru_patch.sh`.
+5. Сервер API/порт/UI проверены.
+6. На Windows выполнен `deploy-domain-users.ps1`.
+7. Проверены процессы, задачи и bucket'ы.
+8. Зафиксированы параметры и дата ввода.
@@ -0,0 +1,116 @@
+# Deployment
+
+## 1. Подготовить env-файлы
+
+На рабочей машине оператора:
+
+```sh
+cp proxmox/ct-vars.example.env /root/activitywatch-ct.env
+cp aw-server/aw-server.env.example /root/activitywatch-aw.env
+```
+
+Заполнить оба файла реальными значениями вне git.
+
+## 2. Создать CT на Proxmox
+
+На узле Proxmox:
+
+```sh
+cd /path/to/ActivityWatch-Russian
+./proxmox/create-ct.sh /root/activitywatch-ct.env
+```
+
+Скрипт:
+
+- валидирует обязательные переменные;
+- создаёт Debian 12 CT;
+- запускает контейнер;
+- выполняет минимальный bootstrap пакетов;
+- готовит `/root/bootstrap` для дальнейшей загрузки артефактов.
+
+## 3. Загрузить артефакты в CT
+
+На узле Proxmox:
+
+```sh
+./proxmox/push-aw-artifacts.sh /root/activitywatch-ct.env
+pct push <CT_ID> /root/activitywatch-aw.env /etc/activitywatch/aw-server.env
+```
+
+В CT будут загружены:
+
+- `install_aw_server.sh`
+- `apply_webui_ru_patch.sh`
+- `activitywatch-server.service`
+- `aw-ru-patch.js`
+- `aw-sw-cleanup.js`
+
+## 4. Установить ActivityWatch Server
+
+Внутри CT:
+
+```sh
+pct enter <CT_ID>
+bash /root/bootstrap/install_aw_server.sh
+```
+
+Скрипт установки:
+
+- ставит `curl`, `unzip`, `jq`, `ca-certificates`;
+- создаёт пользователя `activitywatch`;
+- скачивает release `aw-server-rust`;
+- раскладывает бинарник по версиям;
+- создаёт активный symlink;
+- копирует systemd unit;
+- включает и запускает сервис.
+
+## 5. Применить RU patch для Web UI
+
+Внутри CT:
+
+```sh
+bash /root/bootstrap/apply_webui_ru_patch.sh
+systemctl restart activitywatch-server.service
+```
+
+Патч:
+
+- копирует `aw-ru-patch.js` и `aw-sw-cleanup.js`;
+- делает backup `index.html`;
+- добавляет include в `index.html`;
+- заменяет `service-worker.js` cleanup-версией для сброса старого cache.
+
+## 6. Проверить сервис
+
+```sh
+systemctl status activitywatch-server.service --no-pager
+curl -fsS http://127.0.0.1:5600/api/0/info
+ss -ltnp | grep 5600
+grep -n 'aw-ru-patch\|aw-sw-cleanup' /opt/activitywatch/webui-ru/index.html
+```
+
+Ожидаемо:
+
+- сервис `active (running)`;
+- API отвечает;
+- порт слушается;
+- в `index.html` есть оба include.
+
+## 7. После публикации
+
+Проверить извне:
+
+- открывается `/`;
+- API доступен по ожидаемому URL;
+- после hard refresh видна русификация;
+- reverse proxy не кэширует старую статику.
+
+## 8. Что зафиксировать после ввода
+
+- дата ввода;
+- узел Proxmox;
+- `CT_ID`;
+- IP/FQDN;
+- версия `aw-server-rust`;
+- место хранения backup;
+- фактическая схема публикации.
@@ -0,0 +1,113 @@
+# Operations
+
+## Эксплуатационная модель
+
+Система состоит из:
+
+- узла Proxmox VE;
+- LXC-контейнера с Debian 12;
+- `ActivityWatch Server` на Rust;
+- Web UI override с RU patch;
+- systemd unit `activitywatch-server.service`.
+
+Базовые правила:
+
+- все изменения только через backup-first workflow;
+- секреты не хранить в git;
+- каждое изменение фиксировать в ticket/run log;
+- публичную публикацию делать через отдельный proxy/security layer.
+
+## Регулярные проверки
+
+### Ежедневно или перед работами
+
+- `pct status <CT_ID>`;
+- `systemctl is-active activitywatch-server.service`;
+- локальный `curl /api/0/info`;
+- `df -h`;
+- `journalctl -p err -b`.
+
+### Еженедельно
+
+- проверить свежесть backup/snapshot;
+- проверить publish URL извне;
+- проверить срок TLS, если есть reverse proxy;
+- перепроверить firewall/ACL для `5600/tcp`.
+
+### Ежемесячно
+
+- проверить новые релизы ActivityWatch;
+- сделать dry-run rollback;
+- обновить runbook при изменениях инфраструктуры.
+
+## Backup
+
+Минимум сохранять:
+
+- backup CT через `vzdump`;
+- `/etc/activitywatch/aw-server.env`;
+- `/etc/systemd/system/activitywatch-server.service`;
+- `/opt/activitywatch/webui-ru/`;
+- `/opt/activitywatch/releases/`;
+- конфиг reverse proxy, если он есть.
+
+Пример:
+
+```sh
+vzdump <CT_ID> --mode snapshot --compress zstd --storage <BACKUP_STORAGE>
+pct exec <CT_ID> -- tar -C / -czf /root/activitywatch-config-backup.tgz \
+  etc/activitywatch etc/systemd/system/activitywatch-server.service opt/activitywatch/webui-ru
+```
+
+## Rollback
+
+### Быстрый rollback RU patch
+
+```sh
+cp /opt/activitywatch/webui-ru/index.html.bak.<timestamp> /opt/activitywatch/webui-ru/index.html
+systemctl restart activitywatch-server.service
+```
+
+### Rollback server release
+
+1. Остановить сервис.
+2. Переключить symlink на предыдущий release.
+3. Проверить права.
+4. Запустить сервис.
+5. Проверить API/UI.
+
+### Полный rollback CT
+
+- остановить CT;
+- восстановить snapshot или `vzdump`;
+- поднять CT;
+- проверить API и publish path.
+
+## Обновление
+
+Порядок:
+
+1. Сделать backup.
+2. Скачать новый release в отдельную директорию.
+3. Не затирать прошлую версию до успешной проверки.
+4. Проверить совместимость RU patch.
+5. Перезапустить сервис.
+6. Проверить API/UI.
+7. Зафиксировать результат.
+
+## Эскалация
+
+Эскалировать сразу, если:
+
+- потерян доступ к Proxmox или CT;
+- backup chain повреждён;
+- UI/API не вернулись после rollback;
+- изменились маршруты, bridge, VLAN или firewall policy;
+- нужен новый публичный endpoint.
+
+## Что не делать
+
+- не вшивать реальные IP, пароли и токены;
+- не обновлять поверх рабочего бинарника без backup;
+- не открывать `5600/tcp` наружу без отдельной защиты;
+- не править `index.html` вручную без backup.
@@ -0,0 +1,92 @@
+# Preparation
+
+## Цель
+
+Подготовить чистое окружение для повторяемого развёртывания отдельного `ActivityWatch Server` в LXC-контейнере на Proxmox без зависимости от старой инсталляции.
+
+## Что определить заранее
+
+### Инфраструктурные параметры
+
+- имя узла Proxmox;
+- `CT_ID`;
+- `CT_HOSTNAME`;
+- `CT_BRIDGE`;
+- `CT_VLAN`, если нужен;
+- статический IP/маска/шлюз;
+- список DNS;
+- storage для `rootfs`;
+- размер диска;
+- лимиты CPU/RAM/SWAP;
+- timezone;
+- внутренний или внешний FQDN для публикации.
+
+### Доступы
+
+Хранить вне репозитория:
+
+- SSH/API-доступ к Proxmox;
+- пароль или ключ для CT;
+- TLS-сертификаты reverse proxy;
+- токены внешнего мониторинга или backup target.
+
+## Рекомендуемая базовая схема
+
+- Proxmox VE 8/9
+- Debian 12 LXC
+- `unprivileged=1`
+- `nesting=1,keyctl=1`
+- внутренний listen ActivityWatch: `0.0.0.0:5600`
+- внешняя публикация только через VPN или reverse proxy
+
+## Проверки на узле Proxmox
+
+```sh
+pveversion
+pveam update
+pveam available | grep debian-12
+pvesm status
+pct list
+```
+
+Проверить:
+
+- есть место под CT и backup;
+- `CT_ID` не занят;
+- выбранный bridge/VLAN реально маршрутизируется;
+- Debian template доступен;
+- есть маршрут до будущего адреса контейнера.
+
+## Что подготовить до деплоя
+
+- заполненный `secrets/deploy.secrets.env` (единый файл для CT + AW server);
+- согласованный URL релиза `aw-server-rust`;
+- решение по публикации: VPN или reverse proxy;
+- решение по backup: `vzdump`, snapshot, rsync, NAS или object storage.
+
+## Единый файл секретов
+
+Файл `secrets/deploy.secrets.env` автоматически подхватывается:
+
+- `proxmox/create-ct.sh`
+- `proxmox/push-aw-artifacts.sh`
+
+В нём хранятся:
+
+- `CT_*` параметры контейнера;
+- `AW_SERVER_*` параметры сервера.
+
+## Базовые каталоги внутри CT
+
+- `/opt/activitywatch/bin`
+- `/opt/activitywatch/releases`
+- `/opt/activitywatch/webui-ru`
+- `/etc/activitywatch`
+- `/var/lib/activitywatch`
+- `/var/log/activitywatch`
+
+## Security-заметки
+
+- не публиковать `5600/tcp` напрямую в интернет;
+- не хранить реальные значения в `.example` файлах;
+- перед вводом в эксплуатацию зафиксировать firewall, DNS и publish path в `docs/operations.md`.
@@ -0,0 +1,91 @@
+# Runbook
+
+## Быстрый health-check
+
+### На Proxmox
+
+```sh
+pct status <CT_ID>
+pct config <CT_ID>
+pct exec <CT_ID> -- systemctl is-active activitywatch-server.service
+pct exec <CT_ID> -- curl -fsS http://127.0.0.1:5600/api/0/info
+```
+
+### Внутри CT
+
+```sh
+systemctl status activitywatch-server.service --no-pager
+journalctl -u activitywatch-server.service -n 100 --no-pager
+curl -fsS http://127.0.0.1:5600/api/0/info
+ss -ltnp | grep 5600
+```
+
+## Проверка RU patch
+
+```sh
+grep -n 'aw-ru-patch\|aw-sw-cleanup' /opt/activitywatch/webui-ru/index.html
+ls -l /opt/activitywatch/webui-ru/js/
+```
+
+Проверить:
+
+- есть `aw-ru-patch.js`;
+- есть `aw-sw-cleanup.js`;
+- `index.html` содержит оба include;
+- `service-worker.js` заменён cleanup-версией.
+
+## Типовые инциденты
+
+### Сервис не стартует
+
+```sh
+systemctl cat activitywatch-server.service
+cat /etc/activitywatch/aw-server.env
+journalctl -xeu activitywatch-server.service --no-pager
+```
+
+Частые причины:
+
+- битый URL релиза;
+- неполная распаковка архива;
+- занят порт;
+- не созданы каталоги или пользователь;
+- ошибка в env-файле.
+
+### API отвечает, но UI без русификации
+
+Проверить:
+
+- патч реально вставлен в `index.html`;
+- browser cache/service worker очищен;
+- reverse proxy не отдаёт старую статику;
+- сервис был перезапущен после правок.
+
+Повторное применение:
+
+```sh
+bash /root/bootstrap/apply_webui_ru_patch.sh
+systemctl restart activitywatch-server.service
+```
+
+### После обновления UI сломался патч
+
+- сравнить `index.html` с backup;
+- заново применить patch script;
+- проверить словарь в `aw-ru-patch.js`;
+- при необходимости откатить только Web UI override.
+
+## Перед любыми изменениями
+
+1. Сделать snapshot или `vzdump`.
+2. Сохранить текущий `/etc/activitywatch/aw-server.env`.
+3. Сохранить текущий `index.html`.
+4. Зафиксировать текущую версию `aw-server-rust`.
+
+## Критерии готовности
+
+- systemd unit стартует без ручного вмешательства;
+- API `/api/0/info` отвечает локально;
+- UI открывается;
+- русификация присутствует;
+- rollback-путь понятен оператору.
@@ -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 события без расширений браузера.