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

Начинайте с error.code, а не с кода выхода: разные сбои делят один статус, а у PROPERTY_NOT_FOUND нет отдельного кода. Каждая CLI-команда принимает --json:

{"ok": false, "error": {"code": "AUTH_REQUIRED", "message": "Google Search Console token is missing", "retryable": false, "next_action": "lv24-seo auth login --provider gsc"}, "meta": {"version": "0.5.2"}, "warnings": ["gsc: token missing"]}

MCP-инструменты возвращают тот же конверт как structuredContent и ставят isError: true при сбое. Приложение превращает ok=false в типизированную ошибку UI.

Первые проверки

lv24-seo doctor --json
lv24-seo auth status --json
lv24-seo config show --json
# repeat the failing command with --json added

doctor проверяет Python, платформу, путь конфигурации, запись в текущий каталог, эффективный каталог данных и его область, а также наличие токенов, без сетевых вызовов. Его верхнеуровневый ok зависит только от фатальных проверок: Python и запись в текущий каталог. Остальное смотрите в checks[].

Частые коды выхода: AUTH_REQUIRED и AUTH_INVALID (3), PROPERTY_NOT_FOUND (1), QUOTA_EXCEEDED и UPSTREAM_UNAVAILABLE (4), WRITE_DISABLED (2), CONFIRM_REQUIRED (1), INVALID_INPUT и CONFIG_INVALID (2), INTERNAL (1). TRUNCATED зарезервирован и не выдаётся: усечение — это meta.truncated или limitations, а команда выходит с 0.

Отсутствующие токены и аутентификация

AUTH_REQUIRED локален: хранилище секретов не нашло значение для этого движка. Однодвижковые команды падают; агрегированные поверхности продолжают работу с предупреждением вроде gsc: token missing.

lv24-seo auth status
lv24-seo auth set --provider gsc
printf '%s' "$TOKEN" | lv24-seo auth set --provider gsc --stdin

auth set принимает gsc, yandex, metrika, bing, crux, psi, smtp и telegram. Токен Webmaster сохраняйте через auth set --provider yandex, токен Metrika — через auth set --provider metrika или LV24_SEO_YANDEX_METRIKA_TOKEN. auth login --provider gsc|yandex не открывает браузер и ничего не пишет; он печатает ручные шаги.

401 означает, что токен истёк, отозван, повреждён или принадлежит другому аккаунту — замените его. 403 означает, что учётные данные валидны, но не хватает прав: исправляйте доступ к свойству или хосту, а не повторяйте аутентификацию. Для Yandex сравните providers.yandex_webmaster.host_id с точным id (https:example.com:443, не URL); неподтверждённый хост выглядит как 403.

В текущем движке нет OAuth refresh flow и аутентификации сервисного аккаунта. auth set --provider gsc сохраняет одну строку, которая отправляется как Authorization: Bearer; это Google access token, живущий обычно около часа. Сохраняйте свежий токен на каждый запуск. auth status показывает present и источник (env, keyring, file), но никогда значение. Токен из окружения только для чтения: auth set и auth logout возвращают WRITE_DISABLED, пока он задан.

data_dir и относительные пути

Относительный storage.data_dir из seo.toml привязывается к каталогу этого файла. init создаёт <config dir>/data и пишет data_dir = "./data", поэтому --config /srv/site/seo.toml использует /srv/site/data из любого рабочего каталога. Пути делаются абсолютными через os.path.abspath (~ раскрывается, .. нормализуется); symlinks намеренно не разрешаются.

Два случая намеренно остаются process-scoped: встроенное значение по умолчанию (без блока [storage]) — это data относительно рабочего каталога, а LV24_SEO_DATA_DIR переопределяет файл и разрешает относительное значение относительно рабочего каталога.

