ваше сообщение коммита

docs/webssh-agent-detailed-analysis.md

@@ -0,0 +1,315 @@
+# 🤖 WebSSH Agent - Детальный анализ функциональности (ОБНОВЛЕНО)
+
+## 🆕 **ОСНОВНЫЕ ИЗМЕНЕНИЯ В ВЕРСИИ 2.0:**
+- ✅ **Умная проверка nginx** - агент автоматически определяет наличие системного nginx и удаляет его
+- ✅ **Docker nginx с автоматическим SSL** - полная автоматизация получения и обновления SSL сертификатов
+- ✅ **Certbot контейнер** - автоматическое получение SSL через webroot режим
+- ✅ **Автообновление SSL** - cron задача для ежедневного обновления сертификатов
+- ✅ **Исправлены все 12 ошибок** из отчета о развертывании
+- ✅ **Универсальность** - работает на любом VDS (с nginx или без)
+
+## 📋 **API Endpoints и их функции:**
+
+### 1. **GET /health** - Проверка состояния
+- **Что делает:** Возвращает статус агента и информацию о настроенных VDS
+- **Данные:** Текущее время, версия, состояние VDS
+- **Передает:** JSON с статусом агента
+
+### 2. **POST /vds/check-requirements** - Проверка системных требований
+- **Входные данные:**
+  - `vdsIp` - IP адрес VDS сервера
+  - `ubuntuUser` - имя пользователя Ubuntu
+  - `sshHost` - SSH хост (опционально)
+  - `sshPort` - SSH порт (по умолчанию 22)
+  - `sshConnectUser` - пользователь для SSH подключения
+  - `sshConnectPassword` - пароль для SSH подключения
+
+- **Что делает:**
+  - Подключается к VDS по SSH
+  - Проверяет системные требования (ОС, память, диск, CPU)
+  - Анализирует совместимость с приложением
+
+- **Передает:** JSON с результатами проверки, системной информацией, предупреждениями и ошибками
+
+### 3. **POST /vds/transfer-encryption-key** - Передача ключа шифрования
+- **Входные данные:**
+  - `vdsIp` - IP адрес VDS сервера
+  - `dockerUser` - пользователь Docker
+  - `sshConnectUser` - пользователь для SSH подключения
+  - `sshConnectPassword` - пароль для SSH подключения
+
+- **Что делает:**
+  - Читает ключ шифрования с локальной машины (`/app/ssl/keys/full_db_encryption.key`)
+  - Передает ключ на VDS через SCP в `/home/dockerUser/dapp/ssl/keys/full_db_encryption.key`
+  - Устанавливает правильные права доступа (600, владелец dockerUser)
+  - **Важно:** Путь соответствует монтированию `./ssl:/app/ssl:ro` в docker-compose.prod.yml
+
+- **Передает:** Ключ шифрования базы данных
+- **НЕ передает:** Пароли или другие секретные данные
+
+### 4. **POST /vds/setup** - Полная настройка VDS (ОСНОВНАЯ ФУНКЦИЯ)
+- **Входные данные:**
+  - `vdsIp` - IP адрес VDS сервера
+  - `domain` - доменное имя
+  - `email` - email для SSL сертификата
+  - `ubuntuUser` - пользователь Ubuntu
+  - `dockerUser` - пользователь Docker
+  - `sshConnectUser` - пользователь для SSH подключения
+  - `sshConnectPassword` - пароль для SSH подключения
+
+## 🔄 **Детальный порядок выполнения /vds/setup:**
+
+### **Этап 0: Проверка системных требований**
+- Подключается к VDS по SSH
+- Проверяет ОС, память, диск, CPU
+- Анализирует совместимость архитектуры
+- **Поддерживаемые архитектуры:** x86_64, amd64, aarch64, arm64, armv7l, armv8l, i386, i686, ppc64le, s390x
+- **Минимальные требования:** 6GB RAM, 30GB диск, 2 CPU ядра
+- **Рекомендуемые требования:** 8GB RAM, 50GB диск
+
+### **Этап 1: Создание SSH ключей локально**
+- Создает SSH ключи на хосте (`~/.ssh/id_rsa`, `~/.ssh/id_rsa.pub`)
+- Использует email для генерации ключей
+- **Приватный ключ остается на хосте** для будущего использования
+- **Публичный ключ передается в контейнер** через монтирование
+
+### **Этап 2: Настройка SSH ключей для root**
+- Добавляет публичный ключ в `/root/.ssh/authorized_keys` на VDS
+- Настраивает права доступа
+
+### **Этап 3: Очистка VDS сервера**
+- Останавливает и удаляет все Docker контейнеры
+- Очищает Docker систему (образы, volumes, networks)
+- **🆕 Умная проверка nginx:** автоматически определяет наличие системного nginx
+- **🆕 Полное удаление nginx:** если найден системный nginx - полностью удаляет его
+- Очищает временные файлы
+
+### **Этап 4: Создание пользователей**
+- Создает пользователя `ubuntuUser` с sudo правами
+- Создает пользователя `dockerUser` с sudo и docker правами
+- Настраивает SSH ключи для обоих пользователей
+- Создает директорию `/home/dockerUser/dapp`
+
+### **Этап 5: Установка Docker**
+- Скачивает и устанавливает Docker
+- Добавляет `dockerUser` в группу docker
+
+### **Этап 6: Установка Docker Compose**
+- Скачивает и устанавливает Docker Compose
+- Настраивает права выполнения
+
+### **Этап 7: Отключение парольной аутентификации**
+- Настраивает SSH для работы только с ключами
+- Отключает парольную аутентификацию
+
+### **Этап 8: Настройка firewall**
+- Включает UFW
+- Разрешает SSH (22), HTTP (80), HTTPS (443)
+
+### **Этап 9: Создание директории для ключей шифрования**
+- Создает `/home/dockerUser/dapp/ssl/keys`
+- Настраивает права доступа (700)
+
+### **Этап 10: 🆕 Умная проверка и удаление системного nginx**
+- **🔍 Проверяет наличие системного nginx** в системе
+- **⚠️ Если найден:** полностью удаляет системный nginx (stop, disable, mask, purge)
+- **ℹ️ Если не найден:** продолжает без изменений
+- **✅ Результат:** порты 80/443 полностью освобождены для Docker nginx
+
+### **Этап 11: 🆕 Автоматический SSL через Docker**
+- **🔒 SSL сертификаты получаются автоматически** через Docker certbot контейнер
+- **📋 Certbot настроен** для автоматического получения и обновления SSL сертификатов
+- **🚫 НЕ устанавливает системный certbot** - все через Docker
+
+### **Этап 12: 🆕 Настройка Docker nginx**
+- **🐳 Nginx конфигурация встроена** в Docker образ frontend-nginx
+- **🔧 Конфигурация применяется автоматически** при запуске контейнера
+- **🌐 Поддержка HTTPS** с автоматическими SSL сертификатами
+
+### **Этап 13: Передача docker-compose.prod.yml**
+- Читает файл с локальной машины (`/app/docker-compose.prod.yml`)
+- Передает на VDS как `/home/dockerUser/dapp/docker-compose.yml`
+
+### **Этап 14: 🆕 Создание полного .env файла**
+- Создает файл с полными переменными окружения:
+  ```
+  # Основные настройки
+  DOMAIN=example.com
+  BACKEND_CONTAINER=dapp-backend
+  EMAIL=admin@example.com
+  
+  # Настройки базы данных
+  DB_NAME=dapp_db
+  DB_USER=dapp_user
+  DB_PASSWORD=dapp_password
+  
+  # Настройки Node.js
+  NODE_ENV=production
+  PORT=8000
+  
+  # Настройки Ollama
+  OLLAMA_MODEL=qwen2.5:7b
+  OLLAMA_EMBEDDINGS_MODEL=qwen2.5:7b
+  
+  # Настройки безопасности
+  SSL_CERT_PATH=/etc/ssl/certs
+  SSL_KEY_PATH=/etc/ssl/private
+  ```
+
+### **Этап 15: Экспорт и передача Docker образов и данных**
+- **Экспортирует с локальной машины (образы + данные):**
+  - `postgres:16-alpine` - образ PostgreSQL + данные БД
+  - `digital_legal_entitydle-ollama:latest` - образ Ollama + модели
+  - `digital_legal_entitydle-vector-search:latest` - образ Vector Search + индексы
+  - `digital_legal_entitydle-backend:latest` - образ Backend
+  - `digital_legal_entitydle-frontend:latest` - образ Frontend
+  - `digital_legal_entitydle-frontend-nginx:latest` - образ Nginx
+  - `digital_legal_entitydle-webssh-agent:latest` - образ WebSSH Agent
+
+- **Экспортирует данные из volumes:**
+  - `postgres_data` - данные базы данных PostgreSQL
+  - `ollama_data` - модели Ollama
+  - `vector_search_data` - индексы векторного поиска
+
+- **Создает архив:** `docker-images-and-data.tar.gz` со всеми образами и данными
+- **Передает на VDS:** Через SCP в `/home/dockerUser/dapp/`
+- **Импортирует на VDS:** Распаковывает и загружает образы + создает volumes с данными
+- **Очищает локальные файлы:** Удаляет временные tar файлы
+- **✅ Важно:** Передаются образы И данные для полного развертывания
+
+### **Этап 16: 🆕 Запуск приложения с автоматическим SSL**
+- Запускает `docker compose up -d` на VDS
+- Запускает все контейнеры приложения, включая certbot контейнер
+- **🔒 Автоматическое получение SSL:** certbot получает сертификаты через webroot режим
+
+### **Этап 16.0: 🆕 Настройка автообновления SSL**
+- **📅 Создает cron задачу** для ежедневного обновления SSL сертификатов
+- **🔄 Скрипт обновления:** `renew-ssl.sh` - обновляет сертификаты и перезапускает nginx
+- **⏰ Расписание:** ежедневно в 12:00
+
+### **Этап 17: 🆕 Проверка готовности и целостности БД**
+- **⏳ Ожидание готовности базы данных:** проверяет доступность PostgreSQL с повторными попытками
+- **🗃️ Проверка целостности переданной БД:** проверяет наличие таблиц (email_settings, db_settings, session)
+- **📊 Подсчет таблиц:** показывает количество таблиц в переданной базе данных
+- **🔑 Проверка ключа шифрования:** проверяет наличие ключа в backend контейнере
+- **📈 Проверка статуса контейнеров:** логирует результаты всех проверок
+
+## 📊 **Что передается и что НЕ передается:**
+
+### ✅ **ПЕРЕДАЕТСЯ:**
+- **Docker образы:** Все 7 образов приложения (полный стек)
+- **Docker данные:** Данные из volumes (PostgreSQL, Ollama модели, Vector Search индексы)
+- **Конфигурационные файлы:** docker-compose.prod.yml, .env
+- **SSH ключи:** Публичные ключи для доступа (создаются на хосте, передаются в контейнер)
+- **Ключ шифрования:** Ключ для шифрования базы данных
+- **SSL сертификаты:** Получаются автоматически через Let's Encrypt
+
+### ❌ **НЕ ПЕРЕДАЕТСЯ:**
+- **Пароли:** Только SSH ключи, пароли не передаются
+- **Приватные SSH ключи:** Остаются на хосте для безопасности
+- **Секретные данные:** Только ключ шифрования БД
+- **Пользовательские данные:** Только системная настройка
+- **Исходный код:** Только скомпилированные Docker образы
+
+## 🎯 **Результат работы агента:**
+- **Полностью настроенный VDS сервер** с Ubuntu
+- **Работающее приложение** на домене с SSL
+- **Безопасный доступ** только по SSH ключам
+- **Автономная работа** без зависимости от локальной машины
+
+## 🔧 **Технические детали:**
+
+### **Архитектура:**
+- Агент работает в Docker контейнере `dapp-webssh-agent`
+- Порт 3000 проброшен с контейнера на хост (`0.0.0.0:3000->3000/tcp`)
+- Доступен локально через `http://localhost:3000`
+
+### **Процесс создания SSH ключей:**
+1. **Создание на хосте:** `ssh-keygen -t rsa -b 4096 -C "email" -f ~/.ssh/id_rsa -N ""`
+2. **Исправление прав доступа:** Автоматическое исправление прав доступа к SSH конфигу (`chmod 600 /root/.ssh/config`)
+3. **Приватный ключ:** Остается на хосте (`~/.ssh/id_rsa`) для безопасности с правами 600
+4. **Публичный ключ:** Передается в контейнер через монтирование (`~/.ssh/id_rsa.pub` → `/root/.ssh/id_rsa.pub`) с правами 644
+5. **Передача на VDS:** Публичный ключ передается через SSH команду
+6. **Очистка:** Временные файлы удаляются, SSH ключи сохраняются на хосте
+
+### **Права доступа:**
+- **SSH ключи:** Полный доступ к локальным SSH ключам (`~/.ssh/`) с автоматическим исправлением прав доступа
+- **SSH конфигурация:** Автоматическое исправление прав доступа к `/root/.ssh/config` (600) перед каждой операцией
+- **Docker API:** Полный доступ к Docker socket для управления контейнерами
+- **Файловая система:** Доступ к временным файлам и SSL сертификатам
+- **Сетевые операции:** Выполнение SSH/SCP команд на удаленных серверах с предварительной проверкой прав доступа
+
+## 🛠️ **ИСПРАВЛЕННЫЕ ОШИБКИ ИЗ ОТЧЕТА:**
+
+### ✅ **ВСЕ 12 ОШИБОК ПОЛНОСТЬЮ ИСПРАВЛЕНЫ:**
+
+| № | Ошибка | Статус | Решение |
+|---|--------|--------|---------|
+| 1 | HTTP ERROR 503 - конфликт портов nginx | ✅ ИСПРАВЛЕНО | Умная проверка и удаление системного nginx |
+| 2 | Конфликт портов nginx | ✅ ИСПРАВЛЕНО | Системный nginx полностью удаляется |
+| 3 | Проблемы с health checks | ✅ ИСПРАВЛЕНО | Улучшены health checks, изменены зависимости |
+| 4 | Ошибки конфигурации nginx | ✅ ИСПРАВЛЕНО | Исправлены переменные, добавлена валидация |
+| 5 | Проблемы с системным nginx | ✅ ИСПРАВЛЕНО | Системный nginx удаляется автоматически |
+| 6 | Ошибки подключения к БД | ✅ ИСПРАВЛЕНО | Добавлен SCRAM-SHA-256, исправлены переменные |
+| 7 | YAML синтаксис | ✅ ИСПРАВЛЕНО | Корректный формат переменных окружения |
+| 8 | Отсутствующие таблицы БД | ✅ ИСПРАВЛЕНО | Проверка целостности переданной БД с таблицами |
+| 9 | Проблемы с пробросом портов | ✅ ИСПРАВЛЕНО | Правильные порты в docker-compose |
+| 10 | Проблемы с переменными окружения | ✅ ИСПРАВЛЕНО | Полный .env файл со всеми переменными |
+| 11 | Отсутствие миграций БД | ✅ ИСПРАВЛЕНО | Проверка целостности переданной БД вместо миграций |
+| 12 | Проверка ключа шифрования | ✅ ИСПРАВЛЕНО | Агент проверяет наличие ключа |
+
+### 🚀 **ДОПОЛНИТЕЛЬНЫЕ УЛУЧШЕНИЯ:**
+
+- ✅ **Автоматический SSL** - certbot контейнер для получения сертификатов
+- ✅ **HTTPS редирект** - принудительный переход на HTTPS
+- ✅ **Автообновление SSL** - cron задача для ежедневного обновления
+- ✅ **Универсальность** - работает на любом VDS (с nginx или без)
+- ✅ **Безопасность** - современные SSL настройки + полная защита
+- ✅ **Health checks** - проверка состояния всех контейнеров
+- ✅ **Fail2ban** - защита от SSH и HTTP атак
+
+### 🎯 **ИТОГОВАЯ АРХИТЕКТУРА:**
+
+```
+Интернет → Docker nginx (порты 80/443) → Docker контейнеры
+                              ├── HTTP → HTTPS редирект
+                              ├── Frontend (порт 5173)
+                              ├── Backend API (порт 8000)
+                              ├── WebSocket (порт 8000/ws)
+                              └── Certbot (автообновление SSL)
+```
+
+**Система полностью готова к продакшну!** 🚀
+
+### **Безопасность:**
+- Агент работает в Docker контейнере, порт 3000 проброшен на хост
+- SSH ключи монтируются в режиме только чтения
+- Docker socket доступен только для управления контейнерами
+- Все операции логируются для аудита
+- Доступен локально через `http://localhost:3000`
+
+## 🔧 **Исправления SSH проблем (v1.1):**
+
+### **Проблема:**
+SSH команды падали с ошибкой `Bad owner or permissions on /root/.ssh/config`, что препятствовало подключению к VDS серверам.
+
+### **Решение:**
+1. **Dockerfile:** Добавлено создание SSH конфига с правильными правами доступа (600)
+2. **SSH утилиты:** Добавлена функция `fixSshPermissions()` для автоматического исправления прав
+3. **Создание ключей:** Улучшена функция создания SSH ключей с установкой правильных прав доступа
+4. **Предварительная проверка:** Каждая SSH/SCP команда теперь автоматически исправляет права доступа
+
+### **Результат:**
+- ✅ Устранена ошибка "Bad owner or permissions on /root/.ssh/config"
+- ✅ Повышена надежность SSH подключений
+- ✅ Автоматическое исправление прав доступа
+- ✅ Сохранена вся существующая функциональность
+
+## 🚨 **Важно:**
+Агент имеет расширенные права для автоматизации развертывания. Используйте только на доверенных серверах и в защищенных сетях.
+
+**Агент выполняет полную автоматизацию развертывания от чистого VDS до работающего приложения!** 🚀
+
+---
+
+**© 2024-2025 Тарабанов Александр Викторович. Все права защищены.**