Устранение неполадок в приложении Marinara Engine

Найдите свой симптом и выполните описанное исправление. Большинство проблем исчезает после перезапуска Marinara через ее скрипт запуска (start.bat, start.sh или start-termux.sh).

Что попробовать в первую очередь

1. Обновите страницу принудительно: <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>R</kbd> в Windows или Linux, <kbd>⌘</kbd>+<kbd>Shift</kbd>+<kbd>R</kbd> на Mac.
2. Посмотрите в консоль сервера (окно терминала, в котором запущена Marinara) и найдите красные строки с ошибками. Обычно они называют настоящую причину.
3. Прежде чем просить о помощи, включите Debug mode (режим отладки). См. Как получить помощь.

Персонаж не отвечает

Проверьте по порядку.

1. Посмотрите, нет ли всплывающего сообщения (короткого сообщения внизу экрана). Обычно оно называет проблему. См. Ошибки подключения и генерации.
2. Проверьте, что у чата есть аккаунт и модель: откройте Chat Settings (настройки чата) и посмотрите на подключение. Если его нет, добавьте аккаунт в Connections (подключения). См. Подключение к провайдеру ИИ.
3. Проверьте, что ключ API верный и на балансе аккаунта есть средства. Неверный ключ или пустой баланс – частая причина.
4. Проверьте название модели, а для локального сервера, например Ollama или LM Studio, – что сервер запущен.
5. Отправьте сообщение еще раз или выберите другую модель.

Если ничего не помогает, включите Debug mode и прочитайте консоль сервера. См. Как получить помощь.

Приложение не загружается на телефоне или другом устройстве

Не получается открыть Marinara с телефона, планшета или другого компьютера?

Чаще всего причина в одном из трех:

• Адрес. По умолчанию сервер слушает 127.0.0.1 (только этот компьютер). Скрипты запуска задают HOST=0.0.0.0. Если вы запускали через pnpm start, сначала задайте HOST=0.0.0.0 в .env.
• Сеть. Оба устройства должны быть в одной сети Wi-Fi, и файрвол не должен блокировать порт. Порт по умолчанию – 7860 или ваш PORT.
• Вход. Задайте его. На заблокированном устройстве введите одноразовый код настройки из журнала сервера вместе с новыми именем пользователя и паролем. В Docker код можно найти командой docker logs <container> 2>&1 | grep "setup code". Либо задайте вход в Settings → Advanced → Access (настройки → дополнительно → доступ) в браузере, где вы уже вошли. На сервере без монитора выполните ssh -L 7860:127.0.0.1:7860 user@server, откройте http://localhost:7860 и используйте Settings. См. Удаленный доступ.

Другие причины:

• Прокси или туннель на той же машине. Обратному прокси или туннелю на той же машине нужен вход. Прямой трафик Tailscale по умолчанию считается доверенным. Tailscale Serve или Funnel и proxy_pass nginx по умолчанию (HTTP/1.0) считаются пересланными и требуют входа. Трафик моста Docker на том же хосте считается доверенным, только пока не задан вход, IP_ALLOWLIST или TRUSTED_AUTH_PROXY.
• Собственное имя для этого компьютера. Имя, которое в /etc/hosts указывает на 127.0.0.1, считается пересланным. Вместо него используйте localhost, 127.0.0.1, имя компьютера в сети или имя вида *.localhost.
• Too many wrong passwords. Подождите 15 минут, затем войдите. Забыли пароль? Выполните node scripts/reset-login.mjs в папке Marinara на компьютере, где запущена Marinara. В Docker выполните docker exec <container> node scripts/reset-login.mjs. Перезапуск сервера тоже позволяет попробовать снова.
• Untrusted request host. Для публичного домена или домена обратного прокси добавьте точное имя его хоста в TRUSTED_HOSTS в .env. Прямые IP-адреса по-прежнему принимаются.
• Опасные действия заблокированы (резервные копии, очистка данных, обновления) на этом устройстве. На компьютере, где работает сервер, откройте Settings → Advanced → Admin Access (настройки → дополнительно → доступ администратора) и нажмите Make admin secret (создать секрет администратора) или задайте ADMIN_SECRET в файле .env сервера. Введите секрет в Admin Access на другом устройстве и нажмите Save (сохранить).

См. Удаленный доступ и Частые вопросы. Если после обновления вы потеряли доступ, см. Нет доступа после обновления.

Сохранение заблокировано или настройки не сохраняются

Сохранение вроде бы проходит, но после перезагрузки страницы все возвращается назад. Его блокирует межсайтовая защита (CSRF), потому что она не доверяет этому адресу браузера. Вы видите красную полосу с предупреждением, что сохранение будет молча срываться, или всплывающее сообщение с заголовком Save blocked: missing CSRF header, Save blocked: cross-site request rejected или Save blocked: origin not trusted.

Loopback, адреса частных сетей, Tailscale и мост Docker считаются доверенными автоматически. Обычно это случается при обращении по публичному IP-адресу или доменному имени. Добавьте адрес в CSRF_TRUSTED_ORIGINS в .env, перечисляя адреса через запятую. В полосе есть кнопка Copy (копировать), которая подставляет готовую строку. Перезапуск не нужен.

CSRF_TRUSTED_ORIGINS=http://203.0.113.10:7831,https://chat.example.com

Ошибки подключения и генерации

