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