SCADA.AI v1.0.0 — Руководство по установке (INSTALL.md)

Данный документ описывает полный процесс развёртывания системы SCADA.AI v1.0.0 в среде Windows с использованием Docker Desktop, включая настройку подключения к удалённой базе данных PostgreSQL.

1. Системные требования

Аппаратное обеспечение

Компонент	Минимальные требования	Рекомендуемые требования
CPU	4 ядра	8+ ядер (для параллельной сборки и DDA)
RAM	8 ГБ	16 ГБ и выше
Диск	20 ГБ свободного места (SSD)	50+ ГБ SSD (для образов, логов и БД)
Сеть	Локальная сеть (LAN)	Стабильное подключение к интернету (для YandexGPT API)

Программное обеспечение

ОС: Windows 10/11 Pro или Enterprise (с поддержкой WSL2).
Docker: Docker Desktop (последняя стабильная версия) с включённым WSL2 backend.
База данных: PostgreSQL 14+ (развёрнута на отдельном сервере или хост-машине).
Браузер: Google Chrome, Microsoft Edge или Яндекс.Браузер (последние версии).

Настройка ресурсов WSL2

По умолчанию Docker Desktop выделяет виртуальной машине WSL2 всего 2-4 ГБ оперативной памяти, чего недостаточно для компиляции Cython-модулей.

Создайте или отредактируйте файл C:\Users\<Ваш_Пользователь>\.wslconfig и добавьте:

[wsl2]
networkingMode=mirrored
memory=8GB
swap=4GB
processors=4

После этого выполните в PowerShell:

wsl --shutdown

И перезапустите Docker Desktop.

2. Установка Docker Desktop

Скачайте Docker Desktop с официального сайта: https://www.docker.com/products/docker-desktop/
Запустите установщик и выберите Use WSL 2 instead of Hyper-V (рекомендуется).
После установки перезагрузите компьютер.
Запустите Docker Desktop и дождитесь сообщения Docker Desktop is running.
Проверьте работу:

docker --version
docker run hello-world

3. Установка SCADA.AI

Распакуйте архив релиза SCADA_AI_v1.0.0.zip в любую папку (например, C:\SCADA).

ПРЕДУПРЕЖДЕНИЕ Не используйте пути с пробелами или кириллицей (например, C:\Мои документы\SCADA), это может вызвать ошибки в Docker.

Откройте папку релиза и запустите от имени администратора:

install.bat

Скрипт автоматически:
Проверит наличие Docker
Загрузит образы из scada_ai_bundle.tar
Запустит контейнеры scada-backend и scada-frontend
После сообщения "Установка завершена!" откройте в браузере: http://localhost

4. Проброс порта к удалённой БД (для ноутбуков)

Если база данных SCADA расположена на удалённой машине (а не на самом ноутбуке), необходимо настроить проброс порта через встроенную утилиту Windows netsh.

Суть проблемы

Docker-контейнер SCADA.AI стучится в host.docker.internal:5433. Если БД физически находится на другом компьютере в сети (например, 172.17.130.54:5433), контейнер не сможет до неё достучаться напрямую.

Схема работы

Docker-контейнер
    ↓ стучится в host.docker.internal:5433
Windows-хост (локальный порт 5433)
    ↓ netsh portproxy перенаправляет
Удалённая БД 172.17.130.54:5433

Решение: netsh portproxy

Создаём локальный слушатель на порту 5433, который перенаправляет весь трафик на удалённую БД.

Шаг 1. Откройте PowerShell от имени администратора.

Шаг 2. Выполните команду:

netsh interface portproxy add v4tov4 listenport=5433 listenaddress=0.0.0.0 connectport=5433 connectaddress=172.17.130.54

Шаг 3. Разрешите порт в брандмауэре:

New-NetFirewallRule -DisplayName "PostgreSQL 5433 proxy" -Direction Inbound -Protocol TCP -LocalPort 5433 -Action Allow

Шаг 4. Проверьте, что правило создано:

netsh interface portproxy show v4tov4

Должно вывести:

Listen on ipv4:             Connect to ipv4:
Address         Port        Address         Port
--------------  ----------  --------------  ----------
0.0.0.0         5433        172.17.130.54   5433

Шаг 5. Проверьте доступность:

Test-NetConnection -ComputerName localhost -Port 5433

Должно быть TcpTestSucceeded : True.

Альтернатива: прямой IP

Если ноутбук и БД находятся в одной локальной сети, можно обойтись без проброса — укажите в конфигураторе напрямую: * DB_HOST: 172.17.130.54 * DB_PORT: 5433

Но netsh portproxy предпочтительнее, т.к. позволяет использовать единый конфиг host.docker.internal на всех машинах.

Удаление правила

netsh interface portproxy delete v4tov4 listenport=5433 listenaddress=0.0.0.0

5. Подключение к Базе Данных через Конфигуратор

Пошаговая инструкция

Откройте в браузере http://localhost и войдите под учётной записью admin / admin123.
Перейдите в раздел Конфигуратор → вкладка Система.
В блоке "База данных (PostgreSQL)" введите:
Host: host.docker.internal
Port: 5433
Database: postgres
User: postgres
Password: <ваш пароль>
Нажмите Сохранить конфигурацию.
ОБЯЗАТЕЛЬНО перезапустите backend для применения изменений:

stop.bat
start.bat

Проверьте статус в боковой панели: индикатор рядом с "БД" должен стать зелёным (OK).

Частые ошибки

Ошибка	Причина	Решение
`Connection refused`	Неверный хост или порт	Проверьте `host.docker.internal` и порт `5433`
`password authentication failed`	Неверный пароль или раскладка клавиатуры	Введите пароль заново, проверив язык ввода
`timeout`	БД недоступна	Проверьте `netsh portproxy` и доступность удалённой машины
`name or service not known`	Неверный хост	Используйте `host.docker.internal` или реальный IP