Ошибки генерации показываются всплывающим сообщением внизу экрана. Оно называет причину и висит достаточно долго, чтобы его скопировать.

После обновления

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

• Экран пустой или выглядит старым: см. Пустой экран или устаревший вид приложения и Пустая страница или JavaScript в виде HTML после обновления.
• Чаты или пресеты как будто пропали: см. После обновления данные как будто пропали. Ваши данные почти всегда по-прежнему лежат на диске.
• Чаты выглядят пустыми после возврата на старую версию: см. После перехода на старую версию в чатах не видно сообщений.

Пустой экран или устаревший вид приложения

Сервер работает, но браузер показывает пустую страницу или приложение после обновления выглядит старым. Браузер держит в кеше копию веб-приложения.

1. Обновите страницу принудительно.
2. Если это не помогло, откройте Settings → Advanced → Updates (настройки → дополнительно → обновления) и нажмите Refresh App (обновить приложение).

Кнопка Refresh App очищает service worker браузера (фоновый скрипт, который кеширует приложение) и кеш, а затем перезагружает страницу. Ваши данные она не меняет и сервер не обновляет. Чтобы обновить само приложение, см. Обновление приложения Marinara Engine.

Пустая страница или JavaScript в виде HTML после обновления

Ошибка вроде "Failed to load module script" с типом text/html означает, что браузер запросил файл JavaScript, которого нет в сборке. Удаление ваших данных этого не исправит.

1. Остановите сервер.
2. Снова запустите start.bat, start.sh или start-termux.sh. Перед запуском скрипт запуска пересобирает неполные файлы клиента. При ручной установке сначала выполните pnpm build из корня репозитория.
3. Если страница все еще пустая, обновите ее принудительно или попробуйте приватное окно.

Если ошибка не исчезает, сообщите полный URL проблемного файла, статус HTTP, Content-Type и первую строку ответа вместе с выводом скрипта запуска.

После обновления данные как будто пропали

Не удаляйте папки с данными. Marinara хранит рабочие данные в папке storage внутри своей папки данных. Поищите storage в packages/server/data/ и в data/. При запуске сервер печатает, какие папки он определил.

После перехода на старую версию в чатах не видно сообщений

Новые версии Marinara хранят записи каждого чата (сообщения, свайпы, воспоминания, изображения) в отдельных файлах, и благодаря этому длинные чаты сохраняются быстрее. Старые версии не понимают такую структуру, поэтому чаты выглядят пустыми. Данные по-прежнему лежат на диске.

Marinara блокирует очевидные понижения версии. Скрипт запуска пропускает автообновление, которое привело бы к несовместимой версии, а встроенный механизм обновления показывает ошибку, ведущую к этому разделу.

Если вы обновились, а затем вернулись на старую версию, восстановите резервную копию, созданную перед обновлением. См. Переход на старую версию. Технические подробности ниже.

Сейчас ваши данные в формате хранения 10. Форматы 8, 9 и 10 добавляют настройки 3D-аватаров (сначала MMD, затем GLB и FBX) и привязки подключений к аккаунтам, которые старые сборки не могут безопасно прочитать. Если ваши данные достигли формата 8 или новее, то для работы с более старой сборкой восстановите полную резервную копию, созданную до этого обновления. Команда ниже преобразует только старые структуры файлов чатов. Не меняйте номер формата вручную. См. Переход на старую версию.

Для данных ниже формата 8 преобразуйте структуру файлов чатов:

1. Остановите сервер Marinara.
2. В папке Marinara выполните:

   node scripts/protect-launcher-data.mjs unshard

1. Переключитесь на старую версию и запустите ее.

Команда восстанавливает однофайловую структуру из файлов отдельных чатов. Ничего не удаляется. Файлы отдельных чатов остаются в папках с именем <table>.post-unshard-<timestamp>, и все оригиналы .pre-shard тоже остаются. При следующем обновлении Marinara преобразует ваши данные обратно.

В Docker или Podman данные хранятся в томе marinara-data. Остановите контейнер, выполните команду ниже, затем запустите старый образ:

docker compose run --rm marinara node scripts/protect-launcher-data.mjs unshard

Проблемы установки и запуска

Termux: ошибка CANNOT LINK EXECUTABLE "node"

Termux выводит CANNOT LINK EXECUTABLE "node" вместе с cannot locate symbol или library ... not found. Node.js обновился отдельно от остальных пакетов Termux. Тогда приложение для Android может остановиться с сообщением Could not verify that this Marinara Android build can safely read your stored data. Причина не в ваших данных, и повторная установка APK этого не исправит.

1. В Termux выполните:

   pkg upgrade -y

1. Нажмите Install / Start Marinara в приложении для Android. При ручной установке выполните cd "$HOME/Marinara-Engine" && ./start-termux.sh.

Если при обновлении появится вопрос, сохранить ли файл конфигурации, нажмите Enter, чтобы оставить текущий. Актуальные скрипты запуска и приложения для Android выполняют это обновление сами.

Termux: ошибка JavaScript heap out of memory при сборке клиента

