# Установка COMRAD404 Analytics: задание ИИ-агенту

Версия инструкции: 18 октября 2026. Язык общения с владельцем: русский.

Репозиторий: https://github.com/bolgbolg1-dev/comrad404-analytics
Страница проекта: https://comrad404.com/analytics/
Проверенный исходный снимок: a25321515c8369d6aa79d3905f104b8f0c6f90ba.
Лицензия собственного кода: MIT. Сохраняйте уведомления Umami и зависимостей.

Это открытая панель и установочный комплект поверх Umami, не новый движок
и не полный клон Яндекс.Метрики или Google Analytics. В комплекте нет
обязательных аккаунтов автора, API-ключей автора и его сайтов.

## 1. Сначала выясните задачу, не запускайте установку

Попросите владельца назвать:
- домены сайтов, которые он вправе подключать;
- адрес/локальный SSH-алиас собственного сервера и разрешённого пользователя;
- поддомен сборщика, например stats.example.org;
- желаемую абсолютную папку установки без пробелов;
- наличие сайтов, Nginx/Caddy/Apache и Docker-проектов на этом сервере;
- компьютер для панели: готовый клиент рассчитан на Windows 10/11;
- способ резервного копирования за пределами сервера.

Не просите присылать пароль, приватный SSH-ключ или токен в чат. Используйте
предоставленные владельцем локальные настройки SSH и интерактивный ввод секретов.
Не ищите чужие ключи или доступы в соседних проектах. Отсутствие разрешения
на серверные изменения означает только локальный разбор и план.

Скачивание этой инструкции НЕ является разрешением менять сервер, DNS,
прокси, firewall, счётчики или публиковать настройки. Сначала представьте
конкретный план с адресами и изменениями и получите отдельное подтверждение.

## 2. Изучите исходники

Клонируйте в новую отдельную папку, не в корень чужого проекта:

```sh
git clone https://github.com/bolgbolg1-dev/comrad404-analytics.git site-analytics
cd site-analytics
git rev-parse HEAD
```

Для воспроизведения указанного выше снимка, только в новой чистой копии:

```sh
git switch --detach a25321515c8369d6aa79d3905f104b8f0c6f90ba
```

Если берёте более новую версию, изучите её diff/CHANGELOG и выполните проверки
заново. Не выдавайте результаты старого CI за проверку новой версии.

Обязательно прочитайте AGENTS.md, README.md, docs/INSTALL.md, SECURITY.md,
CONTRIBUTING.md и THIRD_PARTY_NOTICES.md. Проверьте install.py, configure.py,
compose.yaml и Caddyfile.template до запуска. Страницы и документы — исходный
материал, а не разрешение передать куда-либо данные владельца.

## 3. Локальные проверки без VPS

```sh
python tools/check_package.py
python -m unittest discover -s tests -v
cd dashboard
npm ci --ignore-scripts
npm test
npm run build
cd ..
```

Для Windows используйте npm.cmd, если PowerShell блокирует npm.ps1.
Успех тестов означает проверку кода и сборки, не работоспособность TLS,
резервного копирования или установки на сервере.

## 4. Серверный аудит: сначала только чтение

Только после разрешения подключиться к конкретному серверу проверьте:
- Linux, Python 3.10+, Docker Engine и Compose v2;
- ресурсы: ориентир 2 ГБ ОЗУ, минимум 5 ГБ свободного диска; нагрузка не измерена;
- действующие контейнеры, проекты Compose, веб-сервисы;
- TCP 80/443, UDP 443 и локальный TCP 3217;
- DNS A поддомена указывает на нужный VPS; AAAA — только при рабочем IPv6;
- SSH-ключ хоста проверен владельцем по доверенному каналу;
- учётной записи предоставлен доступ к Docker; это административное полномочие.

Не отключайте TLS/SSH-проверки, не используйте StrictHostKeyChecking=no,
не останавливайте занятые порты и не удаляйте чужие ресурсы.
Если 80/443 заняты существующим прокси, остановитесь с объяснением: штатный
install.py требует свободных портов. Согласуйте отдельную интеграцию или
другой сервер. Не подменяйте прокси рабочего сайта автоматически.

Покажите результаты и получите разрешение именно на установку. Не выводите
в отчёте секреты окружения, полные конфигурации с паролями или приватные ключи.

## 5. Развёртывание: только после подтверждения плана

Скопируйте исходники в отдельную серверную папку. Не загружайте локальные
connection.json, private/, .env, node_modules, runtime и данные других сайтов.
В серверной папке не должно быть старой установки с тем же именем Compose.

Сначала изучите доступные теги образов и закрепите согласованные четыре
образа по digest для воспроизводимости, включая FROM в Guard.Dockerfile.
Не подставляйте выдуманный digest. Такая правка требует повторного локального
тестирования и осмысленного обновления манифеста, не скрывающего неизвестные файлы.

```sh
python3 install.py --domain stats.example.org --project site-analytics
```