6. Архитектура конфигурации v1.0.0

Начиная с версии 1.0.0, конфигурация системы разделена на два уровня для безопасности и удобства:

Секреты (.env): Зашиты в Docker-образ при сборке (build_release.py). Содержат только:
YANDEX_API_KEY
YANDEX_FOLDER_ID
ENABLED_MODULES

Изменить их после сборки нельзя (требуется пересборка образа).

Runtime-настройки (/data/system_config.json): Хранятся на постоянном томе Docker (./data в папке релиза). Содержат:
Настройки БД (db_host, db_port, db_name, db_user, db_password)
Город и координаты (city, latitude, longitude, timezone)
Параметры LLM (yandex_gpt_model, llm_temperature, llm_max_tokens, llm_timeout)
Список активных модулей (enabled_modules)

Изменяются через Конфигуратор в UI и сохраняются даже после удаления и пересоздания контейнеров.

7. Устранение неполадок (Troubleshooting)

Проблема 1: Ошибка `ERR_CONNECTION_TIMED_OUT` при обращении к `http://<IP-адрес>:8081`

Причина: Docker Desktop на Windows пробрасывает порты (port mapping) только на localhost (127.0.0.1). Обращение к виртуальному IP-адресу WSL2 (172.x.x.x) блокируется брандмауэром Windows или не маршрутизируется.
Решение: Всегда открывайте интерфейс через http://localhost. Если доступ по IP критически необходим, добавьте правило в Брандмауэр Windows:

New-NetFirewallRule -DisplayName "SCADA Backend 8081" -Direction Inbound -Protocol TCP -LocalPort 8081 -Action Allow

Проблема 2: Backend падает с ошибкой `Permission denied` при сохранении истории DDA

Причина: Скрипт пытался сохранить файл в относительный путь backend/data/..., который внутри контейнера недоступен для записи или не существует.
Решение: В версии 1.0.0 это исправлено. Убедитесь, что в коде modules/deep_analysis/history/storage.py используется абсолютный путь /data/analysis_history, а в docker-compose.yml том ./data:/data проброшен корректно.

Проблема 3: Ошибка компиляции Cython: `can't open file '/app/compile_cython.py'`

Причина: Файл compile_cython.py был заблокирован правилами .dockerignore и не попал в контекст сборки.
Решение: Убедитесь, что в файле backend/.dockerignore присутствует строка:

!compile_cython.py

Эта строка должна находиться после общих правил игнорирования (например, *.py), чтобы переопределить их.

Проблема 4: Настройки в Конфигураторе сбрасываются на дефолтные после `stop.bat` / `start.bat`

Причина: Функция get_env() в backend/api/routes/config.py читала данные из зашитого в образ .env, а не из system_config.json.
Решение: В v1.0.0 это исправлено. Убедитесь, что в config.py функция get_env() импортирует и возвращает значения из from config.settings import settings, а не парсит .env напрямую.

Проблема 5: Графики в Аналитике не отображают тренд/прогноз для VOC

Причина: В TrendChart.svelte было условие trend.slope_per_day !== 0, которое скрывало линию тренда для стабильных параметров.
Решение: В v1.0.0 условие изменено на проверку !== undefined && !== null, что позволяет отрисовывать тренд даже при нулевом наклоне.

Проблема 6: `password authentication failed for user "postgres"`

Причина: Неверный пароль или раскладка клавиатуры при вводе.
Решение: Введите пароль заново, проверив язык ввода. Убедитесь, что Caps Lock выключен.

8. Первая проверка работоспособности

После успешного запуска и настройки БД выполните чек-лист:

[ ] Открывается http://localhost, отображается версия v1.0.0 в хидере.
[ ] Успешный вход под admin / admin123.
[ ] В боковой панели индикаторы БД и LLM горят зелёным.
[ ] В разделе Аналитика строятся графики с трендами (включая VOC).
[ ] В разделе Deep Analysis успешно запускается сравнительный анализ (A/B) без ошибок 500.
[ ] Изменение любого параметра в Конфигуратор → Система сохраняется и отображается после перезапуска контейнеров.

9. Полезные команды

# Просмотр статуса контейнеров
docker ps

# Просмотр логов backend
docker logs scada-backend --tail=50

# Просмотр логов frontend
docker logs scada-frontend --tail=50

# Полный перезапуск системы
cd release/SCADA_AI_v1.0.0
stop.bat
start.bat

# Полное удаление (с очисткой volume)
uninstall.bat

10. Обновление системы

Для обновления на новую версию:

Остановите текущую систему:

stop.bat

Сделайте резервную копию папки data/ (там хранятся настройки и история):

xcopy data data_backup /E /I /H

Распакуйте новый релиз в отдельную папку.
Скопируйте папку data/ из старого релиза в новый (сохранит настройки БД и историю DDA).
Запустите установку:

install.bat

11. Удаление системы

Для полного удаления SCADA.AI:

cd release/SCADA_AI_v1.0.0
uninstall.bat

Скрипт удалит: - Контейнеры scada-backend и scada-frontend - Docker-образы scada-ai-backend:1.0.0 и scada-ai-frontend:1.0.0

Данные в папке data/ останутся нетронутыми (удалите вручную при необходимости).

12. Поддержка

При возникновении проблем:

Проверьте логи: docker logs scada-backend --tail=100
Убедитесь, что Docker Desktop запущен и работает.
Проверьте подключение к БД через Test-NetConnection.
Обратитесь к разделу "Устранение неполадок" выше.

Документация актуальна для релиза SCADA.AI v1.0.0. Дата обновления: 2026-10-15.