Устранение неполадок Moonpool: трей, приложения, которые не запускаются, обновления

Найдите свой симптом и выполните исправление. Текст в кавычках - это то, что показывает Moonpool. Чтобы найти точное сообщение, см. Сообщения об ошибках.

Я не вижу значок в трее

• Windows. Значок может находиться в области скрытых значков. Нажмите стрелку ^ в правой части панели задач. Перетащите значок на панель задач, чтобы он оставался видимым.
• Linux в стандартном GNOME. GNOME не показывает значки в трее без расширения AppIndicator. См. Linux.
• Настройки. Параметр Показывать в трее может быть выключен. Откройте главное окно с панели задач или из меню «Пуск» и включите его обратно в настройках.

Установщик показывает ошибку

Сообщение	Что делать
Install failed: <error>	Текст после двоеточия называет шаг, на котором произошёл сбой, например copy exe: .... Если файл занят, завершите любой Moonpool, запущенный из %USERPROFILE%\.moonpool, и повторите попытку.
target folder does not exist	Папка, выбранная для портативной копии, исчезла. Выберите существующую папку.
that folder already has a .moonpool with an exe of this name that isn't a portable Moonpool - pick an empty folder	Выберите пустую папку или сначала удалите эту папку .moonpool.

При запуске установщика появляется «Windows protected your PC»

Это Windows SmartScreen, потому что moonpool.exe не имеет цифровой подписи. Нажмите More info («Подробнее»), затем Run anyway («Выполнить в любом случае»). См. Windows защитила ваш компьютер.

Окно Moonpool пустое или не открывается в Windows

Возможно, отсутствует Microsoft Edge WebView2 Runtime. См. Отсутствует среда WebView2.

Приложение не запускается

1. Щёлкните по названию приложения, чтобы открыть вкладку его терминала и прочитать вывод. Агент может прочитать тот же текст с помощью moonpool_app_output.
2. Проверьте cwd. Обычная причина - отсутствующая папка или относительный путь без ./. См. Пути и окружение.
3. Проверьте command. Выполните её вручную в терминале в каталоге cwd. В Windows избегайте вложенных двойных кавычек; cmd /c их искажает.
4. Включите Записывать отладочные данные в файл в настройках и запустите снова. moonpool.log записывает точную команду и папку. См. Журналы.

Сообщение	Значение
already running	У Moonpool уже есть терминал для этого приложения. Сначала остановите его или воспользуйтесь перезапуском.
stopped during launch	Остановка была нажата, пока запуск ещё выполнялся.
did not reach running in time	Из скрипта или агента: приложение не перешло в состояние «работает» за 25 секунд. Проверьте его port или processName и его вывод.

Неверный индикатор состояния

Moonpool определяет состояние «работает» по port, затем по processName, затем по тому, жив ли его собственный терминал. См. Как определяется состояние «работает».

• Никогда не становится сплошным. port приложения web не отвечает или processName приложения desktop не совпадает. В Linux processName должно содержать не более 15 символов.
• Становится серым сразу после запуска. Приложение cli перестаёт считаться работающим, когда завершается его команда. Используйте оболочку с -NoExit, если хотите, чтобы она оставалась открытой.
• Приложение static никогда не показывается работающим. Для записи только с url это ожидаемо.
• Показывается работающим, хотя вы его не запускали. Этот порт или имя процесса использует что-то другое. Moonpool показывает его как работающее, но не «управляемое Moonpool».

Error: listen EADDRINUSE или «Port 5173 is in use»

Что-то другое уже слушает порт, который нужен вашему серверу. Найдите это и завершите либо задайте port у приложения, чтобы остановка его освобождала. См. Исправление EADDRINUSE и «Port 5173 is in use» и Поиск и завершение процесса, занимающего порт.

Два приложения используют один порт

В нижней части меню … появляется строка с предупреждением, например порт 3000: App A / App B. Измените port одного из приложений (и его env, если оно читает PORT). См. Предупреждение о конфликте портов.

Приложение продолжает работать после остановки

Из скрипта или агента ошибка выглядит как still running after stop (через 15 секунд).

• Приложение переживает свой терминал. Задайте killMode равным port или processName. См. Остановка и перезапуск.
• Приложение Docker в Windows: используйте killMode со значением command и stopCommand, например docker compose stop app. Но не port.

В apps.json ошибка

Боковая панель показывает баннер «В apps.json ошибка, показан последний загруженный список» или, при запуске, «В apps.json ошибка, поэтому приложения не загружены.» Сохранение из Moonpool приостановлено, пока файл снова не загрузится.