Vite останавливается с Reached heap limit или JavaScript heap out of memory. Обновитесь, затем снова запустите ./start-termux.sh. Сборка клиента получает собственную кучу 1536 MiB, но не больше половины RAM устройства и не меньше 1280 MiB. Лимит кучи, который вы задали в NODE_OPTIONS, важнее, поэтому удалите старое ограничение 1024 MiB. Перед повтором закройте другие приложения. На телефонах, где RAM меньше примерно 3 ГБ, памяти все еще может не хватить. Не удаляйте чаты и профиль ради исправления сборки.

Компьютер: ошибка JavaScript heap out of memory при проверке типов клиента

Сборка останавливается с сообщением The client type-check needs about 2.5 GiB of Node.js heap. Лимит в вашей переменной NODE_OPTIONS слишком мал, а сборка сохраняет заданный вами лимит. Повысьте --max-old-space-size до 2560 или больше. Если NODE_OPTIONS содержит --max-old-space-size-percentage, повысьте вместо этого его, потому что он имеет приоритет над другим параметром. Либо удалите оба параметра. Затем снова запустите скрипт запуска. Ваши данные это не затрагивает.

Termux: отсутствует файл гостевого клиента многопользовательского режима

При запуске сообщается об отсутствии packages/client/dist/multiplayer/guest.js. Обновите Marinara и снова выполните ./start-termux.sh: он выполняет полную сборку клиента. Включать многопользовательский режим не нужно.

Termux: сервер останавливается при открытии Marinara или Sharp не загружается

Sharp – это библиотека изображений, с помощью которой Marinara создает миниатюры и спрайты. На Android она работает через резервный вариант на WebAssembly. Обновите Marinara и дайте скрипту запуска переустановить зависимости. Если сервер останавливается раньше, чем вы успеваете обновиться, восстановите установку вручную в Termux:

cd ~/Marinara-Engine
rm -f node_modules/.modules.yaml
SHARP_IGNORE_GLOBAL_LIBVIPS=1 pnpm --config.trustPolicy=off --config.confirmModulesPurge=false install --frozen-lockfile --prefer-offline
./start-termux.sh

Ваши чаты и настройки не затрагиваются. Если Sharp по-прежнему не загружается, Marinara продолжает работать с выключенной обработкой изображений. Уже созданные миниатюры по-прежнему видны, для новых используется полноразмерное изображение, а создание спрайтов и встроенное удаление фона недоступны. Не заменяйте Sharp другой версией. Сохраните полный вывод ошибки для сообщения о проблеме.

Браузер открывается до завершения запуска

Обновитесь и перезапустите Marinara через скрипт запуска. Он открывает браузер только после того, как сервер сообщит о готовности. Если запуск не удался, вкладка не открывается, поэтому сохраните ошибку из терминала. Чтобы открывать приложение самостоятельно, задайте AUTO_OPEN_BROWSER=false.

Windows: ошибка EPERM или проверки подписи corepack при установке pnpm

pnpm – это менеджер пакетов, с помощью которого Marinara устанавливает свой код. EPERM: operation not permitted или ошибка проверки подписи corepack означает, что corepack не смог записать файлы в папку установки Node. Попробуйте один из способов, затем снова запустите скрипт запуска:

1. Нажмите правой кнопкой мыши на терминал, выберите Run as administrator (запуск от имени администратора) и запустите скрипт запуска.
2. Установите pnpm самостоятельно: npm install -g pnpm@12.15.0
3. В терминале администратора обновите corepack: npm install -g corepack

Ошибка версии pnpm или 'pnpm' is not recognized

Marinara использует pnpm 12.15.0. Скрипт запуска сам получает нужную версию, и старую глобальную версию pnpm сначала заменять не нужно. Обновите Marinara (выполните git pull в ее папке, если скрипт запуска не может этого сделать), затем снова запустите скрипт запуска. Если ошибка не исчезает, установите точную версию и снова запустите скрипт запуска:

npm install -g pnpm@12.15.0

Linux: ERR_PNPM_ENAMETOOLONG при установке

Старая установка оставила длинные пути к папкам. Из папки Marinara выполните:

rm -rf node_modules .pnpm .pnpm-store

Затем снова запустите ./start.sh. При ручной установке выполните pnpm install.

Установка сообщает "Ignored build scripts: @google/genai"

Это безобидное уведомление. Не выполняйте pnpm approve-builds: эта команда меняет файл, который отслеживает Marinara. Если уведомление продолжает появляться после обновления, удалите node_modules/.modules.yaml в папке Marinara и снова запустите скрипт запуска.

ERR_PNPM_TRUST_DOWNGRADE при установке

Почти всегда это незавершенная установка. Снова запустите скрипт запуска. При ручной установке выполните из папки Marinara:

pnpm --config.trustPolicy=off --config.confirmModulesPurge=false install --frozen-lockfile

Проблемы со встроенной моделью

Built-in model (встроенная модель) работает на вашем компьютере без ключа API. В некоторых сообщениях об ошибках она называется sidecar. Настройка описана в руководстве Настройка встроенной модели.

• Sidecar runtime install is disabled. На своем компьютере задайте SIDECAR_RUNTIME_INSTALL_ENABLED=true в .env. С другого устройства сначала сохраните свой секрет администратора в Settings → Advanced → Admin Access.
• Скачивание или настройка модели не проходит с другого устройства (по сетевому адресу или из Docker). Возможно, здесь тоже нужен секрет администратора. На своем компьютере он не нужен.
• Несовпадение размера или SHA-256 у поставляемого файла llama.cpp, MLX или uv. Marinara отклонила файл до его использования. Обновите или переустановите Marinara и повторите попытку. Не распаковывайте, не правьте и не обходите этот файл.

