Перейти к основному содержимому

Интерфейс не запускается

Что это​

Команда uv run raytsystem ui поднимает локальный веб-интерфейс raytsystem только на петле 127.0.0.1. Перед запуском сервера она делает три проверки и, если любая не проходит, выходит с кодом 2 и печатает причину в поток ошибок. Эта страница разбирает типовые причины по порядку, в котором их проверяет сама команда.

Симптом​

Одно из:

  • команда raytsystem ui завершается сразу с ненулевым кодом и сообщением об ошибке;
  • команда не стартует при указании нестандартного хоста;
  • сервер поднимается, но браузер не открывает страницу или показывает пустое окно.

Вероятная причина и безопасная диагностика​

1. Указан удалённый хост​

Если передать --host, отличный от 127.0.0.1, команда откажется стартовать: Refusing remote bind: v1 supports only 127.0.0.1. Это защита: в v1 интерфейс работает только на локальной петле.

Решение: запускайте без --host (значение по умолчанию — 127.0.0.1) или явно --host 127.0.0.1.

2. Не собран веб-бандл​

Команда проверяет наличие собранного index.html в каталоге статики. Если файла нет, она печатает Web bundle is missing. Run the documented frontend build. и выходит с кодом 2. Обычно так бывает после свежего клонирования репозитория без сборки фронтенда.

Решение: соберите фронтенд документированной командой сборки, затем повторите запуск. См. Установка.

3. Недоступен проверенный снимок рабочего пространства​

Перед запуском команда запрашивает проверенный снимок состояния. Если он не проходит проверку целостности, вы увидите Verified workspace snapshot is unavailable. и код выхода 2.

Безопасная диагностика — запустить общий отчёт, он не меняет состояние:

uv run raytsystem doctor
uv run raytsystem status

Если doctor показывает false в проверках указателей (ledger_pointer_exists, generation_exists), сначала разберитесь с ними на странице doctor сообщает ошибку.

4. Порт занят​

По умолчанию сервер слушает порт 8765. Если порт занят другим процессом, uvicorn не сможет привязаться.

Решение: укажите другой порт в диапазоне 1024–65535:

uv run raytsystem ui --port 8766

5. Браузер не открылся, но сервер работает​

По умолчанию команда пытается открыть браузер сама. Если этого не произошло, откройте вручную адрес, который она печатает в строке raytsystem: http://127.0.0.1:<порт>. Можно запускать без автозапуска браузера флагом --no-open.

Пример​

# Запуск на свободном порту без автозапуска браузера
uv run raytsystem ui --port 8766 --no-open

Ожидаемый результат​

В консоли появляется строка raytsystem: http://127.0.0.1:<порт>, а страница открывается в браузере. Интерфейс отдаётся тем же источником (same-origin) и только с локальной петли.

Ограничения и безопасность​

  • Интерфейс v1 работает только на 127.0.0.1; удалённый bind запрещён кодом.
  • Запросы GET/HEAD ничего не пишут; в браузере нельзя задать команду, каталог запуска или окружение.
  • Команда не запускает моделей и не ходит во внешние сети.

Частые ошибки​

  • Пытаться открыть интерфейс до сборки фронтенда — будет Web bundle is missing.
  • Пытаться привязать сервер к внешнему адресу.

Когда открыть issue​

Если бандл собран, doctor здоров, порт свободен, но raytsystem ui всё равно падает с ошибкой снимка или неожиданным исключением, приложите к issue вывод raytsystem doctor и точный текст ошибки из потока stderr.

Связанные страницы​

Источники истины​

  • src/raytsystem/cli.py