10 Troubleshooting

10 · Неполадки

Каждый пункт: симптом → причина → действие. Всё проверено на живой установке.

Панель не запускается

Симптом	Причина	Действие
Fornex Control: no configuration found	нет fornex.env, нет .env, нет FORNEX_ENV и нет FORNEX_API_KEY в окружении	положить файл настроек уровнем выше приложения
FORNEX_API_KEY is not set in .env	файл найден, ключ пуст	вписать ключ из кабинета Fornex
500 без тела, в журнале «permission denied»	var/ не доступен на запись пользователю PHP	chown -R www-data:www-data var
Вход отвечает bad_credentials при верном пароле	ADMIN_PASSWORD_HASH пуст либо вписан с переносом строки	пересоздать хэш и вставить без переноса

Интерфейс после обновления

Симптом	Причина	Действие
Старая вёрстка, старый код, старый текст	app.js взят из кеша браузера	ссылки содержат ?v=<версия>; поднять APP_VERSION, и адрес изменится
Белая страница, в консоли 404 на assets/…	APP_BASE не совпадает с подкаталогом	APP_BASE=/fornex либо пусто для корня
Окно появляется в углу и закрывается от любого клика	диалог был соседом подложки, а не её ребёнком	исправлено в 1.1.0: диалог внутри .modal-backdrop, закрытие по mousedown вне окна
Кнопка не нажимается и ничего не объясняет	disabled не умеет объяснять	кнопка aria-disabled: клик сообщает, чего не хватает

Зона и записи

Симптом	Причина	Действие
403 You do not have permission to perform this action при создании зоны	у аккаунта Fornex выключено право создавать зоны через API	создать зону в кабинете; панель показывает готовый текст тикета
400 … already exists при добавлении второй MX	Fornex сравнивает строку значения и не смотрит на приоритет	сделать значение отличным: точка на конце (SMTP.GOOGLE.COM.) или другой регистр
Запись «создана», но в зоне её нет	зона пересобирается минутами, публичный резолвер отвечает старым	спрашивать ns1.fornex.com, как это делает проверка
Две SPF в зоне → письма отбиваются с permerror	пресет применили к зоне с готовой SPF в обход слияния	удалить лишнюю по id и применить пресет снова: слияние сохранит незнакомые механизмы
DMARC остался p=none, хотя в пресете quarantine	пресет не понижает и не повышает политику сам	выставить p=quarantine осознанно
Проверка DKIM не проходит, запись на вид есть	значение вставлено фрагментами: потерян префикс v=DKIM1; k=rsa; или добавлен перенос	вставить строку целиком; нормализация добавит префикс и уберёт пробелы, но обрезанный ключ не спасёт
405 method_not_allowed	путь есть, метод другой	в ответе есть Allow и details.allowed
409 при применении шага	шаг требует имя домена как подтверждение	передать "confirm": "example.com" (шаги DKIM и подтверждения)

Клиент API

Симптом	Причина	Действие
Запросы висят без ответа	нет браузерного User-Agent, Fornex придерживает TLS-рукопожатие	FORNEX_USER_AGENT должен быть задан (по умолчанию задан)
502 upstream_error на всё	неверный хост в FORNEX_BASE_URL	нужен https://ru.fornex.com/api; fornex.com/api/ отвечает 302 или 403
Ответ через 30 секунд и ошибка	сеть или API медленные	поднять FORNEX_TIMEOUT; повторы действуют только на сеть и 5xx
Панель показывает версию старее кода	APP_VERSION не поднят	поднять: из него строится ?v=

Отчёт проверки

Симптом	Причина	Действие
«MX не найден», хотя запись в зоне есть	один запрос к резолверу не прошёл	повторить: отчёт спрашивает публичный резолвер и ns1.fornex.com раздельно
NS «не делегирован» у работающего домена	NS сменили минуту назад	подождать TTL реестра и проверить снова
PTR не совпадает	PTR принадлежит владельцу адреса, а не зоне	попросить владельца адреса поставить запись

Ничего не помогает

php tools/lint.php
php tests/plan_test.php
php backend/bin/fornex help          # проверяет настройки и базу
curl -s https://panel.example.com/fornex/api/health
tail -n 50 var/log/app.log

var/log/app.log пишет каждую неудачную операцию с причиной; request_id из строки журнала совпадает с записью в журнале действий. В issue прикладывайте строку журнала, маршрут или команду и состояние зоны — но никогда ключ API.