Память и сводки

Memory Recall ничего не вспоминает

Функция Memory Recall ищет в прежних сообщениях самые подходящие и добавляет их обратно в промпт.

1. Откройте Chat Settings → Memory Recall и убедитесь, что переключатель Enable Memory Recall включен.
2. Откройте Access memories for this chat. В разделе Memories for This Chat посмотрите статус каждого фрагмента.
3. Статус Waiting for vector означает, что воспоминание еще обрабатывается. Подождите и снова напишите в чат.
4. Статус Embedding unavailable означает, что ни один источник эмбеддингов не работает. Настройте аккаунт для эмбеддингов или дайте загрузиться встроенной модели. Чтобы использовать один источник для всех чатов, выберите его в пункте Embeddings (эмбеддинги) раздела Defaults (по умолчанию) панели Connections.

Воспоминание создается только после минимум 5 новых сообщений. Memory Recall показывает лишь воспоминания, близкие к вашему новому сообщению, поэтому результат может быть пустым, даже когда воспоминания есть.

Advanced Memory сообщает, что сцены требуют внимания

Немигающая точка на кнопке Chat Settings или уведомление о том, что Advanced Memory нашла проблемы, означает, что некоторые воспоминания о сценах неясны, устарели или отсутствуют.

1. Откройте Chat Settings → Memory Recall или нажмите Fix (исправить) в уведомлении.
2. Нажмите Fix. Кнопка исправляет все сцены, какие может, с помощью вспомогательной модели (Helper model) и никогда не меняет сводки, которые вы отредактировали.
3. Выберите номер каждой сцены под надписью need your review, проверьте ее текст и персонажей в Access memories for this chat и нажмите Save correction (сохранить исправление).

Если Fix останавливается с ошибкой, проверьте аккаунт вспомогательной модели, затем нажмите Resume processing (продолжить обработку) или снова Fix. См. Исправление проблем с памятью.

Сводки не генерируются

Для сводок нужен работающий текстовый аккаунт.

• Roleplay: откройте Chat Settings → Chat Summary, проверьте, что аккаунт выбран, и нажмите Backfill Summary, чтобы догнать старый чат.
• Conversation: откройте Automatic Summarization и нажмите Backfill, чтобы повторить неудавшиеся дни.
• Если в чате требуется подтверждение записи от агентов, сводка от ИИ ждет вашей проверки.
• Сводку, которая продолжает срываться, например из-за неверного ключа API, Marinara повторяет позже. Исправьте аккаунт, затем нажмите Backfill.

Проблемы со скачиваемыми агентами

• Каталог недоступен в Agent Organizer. Доступ к каталогу Pasta-Devs/Marinara-Agents по HTTPS нужен компьютеру, на котором работает сервер, а не только вашему браузеру. Установленные агенты продолжают работать без сети. Восстановите соединение, затем нажмите Refresh (обновить) или Try again (повторить).
• Установленная карта или звонок не появляются. Полностью закройте Marinara и запустите ее заново. Такие пакеты остаются в состоянии Restart required до следующего запуска. Игры для Conversation включаются сразу. Если установка не удалась, обновите каталог и убедитесь, что игра отмечена как готовая. Добавлять игру в настройках Commands (команды) чата нужно только для того, чтобы персонажи могли начинать ее сами; для ее ручной слеш-команды это не требуется.
• Первая миграция пакетов не может завершиться. Не удаляйте data/capability-packages и данные чатов. Marinara повторит попытку при следующем запуске, а то, что вы выбрали в чатах, остается сохраненным.
• Большие папки data/capability-runtime-snapshots или data/capability-packages/versions. Чистить их не нужно. Marinara удаляет старые копии при запуске и оставляет текущую и предыдущую версии каждого агента.
• Скачивание пакета отклонено. Контрольная сумма, список файлов, диапазон версий Marinara или пути внутри архива не совпадают с официальным каталогом. Обновите Marinara, обновите каталог и повторите попытку. Не распаковывайте артефакт в папку данных вручную.
• Обновления. Обновления агентов никогда не применяются при запуске. Marinara сначала спрашивает. Not now (не сейчас) оставляет установленную версию, а кнопка Update (обновить) остается в Agents → Agent Organizer (агенты → организатор агентов). Неудачное обновление оставляет установленную версию на месте. Среда выполнения сервера, которая не прошла проверку при запуске, откатывается.

Проблемы с Card Browser

Раздел Card Browser ищет по публичным сайтам с персонажами. Откройте его кнопкой Download (скачать) в верхней части панели Characters (персонажи) или Personas (персоны).

• JannyAI показывает блокировку Cloudflare. Один раз зайдите на сайт JannyAI в этом же браузере, чтобы пройти проверку, затем повторите попытку.
• Вход на Pygmalion перестает работать после перезапуска. Это ожидаемо. Этот вход хранится только в памяти сервера. Откройте окно входа и вставьте токен заново.
• CharacterTavern показывает уведомление вместо результатов. Это ожидаемо. Новый сайт больше не поддерживает способ подключения, которым пользовалась Marinara. Скачайте карточку с character-tavern.com и импортируйте файл.

Проблемы с генерацией медиа

