uploader-bot/docs/DOCS_RU.md

729 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 🚀 MY Network v2.0 - Распределенная сеть контента
## 📖 Полная документация на русском языке
---
## 🎯 Что такое MY Network?
**MY Network** — это современная распределенная P2P система для автоматического управления и синхронизации контента между серверами. Система работает как overlay-протокол поверх существующей инфраструктуры, не нарушая работу текущих приложений.
### ✨ Ключевые возможности
- 🌐 **P2P сеть** - автоматическое обнаружение и подключение узлов
- 🔄 **Автосинхронизация** - реплицирование контента между узлами
- 📊 **Веб-мониторинг** - красивые дашборды с ASCII-артом
- 🔒 **Безопасность** - SSL/TLS шифрование, firewall, rate limiting
- 🐳 **Контейнеризация** - полная поддержка Docker
- 📡 **REST API** - программное управление всеми функциями
- ⚖️ **Load Balancing** - распределение нагрузки между узлами
---
## 🏗️ Архитектура системы
```mermaid
graph TB
subgraph "MY Network Cluster"
Node1[Node 1<br/>Bootstrap]
Node2[Node 2<br/>Worker]
Node3[Node 3<br/>Worker]
Node4[Node 4<br/>Worker]
end
subgraph "Node 1 Components"
API1[REST API<br/>:15100]
Monitor1[Web Monitor<br/>/monitor]
Sync1[Sync Manager]
Peer1[Peer Manager]
Storage1[Storage<br/>/opt/storage]
end
subgraph "External Services"
Nginx[Nginx<br/>SSL Proxy]
DB[(MariaDB<br/>Database)]
Redis[(Redis<br/>Cache)]
end
subgraph "Security Layer"
UFW[UFW Firewall]
Fail2Ban[Fail2ban]
SSL[Let's Encrypt<br/>SSL]
end
Internet --> UFW
UFW --> SSL
SSL --> Nginx
Nginx --> API1
Node1 <--> Node2
Node1 <--> Node3
Node1 <--> Node4
Node2 <--> Node3
Node3 <--> Node4
API1 <--> DB
API1 <--> Redis
API1 <--> Storage1
Sync1 <--> Peer1
Monitor1 <--> API1
```
---
## 🔄 Схема синхронизации контента
```mermaid
sequenceDiagram
participant C as Client
participant N1 as Node 1 (Source)
participant N2 as Node 2 (Target)
participant N3 as Node 3 (Target)
Note over N1,N3: Автоматическая синхронизация каждые 5 минут
C->>N1: Загрузка файла
N1->>N1: Сохранение в /opt/storage
N1->>N1: Обновление базы данных
loop Каждые 5 минут
N1->>N2: Проверка статуса
N2->>N1: Список файлов + хеши
N1->>N1: Сравнение с локальными файлами
alt Файл отсутствует на N2
N1->>N2: Передача файла (chunked)
N2->>N2: Сохранение + проверка целостности
N2->>N1: Подтверждение получения
end
N1->>N3: Аналогично для Node 3
end
Note over N1,N3: Все узлы содержат идентичные данные
```
---
## 🌐 Схема сетевого взаимодействия
```mermaid
graph LR
subgraph "Internet"
User[👤 Пользователь]
Bot[🤖 Telegram Bot]
end
subgraph "Security Layer"
FW[🔥 UFW Firewall<br/>Ports: 22,80,443]
FB[🚫 Fail2ban<br/>Защита от брутфорса]
end
subgraph "Web Layer"
NG[🌐 Nginx<br/>SSL Termination<br/>Rate Limiting]
end
subgraph "Application Layer"
API[📡 MY Network API<br/>Port 15100]
MON[📊 Web Monitor<br/>/api/my/monitor]
SYNC[🔄 Sync Manager<br/>Background Process]
end
subgraph "Data Layer"
DB[(🗄️ MariaDB<br/>Port 3306)]
RD[(⚡ Redis<br/>Port 6379)]
FS[📁 File Storage<br/>/opt/storage]
end
User --> FW
Bot --> FW
FW --> FB
FB --> NG
NG --> API
API --> MON
API --> SYNC
API --> DB
API --> RD
API --> FS
style FW fill:#ff9999
style FB fill:#ff9999
style NG fill:#99ccff
style API fill:#99ff99
style DB fill:#ffcc99
```
---
## ⚙️ Установка в две команды
### 🥇 Команда 1: Установка сервиса
```bash
# Скачиваем и устанавливаем базовый сервис
curl -O https://your-domain.com/install_service.sh
sudo bash install_service.sh
```
**Что делает эта команда:**
- ✅ Обновляет систему
- ✅ Устанавливает Docker, Python, зависимости
- ✅ Создает структуру директорий
- ✅ Настраивает systemd сервис
- ✅ Запускает базовый сервис на порту 15100
### 🥈 Команда 2: Защита и SSL
```bash
# Настраиваем защиту, nginx, SSL, firewall
sudo bash secure_service.sh
```
**Что делает эта команда:**
- 🔒 Устанавливает SSL сертификат (Let's Encrypt)
- 🌐 Настраивает Nginx с rate limiting
- 🔥 Настраивает UFW firewall
- 🚫 Устанавливает Fail2ban
- 📊 Настраивает мониторинг системы
- 🔄 Настраивает автообновление сертификатов
---
## 🛠️ Компоненты системы
### 📡 REST API Endpoints
```mermaid
graph TD
API[MY Network API<br/>/api/my/]
API --> NODE[/node/*<br/>Управление узлом]
API --> PEER[/peer/*<br/>Управление пирами]
API --> SYNC[/sync/*<br/>Синхронизация]
API --> NET[/network/*<br/>Статистика сети]
API --> MON[/monitor/*<br/>Веб-мониторинг]
NODE --> NINFO[GET /info<br/>Информация об узле]
NODE --> NPEERS[GET /peers<br/>Список пиров]
NODE --> NHEALTH[GET /health<br/>Проверка здоровья]
PEER --> PADD[POST /add<br/>Добавить пир]
PEER --> PREM[DELETE /remove<br/>Удалить пир]
PEER --> PSTAT[GET /stats<br/>Статистика пира]
SYNC --> SSTART[POST /start<br/>Запуск синхронизации]
SYNC --> SSTOP[POST /stop<br/>Остановка синхронизации]
SYNC --> SSTAT[GET /status<br/>Статус синхронизации]
MON --> MDASH[GET /<br/>Веб-дашборд]
MON --> MASCII[GET /ascii<br/>ASCII статус]
MON --> MAPI[GET /api<br/>JSON метрики]
```
### 📊 Веб-мониторинг
```mermaid
graph TB
subgraph "Web Monitor Dashboard"
HEADER[🎯 MY Network Monitor<br/>ASCII Art Header]
METRICS[📈 System Metrics<br/>CPU, Memory, Disk]
NETWORK[🌐 Network Status<br/>Peers, Connections]
SYNC[🔄 Sync Status<br/>Last Sync, Progress]
STORAGE[💾 Storage Info<br/>Used/Free Space]
REALTIME[⚡ Real-time Updates<br/>Auto-refresh каждые 5 сек]
CHARTS[📊 ASCII Charts<br/>Bandwidth, Load]
end
HEADER --> METRICS
HEADER --> NETWORK
HEADER --> SYNC
HEADER --> STORAGE
METRICS --> REALTIME
NETWORK --> REALTIME
SYNC --> REALTIME
STORAGE --> REALTIME
REALTIME --> CHARTS
style HEADER fill:#ff6b6b
style REALTIME fill:#4ecdc4
style CHARTS fill:#45b7d1
```
---
## 🔧 Конфигурация
### 📄 Основной конфиг (.env)
```bash
# MY Network Configuration
NODE_ID=node-1234567890 # Уникальный ID узла
NODE_PORT=15100 # Порт приложения
DOMAIN=my-network.example.com # Домен сервера
# Database Configuration
DB_HOST=localhost
DB_PORT=3306
DB_NAME=my_network
DB_USER=my_network_user
DB_PASSWORD=secure_password_here
# Security
SECRET_KEY=very_long_secret_key_here
JWT_SECRET=jwt_secret_key_here
# Network Settings
BOOTSTRAP_NODES=["node1.example.com", "node2.example.com"]
SYNC_INTERVAL=300 # Интервал синхронизации (секунды)
MAX_PEERS=10 # Максимум пиров
```
### 🗂️ Структура директорий
```
/opt/
├── my-network/ # Основная директория проекта
│ └── my-uploader-bot/ # Код приложения
│ ├── app/ # Python приложение
│ ├── static/ # Статические файлы
│ ├── templates/ # HTML шаблоны
│ └── logs/ # Логи приложения
├── storage/ # Хранилище файлов
├── logs/ # Системные логи
└── my-network-config.txt # Конфигурация установки
```
---
## 🚀 Использование
### 🔍 Проверка статуса
```bash
# Проверка сервиса
systemctl status my-network
# Проверка nginx
systemctl status nginx
# Проверка firewall
ufw status
# Проверка SSL
certbot certificates
# Проверка API
curl https://your-domain.com/api/my/health
```
### 📊 Мониторинг
```bash
# Веб-интерфейс мониторинга
https://your-domain.com/api/my/monitor/
# ASCII статус в терминале
curl https://your-domain.com/api/my/monitor/ascii
# JSON метрики
curl https://your-domain.com/api/my/monitor/api
```
### 🔄 Управление синхронизацией
```bash
# Запуск синхронизации
curl -X POST https://your-domain.com/api/my/sync/start
# Остановка синхронизации
curl -X POST https://your-domain.com/api/my/sync/stop
# Статус синхронизации
curl https://your-domain.com/api/my/sync/status
```
---
## 🔒 Безопасность
### 🛡️ Уровни защиты
```mermaid
graph TD
Internet[🌐 Internet] --> FW[🔥 UFW Firewall]
FW --> |Port 80,443,SSH| SSL[🔐 SSL/TLS<br/>Let's Encrypt]
SSL --> Nginx[🌐 Nginx Proxy]
Nginx --> |Rate Limiting| FB[🚫 Fail2ban]
FB --> API[📡 Application]
subgraph "Security Features"
FW1[✅ Firewall Rules]
SSL1[✅ SSL Certificates]
RL[✅ Rate Limiting]
FB1[✅ Brute Force Protection]
HD[✅ Security Headers]
IP[✅ IP Whitelisting]
end
style FW fill:#ff9999
style SSL fill:#99ff99
style FB fill:#ffcc99
```
### 🔐 Настройки безопасности
**Firewall (UFW):**
- ✅ Закрыты все порты кроме SSH, HTTP, HTTPS
- ✅ Разрешен доступ только к необходимым сервисам
- ✅ Блокировка подозрительного трафика
**SSL/TLS:**
- ✅ Автоматические сертификаты Let's Encrypt
- ✅ Принудительное перенаправление HTTP → HTTPS
- ✅ Современные алгоритмы шифрования
**Rate Limiting:**
- ✅ Ограничение запросов к API (10 req/s)
- ✅ Ограничение мониторинга (2 req/s)
- ✅ Защита от DDoS атак
**Fail2ban:**
- ✅ Блокировка брутфорс атак на SSH
- ✅ Защита от злоупотребления API
- ✅ Автоматическая разблокировка
---
## 📈 Мониторинг и логи
### 📊 Системные метрики
```mermaid
graph LR
subgraph "Monitoring Stack"
APP[📱 Application Metrics]
SYS[💻 System Metrics]
NET[🌐 Network Metrics]
SEC[🔒 Security Metrics]
end
subgraph "Log Files"
APPLOG[📄 /opt/logs/app.log]
SYSLOG[📄 /var/log/syslog]
NGINX[📄 /var/log/nginx/]
FAIL2BAN[📄 /var/log/fail2ban.log]
end
APP --> APPLOG
SYS --> SYSLOG
NET --> NGINX
SEC --> FAIL2BAN
subgraph "Monitoring Tools"
CRON[⏰ Cron Monitor<br/>Каждые 5 минут]
WEB[🌐 Web Dashboard<br/>Real-time]
ALERT[🚨 Alert System<br/>Critical Events]
end
APPLOG --> WEB
SYSLOG --> WEB
NGINX --> WEB
FAIL2BAN --> WEB
WEB --> ALERT
CRON --> ALERT
```
### 📜 Полезные команды для мониторинга
```bash
# Просмотр логов сервиса
journalctl -u my-network -f
# Просмотр логов nginx
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log
# Мониторинг системы
tail -f /opt/logs/monitor.log
# Статистика fail2ban
fail2ban-client status
# Проверка дискового пространства
df -h
# Мониторинг сетевых соединений
netstat -tlnp | grep :15100
```
---
## 🔧 Troubleshooting
### ⚠️ Частые проблемы и решения
#### 1. Сервис не запускается
```bash
# Проверка статуса
systemctl status my-network
# Просмотр логов
journalctl -u my-network -n 50
# Перезапуск сервиса
systemctl restart my-network
# Проверка портов
netstat -tlnp | grep :15100
```
#### 2. SSL сертификат не работает
```bash
# Проверка сертификатов
certbot certificates
# Обновление сертификата
certbot renew --dry-run
# Перезапуск nginx
systemctl reload nginx
# Проверка конфигурации nginx
nginx -t
```
#### 3. Firewall блокирует соединения
```bash
# Проверка правил firewall
ufw status numbered
# Добавление правила
ufw allow from IP_ADDRESS to any port 15100
# Проверка логов
grep UFW /var/log/syslog
```
#### 4. Синхронизация не работает
```bash
# Проверка статуса синхронизации
curl https://your-domain.com/api/my/sync/status
# Перезапуск синхронизации
curl -X POST https://your-domain.com/api/my/sync/stop
curl -X POST https://your-domain.com/api/my/sync/start
# Проверка пиров
curl https://your-domain.com/api/my/node/peers
```
---
## 🎨 Примеры API запросов
### 📡 Основные операции
```bash
# Получение информации об узле
curl -X GET https://your-domain.com/api/my/node/info \
-H "Content-Type: application/json"
# Добавление нового пира
curl -X POST https://your-domain.com/api/my/peer/add \
-H "Content-Type: application/json" \
-d '{
"host": "peer.example.com",
"port": 15100,
"ssl": true
}'
# Получение статистики сети
curl -X GET https://your-domain.com/api/my/network/stats \
-H "Content-Type: application/json"
# Запуск полной синхронизации
curl -X POST https://your-domain.com/api/my/sync/start \
-H "Content-Type: application/json" \
-d '{
"force": true,
"verify": true
}'
```
### 📊 Мониторинг через API
```bash
# JSON метрики для интеграции с внешними системами
curl -X GET https://your-domain.com/api/my/monitor/api \
-H "Content-Type: application/json" | jq
# Пример ответа:
{
"node": {
"id": "node-1234567890",
"status": "active",
"uptime": 86400,
"version": "2.0.0"
},
"network": {
"peers_count": 5,
"active_connections": 3,
"total_bandwidth": "1.2GB",
"sync_status": "synchronized"
},
"system": {
"cpu_usage": 25.5,
"memory_usage": 512,
"disk_usage": 75.2,
"load_average": [0.5, 0.3, 0.2]
}
}
```
---
## 🔄 Обновление системы
### 📦 Обновление MY Network
```bash
# Остановка сервиса
systemctl stop my-network
# Обновление кода
cd /opt/my-network/my-uploader-bot
git pull origin main
# Обновление зависимостей
source venv/bin/activate
pip install -r requirements_new.txt --upgrade
# Применение миграций базы данных (если есть)
python -m alembic upgrade head
# Запуск сервиса
systemctl start my-network
# Проверка статуса
systemctl status my-network
```
### 🔒 Обновление системы безопасности
```bash
# Обновление пакетов системы
apt update && apt upgrade -y
# Обновление SSL сертификатов
certbot renew
# Обновление правил fail2ban
systemctl restart fail2ban
# Проверка безопасности
ufw status
fail2ban-client status
certbot certificates
```
---
## 📋 Чек-лист развертывания
### ✅ Pre-deployment checklist
- [ ] **Сервер подготовлен** (Ubuntu 20.04+)
- [ ] **Домен настроен** (A-запись указывает на сервер)
- [ ] **SSH доступ настроен** (ключи, порт безопасности)
- [ ] **Email для SSL указан** (действующий email)
### ✅ Installation checklist
- [ ] **Шаг 1: Базовая установка**
- [ ] `sudo bash install_service.sh` выполнен успешно
- [ ] Сервис запущен: `systemctl status my-network`
- [ ] API отвечает: `curl http://localhost:15100/api/my/health`
- [ ] **Шаг 2: Безопасность**
- [ ] `sudo bash secure_service.sh` выполнен успешно
- [ ] SSL работает: `curl https://your-domain.com/api/my/health`
- [ ] Firewall активен: `ufw status`
- [ ] Fail2ban активен: `systemctl status fail2ban`
### ✅ Post-deployment checklist
- [ ] **Функциональность**
- [ ] Веб-мониторинг доступен: `https://your-domain.com/api/my/monitor/`
- [ ] API endpoints отвечают корректно
- [ ] Синхронизация работает (если есть пиры)
- [ ] Логи пишутся без ошибок
- [ ] **Безопасность**
- [ ] SSL A+ рейтинг (проверить на ssllabs.com)
- [ ] Только необходимые порты открыты
- [ ] Rate limiting работает
- [ ] Backup и мониторинг настроены
---
## 📞 Поддержка
### 🆘 Получение помощи
1. **Проверьте логи:**
```bash
journalctl -u my-network -n 100
tail -f /opt/logs/monitor.log
```
2. **Проверьте статус сервисов:**
```bash
systemctl status my-network nginx fail2ban
```
3. **Проверьте сетевое соединение:**
```bash
curl -v https://your-domain.com/api/my/health
```
4. **Соберите диагностическую информацию:**
```bash
/opt/monitor.sh
ufw status numbered
df -h
free -h
```
### 📧 Контакты
- **Документация:** `/opt/my-network/my-uploader-bot/DOCS_RU.md`
- **Конфигурация:** `/opt/my-network-config.txt`
- **Логи:** `/opt/logs/` и `/var/log/`
---
## 🎉 Заключение
**MY Network v2.0** - это полноценная, готовая к продакшену система для создания распределенных сетей контента. Система обеспечивает:
-**Простую установку** в две команды
- 🔒 **Максимальную безопасность** из коробки
- 📊 **Полный мониторинг** в реальном времени
- 🔄 **Автоматическую синхронизацию** между узлами
- 🌐 **Масштабируемость** до любого количества узлов
Система готова к использованию и может быть развернута на любом современном Linux сервере за считанные минуты!
---
*Документация MY Network v2.0 | Версия 1.0 | 2025*