Настройки сервера: справочник

В этом руководстве перечислены настройки сервера, которые можно менять через переменные окружения. Переменные окружения – это настройки, которые сервер читает из обычного текстового файла с именем .env. Приложение Marinara Engine работает и без настройки. Большинству она нужна, только чтобы открыть доступ другим устройствам, защитить общий сервер, перенести папку данных, повысить подробность журнала или дать медленным задачам больше времени.

Аккаунты ИИ, персонажи и параметры чатов настраиваются в самом приложении. О добавлении аккаунта ИИ читайте в руководстве Подключение к провайдеру ИИ.

Редактирование файла .env

Marinara создает пустой файл .env при первом запуске. Каждая строка имеет вид KEY=value. Строки, начинающиеся с #, – это комментарии.

1. Откройте .env.example в той же папке. В нем перечислены все настройки со значениями по умолчанию.
2. Скопируйте нужную строку в .env.
3. Измените значение после = и сохраните файл.

PORT=8080
BASIC_AUTH_USER=alice
BASIC_AUTH_PASS=correct-horse-battery-staple

Файл .env – это данные, а не сценарий оболочки. Marinara не выполняет $, $(...) и другой синтаксис оболочки внутри значения. Значение, уже заданное в окружении скрипта запуска, имеет приоритет над такой же строкой в .env.

Сервер читает .env при любом способе запуска. Скрипты запуска (start.bat, start.sh, start-termux.sh) вдобавок задают HOST=0.0.0.0, чтобы могли подключаться другие устройства, и открывают браузер, когда сервер готов. AUTO_OPEN_BROWSER=false отключает это. При запуске просто через pnpm start сервер слушает только этот компьютер, пока вы не зададите HOST.

Перезапуск или применение на ходу

Marinara следит за файлом .env во время работы. Большинство настроек применяется почти сразу, без перезапуска. Для каждого изменения в журнале появляется строка [env-watcher]. Если слежение не удается запустить, сервер проверяет файл раз в 30 секунд и сообщает об этом в журнале.

Если правки не подхватываются, например когда вы правите файл с другой машины или в примонтированной папке контейнера (bind mount), задайте MARINARA_ENV_WATCH=poll. Чтобы отключить слежение, задайте MARINARA_ENV_WATCH=0. Оба варианта рассчитаны на опытных пользователей.

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

• PORT, HOST, SSL_CERT и SSL_KEY
• DATA_DIR, FILE_STORAGE_DIR, ENCRYPTION_KEY и MARINARA_EAGER_STORAGE
• MARINARA_ENV_FILE, MARINARA_ENV_WATCH и TZ
• AUTO_OPEN_BROWSER и AUTO_CREATE_DEFAULT_CONNECTION
• LOG_DISABLE_REQUEST_LOGGING и LOG_FORMAT
• STORAGE_CACHE_WINDOWS_BOOT_ID, SHUTDOWN_WINDOWS_CONSOLE_SIGNALS и SHUTDOWN_FORCE_EXIT_ON_REPEAT
• Тайм-ауты и настройки опроса для изображений, видео, спрайтов и ComfyUI: IMAGE_GEN_TIMEOUT_MS, IMAGE_GEN_MAX_RESPONSE_BYTES, VIDEO_GEN_TIMEOUT_MS, VIDEO_GEN_MAX_RESPONSE_BYTES, SPRITE_GENERATION_TIMEOUT_MS, SPRITE_ANIMATED_FFMPEG_TIMEOUT_MS, COMFYUI_GEN_TIMEOUT и четыре настройки *_VIDEO_POLL_INTERVAL_MS

Скрипты запуска читают AUTO_UPDATE_ENABLED до старта сервера, поэтому изменение применяется со следующего запуска, и журнал о нем не предупреждает.

Настройкам управления доступом и секретам (BASIC_AUTH_USER, BASIC_AUTH_PASS, IP_ALLOWLIST, ADMIN_SECRET, CSRF_TRUSTED_ORIGINS) перезапуск не нужен.

Управление доступом

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

Вход можно задать и без .env: через Settings → Advanced → Access (настройки → дополнительно → доступ) в браузере, где вы уже вошли, или с помощью одноразового кода настройки из журнала сервера. Сервер печатает этот код, только пока вход не задан и сервер слушает не только loopback. Вход сохраняется в DATA_DIR/.remote-login.json. Команда node scripts/reset-login.mjs (запускайте ее в папке Marinara) удаляет его и выводит из системы все браузеры. Вход из .env имеет приоритет. Чтобы изменить или убрать вход, нужен текущий пароль. О прокси со входом читайте в разделе Прокси со входом (forward auth).

