umbrix/update-server/README.md

# 🚀 Сервер Обновлений Umbrix

> **⚠️ Внимание:** Этот сервер предназначен **только для Desktop платформ** (Windows, macOS, Linux).  
> Для Android используется Google Play Store.

---

## 📋 Что это?

Система автоматических обновлений для настольных версий Umbrix. Пользователи получают уведомления об обновлениях прямо в приложении с автоматической загрузкой и установкой.

---

## 🎯 Как это работает?

```
┌──────────────┐          ┌──────────────────┐          ┌─────────────┐
│  Desktop App │ -------> │  Ваш сервер      │ <------- │ Вы загружаете│
│ Windows/Mac/ │  запрос  │  (PHP API)       │  файлы   │ новую версию │
│    Linux     │          │                  │          │  .exe/.dmg   │
└──────────────┘          └──────────────────┘          └─────────────┘
      │                           │
      │  ответ JSON               │
      │  + скачивание             │
      │  с прогресс-баром         │
      └──────────────────────────>│
```

**Процесс:**
1. **Desktop приложение** проверяет сервер на наличие обновлений
2. **Сервер** возвращает информацию о последней версии
3. **Приложение** скачивает обновление с прогресс-баром
4. **Пользователь** запускает установщик

**Для Android:** Обновления через Google Play Store (автоматически)

---

## 📦 Что нужно?