doctor --json делает область видимой: meta.data_dir — эффективный каталог, meta.data_dir_source равен config, когда путь абсолютный, и working directory, когда он относительный. Относительный каталог при наличии конфига добавляет предупреждение с каталогом конфига. config show --json сообщает тот же эффективный путь. Абсолютный data_dir закрепляет базу.

Повтор токена записи

Apply записи с --confirm использует SQLite-журнал идемпотентности рабочей области, если она инициализирована. Повторный токен возвращает status: skipped с reason: duplicate, и провайдер вызывается один раз. Dry run не открывает журнал и не создаёт базу. Без каталога данных применение всё равно выполняется, но конверт предупреждает, что защита от повтора отключена на пять минут жизни токена. Pending-заявка после падения не имеет TTL и считается выполняющейся, пока оператор её не освободит.

Sitemap too_large

Обнаружение sitemap использует бюджет 50 МБ на документ, включая распакованный размер gzip-тела. Обычные страницы сохраняют лимит 5 МБ. Документ сверх бюджета помечается too_large, а не пустым sitemap. Протокольный лимит — 50 000 URL на sitemap; обход индекса ограничен 20 документами и глубиной 2.

Бюджет — это ограничение размера тела, а не времени: медленный сервер может сначала упереться в таймаут запроса. Разбейте большой sitemap на несколько документов и сошлитесь на них из индекса. Увеличение бюджета URL обхода не увеличивает бюджет тела.

Память и бюджет URL при обходе

crawl.max_urls по умолчанию равен 500. CLI --max-urls принимает положительное целое; MCP seo_crawl_site ограничивает значение выше 5 000 с предупреждением. Обход последовательный, с паузами robots Crawl-delay; concurrency зарезервирован и ни на что не влияет.

Память ограничена: тела страниц — до 5 МБ, сохраняемый текст страницы — до 20 000 символов, бюджет запросов — 1 + max_urls * (max_redirects + 1). word_count по-прежнему считается по полному видимому тексту. Если обход слишком большой или медленный, уменьшите --max-urls и обходите сайт частями. Возобновления и очереди заданий в 0.5.2 нет; у приложения таймаут обхода 600 секунд и нет кнопки отмены.

Ограничения --days

stats и report weekly отклоняют --days больше 3 660 с INVALID_INPUT и exit 2. Десять лет превышают срок хранения любого провайдера. Уменьшите --days или запросите длинную историю явными датами:

lv24-seo gsc query --start 2026-01-01 --end 2026-06-30 --json

GSC search analytics отстаёт на 2–3 дня, Yandex queries — примерно на 4 дня, CrUX — это rolling p75 за 28 дней, PSI — текущий lab-запуск. --lag-days 2 — значение по умолчанию для отчёта.

В report diff нет снимков

report diff нужны два сохранённых недельных снимка для одного свойства. По умолчанию base — второй с конца период, head — последний. Типичные ошибки:

Сообщение	Причина
report diff needs stored snapshots, but no store is configured	Нет init или другой каталог данных
need two stored weekly snapshots for <property>; found N	Меньше двух периодов
no stored weekly snapshot for <label> period <period>	Явного --base или --head не существует

Запустите init один раз, затем report weekly дважды для разных периодов. report diff только читает и не вызывает провайдеров. Метрики, присутствующие только в одном снимке, неизвестны, а не равны нулю; comparable: false означает, что периоды или окна GSC нельзя сравнить.

Установка MCP-клиента

lv24-seo install --client claude
lv24-seo install --client opencode
lv24-seo install --client vscode
lv24-seo install --client cursor
lv24-seo install --client vscode --print

Команда объединяет конфигурацию хоста и печатает, что изменила.

Симптом	Причина	Исправление
«not valid JSON», хотя файл выглядит валидным	UTF-8 BOM, часто от PowerShell 5.1	Перепишите без BOM или удалите файл и повторите
No such command 'mcp'	Старая сборка без mcp serve	Обновитесь до 0.5.2
GUI-клиент не запускает сервер	Приложение не наследует PATH оболочки	Укажите абсолютный путь uvx в command
VS Code ничего не показывает	install пишет mcpServers; VS Code использует servers	Переименуйте ключ или используйте блок для VS Code

