Gateway

Блокування Gateway

Навіщо це потрібно

Лише один процес Gateway має використовувати певну конфігурацію та порт на хості; запускайте додаткові Gateway з ізольованими профілями й унікальними портами.
Забезпечення відновлення після аварійного завершення/SIGKILL без залишення застарілих файлів блокування.
Швидке завершення з чіткою помилкою, якщо порт уже належить іншому Gateway.

Два рівні

Під час запуску одноекземплярне володіння забезпечується двома незалежними послідовними кроками:

Файлове блокування отримує окремий для кожної конфігурації файл блокування в каталозі блокувань стану. Під час його отримання процес запуску перевіряє налаштований порт на наявність активного прослуховувача, щоб виявити застарілого власника блокування, роботу якого було аварійно завершено.
Прив’язування сокета прив’язує прослуховувач HTTP/WebSocket (типово ws://127.0.0.1:18789) як ексклюзивний прослуховувач TCP.

Кожен рівень може завершитися помилкою незалежно від іншого та створює власну помилку GatewayLockError.

Файлове блокування

Якщо файл блокування відсутній, записаний процес-власник уже не працює або перевірка порту власника не виявляє активного прослуховувача, процес запуску повторно захоплює блокування та продовжує роботу.
Якщо блокування активно утримується й жодна з наведених вище умов не виконується, процес запуску повторює спроби протягом щонайбільше 5 секунд (типово), перш ніж припинити їх:
text
```
GatewayLockError("gateway already running (pid <pid>); lock timeout after <ms>ms")
```

Прив’язування сокета

У разі EADDRINUSE процес запуску повторює спроби прив’язування до 20 разів з інтервалом 500 мс (загалом приблизно 10 секунд), щоб дочекатися завершення стану TIME_WAIT після нещодавнього завершення процесу.
Якщо після повторних спроб порт усе ще використовується:
text
```
GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")
```

Інші помилки прив’язування:

text

GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: <cause>")

Під час завершення роботи Gateway закриває сервер HTTP/WebSocket і видаляє файл блокування.

Примітки щодо експлуатації

Якщо порт зайнятий іншим процесом, що не є Gateway, помилка буде такою самою; звільніть порт або виберіть інший за допомогою openclaw gateway --port <port>.
Під керуванням диспетчера служб новий процес Gateway, який отримує одну з наведених вище помилок, спочатку перевіряє /healthz наявного процесу. Якщо цей процес справний, новий процес залишає керування за ним замість завершення з помилкою. У systemd він завершується з кодом 78; параметр модуля RestartPreventExitStatus=78 запобігає циклічному перезапуску через Restart=always у разі конфлікту блокування або EADDRINUSE. Якщо наявний процес так і не стає справним, повторні перевірки справності обмежуються в часі, після чого запуск завершується з наведеною вище помилкою блокування, а не повторюється нескінченно.
Застосунок macOS використовує власну спрощену перевірку PID перед запуском Gateway; фактичне забезпечення обмеження під час виконання здійснюють описані вище файлове блокування та прив’язування сокета.

Пов’язані матеріали

Кілька Gateway — запуск кількох екземплярів з унікальними портами
Усунення несправностей — діагностика EADDRINUSE і конфліктів портів

Was this useful?