Термины, которые используются ниже:

• Loopback – компьютер, на котором работает сервер, по адресу 127.0.0.1 или localhost.
• Диапазон CIDR – короткая запись блока IP-адресов, например 192.168.1.0/24.
• Basic Auth – имя пользователя и пароль, которые отправляются с каждым запросом. Их используют скрипты и клиенты API, а браузеры используют страницу /login. Эти данные только кодируются, но не шифруются, поэтому на публичном сервере используйте HTTPS.

Пока вход не задан, сервер принимает подключения только из доверенных источников: loopback, адресов из IP_ALLOWLIST, сети Tailscale и трафика моста Docker с того же хоста. Все остальные, включая вашу домашнюю сеть, получают ответ 403 Forbidden. Чтобы другие устройства вообще могли подключиться, сервер должен слушать доступный адрес: задайте HOST=0.0.0.0.

Предупреждение: широкий публичный диапазон в IP_ALLOWLIST, например 0.0.0.0/0, может впустить клиентов из интернета без входа. Указывайте только адреса, которым доверяете.

Хранение данных

Сгенерируйте ключ шифрования и вставьте его в ENCRYPTION_KEY:

openssl rand -hex 32

Marinara хранит ваши данные в обычных файлах JSON, поэтому резервные копии можно копировать и читать. О том, что лежит в каждой папке, читайте в руководстве Где Marinara хранит ваши данные.

Уровни логирования

LOG_LEVEL задает, насколько подробно пишет сервер. Все, что ниже выбранного уровня, скрывается.

В терминале сервер печатает удобочитаемые строки. В других местах, например в журналах Docker, сервер в режиме production печатает строки JSON. Скрипт запуска Termux запрашивает удобочитаемые строки. Логирование в браузере работает отдельно, и LOG_LEVEL им не управляет.

Тайм-ауты

Тайм-аут – это максимальное время, которое сервер ждет медленную задачу. Откройте Settings → Advanced → Request timeouts (тайм-ауты запросов), чтобы задать в секундах лимиты для текста, агентов, промптов изображений Game, изображений, видео, ComfyUI и эмбеддингов. Более высокие лимиты помогают медленным локальным бэкендам. Они не отменяют ограничение, которое устанавливает сам сервис. Для сохранения нужен доступ администратора сервера.

Эти настройки действуют для всех профилей и сохраняются рядом с активным .env в файле .env.timeouts.json (или <custom-env-path>.timeouts.json). Они имеют приоритет над соответствующими переменными, не меняя .env. Изменения для текста, агентов, промптов изображений Game и эмбеддингов применяются к новым запросам. Изменениям для медиа и установленным пакетам агентов нужен перезапуск. Чтобы вернуться к переменным, удалите этот файл и перезапустите сервер.

Значения указаны в миллисекундах, если в названии не сказано иначе. Недопустимые, нулевые, отрицательные или выходящие за диапазон значения для проверяемых тайм-аутов чата, агентов и промптов изображений Game вызывают предупреждение в журнале, и берется значение по умолчанию. О задачах видео читайте в руководстве Генерация видео сцены.

Особые действия по API (ADMIN_SECRET)

Разрушительным или рискованным действиям, таким как резервные копии, очистка данных, применение обновлений и установка тем оформления, нужен дополнительный секрет вдобавок к обычным проверкам доступа. Его можно создать в Settings → Advanced → Admin Access (доступ администратора) на компьютере, где работает сервер (см. раздел Admin Access), или задать на сервере длинное случайное значение:

ADMIN_SECRET=replace-this-with-a-long-random-secret

На компьютере, где работает сервер, такие действия обычно проходят и без секрета. Запрос, который пересылает прокси или туннель на этом компьютере, считается удаленным, если не задано REQUIRE_AUTH_FOR_LOOPBACK_PROXY=false. Прямым запросам с другого устройства секрет нужен. Вставьте то же значение в Settings → Advanced → Admin Access, и приложение будет отправлять его само. ADMIN_SECRET в .env имеет приоритет над секретом, созданным в приложении. Если секрета администратора нет, особые действия не выполняются ни с одного устройства, кроме компьютера сервера, а сообщение об ошибке предлагает задать секрет. Установленные агенты работают с любого устройства, на котором выполнен вход; для их установки, обновления и удаления нужен секрет.

Разрешения для локальных адресов