Очистка фона спрайта не справляется со сложной сценой

Сгенерированные спрайты обычно используют собственную прозрачность или однотонную подложку, которую Marinara удаляет. Сфотографированная комната, подробный пейзаж, густые тени или цвета, совпадающие с фоном, могут потребовать дополнительной очистки через ИИ:

pnpm backgroundremover:install

Затем перезапустите Marinara и нажмите кнопку Reapply Cleanup в окне генерации спрайтов. Marinara сначала пробует встроенную очистку и обращается к модели ИИ, только когда край выглядит неоднородным. Если установка не удалась:

• Проверьте, что установлен Python версии от 3.9 до 3.11. Более новые версии могут запустить медленную сборку из исходников.
• Выполните pnpm backgroundremover:reinstall.
• Чтобы на время разбирательств обойтись без очистки через ИИ, задайте SPRITE_BACKGROUND_REMOVAL_ENGINE=builtin в .env.

Раскадровки в Game Mode или Roleplay не появляются

Раскадровки превращают завершенное повествование в ключевые кадры и, по желанию, в клипы. См. Руководство по агенту Storyboard и Game Mode: начало работы.

• Установите Storyboard через Agents → Agent Organizer, затем включите для чата Enable Agents (включить агентов) и Enable Storyboards (включить раскадровки).
• Ключевым кадрам нужен аккаунт для изображений. Клипам нужен еще и аккаунт для видео.
• Game, автоматический режим: откройте Chat Settings → Agents → Storyboards и проверьте, что переключатель Automatic Storyboard Illustrations включен. Для клипов включите Automatic Storyboard Animations.
• Видео сцены вручную: откройте Chat Settings → Gallery, сгенерируйте или загрузите изображение, затем используйте Video или Animate. Смотрите на вкладке Videos.
• Roleplay: добавьте в чат агента Storyboard. Выберите Still images или Animations, задайте Messages per episode и выберите аккаунт для изображений. Вариант Manual only запускается кнопкой Create storyboard в разделе Gallery внутри Chat Settings.
• Если ваш промпт работает лучше, когда все персонажи объединены, выключите Use NovelAI Character Prompts.
• У медленных сервисов может истечь тайм-аут. Увеличьте IMAGE_GEN_TIMEOUT_MS или VIDEO_GEN_TIMEOUT_MS в .env, затем перезапустите Marinara.
• Outbound response exceeded 31457280 bytes: по умолчанию ответ с изображением больше 30 MiB завершается ошибкой. Такого размера могут достигать файлы ComfyUI, в которые встроены рабочий процесс и референсные изображения. Увеличьте IMAGE_GEN_MAX_RESPONSE_BYTES в .env и перезапустите Marinara или отключите метаданные в ComfyUI.

Генерация мира в Game Mode выдает ошибку JSON

Если модель вернула испорченный JSON (структурированный текст), Marinara открывает окно Repair JSON вместо того, чтобы выбросить ход.

1. Исправьте скобки, запятые или поля в редакторе. Когда текст разбирается, полоса сообщает JSON is valid.
2. Нажмите кнопку Format, чтобы привести оформление в порядок.
3. Нажмите кнопку Apply Repaired JSON, чтобы применить исправленный текст без повторной генерации ответа.

Голос, звонки и TTS

• Персонажи молчат во время звонка. Синтез речи не настроен. Откройте Connections → Text to Speech (подключения → синтез речи), включите его, выберите источник, введите ключ, выберите голос и сохраните. Персонаж без голоса отвечает только текстом.
• Речь обрывается с сообщением "No audio after N s". Ваш голосовой сервер работает медленнее, чем Marinara готова ждать; локальный сервер на ноутбуке часто именно такой. N – ваш текущий тайм-аут. Увеличьте Request timeout (seconds) (тайм-аут запроса в секундах) в Connections → Text to Speech или в аудиоаккаунте, который назван в сообщении. См. Тайм-аут запроса.
• Микрофон не работает. Установите Calls через Agents → Agent Organizer. Затем откройте Connections → Speech to text (подключения → распознавание речи), найдите Local speech model (локальная речевая модель) в группе On this device (на этом устройстве), выберите модель Whisper и нажмите Download Whisper. В Firefox это нужно, потому что в нем нет браузерного распознавания речи. При удалении Calls его модели Whisper тоже удаляются. Можно также использовать собственный сервер: см. Использование собственного сервера распознавания речи.
• Local Whisper is disabled in Lite mode. Облегченный образ не может запускать локальную речевую модель. Используйте полную установку.

Вход в Spotify для Music DJ не работает при удаленной или сетевой установке

Режим Spotify у агента Music DJ работает через OAuth – передачу входа, при которой Spotify возвращает вас на адрес обратного вызова (redirect URI). Spotify принимает только адреса https:// или http://127.0.0.1 и отклоняет обычные сетевые IP-адреса.

• На localhost редактор показывает адрес обратного вызова с 127.0.0.1. Зарегистрируйте его в Spotify.
• По HTTPS редактор показывает ваш адрес обратного вызова с HTTPS. Зарегистрируйте его.
• Если HTTPS завершается на внешнем прокси и хост не совпадает, задайте в .env переменную SPOTIFY_REDIRECT_URI со своим публичным адресом обратного вызова.
• При сетевой установке по обычному HTTP всплывающее окно не может загрузиться, но в его адресной строке есть действующий код. Скопируйте полный URL, разверните Browser couldn't reach the callback? под кнопкой Connect и вставьте его. URL действует 10 минут.

