Устранение неполадок

На этой странице описаны распространённые проблемы при работе с Fenfa и их решения.

iOS установка

«Unable to Install» / Установка не происходит

Симптомы: Нажатие кнопки «Установить» на iOS показывает «Unable to Install» или ничего не происходит.

Причины и решения:

1. HTTPS не настроен. iOS требует HTTPS с действующим TLS-сертификатом для OTA-установки. Самоподписанные сертификаты не работают.

   • Решение: Настройте обратный прокси с действующим TLS-сертификатом. См. Продакшн деплой.
   • Для тестирования: Используйте ngrok для создания HTTPS-туннеля: ngrok http 8000

2. Неверный primary_domain. Манифест plist содержит URL скачивания на основе primary_domain. Если он неверный, iOS не может получить IPA.

   • Решение: Установите FENFA_PRIMARY_DOMAIN в точный HTTPS URL, по которому пользователи обращаются к сервису (например, https://dist.example.com).

3. Проблемы с сертификатом. TLS-сертификат должен покрывать домен и быть доверенным iOS.

   • Решение: Используйте Let's Encrypt для бесплатных доверенных сертификатов.

4. Истёкшая подпись IPA. Provisioning profile или сертификат подписи могли истечь.

   • Решение: Перезагрузите IPA с действующим сертификатом.

Привязка UDID не работает

Симптомы: Профиль mobileconfig устанавливается, но устройство не регистрируется.

Причины и решения:

1. Callback URL недоступен. URL обратного вызова UDID должен быть доступен с устройства.

   • Решение: Убедитесь, что primary_domain корректен и доступен из сети устройства.

2. Nonce истёк. Nonce профиля истекает по таймауту.

   • Решение: Повторно скачайте профиль mobileconfig и попробуйте снова.

Проблемы загрузки

Загрузка завершается с ошибкой 401

Симптом: {"ok": false, "error": {"code": "UNAUTHORIZED", ...}}

Решение: Убедитесь, что заголовок X-Auth-Token содержит действующий токен. Upload-эндпоинты принимают токены обоих скоупов — upload и admin.

# Проверить работоспособность токена
curl -H "X-Auth-Token: YOUR_TOKEN" http://localhost:8000/admin/api/products

Загрузка завершается с ошибкой 413 (Request Entity Too Large)

Симптом: Большие файлы не загружаются с ошибкой 413.

Решение: Это, как правило, ограничение обратного прокси, а не самого Fenfa. Увеличьте лимит:

Nginx:

client_max_body_size 2G;

Caddy: У Caddy нет ограничения на размер тела по умолчанию, но если оно было установлено:

dist.example.com {
    request_body {
        max_size 2GB
    }
    reverse_proxy localhost:8000
}

Умная загрузка не определяет метаданные

Симптом: После умной загрузки поля version и build остаются пустыми.

Решение: Автоопределение метаданных при умной загрузке работает только для IPA и APK. Для десктопных форматов (DMG, EXE, DEB и т.д.) явно указывайте version и build в запросе загрузки.

Проблемы Docker

Контейнер запущен, но панель администратора пуста

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

Решение: Убедитесь, что контейнер работает и маппинг портов корректен:

docker ps
docker logs fenfa

Данные потеряны после перезапуска контейнера

Симптом: Все продукты, варианты и релизы исчезают после перезапуска контейнера.

Решение: Монтируйте постоянные тома:

docker run -d --name fenfa -p 8000:8000 \
  -v ./data:/data \
  -v ./uploads:/app/uploads \
  fenfa/fenfa:latest

Permission Denied при монтировании томов

Симптом: Fenfa не может писать в /data или /app/uploads.

Решение: Убедитесь, что директории на хосте существуют и имеют корректные права:

mkdir -p data uploads
chmod 777 data uploads  # Или установите подходящий UID/GID

Проблемы базы данных

Ошибка «database is locked»

Симптом: SQLite возвращает «database is locked» при высокой конкурентности.

Решение: SQLite хорошо справляется с конкурентным чтением, но последовательно обрабатывает записи. Эта ошибка обычно возникает при очень высокой нагрузке на запись:

• Убедитесь, что только один экземпляр Fenfa пишет в один файл базы данных.
• При необходимости нескольких экземпляров используйте S3-хранилище и разделяемую базу данных.

Повреждённая база данных

Симптом: Fenfa не запускается с ошибками SQLite.

Решение: Восстановите из резервной копии:

# Остановить Fenfa
docker stop fenfa

# Восстановить резервную копию
cp /backups/fenfa-latest.db /path/to/data/fenfa.db

# Перезапустить
docker start fenfa

Профилактика

Настройте автоматическое ежедневное резервное копирование. Смотрите скрипт резервного копирования в разделе Продакшн деплой.

Сетевые проблемы

iOS-манифест содержит неверные URL

Симптом: Манифест plist содержит http://localhost:8000 вместо публичного домена.

Решение: Установите FENFA_PRIMARY_DOMAIN в ваш публичный HTTPS URL:

FENFA_PRIMARY_DOMAIN=https://dist.example.com

Медленные загрузки или таймауты

Симптом: Скачивание больших файлов работает медленно или обрывается.

Возможные решения:

• Увеличьте таймаут обратного прокси: proxy_read_timeout 600s; (Nginx)
• Отключите буферизацию запросов: proxy_request_buffering off; (Nginx)
• Рассмотрите использование S3-совместимого хранилища с CDN для больших файлов

Получение помощи

Если проблема не описана здесь:

1. Проверьте GitHub Issues на наличие известных проблем.
2. Просмотрите логи контейнера: docker logs fenfa
3. Создайте новый issue с указанием:
   • Версии Fenfa (docker inspect fenfa | grep Image)
   • Соответствующего вывода логов
   • Шагов воспроизведения