OpenCode держит старые инструменты до opencode reload или перезапуска сессии; VS Code может требовать MCP: Reset Cached Tools после обновления.

Приложение не сохраняет MCP-записи; lv24-seo install — это операция CLI. Если показывается объединённый документ хоста, извлекайте только свою запись, потому что документ может содержать токены других серверов.

npm .cmd launcher в Windows

npm-пакет — тонкий лаунчер. Он передаёт аргументы установленному бинарю lv24-seo или uvx --from lv24-seo==<version> lv24-seo. В Windows Node не может запустить .cmd-шим с shell: false; это падает с EINVAL.

Версия 0.5.2 игнорирует шимы lv24-seo.cmd и .bat и предпочитает lv24-seo.exe или бинарник без расширения, прежде чем откатиться к uvx. Если лаунчер всё равно выбирает не тот бинарник, задайте абсолютное переопределение:

LV24_SEO_BIN=/absolute/path/to/lv24-seo npx @lv24/seo version --json

В PowerShell задайте $env:LV24_SEO_BIN перед запуском лаунчера. LV24_SEO_PIN=0 возвращает незакреплённый поиск latest. Лаунчер отказывается запускать собственный шим, поэтому затенение в PATH не приводит к рекурсии.

Движок приложения offline или version gate

Оболочка ищет движок в порядке: LV24_SEO_BIN (только абсолютный), встроенный engine/lv24-seo/, плоский lv24-seo/, соседний lv24-seo/, затем PATH только при LV24_SEO_ALLOW_PATH_ENGINE=1. Она запускает lv24-seo version --json и сравнивает результат с MIN_ENGINE_VERSION, который в текущем исходнике равен 0.5.2.

Старый движок помечается compatible: false; UI считает его offline и не запускает команду. Ничего не скачивается автоматически.

Симптом	Исправление
Движок не найден	Переустановите приложение или задайте абсолютный LV24_SEO_BIN
Движок слишком старый	Установите движок 0.5.2 или новее
Метка external engine	Ожидаемо, если задан LV24_SEO_BIN

Случайный lv24-seo в PATH игнорируется, если не задан LV24_SEO_ALLOW_PATH_ENGINE=1.

Portable, deb и rpm не обновляются автоматически

Автообновление включено только для Windows NSIS, macOS .app и Linux AppImage. deb, rpm, MSI и portable ZIP — manual-only: они не могут безопасно заменить работающую установку. Панель Settings отключает встроенный установщик и ссылается на страницу релиза.

Пакет	Путь обновления
Windows NSIS	Встроенное подписанное обновление
Windows portable ZIP	Скачать и распаковать новый ZIP
Linux AppImage	Встроенное подписанное обновление
Linux deb или rpm	Обновление менеджером пакетов

Portable-сборка определяется по источнику движка sibling или bundled-flat, поэтому сохранение папки lv24-seo/ рядом с исполняемым файлом также оставляет updater в ручном режиме.

Ошибка подписи updater

Ошибка подписи — это блокировка безопасности, а не временная сетевая ошибка. Updater помечает её non-retryable, блокирует артефакт и ведёт на страницу релиза. Не отключайте requireSignedVersion и не повторяйте тот же артефакт.

Скачайте релиз вручную, проверьте его по SHA256SUMS.txt и установите. Подпись updater аутентифицирует обновления; она не делает доверенной первую ручную загрузку. Плохая подпись может означать повреждённую загрузку, несоответствие манифеста и пакета или ротацию ключа. Сообщите о ней, а не обходите.

Linux keyring и DBus

