# 🤖 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 Тарабанов Александр Викторович. Все права защищены.**