Самое надежное решение – открывать Marinara по HTTPS.

Хранилище и данные

Сервер не возвращается после Restart Server

Запускайте Marinara через start.bat, start-local.bat, start.sh, start-termux.sh или pnpm start. Они сохраняют связь сервера с его скриптом запуска и запускают замену после завершения старого процесса. Перезапуск из приложения закрывает оставшиеся соединения через четыре секунды и принудительно завершает процесс через восемь. Принудительное завершение может прервать ожидающие операции записи. Прямые запуски через node и процессы наблюдения за файлами в режиме разработки не заменяются: остановите и снова запустите их сами. Docker использует политику перезапуска контейнера. В Windows нажмите <kbd>Ctrl</kbd>+<kbd>C</kbd> в консоли скрипта запуска и дождитесь Shutdown complete, прежде чем закрывать ее.

Не запускайте второй сервер с той же папкой данных, пока первый еще работает. Сначала остановите оставшийся процесс.

При запуске говорится, что каталог данных может использовать другой процесс

Записывать в локальную папку данных может только один сервер. Если при запуске для этой папки появляется Another Marinara Engine process ... may be using, закройте другой процесс Marinara и запустите снова.

После сбоя или перемещения тома Docker при запуске может появиться The storage writer lease ... is incomplete or invalid или указание на процесс, которого уже нет.

1. Убедитесь, что остановлены все процессы и контейнеры Marinara, использующие эту папку данных.
2. Удалите только папку .writer-lease, названную в ошибке.
3. Перезапустите Marinara. Не удаляйте папку storage и файлы таблиц.

Marinara сама освобождает аренду права записи, оставленную аварийно завершившимся процессом, в Linux, Android, контейнерах и Windows, когда папка данных находится на локальном диске. Ручной шаг – запасной вариант для сетевого или общего хранилища, съемных дисков и (в Windows) компьютера, переименованного после сбоя.

Резервная копия или экспорт возвращает 403

Сессии на этом же компьютере могут создавать резервные копии без секрета администратора. Запросам с другого устройства, по сетевому адресу, из Docker или через прокси либо туннель на том же компьютере он нужен. Создайте его в Settings → Advanced → Admin Access на компьютере, где работает сервер, или задайте ADMIN_SECRET на сервере, а затем сохраните то же значение в Admin Access на другом устройстве. Чтобы секрет требовался и для loopback, задайте MARINARA_REQUIRE_ADMIN_SECRET_ON_LOOPBACK=true. Если задано REQUIRE_AUTH_FOR_LOOPBACK_PROXY=false, пересланные посетители получают локальное исключение. Для публичного прокси или туннеля оставьте эту защиту включенной.

Импорт сообщает, что файл не является читаемым архивом ZIP

Marinara читает карточки .charx, пакеты .marinara, пакеты агентов и свои репозитории агентов как архивы ZIP. Она отклоняет поврежденный архив или архив, содержимое которого не совпадает с его списком файлов, с сообщением The file is not a readable ZIP archive (или Could not read .marinara package). Обычная причина – файл скачался не полностью: скачайте его заново. Если архив вы собирали сами, создайте его заново функцией сжатия вашей системы, zip или 7-Zip.

Package contains too many files означает, что пакет агента или репозиторий содержит больше 8192 файлов. .marinara package has too many entries означает, что пакет .marinara содержит больше 8 записей. Удалите лишние файлы и попробуйте снова.

Расписания Conversation или Noodle используют неверный часовой пояс или показывают Etc/Unknown

Для расписаний Conversation выберите Schedule timezone (часовой пояс расписаний) в настройках чата Conversation или в редакторе расписания персонажа. Use device (как на устройстве) сбрасывает выбор.

Для Noodle и других серверных задач удалите из .env пустую строку TZ=, если она есть, и перезапустите Marinara, чтобы она использовала часовой пояс хоста. Чтобы задать пояс явно, укажите имя IANA, например TZ=Europe/Warsaw.

Проблемы с Android

Приложение Android застряло на Connecting или Waiting for Server

Приложение для Android – это небольшая оболочка вокруг Termux, приложения с терминалом Linux для Android, в котором работает настоящий сервер Marinara.

1. Нажмите Install / Start Marinara.
2. Если Android предлагает установить Termux, подтвердите запросы.
3. Если Android просит разрешение выполнять команды в Termux, дайте его.
4. Дождитесь, пока скрипт запуска запустит сервер, затем вернитесь в приложение.

Приложение создает собственные закрытые учетные данные для localhost и входит автоматически. Вставлять секрет никогда не нужно. Не добавляйте null, http://null или секрет APK в CSRF_TRUSTED_ORIGINS.

Проверьте также, что приложение и Termux используют один порт. По умолчанию это 7860. Если вы собрали приложение с другим портом, укажите такой же PORT в файле .env внутри Termux.

Android localhost открывает страницу входа или возвращает 401/503

Установки Termux под управлением APK защищают localhost закрытым секретом для каждой установки, а приложение входит автоматически. Если страница входа появляется внутри приложения, установите последнюю версию APK, снова нажмите Install / Start Marinara и вернитесь в приложение, когда Termux закончит.