По умолчанию исходящие запросы к сервисам ИИ, сервисам изображений и вебхукам не обращаются к частным или локальным адресам. Это защищает от SSRF (подделки запроса на стороне сервера), когда запрос обманом направляют на внутренний адрес. Серверы моделей на loopback продолжают работать. Включайте только тот переключатель, который нужен для вашего сервиса на другой машине в частной сети.

О подключении локальной модели или модели на своем сервере читайте в руководстве Подключение локальной модели или модели на своем сервере.

Переключатели функций

Необязательные функции сервера, например повтор неудачных вызовов провайдера или стабильный выбор групп лорбука, находятся в Settings → Advanced → Features (функции). По умолчанию все выключены. У некоторых есть переменная, которая, если задана, имеет приоритет над переключателем. См. Переключатели функций.

Уведомления Marinara

Уведомления – это короткие предупреждения от мейнтейнеров, например о проблеме безопасности или о ручном шаге, который нужен вашей версии. Они показываются в виде баннера.

• При запуске, а потом каждый час сервер скачивает один небольшой файл, notices.json, из ветки notices репозитория Marinara Engine. Он оставляет только уведомления, в которых указана ваша версия. Браузер запрашивает их у вашего собственного сервера один раз при загрузке страницы, а потом каждый час.
• Если скачивание не удалось, сервер сохраняет уже полученные уведомления, и запуск не задерживается.
• Запрос не отправляет никаких данных о вас, ваших чатах или настройках. Менять ветку notices могут только мейнтейнеры, и каждое изменение проходит ревью.
• Уведомление – это простой текст с ограничением размера. Ссылки сохраняются, только если ведут на https://github.com/Pasta-Devs/. Уведомление не может ничего установить, запустить или изменить.
• Уведомления видите только вы: на компьютере сервера, с адреса из IP_ALLOWLIST или после входа. Остальные посетители получают пустой список.

Чтобы отключить уведомления, задайте MARINARA_NOTICES_ENABLED=false.

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

Форки могут указать в MARINARA_NOTICES_URL свой файл.

Необязательный многопользовательский режим

Многопользовательский режим по умолчанию выключен. Он позволяет людям вместе пользоваться частной комнатой Conversation, Roleplay или Game без фиксированного ограничения на число участников. Каждый гость использует собственную доверенную установку Marinara. Гостям не нужен аккаунт ИИ. Аккаунты ИИ предоставляет хост, и он может читать и сохранять общее содержимое. Пока хотя бы одно из двух разрешений выключено, Marinara не выполняет фоновых проверок сессий, сертификатов и участников.

1. Задайте MULTIPLAYER_ENABLED=true в .env каждой участвующей установки Marinara и перезапустите ее. Работает только точное значение true, и применение на ходу его не подхватывает.
2. Откройте Settings → Advanced → Multiplayer (многопользовательский режим), прочитайте предупреждение и включите настройку. Это не запускает прослушивание порта и не подключает к комнате.
3. Чтобы стать хостом, используйте Create shared session (создать общую сессию) или Play together (играть вместе) при выборе режима или в процессе настройки. Проверьте настройки, свое отображаемое имя и текст персоны, которым вы делитесь. Существующий чат передает только выбранные настройки, но никогда не историю сообщений, заметки или воспоминания.
4. На хосте задайте SSL_CERT и SSL_KEY для сертификата, который действителен для имени хоста комнаты и которому доверяют гости. Выберите отдельные HTTPS-адрес и порт комнаты, например https://room.example.org:7861. Этот порт открывает действие Host. Пропускайте через брандмауэр или роутер только порт комнаты. Не открывайте наружу обычный API Marinara. Проброс портов, ретранслятор и обход сертификатов за вас не настраиваются.
5. Задайте пароль комнаты длиной не менее 12 символов, отличный от ваших учетных данных администратора. Отправьте временное приглашение и пароль по отдельности людям, которым доверяете. Гость проверяет отпечаток имени хоста, имя комнаты и текст персоны, а затем запрашивает вход. Хост одобряет каждый запрос в Players (игроки) до отправки какой-либо истории.

Ограничения и поведение:

• Перед отправкой пароля TLS проверяет цепочку сертификата и имя хоста, а также отпечаток сертификата из приглашения. Самоподписанные сертификаты молча не принимаются. Обновленному сертификату нужно новое приглашение.
• Приглашения истекают через 30 минут. Допущенные сессии длятся не более 12 часов. Замена или отзыв прекращает действие неиспользованных приглашений. Kick (исключить) удаляет допущенного гостя.
• Хост управляет автоматическими или ручными ответами, а также Pause/Resume (приостановить и продолжить) и Stop (остановить). По умолчанию доступно 100 координированных ходов генерации за сессию размещения. Групповой ход или настройка Game может вызвать модель больше одного раза. Это лимит ходов, а не оценка стоимости.
• В Game проверьте отряд перед Start Game (начать игру). Каждый обязательный игрок отправляет действие или пропускает ход, а GM разрешает их, когда все готовы. Отключившийся игрок остается обязательным, пока не вернется или пока хост не пропустит его ход либо не удалит его. Приостановленные или прерванные раунды никогда сами не повторяют платный запрос или уже примененные изменения мира.
• Stop, Leave (уйти), выключение настройки и перезапуск сервера завершают активную сессию. После перезапуска сервер никогда сам не размещает комнату и не подключается к ней.
• Свои инструменты, инструменты пакетов и небезопасные команды в комнатах недоступны. Гости никогда не запускают планировщик и не выполняют локальные команды из полученного текста. Расписания Conversation используют планировщик хоста.
• Новые игроки и изменения персон вступают в силу со следующего раунда.
• Комнаты передают только текст ограниченного размера. Файлы, медиа, расширения и пакеты не передаются. Нативная оболочка Android не может подключаться.

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

Точные ограничения и проверенные платформы описаны в записи о совместимости и проверках. О проблемах читайте в руководстве Устранение неполадок.

Агенты и расширения

Дополнительные официальные агенты устанавливаются в приложении: Agents → Agent Organizer (агенты → организатор агентов). Marinara сама выбирает каталог Pasta-Devs/Marinara-Agents, который соответствует ее основной версии.

• Обновления: Marinara спрашивает, прежде чем скачать новую версию установленного пакета. Not now (не сейчас) оставляет текущую версию, а Update (обновить) остается в Agent Organizer. После свежей установки пакетов нет.
• Где лежат пакеты: DATA_DIR/capability-packages. Тома Docker, свои папки данных, резервные копии и обычные обновления их сохраняют. Это относится к компьютеру, Docker и Termux. iOS и другие браузеры используют пакеты со своего сервера.
• Место на диске: Marinara хранит текущую и предыдущую версии каждого пакета, а более старые версии и временные копии в DATA_DIR/capability-runtime-snapshots удаляет. Данные пакетов никогда не удаляются.
• Без сети: Установленные пакеты продолжают работать в своей версии, если GitHub недоступен, обновление отклонено или проверка не прошла.

Импорт своих агентов

Внешние файлы агентов, папки и репозитории заблокированы. Чтобы разрешить их, включите Allow custom Agent imports (разрешить импорт своих агентов) в Settings → Advanced → Danger Zone (опасная зона). Переменная окружения для этого не нужна. Пока вы этого не сделаете, элементы импорта остаются серыми.

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

Свои репозитории агентов

Репозитории по умолчанию выключены, потому что их промпты и инструменты не проверены. Задайте ENABLE_CUSTOM_AGENT_REPOS=true, включите Allow custom Agent imports, затем откройте Agents → Agent Organizer → Custom Sources (свои источники), чтобы посмотреть публичный репозиторий GitHub. И добавление источника, и применение последующих изменений требуют подтверждения. Синхронизация только ручная: Marinara никогда не клонирует и не опрашивает репозитории в фоне. Принимаются только URL корня репозитория GitHub.

Репозиторий публикует агентов, наборы правил Game Mode или и то и другое. В корне репозитория:

• agents.json – это массив в формате загружаемых агентов:

  [
    {
      "id": "continuity-helper",
      "name": "Continuity Helper",
      "description": "Checks recent turns for contradictions.",
      "phase": "post_processing",
      "enabledByDefault": false,
      "category": "writer",
      "defaultPromptTemplate": "Check {{messages}} for continuity errors."
    }
  ]

• rulesets содержит по одному набору правил в каждом файле .json, всего до 32 файлов размером до 512 KB. Читаются только файлы, лежащие прямо в этой папке. Предпросмотр показывает имя, версию и охват каждого набора правил. Текст набора правил для Game Master отправляется модели в каждой игре, которая его использует, поэтому устанавливайте наборы правил только от тех, кому доверяете.

Имена импортированных наборов правил строятся от владельца репозитория, например alice/my-5e, поэтому они никогда не займут имя официального набора. Сохраняется каждая версия, и игра идет на той версии, с которой началась. Если та же версия приходит с другим содержимым, Marinara оставляет установленную и предлагает попросить автора повысить номер версии. Файл, который Marinara не может прочитать, показывается в списке с причиной и пропускается.

