قفل Gateway

چرا

• تنها یک فرایند Gateway باید مالک یک دایرکتوری وضعیت باشد؛ Gatewayهای اضافی را با پروفایل‌ها، دایرکتوری‌های وضعیت، پیکربندی‌ها و پورت‌های مجزا اجرا کنید.
• بدون باقی‌گذاشتن فایل‌های قفل منقضی‌شده، از خرابی‌ها/SIGKILL جان سالم به‌در ببرد.
• وقتی Gateway دیگری از قبل مالک پورت است، با خطایی روشن و سریع متوقف شود.

سه لایه

راه‌اندازی، مالکیت را در سه مرحله و به‌ترتیب اعمال می‌کند:

1. قفل مالکیت وضعیت قفلی را بر اساس دایرکتوری وضعیت متعارف به‌دست می‌آورد. همه Gatewayها، از جمله Gatewayهایی که با OPENCLAW_ALLOW_MULTI_GATEWAY=1 راه‌اندازی شده‌اند، در آن مشارکت دارند تا نگه‌داری مخرب SQLite نتواند با یک مالک فعال تداخل پیدا کند.
2. قفل پیکربندی قفل قدیمی مختص هر پیکربندی را به‌دست می‌آورد و پورت زمان اجرا را ثبت می‌کند. حالت چند-Gateway این تک‌نمونه‌ای‌بودن پیکربندی را نادیده می‌گیرد، اما قفل مالکیت وضعیت را حفظ می‌کند.
3. اتصال سوکت شنونده HTTP/WebSocket (به‌طور پیش‌فرض ws://127.0.0.1:18789) را به‌عنوان یک شنونده TCP انحصاری متصل می‌کند.

هر لایه می‌تواند مستقل از بقیه ناموفق شود و GatewayLockError مختص خود را ایجاد کند.

قفل‌های وضعیت و پیکربندی

• فعال‌بودن قفل از PID ثبت‌شده، شناسه زمان شروع فرایند در پلتفرم در صورت دسترس‌بودن، و شناسه فرایند Gateway تعیین می‌شود. مالک تأییدشده در طول راه‌اندازی و پیش از شروع شنود پورتش، همچنان مرجع معتبر باقی می‌ماند.

• یک هماهنگ‌کننده اختصاصی SQLite، بازرسی فراداده، بازپس‌گیری مالک منقضی‌شده و جایگزینی قفل را به‌صورت سریالی انجام می‌دهد. اگر فرایند مالک از کار بیفتد، تراکنش انحصاری آن به‌طور خودکار آزاد می‌شود.

• اگر فایل قفل موجود نباشد یا فرایند مالک ثبت‌شده دیگر در حال اجرا نباشد، راه‌اندازی قفل را بازپس می‌گیرد و ادامه می‌دهد.

• اگر هرکدام از قفل‌ها فعالانه نگه داشته شده باشد، راه‌اندازی پیش از صرف‌نظرکردن تا 5 ثانیه (پیش‌فرض) دوباره تلاش می‌کند:

  GatewayLockError("Gateway از قبل در حال اجرا است (pid <pid>)؛ مهلت قفل پس از <ms>ms پایان یافت")

اتصال سوکت

• در EADDRINUSE، راه‌اندازی برای عبور از بازه TIME_WAIT پس از خروج اخیر یک فرایند، اتصال را حداکثر 20 بار با فاصله‌های 500ms دوباره امتحان می‌کند (در مجموع حدود 10 ثانیه).

• اگر پورت پس از تلاش‌های مجدد همچنان در حال استفاده باشد:

  GatewayLockError("نمونه دیگری از Gateway از قبل در ws://127.0.0.1:<port> در حال شنود است")

• سایر خطاهای اتصال:

  GatewayLockError("اتصال سوکت Gateway در ws://127.0.0.1:<port> ناموفق بود: <cause>")

هنگام خاموش‌شدن، 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 پیش از ایجاد Gateway، محافظ سبک PID خود را نگه می‌دارد؛ فایل قفل و اتصال سوکت بالا سازوکارهای واقعی اعمال محدودیت در زمان اجرا هستند.

مرتبط

• چندین Gateway - اجرای چندین نمونه با پورت‌های منحصربه‌فرد
• عیب‌یابی - تشخیص EADDRINUSE و تداخل‌های پورت