Ошибка с источником null означает старую пару APK и сервера. Редактирование .env этого не исправит. Обновите APK и Marinara.

Чтобы открыть браузер на том же телефоне, нажмите Open in browser (открыть в браузере) на экране запуска Android, затем Retry connection (повторить подключение). Открывайте его так же после перезапуска сервера или истечения сеанса. Чтобы вернуться на экран запуска, используйте Settings → General → App Behavior → Open Android launcher (app or browser) (настройки → общие → поведение приложения → открыть экран запуска Android: приложение или браузер).

В старых APK вход выполняется на /android-login со значением из cat ~/.marinara-engine/android-secret. Ссылка для браузера работает один раз и истекает через минуту, поэтому открывайте новую с экрана запуска.

• 401: вставленный секрет или запрос аутентификации отклонен. Перезагрузите /android-login и вставьте текущее значение.
• 503: сервер получил секрет в неправильном формате. Перезапустите через ./start-termux.sh. Если скрипт запуска сообщает, что файл секрета неправильный или пустой, нажмите Install / Start Marinara в приложении, чтобы создать его снова.

Локальная команда mari автоматически читает тот же файл. Не помещайте секрет на снимки экрана и в отчеты о проблемах.

Обновление на Android останавливается с кодом 134

Android не хватило памяти на одном из шагов сборки. Снова запустите скрипт запуска:

./start-termux.sh

Если процесс снова останавливается, закройте другие приложения, откройте Termux заново и повторите попытку.

Termux закрывается или перезапускается во время работы Marinara

Пока сервер работает, скрипт запуска запрашивает блокировку сна и сохраняет каждую сессию в ~/.marinara-engine/logs/. После неожиданного перезапуска приложите к отчету самый новый файл server-*.log. Если он заканчивается без ошибки Marinara или Node, скорее всего, Termux завершил Android или производитель телефона.

В настройках Android разрешите Termux работать в фоне и отключите для него оптимизацию батареи. Команды termux-wake-lock и termux-wake-unlock входят в стандартный Termux. Эти настройки не могут предотвратить все фирменные остановки процессов.

Marinara перестает отвечать, пока Termux не выведен на передний план

Чаты зависают на "Opening chat...", приложение сообщает Server unreachable, в скопированном отчете Support Diagnostics в полях сервера стоит Unreachable (request timed out), и все восстанавливается, как только вы открываете Termux. Механизм заморозки кешированных приложений в Android приостановил процесс Termux. Телефон принимает соединение, но замороженный сервер на него так и не отвечает. Блокировка сна от этого не спасает. В журнале сессии вместо ошибки виден разрыв во временных метках на время заморозки.

Отключите для Termux оптимизацию батареи, разрешите фоновую активность, закрепите Termux в списке недавних приложений, если телефон это умеет, и не убирайте его уведомление. Если заморозки продолжаются, держите Termux на переднем плане или не давайте экрану гаснуть, пока пользуетесь Marinara.

При установке зависимостей на Android заканчивается место

Большой временный объем при обновлении обычно дает хранилище зависимостей pnpm после нескольких выпусков или прерванной переустановки. Текущий скрипт запуска вычищает старые пакеты, а обновления из приложения устанавливают только пакеты для Android. Если устройство заполнил старый скрипт запуска, освободите место и повторите попытку:

cd Marinara-Engine
git pull --ff-only
pnpm store prune
./start-termux.sh

Не удаляйте data, storage и marinara-engine.db: там могут лежать ваши чаты и настройки. Если процесс все равно останавливается, сохраните строки вывода начиная с Installing dependencies и приложите к отчету данные о свободном месте и памяти телефона.

Встроенное обновление не проходит при переключении Stable и Staging на Android

Смена канала вызывает почти полную переустановку зависимостей, а на хранилище Termux это медленно. Встроенный механизм обновления дает каждому шагу дополнительное время. Если обновление все же не проходит, ошибка называет сорвавшийся шаг и показывает конец его вывода. Настоящая ошибка зависимости или файла блокировки видна именно там. Можно также обновиться вручную из Termux командой из подсказки к ошибке или сначала освободить место:

cd Marinara-Engine
pnpm store prune
./start-termux.sh

Проблемы с Docker

Контейнер выдает permission denied на подключенном томе

• Именованный том после обновления: выполните docker compose pull && docker compose up -d. Официальный образ исправляет владельца при запуске.
• Монтирование папки хоста: откройте запись в эту папку для пользователя и группы с идентификатором 1000 или используйте именованный том.
• Системы с SELinux, такие как Fedora или RHEL: добавьте к точке монтирования тома суффикс :Z.

Контейнер lite падает на Raspberry Pi 4

Если образ lite перезапускается каждый раз, когда отправляет запрос к ИИ на Raspberry Pi 4 или похожем устройстве ARM, посмотрите код завершения. Код 132 или SIGILL (процессор наткнулся на инструкцию, которую не может выполнить) указывает на известную проблему исходного проекта в сборке Node для образа lite на некоторых чипах ARM. Используйте на таком устройстве обычный образ.

Server Extension сообщает, что нет поддерживаемой песочницы

Server Extensions и необработанные команды оболочки Professor Mari запускаются только с Seatbelt в macOS или Bubblewrap в Linux. На хосте Linux без контейнера установите bwrap и перезапустите Marinara. Официальный образ Docker содержит Bubblewrap, но стандартный контейнер не может создавать его вложенные пространства имен, поэтому Marinara держит эти функции выключенными.

