Skip to main content

​
Зачем это нужно

  • Только один процесс Gateway должен владеть каталогом состояния; дополнительные процессы Gateway следует запускать с изолированными профилями, каталогами состояния, конфигурациями и портами.
  • Продолжать работу после сбоев/SIGKILL, не оставляя устаревших файлов блокировки.
  • Немедленно завершать работу с понятной ошибкой, если порт уже занят другим процессом Gateway.

​
Три уровня

При запуске владение проверяется в три этапа в следующем порядке:
  1. Блокировка владения состоянием захватывает блокировку, привязанную к каноническому каталогу состояния. В ней участвуют все процессы Gateway, включая запущенные с OPENCLAW_ALLOW_MULTI_GATEWAY=1, поэтому деструктивное обслуживание SQLite не может выполняться одновременно с активным владельцем.
  2. Блокировка конфигурации захватывает историческую блокировку для каждой конфигурации и записывает порт среды выполнения. В режиме нескольких процессов Gateway эта блокировка единственного экземпляра конфигурации пропускается, но блокировка владения состоянием сохраняется.
  3. Привязка сокета привязывает обработчик HTTP/WebSocket (по умолчанию ws://127.0.0.1:18789) как эксклюзивный TCP-обработчик.
Каждый уровень может завершиться ошибкой независимо и генерирует собственное исключение GatewayLockError.

​
Блокировки состояния и конфигурации

  • Актуальность блокировки определяется записанным PID, идентификатором запуска процесса на платформе, если он доступен, и идентификатором процесса Gateway. Проверенный владелец остаётся полномочным во время запуска ещё до того, как его порт начнёт принимать подключения.
  • Специализированный координатор SQLite последовательно выполняет проверку метаданных, освобождение блокировки устаревшего владельца и замену блокировки. Его эксклюзивная транзакция автоматически освобождается при сбое владеющего процесса.
  • Если файл блокировки отсутствует или записанный процесс-владелец завершён, при запуске блокировка освобождается и процесс продолжает работу.
  • Если любая из блокировок активно удерживается, при запуске попытки повторяются до 5 секунд (по умолчанию), после чего процесс прекращает работу:

​
Привязка сокета

  • При EADDRINUSE во время запуска выполняется до 20 повторных попыток привязки с интервалом 500 мс (всего около 10 секунд), чтобы переждать окно TIME_WAIT после недавно завершившегося процесса.
  • Если после повторных попыток порт всё ещё используется:
  • Другие ошибки привязки:
При завершении работы Gateway закрывает сервер HTTP/WebSocket и удаляет свои файлы блокировки состояния и конфигурации.

​
Примечания по эксплуатации

  • Если порт занят другим процессом, не являющимся Gateway, ошибка будет такой же; освободите порт или выберите другой с помощью openclaw gateway --port <port>.
  • OPENCLAW_ALLOW_MULTI_GATEWAY=1 разрешает запуск нескольких экземпляров конфигурации/среды выполнения, но не совместное использование изменяемого состояния. Каждому экземпляру по-прежнему требуется уникальный OPENCLAW_STATE_DIR.
  • При работе под управлением диспетчера служб новый процесс Gateway, столкнувшийся с любой из указанных выше ошибок, сначала проверяет /healthz существующего процесса. Если существующий процесс исправен, новый процесс оставляет управление за ним вместо завершения с ошибкой. В systemd он завершается с кодом 78; параметр модуля RestartPreventExitStatus=78 не позволяет Restart=always зациклиться при конфликте блокировки или EADDRINUSE. Если существующий процесс так и не становится исправным, число повторных проверок работоспособности ограничено по времени, после чего запуск завершается с указанной выше ошибкой блокировки вместо бесконечного цикла.
  • Приложение macOS использует собственную упрощённую проверку PID перед запуском Gateway; фактическое ограничение во время выполнения обеспечивают описанные выше блокировка файла и привязка сокета.

​
См. также