При синхронизации промпты, настройки и инструменты из репозитория заменяют управляемые репозиторием значения, показанные в предпросмотре. Ваш выбор аккаунта и изображений остается локальным. Если агент исчезает из источника, он остается обычным локальным агентом и теряет только связь с репозиторием. Удаление источника работает так же, а его наборы правил остаются установленными.

Свои агенты также могут включить Previous output (предыдущий результат) в разделе Context Sources, чтобы читать свой последний успешный результат. При включенном JSON context output (вывод контекста в JSON) возвращайте {"text":"main prompt content","agent-context":"private continuation context"}. В основной промпт попадает только text. Hide output as spoilers (скрывать результаты как спойлеры) оставляет сохраненные результаты свернутыми. При повторной генерации заменяемый ход исключается, а удаленные сообщения и неактивные свайпы не могут передавать контекст.

Внешние расширения

Импорт сторонних расширений требует двух разрешений. Переменная окружения – это разрешение от того, кто держит сервер. Переключатель в Danger Zone – согласие пользователя.

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

После этого раздел External Extensions (внешние расширения) появится в Settings → Addons (дополнения). Закрытие любого из разрешений отключает записи внешних расширений и останавливает их код. Записи, добавленные вручную, старые, импортированные из профиля и с неизвестным источником считаются внешними, поэтому разрешения нельзя обойти, просто положив файлы в папку. Черновикам от Professor Mari не нужно ни одно из разрешений. Они создаются выключенными, и их точный хеш кода требует одобрения.

По умолчанию используется режим Sandboxed Browser Extensions. Некоторые старые пакеты показывают Full page access (полный доступ к странице), потому что им нужна страница Marinara. В этом режиме одобренный код выполняется прямо на странице Marinara и получает доступ к содержимому страницы, хранилищу браузера, сетевым интерфейсам и вашей сессии. Режим доступен только для External Extensions, когда открыты оба разрешения, и требует отдельного подтверждения предупреждения. После отключения режима перезагрузите страницу.

Полный справочник переменных окружения

Таблицы выше описывают управление доступом, хранение данных, логирование, тайм-ауты, особые действия и разрешения для локальных адресов. Остальные переменные собраны здесь.

Сервер и запуск

По умолчанию Schedule timezone берет часовой пояс вашего устройства. Изменить его можно при настройке Conversation, в Chat Settings режима Conversation или в редакторе расписания персонажа. Это одна общая настройка для всех чатов Conversation, и она синхронизируется с другими клиентами на том же сервере.

Медиа и работа со спрайтами

Провайдеры видео сцены

Аккаунты для видео настраиваются в приложении. Эти настройки лишь подстраивают задачи. Значения указаны в миллисекундах.

Лорбуки

Обе настройки по умолчанию выключены и действуют со следующей генерации после изменения .env. Если LOREBOOK_STABLE_GROUP_WINNERS задана, она имеет приоритет над переключателем Stable lorebook picks (стабильный выбор лорбука) в Settings → Advanced → Features. Иначе решает переключатель. См. Переключатели функций.

scripts/compact-lorebook-scans.mjs применяет то же правило к старым чатам. Сначала остановите сервер. Без --apply выполняется только пробный проход, а перед записью скрипт делает резервные копии обеих таблиц сообщений.

Устойчивость

Все настройки по умолчанию выключены, что сохраняет прежнее поведение. STORAGE_CACHE_WINDOWS_BOOT_ID, SHUTDOWN_WINDOWS_CONSOLE_SIGNALS и SHUTDOWN_FORCE_EXIT_ON_REPEAT требуют перезапуска. Остальные применяются после изменения .env. Если PROVIDER_RETRY_TRANSIENT_ERRORS задана, она имеет приоритет над переключателем Retry failed provider calls (повторять неудачные вызовы провайдера) в Settings → Advanced → Features. Иначе решает переключатель.

Интеграции и прочее

О Built-in model читайте в руководстве Настройка встроенной модели.

Исходящий HTTP-прокси

В некоторых сетях выход в интернет возможен только через HTTP-прокси, например v2rayN без режима TUN. Marinara может отправлять через него запросы к сервисам ИИ, сервисам изображений, серверам эмбеддингов и каталогу агентов. Задайте эти переменные в окружении, из которого запускается Marinara, или в .env, затем перезапустите ее.

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

• Переключатели функций
• Удаленный доступ: вход и список разрешенных адресов
• Где Marinara хранит ваши данные
• Подключение к провайдеру ИИ
• Генерация видео сцены
• Устранение неполадок в приложении Marinara Engine