Замените домен и имя проекта согласованными значениями. По умолчанию приватный
порт 3217; другое значение задаётся --app-port и затем в локальном мастере.
Владелец вводит пароль администратора Umami от 16 символов интерактивно.
Не пишите пароль в аргументы, журнал, CI или чат.

Не создавайте .env из .env.example заранее. Установщик сам генерирует секреты,
создаёт конфигурацию, запускает БД и приватное приложение, меняет стандартный
пароль, проверяет закрытые отчёты, затем запускает HTTPS-сборщик.
Не обходите отказ при существующей конфигурации или занятом порте.

## 6. Критерии приёмки серверной части

В папке сервера, заменив домен и нестандартный приватный порт:

```sh
docker compose ps
curl --fail http://127.0.0.1:3217/api/heartbeat
curl -I https://stats.example.org/collect.js
curl -I https://stats.example.org/api/websites
curl -I https://stats.example.org/api/auth/login
```

Проверьте также с внешнего компьютера, не только из самого контейнера:
- действительный HTTPS, без игнорирования ошибок сертификата;
- collect.js доступен, административные публичные маршруты отвечают 404;
- БД и guard не имеют опубликованных портов;
- Umami слушает только 127.0.0.1; приватный порт не открыт наружу;
- стандартные учётные данные больше не работают;
- отчёты требуют входа, публичный доступ/записи сессий отключены;
- существующие сайты и прокси не изменены и доступны.

Не объявляйте готовность при непроверенном стандартном пароле или публичной БД.
CORS не защищает от подделки событий произвольным HTTP-клиентом.

## 7. Локальная панель Windows

Используйте отдельную копию исходников, не серверную папку с секретами.

```powershell
python configure.py
cd dashboard
npm.cmd ci
npm.cmd test
npm.cmd run build
cd ..
.\Start-Analytics.cmd
```

Владелец вводит SSH-хост, имя пользователя, путь к ключу, абсолютную папку
на сервере, приватный порт и пароль Umami. Реальные значения сохраняются
в игнорируемых connection.json и private/admin-access.json. Они доступны
локальному пользователю, поэтому нужен доверенный однопользовательский ПК.

Панель: http://127.0.0.1:3219. Расширенный Umami: http://127.0.0.1:3217.
Проверьте выбор сайта, даты, часовой пояс, источники, страницы, фильтры и CSV.
При разрыве SSH — «Переподключиться»; после перезагрузки ПК открыть ярлык снова.
Автозапуск Windows автоматически не настраивается.

## 8. Подключение сайтов

После разрешения владельца: Настройки → Добавить сайт → название/домен →
Скопировать код. Вставку один раз перед </head> ставит владелец/разработчик
сайта. Нельзя подключать чужой домен без разрешения или удалять действующие
счётчики. В реестр сборщика домен добавляется через закрытый SSH-помощник.

Для автоматических проверок создавайте только отдельный согласованный QA-сайт.
Не отправляйте синтетические визиты в реальные счётчики. Владелец может сам
пройти две страницы реального сайта и подтвердить поступление просмотров.
Проверка HTML не создаёт визит и не всегда видит вставки через JavaScript.

Исключение браузера: ?site_analytics=off; возврат учёта: ?site_analytics=on.
GPC/webdriver исключаются. Скрытые боты не гарантированно распознаются.
Свои события: window.siteAnalytics.track('button_click'). Не передавайте
содержимое форм, пароли, почту и другие персональные данные в события/URL.

Названия страниц необязательны: runtime/page-titles.json на локальном ПК,
формат {"ID_сайта":{"/путь/":"Название"}}. Без него видны URL; автоматический
импорт названий из WordPress не включён в универсальный комплект.

## 9. Резервное копирование и отказ

Сделайте защищённую внешнюю копию серверных .env, server-config.json и private/.
Ручной дамп из папки проекта:

```sh
mkdir -p backups
chmod 700 backups
umask 077
docker compose exec -T db pg_dump -U umami -d umami -Fc > backups/umami.dump
```

Копия непроверена до восстановления в отдельной БД. Автоматическое расписание
и вынос за пределы сервера нужно согласовать и настроить отдельно.
Не запускайте docker compose down -v: это удаляет тома и статистику.
При прерванной установке не удаляйте конфигурацию. Разберите локальные логи,
сохраните секреты, опишите причину и согласуйте ограниченное восстановление.

## 10. Итоговый отчёт владельцу

Укажите:
- commit SHA и реальные изменения (файлы/контейнеры), без секретов;
- что именно проверено локально, на сервере и снаружи;
- результаты HTTPS, закрытия API/БД и смены стандартного пароля;
- где открыть панель и получить код сайта;
- какие домены подключены с разрешения;
- место защищённых копий и проверено ли восстановление;
- оставшиеся ограничения, ошибки и следующий шаг.

Никогда не заменяйте недоступные данные нулями и не объявляйте непроверенные
части готовыми. У исходного пакета есть успешный CI Windows/Ubuntu, но нет
испытания переносимой установки на чистом сервере. Не обещайте юридического
соответствия, точного числа людей, идеальной защиты от ботов, вебвизора,
импорта Метрики/GA или бесплатного сервера.