Движок использует OS keychain только при установленном extra secrets. Sidecar приложения включает backends keyring. В Linux Secret Service нужен session bus; CLI-раннер приложения наследует DBUS_SESSION_BUS_ADDRESS, XDG_RUNTIME_DIR, XDG-каталоги и TMPDIR, фильтруя остальные переменные хоста.

Симптом	Исправление
Keyring отклонил запись	Разблокируйте его или задайте LV24_SEO_ALLOW_FILE_SECRETS=1 для файлового fallback 0600
Нет доступного backend секретов	Установите lv24-seo[secrets] или включите файловый fallback
Headless-хост без session bus	Используйте токены окружения LV24_SEO_*

Файловый fallback — data/secrets.json, режим 0600 на POSIX. Windows использует ACL. Приложение показывает активный источник и поясняет, что удаление файлового секрета не удаляет переменную окружения.

Gatekeeper macOS и SmartScreen Windows

Сборки macOS подписаны ad-hoc, без notarization. Gatekeeper предупреждает при первом запуске. Используйте System Settings → Privacy & Security → Open Anyway или правый клик по приложению → Open. Не отключайте Gatekeeper глобально.

Сборки Windows не имеют подписи Authenticode. SmartScreen, Smart App Control или антивирус могут предупредить или заблокировать установщик либо portable-бинарник. Выбирайте More info → Run anyway только после проверки SHA-256 по SHA256SUMS.txt. Не отключайте эти защиты глобально. Если нужна подписанная сборка, соберите из исходников и подпишите своим сертификатом.

Updater сообщает UPDATE_ENGINE_BUSY

Sidecar движка лежит внутри установленного каталога ресурсов. Перед обновлением в приложении оболочка останавливает только зарегистрированные ею PID sidecar; движок, запущенный из терминала или другой копии приложения, не убивается. Если такой процесс удерживает установленный файл, установка блокируется с UPDATE_ENGINE_BUSY.

Закройте терминал или запуск приложения, удерживающий lv24-seo, дождитесь выхода и снова нажмите Download and install. Ошибка повторяемая; не удаляйте файлы внутри установленного каталога ресурсов.

Логи и диагностика

Логирование опционально. LV24_SEO_LOG_LEVEL=INFO (или DEBUG, WARNING, …) заставляет CLI и lv24-seo mcp serve установить redacting-handler. Если переменная не задана, конфигурация логирования вызывающего не меняется; импорт библиотеки или create_server() никогда не заменяет root-handlers. Вывод — одна JSON-строка на запись, когда stderr не терминал (pipe, лог планировщика, MCP-хост), и обычная строка иначе. MCP-транспорт пишет только в stderr; stdout остаётся протоколом. Стабильный интерфейс диагностики — по-прежнему конверт --json, а не лог-файл.

У приложения есть каталог логов, каталог данных и каталог экспорта. Их точные пути сообщает shell_status и показывает экран Configuration; не угадывайте их по идентификатору пакета. Диагностический bundle запускается пользователем и содержит версии, пути, проверки doctor, отредактированный эффективный конфиг, имена переменных окружения и последние несекретные ошибки задач. Он никогда не отправляется автоматически.

Перед публикацией конверта удалите токены, cookies, заголовки Authorization, LV24_SEO_WRITE_SECRET, содержимое .env, data/secrets.json, JSON сервисного аккаунта и клиентские запросы. Валидация ввода CLI может отразить переданное значение, а URL query может содержать key=, token= или signature=.

lv24-seo version:
OS / Python:
command:
expected:
actual (redacted --json envelope):

О проблемах безопасности сообщайте через приватный advisory из SECURITY.md, а не в публичный issue.

См. Безопасность и приватность для write-гейтов и Релизы и обновление для поведения updater.

Source: _source/engine-troubleshooting.md, _source/engine-releases-0.5.2.md, _source/desktop-releases-0.2.2.md, _source/desktop-releases-0.2.1.md, _source/desktop-releases-0.2.0.md, _source/desktop-security.md, _source/desktop-architecture.md.