Gateway लॉक

क्यों

• केवल एक Gateway प्रक्रिया को किसी स्टेट डायरेक्टरी का स्वामित्व रखना चाहिए; अतिरिक्त Gateway को पृथक प्रोफ़ाइल, स्टेट डायरेक्टरी, कॉन्फ़िगरेशन और पोर्ट के साथ चलाएँ।
• क्रैश/SIGKILL के बाद भी पुराने लॉक फ़ाइल छोड़े बिना चलते रहें।
• जब किसी अन्य Gateway के पास पहले से पोर्ट का स्वामित्व हो, तो स्पष्ट त्रुटि के साथ तुरंत विफल हों।

तीन परतें

स्टार्टअप क्रमवार तीन चरणों में स्वामित्व लागू करता है:

1. स्टेट स्वामित्व लॉक कैनोनिकल स्टेट डायरेक्टरी द्वारा कुंजीबद्ध लॉक प्राप्त करता है। प्रत्येक Gateway इसमें भाग लेता है, जिसमें OPENCLAW_ALLOW_MULTI_GATEWAY=1 के साथ शुरू किए गए Gateway भी शामिल हैं, ताकि विनाशकारी 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 अवधि से निपटने के लिए स्टार्टअप 500ms के अंतराल पर अधिकतम 20 बार बाइंड का पुनः प्रयास करता है (कुल मिलाकर लगभग 10 सेकंड)।

• यदि पुनः प्रयासों के बाद भी पोर्ट उपयोग में है:

  GatewayLockError("कोई अन्य gateway इंस्टेंस पहले से ws://127.0.0.1:<port> पर लिसन कर रहा है")

• अन्य बाइंड विफलताएँ:

  GatewayLockError("ws://127.0.0.1:<port> पर gateway सॉकेट बाइंड करने में विफल: <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 और पोर्ट टकरावों का निदान