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. Зафиксированы параметры и дата ввода.