mnemo_cards/tools/deploy/BACKEND_FIX_REPORT_2025-11-19.md

# Отчет об исправлении Backend Server
**Дата**: 19 ноября 2025  
**Проблема**: Backend сервер падал при сборке с ошибкой "Address already in use, port = 8443"

## Причина проблемы

**Конфликт портов**: Backend сервер и code-server (VSCode) были настроены на один и тот же порт **8443**.

### Хронология
1. При восстановлении VSCode Server мы настроили code-server на порт 8443
2. Backend сервер также был настроен на порт 8443
3. При попытке запуска backend получал ошибку: `SocketException: Address already in use, port = 8443`
4. Systemd пытался перезапустить сервис 5 раз и сдался

## Решение

### 1. Изменение порта Backend
- **Старый порт**: 8443 (конфликт с code-server)
- **Новый порт**: 8081 (стандартный порт для API)

### 2. Обновление конфигураций

#### systemd Service
Файл: `/etc/systemd/system/mnemo_cards_server.service`

```ini
[Service]
ExecStart=/root/mnemo_cards_backend/server.exe -a 0.0.0.0 -p 8081
```
Изменено: `-p 8443` → `-p 8081`

#### nginx Configuration
Файл: `/etc/nginx/sites-available/api`

```nginx
location / {
    proxy_pass http://localhost:8081;  # было: https://localhost:8443
}
```
Изменения:
- Порт: 8443 → 8081
- Протокол: https → http (SSL терминируется в nginx)

### 3. Включение автозапуска
```bash
systemctl enable mnemo_cards_server
```

## Результаты

### ✅ Backend Server
```bash
● mnemo_cards_server.service - MnemoCardsServer
   Loaded: loaded (/etc/systemd/system/mnemo_cards_server.service; enabled)
   Active: active (running)
```

### ✅ Порты

| Сервис | Порт | Адрес | Статус |
|--------|------|-------|--------|
| code-server (VSCode) | 8443 | 127.0.0.1 | ✅ Работает |
| backend (API) | 8081 | 0.0.0.0 | ✅ Работает |
| nginx (HTTPS) | 443 | 0.0.0.0 | ✅ Работает |

### ✅ Доступность API
```bash
curl -I https://api.mnemo-cards.online/

HTTP/2 404 
server: nginx/1.18.0 (Ubuntu)
access-control-allow-origin: *
```
✅ Сервер отвечает (404 нормально для корневого пути)

## Архитектура

```
Internet
    ↓
nginx (port 443) - SSL Termination
    ├─→ api.mnemo-cards.online → http://localhost:8081 (Backend)
    └─→ vscode.mnemo-cards.online → http://127.0.0.1:8443 (VSCode)
```

## Созданные инструменты

### fix-backend-port-conflict.sh
Автоматический скрипт для исправления конфликта портов:
- Изменяет порт в systemd service
- Обновляет nginx конфигурацию
- Перезапускает сервисы
- Проверяет работоспособность

**Использование**:
```bash
cd /Users/dmitry/StudioProjects/mnemo_cards/tools/deploy
./fix-backend-port-conflict.sh
```

## Управление Backend

### Проверка статуса
```bash
ssh root@147.45.152.129 'systemctl status mnemo_cards_server'
```

### Просмотр логов
```bash
ssh root@147.45.152.129 'journalctl -u mnemo_cards_server -f'
```

### Перезапуск
```bash
ssh root@147.45.152.129 'systemctl restart mnemo_cards_server'
```

### Проверка порта
```bash
ssh root@147.45.152.129 'ss -tuln | grep 8081'
```

## Предотвращение проблем в будущем

### ✅ Сделано
1. Backend настроен на автозапуск при загрузке
2. Backend использует уникальный порт (8081)
3. Созданы скрипты для быстрого восстановления
4. Документирована архитектура и порты

### 📋 Рекомендации
1. При добавлении новых сервисов проверять свободные порты
2. Документировать используемые порты в конфигурации
3. Использовать стандартные порты:
   - Backend API: 8081
   - VSCode: 8443
   - Forgejo: 3000
   - Frontend: через nginx на 443

## Тестирование

### Тест 1: Backend работает
```bash
ssh root@147.45.152.129 'curl -I http://localhost:8081/'
# ✅ HTTP/1.1 404 Not Found
```

### Тест 2: nginx проксирует на backend
```bash
ssh root@147.45.152.129 'curl -I https://api.mnemo-cards.online/'
# ✅ HTTP/2 404 
```

### Тест 3: VSCode работает
```bash
ssh root@147.45.152.129 'curl -I http://127.0.0.1:8443/'
# ✅ HTTP/1.1 302 Found (redirect to login)
```

### Тест 4: Порты не конфликтуют
```bash
ssh root@147.45.152.129 'ss -tuln | grep -E "(8081|8443)"'
# ✅ Оба порта слушают без ошибок
```

## Время восстановления

- **Обнаружение проблемы**: 22:34
- **Диагностика**: 22:35
- **Исправление**: 22:37
- **Проверка**: 22:39

**Общее время**: ~5 минут

## Статус

🟢 **RESOLVED**

### Работающие сервисы
- ✅ Backend API: https://api.mnemo-cards.online/
- ✅ VSCode Server: https://vscode.mnemo-cards.online/
- ✅ Forgejo Git: https://code.mnemo-cards.online/

### Автозапуск
- ✅ mnemo_cards_server: enabled
- ✅ code-server: enabled
- ✅ nginx: enabled

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

### Связанные документы
- [VSCODE_SERVER_SETUP.md](./VSCODE_SERVER_SETUP.md) - Настройка VSCode Server
- [RECOVERY_REPORT_2025-11-19.md](./RECOVERY_REPORT_2025-11-19.md) - Восстановление VSCode
- [README.md](./README.md) - Общая документация по деплою

### Скрипты
- `fix-backend-port-conflict.sh` - Исправление конфликта портов
- `fix-vscode-server.sh` - Восстановление VSCode Server

---

**Вывод**: Проблема полностью решена. Backend сервер работает на порту 8081, конфликт с VSCode устранен. Все сервисы настроены на автозапуск при перезагрузке сервера.