Если вы принимаете более широкие права контейнера, сохраните следующее как docker-compose.override.yml рядом с docker-compose.yml, затем пересоздайте контейнер:

services:
  marinara:
    environment:
      MARINARA_DOCKER_USER: root
    cap_add:
      - SYS_ADMIN
    security_opt:
      - apparmor=unconfined

Предупреждение: запуск сервера от root с SYS_ADMIN и без профиля AppArmor – это широкое повышение прав. Не включайте его только ради того, чтобы убрать это сообщение.

Стандартный профиль seccomp в Docker подстраивается под добавленные возможности, поэтому в актуальных версиях Docker seccomp=unconfined не должен понадобиться.

Windows, Android и другие неподдерживаемые системы отклоняют запуск Server Extension. Browser Extensions продолжают работать в своей песочнице.

Проблемы с расширениями

В разделе Addons нет External Extensions

Раздел скрыт, пока не открыты оба барьера.

1. Задайте ENABLE_EXTERNAL_EXTENSIONS=true в файле .env на хосте.
2. Подождите немного, затем откройте Settings → Advanced → Danger Zone (настройки → дополнительно → опасная зона), прокрутите ниже элементов удаления данных и включите Allow third-party extension imports (разрешить импорт сторонних расширений).

Если переключатель неактивен, значит флаг на хосте все еще равен false или приложение еще не заметило изменение. Проверьте, что вы правили тот .env, который используется на самом деле, – он описан в руководстве Настройки сервера: справочник. В Docker это обычно /app/data/.env.

Пока закрыт хотя бы один барьер, записи внешних расширений не показываются и не запускаются. Повторное открытие барьеров не включает их снова.

Импортированное браузерное расширение появляется, но не работает

Откройте его в Settings → Addons → External Extensions и прочитайте Requested access (запрошенный доступ). Старые пакеты marinara.extension v1 без объявления возможностей показывают Full page access (полный доступ к странице). Подтверждайте только тот точный хеш, который вы проверили и которому доверяете.

Пакет, экспортированный заново с пустым списком возможностей, считается безопасным расширением в песочнице, и код, которому нужен DOM страницы, не заработает. Добавляйте full_page_access в его манифест, только если согласны, что код получит всю страницу, хранилище браузера, сетевые API и вашу сессию.

После выключения расширения с полным доступом к странице перезагрузите Marinara, если остался элемент панели инструментов, наложение или обработчик. Очистка выполняется по мере возможности, потому что код страницы может вызывать побочные эффекты, которые Marinara не отслеживает.

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

Сообщая об ошибке подключения, укажите режим, платформу, видимый текст ошибки и удалось ли получить одобрение. Не публикуйте приглашения, пароли комнат, токены сессий, частную историю или ключи API.

Не удается установить PWA в Chrome на Android при включенном входе

Используйте адрес HTTPS, войдите и перезагрузите страницу после обновления Marinara. Приложение запрашивает свой манифест с учетными данными, поэтому вход можно оставить включенным. Если установка все еще недоступна, проверьте, что прокси отдает /manifest.json как JSON, а не страницу входа или ошибку.

Как получить помощь

1. Откройте Settings → Advanced → Message Tools (настройки → дополнительно → инструменты сообщений) и включите Debug mode. Сервер записывает промпт и ответ в консоль сервера.
2. Запишите свою операционную систему, версию Node.js и полный текст ошибки из консоли.
3. Прежде чем чем-либо делиться, удалите ключи API, токены доступа, секреты администратора и содержимое личных чатов.

Затем обратитесь к сообществу:

• Прочитайте открытые issue.
• Присоединяйтесь к Discord.
• Создайте отчет об ошибке в тех же issue на GitHub и приложите подробности, собранные выше.

Смежные руководства

• Частые вопросы
• Настройки сервера: справочник
• Удаленный доступ
• Обновление приложения Marinara Engine
• Подключение к провайдеру ИИ
• Настройка встроенной модели
• Game Mode: начало работы
• Обзор настроек

Архивы исходников, которые генерирует GitHub, не гарантируют побайтовую стабильность, даже когда содержимое коммита не меняется. Никогда не "исправляйте" несовпадение у пользователя, принимая байты с его машины или ослабляя проверку. Перезакреплять входные файлы среды выполнения можно только изменением в Engine, прошедшим проверку:

1. Выберите неизменяемую ревизию или файл выпуска в исходном проекте и изучите изменения на его стороне.
2. Скачайте артефакт во временную папку, запишите его точный размер в байтах и независимо вычислите его хеш SHA-256.
3. Впишите ревизию, URL, размер и хеш в runtime-integrity-manifest.ts. Для MLX заново соберите packages/server/src/assets/mlx-runtime-requirements.lock из файла .in закрепленной версией uv на Apple Silicon и Python 3.12, проверьте каждое изменение зависимостей и обновите requirementsLockSha256.
4. Выполните pnpm regression:runtime-integrity и pnpm check, а затем настоящую чистую установку среды выполнения на затронутой платформе.
5. Выпустите проверенное обновление Engine и только потом просите пользователей повторить попытку. Не добавляйте ручное переопределение контрольной суммы.