### Минимальные требования:
- ✅ Хостинг с PHP 7.4+ (любой: Timeweb, Beget, VPS)
- ✅ Домен или поддомен (например: `api.umbrix.net`)
- ✅ HTTPS сертификат (бесплатный Let's Encrypt)

---

## 🛠️ Установка - Пошагово

### Шаг 1: Подготовка сервера

1. **Создайте папку на сервере:**
   ```bash
   mkdir -p /var/www/updates
   ```

2. **Загрузите файлы из папки `update-server/`:**
   - `api.php` - главный скрипт
   - `latest.json` - информация о последней версии
   - `.htaccess` - настройки Apache

3. **Создайте папку для APK файлов:**
   ```bash
   mkdir -p /var/www/updates/downloads
   chmod 755 /var/www/updates/downloads
   ```

---

### Шаг 2: Настройка домена

1. **Создайте поддомен** (в панели хостинга):
   - Имя: `api` или `updates`
   - Полный адрес: `api.umbrix.net`
   - Папка: `/var/www/updates`

2. **Включите HTTPS:**
   - В панели хостинга найдите "SSL сертификат"
   - Выберите "Let's Encrypt" (бесплатно)
   - Нажмите "Установить"

---

### Шаг 3: Настройка приложения

Откройте файл `lib/core/model/constants.dart` и измените:

```dart
// Замените на адрес вашего сервера
static const customUpdateServerUrl = "https://api.umbrix.net/api/latest";

// Включите собственный сервер обновлений
static const useCustomUpdateServer = true;
```

---

### Шаг 4: Загрузка новой версии

Когда у вас готова новая версия:

1. **Соберите APK:**
   ```bash
   flutter build apk --release
   ```

2. **Переименуйте файл** (для удобства):
   ```bash
   # Из: build/app/outputs/flutter-apk/app-release.apk
   # В: umbrix-2.5.8.apk
   ```

3. **Загрузите на сервер:**
   - Через FTP/SFTP загрузите APK в папку `/var/www/updates/downloads/`
   - Или через панель хостинга

4. **Обновите файл `latest.json`:**
   ```json
   {
     "version": "2.5.8",
     "build_number": "258",
     "is_prerelease": false,
     "download_url": "https://api.umbrix.net/downloads/umbrix-2.5.8.apk",
     "release_notes": "🎉 Что нового:\n\n- Исправлены ошибки соединения\n- Улучшена стабильность\n- Новые серверы",
     "published_at": "2026-01-17T12:00:00Z",
     "min_required_version": "2.5.0"
   }
   ```

---

## 🧪 Проверка работы

### 1. Проверьте API в браузере:

Откройте: `https://api.umbrix.net/api/latest`

Должны увидеть JSON:
```json
{
  "version": "2.5.8",
  "build_number": "258",
  ...
}
```

### 2. Проверьте скачивание APK:

Откройте: `https://api.umbrix.net/downloads/umbrix-2.5.8.apk`

Должно начаться скачивание файла.

### 3. Проверьте в приложении:

1. Откройте приложение
2. Зайдите в **Настройки → О программе**
3. Нажмите **"Проверить обновления"**
4. Должно появиться окно с новой версией (если она новее текущей)

---

## 📝 Структура файлов на сервере

```
/var/www/updates/
├── api.php              # Главный скрипт API
├── latest.json          # Информация о последней версии
├── .htaccess            # Настройки Apache (ЧПУ, безопасность)
├── downloads/           # Папка с APK файлами
│   ├── umbrix-2.5.7.apk
│   ├── umbrix-2.5.8.apk
│   └── umbrix-2.6.0-beta.apk
└── logs/                # Логи (автоматически создается)
    └── access.log
```

---

## 🔒 Безопасность

### Уже реализовано:

✅ **CORS защита** - только ваше приложение может запрашивать обновления
✅ **Rate Limiting** - не более 10 запросов в минуту с одного IP
✅ **Валидация JSON** - проверка формата данных
✅ **Логирование** - все запросы записываются

### Рекомендации:

1. **Используйте HTTPS** (обязательно!)
2. **Регулярно обновляйте** PHP на сервере
3. **Делайте бэкапы** файлов и APK
4. **Проверяйте логи** на подозрительную активность

---

## 🎨 Дополнительные возможности

### 1. Принудительное обновление

Если нужно **заставить** пользователей обновиться:

```json
{
  "version": "2.6.0",
  "force_update": true,
  "min_required_version": "2.5.0"
}
```

Приложение не запустится на версиях ниже 2.5.0.

### 2. Бета-версии

Для тестировщиков:

```json
{
  "version": "2.6.0-beta",
  "is_prerelease": true,
  "download_url": "https://api.umbrix.net/downloads/umbrix-2.6.0-beta.apk"
}
```

### 3. Аналитика

Смотрите файл `logs/access.log`:
- Сколько пользователей проверяют обновления
- Какие версии используют
- Откуда приходят запросы

---

## ❓ Частые проблемы

### Проблема: "Обновления не приходят"

**Решение:**
1. Проверьте, что `useCustomUpdateServer = true` в `constants.dart`
2. Проверьте, что URL правильный (с `https://`)
3. Проверьте, что `version` в `latest.json` больше текущей
4. Пересоберите приложение после изменения констант

### Проблема: "Ошибка при скачивании APK"

**Решение:**
1. Проверьте права на папку: `chmod 755 downloads`
2. Проверьте, что файл существует
3. Проверьте, что URL в `download_url` правильный

### Проблема: "API возвращает ошибку 500"

**Решение:**
1. Проверьте PHP логи на сервере
2. Убедитесь, что PHP версии 7.4+
3. Проверьте права на файл `latest.json`: `chmod 644 latest.json`

---

## 📞 Поддержка

Если что-то не работает:

1. Проверьте логи: `/var/www/updates/logs/access.log`
2. Проверьте PHP логи на сервере
3. Напишите в поддержку хостинга

---

## 🎓 Дополнительная информация

### Полезные команды для сервера:

```bash
# Посмотреть последние запросы
tail -f /var/www/updates/logs/access.log

# Проверить размер APK файлов
du -h /var/www/updates/downloads/*

# Очистить старые APK (оставить последние 3)
ls -t /var/www/updates/downloads/*.apk | tail -n +4 | xargs rm

# Проверить права доступа
ls -la /var/www/updates/
```

### Тестирование API через curl:

```bash
# Проверить API
curl https://api.umbrix.net/api/latest

# Проверить с бета-версиями
curl "https://api.umbrix.net/api/latest?include_prerelease=true"

# Скачать APK
curl -O https://api.umbrix.net/downloads/umbrix-2.5.8.apk
```

---

## ✅ Чеклист перед запуском

- [ ] PHP 7.4+ установлен
- [ ] Папка `/var/www/updates` создана
- [ ] Файлы `api.php`, `latest.json`, `.htaccess` загружены
- [ ] Папка `downloads/` создана с правами 755
- [ ] Домен `api.umbrix.net` настроен
- [ ] SSL сертификат установлен
- [ ] URL в `constants.dart` обновлен
- [ ] Приложение пересобрано
- [ ] API отвечает в браузере
- [ ] APK скачивается по ссылке
- [ ] Проверка обновлений работает в приложении

---

**🎉 Готово! Теперь вы можете выкатывать обновления без магазинов!**