Типичные ошибки:

apps.json entry 2 (site) requires a command
apps.json entry 3 has invalid id "my app"; use letters, digits, '.', '_', and '-' without a leading '-'
duplicate app id "site"
apps.json entry 4 (api) has invalid port 0

1. Выберите Изменить apps.json в баннере, исправьте запись, сохраните, затем нажмите Обновить (F5).
2. Или вернитесь к недавней исправной копии. См. Резервное копирование и восстановление.

Полный список правил приведён в разделе Проверка.

Если настройку нельзя изменить, а сообщение заканчивается словами Repair settings.json and restart Moonpool before changing settings, исправьте или удалите settings.json в папке конфигурации и снова запустите Moonpool. Удаление сбрасывает все настройки к значениям по умолчанию.

Моя правка не вступила в силу

• Правки вручную требуют Обновить (или F5). Moonpool не следит за файлом.
• Обновление не перезапускает работающие приложения. Перезапустите приложение, чтобы применить изменённые command, cwd или env.
• Агент может править другой apps.json. Попросите его вызвать moonpool_launcher_paths и сравните папку хаба с его собственной. Если у вас несколько копий Moonpool, проверьте, какую из них вы редактируете.

Пропали примеры приложений

Примеры записываются, только когда apps.json не существует. Чтобы вернуть их, см. Сброс к примерам или скопируйте записи из раздела Примеры дашбордов.

Не удалось обновить

Баннер показывает Update failed: <error>. См. Если обновление не удалось.

Веб-ссылка не открывается

refusing to open non-web url: <url> означает, что url не начинается с http://, https://, mailto: или file://. Исправьте url.

Ошибки MCP и скриптов

Сообщение	Что делать
Moonpool is not running - call moonpool_bootup_launcher first	Запустите Moonpool или позвольте агенту вызвать moonpool_bootup_launcher.
frontend not loaded	Главное окно ещё не завершило загрузку. Подождите немного и повторите.
stale token: ...	apps.json изменился после того, как агент его прочитал. Прочитайте его снова, затем запишите.
rejected invalid manifest: ...	Новый apps.json не прошёл проверку. Файл не был изменён.
... A Moonpool process may be hung ...	Что-то удерживает канал управления и не отвечает. Завершите Moonpool из трея или завершите процесс и запустите его снова.

Подробнее в разделах Настройка MCP и Инструменты MCP.

Проблемы с окном

• За пределами экрана. Moonpool игнорирует сохранённое положение, которое не попадает ни на один подключённый дисплей. Если окно всё равно потеряно, завершите Moonpool и удалите window-state.json в папке конфигурации.
• Масштаб слишком крупный или слишком мелкий. Его меняет Ctrl + колесо мыши над главным окном. См. Сочетания клавиш и масштаб.
• Настройки открываются позади главного окна. Выключите и снова включите Поверх всех окон в настройках. Параметр применяется ко всем окнам Moonpool, так что они остаются в одном слое.

Где журналы?

См. Журналы.

Резервная копия, сброс или удаление

См. Резервное копирование и восстановление и Удаление.

FAQ

Останавливает ли закрытие окна мои приложения? По умолчанию закрытие завершает работу Moonpool, а в Windows завершение работы останавливает запущенные им приложения. Включите Закрывать в трей, чтобы Moonpool продолжал работать после закрытия окна. См. Трей, закрытие и сворачивание.

Можно ли запустить Moonpool дважды? По одной копии на папку. Повторный запуск той же копии возвращает её окно. Установленная и портативные копии могут работать параллельно. См. Портативный режим.

Обращается ли Moonpool к серверам без моего ведома? Только для проверки обновлений: он получает файл выпуска (update.json) с GitHub при запуске (если включён параметр Проверять обновления при запуске) и когда вы нажимаете Проверить обновления. Каждая загрузка проверяется по ключу подписи Moonpool перед использованием.

Какая оболочка выполняет мои команды? cmd /c в Windows, $SHELL -c в Linux.

Где хранить секреты? Значения env хранятся в apps.json открытым текстом. Лучше использовать файл, который читает само приложение, или переменную, уже заданную в окружении вашего пользователя, которую наследуют запущенные приложения.

Защищён ли канал управления? В нём нет ни входа, ни токена. Любой процесс, запущенный от вашего имени, может отправлять ему команды. В Linux сокет доступен для чтения только вашему пользователю. См. Свойства безопасности.