لماذا لم يُعِد systemd تشغيل خدمتك؟
تراقب Restart= العملية الرئيسية فقط، لذلك قد يتوقف ابن داخل cgroup من دون إعادة التشغيل. تعرّف إلى أثر Type= وحدود إعادة التشغيل والسجل.
الإجابة المختصرة: تراقب سياسات إعادة تشغيل systemd عملية واحدة
تراقب سياسات إعادة تشغيل systemd عملية واحدة لكل وحدة: العملية الرئيسية. يقرأ Restart= حالة خروج هذه العملية وحدها، وحالة خروج الأوامر القصيرة التي يشغّلها systemd بنفسه حولها، مثل ExecStartPre= وExecStartPost= وExecReload=. ولا يقرأ أي شيء آخر. قد تضم مجموعة التحكم الخاصة بالوحدة عشرين عملية، وقد تتوقف إحداها، بينما تبقى الوحدة active (running) لأن العملية الرئيسية ما زالت تعمل. لم يحدث أي فشل من منظور systemd، ولذلك لا يُعاد تشغيل أي شيء.
يعرف systemd العمليات الأخرى. فهو ينهيها عند إيقاف الوحدة، ويحتسب ذاكرتها ضمن حدود الوحدة، ويطبّق عليها حصة وحدة المعالجة المركزية الخاصة بالوحدة، ويعرضها في systemctl status. لكنه لا يقرأ حالة خروجها مطلقاً. منطق إعادة التشغيل ومجموعة cgroup شيئان مختلفان، ويتناول معظم هذا الدليل الفجوة بينهما.
ما الذي يحتويه cgroup، وما الذي تقرؤه منطقية إعادة التشغيل
cgroup (مجموعة التحكم) هو كائن في kernel يملك مجموعة من العمليات. تحصل كل وحدة خدمة على cgroup خاص بها، ويُسمّى باسم الوحدة. لا يمكن للعملية مغادرته. ترث العمليات الابنة cgroup الخاص بالعملية الأم، ولا يمكن لعملية غير مميّزة نقل نفسها إلى مكان آخر. لذلك يستطيع systemd تنظيف daemon ينشئ عمليات فرعية على مرحلتين، وهو أمر لم تكن نصوص init القديمة تستطيع تنفيذه بشكل موثوق.
انظر إلى الحقيقتين جنباً إلى جنب:
systemd-cgls --unit myapp.service
systemctl show -p MainPID -p NRestarts -p Restart -p RestartUSec myapp.serviceيسرد systemd-cgls كل عملية في الوحدة. أما MainPID فهو الرقم الوحيد الذي تقرؤه سياسة إعادة التشغيل. عندما يختلف هذان الرقمان عن تصورك، يكون هذا الاختلاف هو الخطأ. يعني MainPID=0 أن systemd لا يملك عملية رئيسية يقرأ منها حالة الخروج. لكنه يواصل تتبع cgroup، ولذلك يلاحظ اختفاء آخر عملية فيه، إلا أن منطقية إعادة التشغيل لا تملك حتى ذلك الحين حالة خروج لتقييمها.
توجد حالة استثناء فعلية لقاعدة العملية الرئيسية. إذا أنهى قاتل العمليات بسبب نفاد الذاكرة أي عملية داخل cgroup الخاص بالوحدة، فإن systemd يكتشف ذلك لأنه يراقب ملف memory.events في cgroup. يحدد OOMPolicy= ما يحدث بعد ذلك، وقيمته الافتراضية هي stop: تتوقف الوحدة كاملة، وتُسجَّل النتيجة باعتبارها oom-kill، ويُحتسب ذلك فشلاً، ولذلك يعمل Restart=on-failure. يوضح journal ذلك صراحة.
myapp.service: A process of this unit has been killed by the OOM killer.
myapp.service: Failed with result 'oom-kill'.لذلك، يؤدي إنهاء عملية ابنة بسبب الذاكرة إلى إيقاف الوحدة، بينما لا يؤدي موت العملية الابنة نفسها بسبب segmentation fault إلى ذلك. إذا ضبطت حدود الذاكرة على وحدة، فاقرأ كيفية تطبيق MemoryMax وCPUQuota على cgroup الخاص بالوحدة قبل ضبط سياسة إعادة التشغيل، لأن هاتين الميزتين تلتقيان هنا فقط.
كيفية تحديد Type للعملية الرئيسية
Type= في قسم [Service] لا يقتصر على ترتيب بدء التشغيل. فهو القاعدة التي تحدد أي PID (معرّف العملية) يصبح MainPID، وهذا يحدد أيضاً ما يستطيع Restart= رؤيته.
Type=simpleهو الإعداد الافتراضي. العملية التي ينشئها systemd عبر fork منExecStart=هي العملية الرئيسية. يعلّم systemd الوحدة على أنها بدأت فوراً، قبل أن يعرف ما إذا كانexecقد نجح أصلاً. يؤدي وجود خطأ مطبعي في مسار الملف التنفيذي إلى نجاح مهمة البدء، ثم حدوثMain process exited, code=exited, status=203/EXECبعد لحظة.Type=execيتصرف مثلsimple، باستثناء أن مهمة البدء تنتظر حتى ينجحexec. يحوّل ذلك الخطأ المطبعي السابق إلى فشل صريح في البدء. وهو يحتاج إلى systemd 240 أو إصدار أحدث. يتوفر في Ubuntu 20.04 والإصدارات الأحدث وفي Debian 12، لكن Ubuntu 18.04، الذي لا يزال مشمولاً عبر Ubuntu Pro، يأتي مع systemd 237 ولا يتوفر فيه هذا الخيار. استخدمه بدلاً منsimpleكلما كان متاحاً.Type=forkingيتوقع أن تنشئ العملية منExecStart=خدمة daemon في الخلفية ثم تنتهي. ينتظر systemd انتهاء العملية الأصلية، ثم يبحث عن daemon الفعلي. زوّده بـPIDFile=. من دونه، لا يعملGuessMainPID=(المفعّل افتراضياً) إلا عندما تبقى عملية واحدة بالضبط في cgroup. إذا أبقيت عمليتين، تظلMainPIDفي الحالة0.Type=notifyيعني أن الخدمة تستدعيsd_notify(3)وترسلREADY=1عندما تصبح قادرة على معالجة network traffic. ويمكنها أيضاً إرسالMAINPID=لتسليم systemd عملية مختلفة لتتبّعها. معType=notify، يتم تعيينNotifyAccess=إلىmainما لم تختر خلاف ذلك، ولذلك يتم تجاهل الإشعار المرسل من عملية فرعية، ويذكر journal الـPID الذي أرسله.Type=oneshotلا يملك عملية رئيسية مستمرة. تصبح الوحدة غير نشطة فور انتهاءExecStart=، ما لم تضبطRemainAfterExit=yes. يُرفضRestart=alwaysوRestart=on-successهنا، مع الرسالةService has Restart= set to either always or on-success, which isn't allowed for Type=oneshot services. Refusing.. وتُقبل القيم الأخرى، بما فيهاon-failure.
يجدر حفظ خطأي Type=forking عن ظهر قلب، لأن كلاً منهما يتركك مع وحدة تبدو معطلة من دون سبب ظاهر:
myapp.service: Can't open PID file /run/myapp.pid (yet?) after start: No such file or directory
myapp.service: New main PID 4711 does not belong to service, and PID file is not owned by root. Refusing.يعني الخطأ الأول أن daemon يكتب ملف PID في مكان آخر، أو يكتبه بعد الوقت الذي يبحث فيه systemd عنه. ويعني الخطأ الثاني أن ملف PID يحدد عملية خارج cgroup الخاصة بالوحدة، ويرفض systemd تبنّيها، لأن ملف PID القابل للكتابة سيصبح بخلاف ذلك وسيلة لجعل systemd يرسل إشارات إلى أي عملية على الخادم.
لماذا يخفي البرنامج النصي المغلِّف موت العمليات التابعة له
إليك البنية التي تطرح السؤال الوارد في العنوان.
#!/bin/bash
/usr/local/bin/myapp-web &
/usr/local/bin/myapp-worker &
waitالوحدة هي Type=simple، ولذلك تكون العملية الرئيسية هي الصدفة. يعيد wait بلا وسيطات النتيجة فقط بعد خروج جميع العمليات التابعة. أوقف عملية العامل، فتبقى الصدفة منتظرة عملية الويب، ولذلك لا تخرج الصدفة، ولا يخرج MainPID، ولا تتم استشارة Restart=. أصبحت مجموعة cgroup تحتوي على عملية واحدة أقل، ويطبع systemctl status شجرة أقصر، بينما تظل الوحدة في الحالة active (running). لا يراقب systemd هذه الشجرة بحثاً عن تغييرات.
النسخة الثانية من الخطأ نفسه أكثر هدوءاً:
ExecStart=/bin/sh -c 'export APP_ENV=production; /usr/local/bin/myapp'العملية الرئيسية هي الصدفة، وليست myapp. عند تنفيذ systemctl stop، يرسل systemd الإشارة SIGTERM إلى العملية الرئيسية، ولا تمرر الصدفة المنتظرة لعملية تابعة تعمل في المقدمة الإشارة إليها. لذلك يستغرق الإيقاف كامل TimeoutStopSec، أي 90 ثانية افتراضياً، وينتهي على النحو التالي:
myapp.service: State 'stop-sigterm' timed out. Killing.
myapp.service: Killing process 4711 (myapp) with signal SIGKILL.الحل هو exec. اكتب exec /usr/local/bin/myapp، فتُستبدل الصدفة بالبرنامج، ولذلك تكون MainPID هي البرنامج وتصل الإشارات إليه. والأفضل حذف الصدفة واستخدام Environment= أو EnvironmentFile= في الوحدة. لاحظ أن هذا الخطأ لا يظهر عندما تحتوي السلسلة -c على أمر واحد، لأن bash وdash يحسّنان هذه الحالة إلى exec مباشر. أضف أمراً ثانياً إلى السلسلة، فتبقى الصدفة قيد التشغيل أمام برنامجك.
أعد إنتاج المشكلة على VPS اختباري خلال دقيقتين
احفظ البرنامج النصي المغلِّف أعلاه باسم /usr/local/bin/two-children.sh، واجعله قابلاً للتنفيذ باستخدام chmod +x، واستبدل مساري البرنامج بمسار sleep 3600. اربط وحدة به باستخدام Type=simple وRestart=on-failure، ثم نفّذ systemctl daemon-reload وشغّلها. نفّذ systemd-cgls --unit two-children.service ولاحظ أرقام العمليات الثلاثة: الصدفة وعمليتاها التابعتان. أوقف إحدى العمليتين التابعتين باستخدام sudo kill <pid>. افحص الوحدة مرة أخرى. أصبحت الشجرة أقصر بعملية واحدة، ولا تزال الحالة active (running)، ولا يحتوي السجل على أي رسالة جديدة. نفّذ sudo kill -9 <shell pid> بدلاً من ذلك. تفشل الوحدة، ويُنظَّفَت العملية التابعة الباقية لأن KillMode=control-group هي القيمة الافتراضية، ويعرض السجل Scheduled restart job, restart counter is at 1.
كامل قيم Restart=، ومتى يكون on-failure أفضل من always
Restart= يقبل إحدى سبع قيم. والفرق الأساسي بينها هو تعريف الخروج السليم. يتعامل systemd مع رمز الخروج 0، ومع أي رمز مُدرج في SuccessExitStatus=، ومع الإشارات SIGHUP وSIGINT وSIGTERM وSIGPIPE على أنها خروج سليم، وذلك لكل نوع باستثناء Type=oneshot. وكل ما عدا ذلك، بما في ذلك SIGKILL وSIGSEGV، يُعد خروجاً غير سليم.
noهي القيمة الافتراضية. لا تعيد الوحدة تشغيل نفسها أبداً. لذلك تتوقف الوحدة التي لا تحتوي على سطرRestart=عند أول تعطل وتبقى متوقفة.on-successتعيد التشغيل فقط بعد خروج سليم.on-failureتعيد التشغيل بعد رمز خروج غير صفري، أو إشارة غير سليمة، أو انتهاء مهلة البدء أو الإيقاف، أو انتهاء مهلة watchdog.on-abnormalتعيد التشغيل بعد إشارة غير سليمة، أو انتهاء مهلة، أو انتهاء مهلة watchdog، لكنها لا تعيد التشغيل بعد رمز خروج غير صفري عادي.on-abortتعيد التشغيل فقط بعد إشارة غير سليمة، أي بعد تعطل.on-watchdogتعيد التشغيل فقط عند انتهاءWatchdogSec=.alwaysتعيد التشغيل بعد كل الحالات السابقة، بما فيها الخروج السليم بالحالة 0.
on-failure هي القيمة الافتراضية المناسبة لخدمة daemon طويلة التشغيل. فهي تعيد الخدمة بعد التعطل، وتترك exit 0 المتعمّد دون تغيير. تناسب always البرامج التي تخرج بشكل سليم لأسباب خارجة عن سيطرتها، مثل عميل نفق يعيد 0 عند انقطاع الطرف البعيد. لكن always قد تخفي الأخطاء. فإذا بدأت الخدمة، وقرأت ملف إعداد معطوباً، وسجلت الخطأ، ثم خرجت بالحالة 0، فسيُعاد تشغيلها ببساطة. ومع الفاصل الافتراضي البالغ 100 ميلي ثانية، ستتجاوز قريباً حد معدل البدء الموضح أدناه، وتنتهي بحالة فشل مع start-limit-hit. أما إذا كان RestartSec= طويلاً بما يكفي للبقاء دون ذلك الحد، فستدخل الخدمة في حلقة لا نهائية، ولن تكون العلامة الوحيدة على ذلك سوى ارتفاع عداد إعادة التشغيل.
SuccessExitStatus= يغيّر الحد الفاصل بين الخروج السليم وغير السليم. يعيد Borg القيمة 1 للتحذيرات والقيمة 2 للأخطاء. لذلك تُعلَّم وحدة النسخ الاحتياطي بحالة الفشل في كل مرة تتجاوز فيها ملفاً يتعذر قراءته، ما لم تستخدم SuccessExitStatus=1. تسرد RestartPreventExitStatus= الرموز التي تمنع إعادة التشغيل حتى مع always. وهذه هي الطريقة السليمة التي يعبّر بها البرنامج عن عدم وجوب تشغيله مجدداً. أما RestartForceExitStatus= فتفعل العكس. يجب أن تكون مهمة النسخ الاحتياطي ضمن وحدة Type=oneshot يشغّلها مؤقت، لا ضمن حلقة إعادة تشغيل. ويمكنك نسخ بنية زوج الخدمة والمؤقت الذي يشغّل مهمة وفق جدول زمني.
تنبيه مهم عند الاختبار. يؤدي قتل خدمتك باستخدام kill <pid> وحده إلى إرسال SIGTERM، وهي ضمن قائمة الخروج السليم. لذلك لا يفعل Restart=on-failure شيئاً، وقد تستنتج أن إعدادك معطوب. استخدم kill -9 <pid> أو systemctl kill -s SIGKILL myapp.service بدلاً من ذلك. تذكّر أيضاً أن أياً من قيم Restart= لا يعمل بعد systemctl stop، أو عندما تكون الوحدة قد أوقفت بسبب زوال تبعية BindsTo= أو PartOf=. مهمة الإيقاف ليست فشلاً.
RestartSec والفاصل الافتراضي البالغ 100 ميلي ثانية
RestartSec= هو فترة التوقف بين إيقاف الوحدة وإعادة systemd تشغيلها، والقيمة الافتراضية هي 100 ميلي ثانية. تحقّق من القيمة التي حمّلتها وحدتك فعلياً:
systemctl show -p RestartUSec -p StartLimitIntervalUSec -p StartLimitBurst myapp.serviceتطبع الوحدة التي لم تضبط هذه القيمة RestartUSec=100ms، ما لم يغيّر أحدهم DefaultRestartSec= في /etc/systemd/system.conf، وهو مصدر القيمة غير المضبوطة. هذه القيمة الافتراضية مناسبة لخدمة تتعطل مرة واحدة ثم تعود للعمل. لكنها غير مناسبة لخدمة لا يمكنها البدء أصلاً، لأن عملية البدء الأولى وأربع عمليات إعادة تشغيل تحدث في أقل بكثير من ثانية عندما يفشل البرنامج فوراً، وبذلك تستهلك عمليات البدء الخمس التي يسمح بها حد المعدل الموضح لاحقاً. بالنسبة إلى أي خدمة تنتظر قاعدة بيانات أو mount أو مسار شبكة، اضبط RestartSec=5s أو قيمة أكبر.
اعتباراً من October 2026، يوفّر systemd 254 والإصدارات الأحدث أيضاً RestartSteps= وRestartMaxDelaySec=، وهما يزيدان فترة التأخير من RestartSec= حتى حد أقصى خلال ذلك العدد من المحاولات. يأتي Ubuntu 24.04 مع systemd 255 ويدعم هذين الخيارين. يأتي Debian 12 مع systemd 252 ولا يدعمهما، مع أن bookworm-backports يتضمن systemd 254. تكون فترات التأخير المتزايدة هي الحل المناسب عندما قد تبقى التبعية متوقفة مدة طويلة.
ما الذي يعنيه فعلياً "start request repeated too quickly"
يفهم بعض القراء هذه الحالة على أنها تخلٍّ عشوائي من systemd عن الخدمة. لكنها في الواقع عدّاد. القاعدة هي: إذا بدأ تشغيل الوحدة أكثر من StartLimitBurst= مرات خلال StartLimitIntervalSec=، يرفض systemd تشغيلها مرة أخرى ويضعها في حالة الفشل. القيم الافتراضية هي 5 محاولات تشغيل خلال 10 ثوانٍ.
يعرض السجل التسلسل التالي:
myapp.service: Scheduled restart job, restart counter is at 5.
myapp.service: Start request repeated too quickly.
myapp.service: Failed with result 'start-limit-hit'.
Failed to start myapp.service - My application.ويجيب systemctl start مع تطبيق الإصلاح مباشرة:
Job for myapp.service failed because start of the service was attempted too often. See "systemctl status myapp.service" and "journalctl -xeu myapp.service" for details. To force a start use "systemctl reset-failed myapp.service" followed by "systemctl start myapp.service" again.يصفّر systemctl reset-failed myapp.service العدّاد وحالة الفشل. من دونه، يظل systemctl start العادي مرفوضاً حتى تنقضي مدة StartLimitIntervalSec=، وتبقى عمليات إعادة التشغيل التلقائية متوقفة إلى أن يبدأ شيء ما تشغيل الوحدة مجدداً. تُحتسب عمليات التشغيل اليدوية أيضاً ضمن الحد، لذلك قد تؤدي عدة عمليات systemctl restart متعجلة أثناء تعديل ملف إعداد إلى تفعيل الحد، من دون حدوث أي تعطل فعلي.
الجزء المضلل هو أن start-limit-hit لا يذكر أبداً سبب فشل الخدمة. فهو يذكر فقط أنها فشلت مراراً وبسرعة. أما السبب الحقيقي فموجود في أسطر السجل السابقة.
ينبغي وضع الإعدادين في قسم [Unit]. ستجد أمثلة تضعهما في [Service]، وقد كان systemd يقبل ذلك في الإصدارات الأقدم، ومن هنا يبدأ الالتباس. اكتب الإعدادين في [Unit]، ثم اطلب من systemd عرض ما حمّله باستخدام systemctl show، لأن القيمة المحمّلة هي الوحيدة التي يُعتد بها.
[Unit]
Description=My application
StartLimitIntervalSec=300
StartLimitBurst=5
[Service]
Type=exec
ExecStart=/usr/local/bin/myapp
Restart=on-failure
RestartSec=10sيحدد ذلك خمس محاولات للوحدة خلال نافذة مدتها خمس دقائق قبل أن تتوقف عن المحاولة. يعطّل StartLimitIntervalSec=0 الحد بالكامل. يجب أن تعرف ما تختاره: الخدمة التي لا يمكنها البدء ستعيد المحاولة الآن إلى ما لا نهاية، وستكتب في السجل في كل مرة. توجد القيم الافتراضية على مستوى الجهاز بأكمله في /etc/systemd/system.conf تحت الاسمين DefaultStartLimitIntervalSec= وDefaultStartLimitBurst=.
هناك إعداد مجاور يستحق التحذير. يحدد StartLimitAction= ما يحدث عند بلوغ الحد، ويقبل قيماً تشمل reboot وreboot-force وpoweroff. القيمة الافتراضية هي none، التي تفشل الوحدة وتترك الجهاز دون تغيير. على VPS بعيد، يعني poweroff أن الجهاز سيبقى متوقفاً إلى أن تفتح وحدة تحكم المزوّد.
الإصلاح الأول: عملية واحدة لكل وحدة
هذه هي الإجابة في معظم الحالات. إذا كان يجب تشغيل برنامجين، فاكتب وحدتين. عندها تكون لكل وحدة عملية رئيسية فعلية، وحالة خروج فعلية، وسياسة إعادة تشغيل خاصة بها. وستحصل أيضاً على سجلات منفصلة، وحدود موارد منفصلة، وعدادات إعادة تشغيل منفصلة. هذا هو المطلوب في الساعة الثالثة صباحاً.
عبّر عن العلاقة بين الوحدات داخل ملفات الوحدات، وليس داخل برنامج shell نصي.
After=يرتّب بدء التشغيل فقط. ولا يعبّر عن أي شيء بشأن حالات الفشل.Requires=يبدأ الوحدة الأخرى بالتوازي مع هذه الوحدة، ويوقف هذه الوحدة إذا أوقِفت الوحدة الأخرى صراحةً.BindsTo=هوRequires=مع إضافة الحالة التي تهمك: تتوقف هذه الوحدة عندما تتوقف الوحدة الأخرى لأي سبب، بما في ذلك التعطل. اقرنه معAfter=، وإلا فسيكون ترتيب التشغيل غير محدد.PartOf=يمرّر الإيقاف وإعادة التشغيل إلى الوحدات التابعة، ولذلك يصلsystemctl restart myapp.targetإلى كل وحدة تكونPartOf=لها.Upholds=(في systemd 249 والإصدارات الأحدث، أي Ubuntu 22.04 والإصدارات الأحدث) يحافظ على تشغيل الوحدة المحددة: إذا توقفت، يشغّلها systemd مرة أخرى. ويخضع ذلك لحد معدل البدء نفسه الذي تخضع له جميع الوحدات الأخرى.
عامل يجب ألا يعمل مطلقاً من دون خادم API، ويحافظ systemd على تشغيله ما دام API قيد التشغيل:
# /etc/systemd/system/myapp-api.service
[Unit]
Description=myapp API server
Wants=network-online.target
After=network-online.target
Upholds=myapp-worker.service
[Service]
Type=exec
User=myapp
ExecStart=/usr/local/bin/myapp serve
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=multi-user.target# /etc/systemd/system/myapp-worker.service
[Unit]
Description=myapp background worker
BindsTo=myapp-api.service
After=myapp-api.service
StartLimitIntervalSec=120
StartLimitBurst=5
[Service]
Type=exec
User=myapp
ExecStart=/usr/local/bin/myapp worker
Restart=on-failure
RestartSec=5sلا يحتوي العامل على قسم [Install]، ولا يتم تمكينه يدوياً مطلقاً. تستدعيه وحدة API باستخدام Upholds=، ولذلك فإن systemctl enable --now myapp-api.service هو الأمر الوحيد الذي تشغّله. أعد التحميل وتحقق مما أنشأه systemd من الوحدتين:
sudo systemctl daemon-reload
systemd-analyze verify /etc/systemd/system/myapp-worker.service
systemctl list-dependencies myapp-api.serviceيطبع systemd-analyze verify لا شيء على الإطلاق عندما يكون الملف سليماً. وأي مخرجات تعني وجود مشكلة، وعادةً تكون مفتاحاً لا يتعرّف عليه systemd في القسم الذي كتبته فيه، أو تبعيةً لوحدة غير موجودة.
الإصلاح الثاني: Type=notify، لكي يعرف systemd أكثر من مجرد PID
إذا كان البرنامج يتحدث بروتوكول الإشعارات الخاص بـsystemd، فاستخدمه. مع Type=notify، تُبلغ الخدمة systemd عندما تصبح جاهزة، ما يجعل ترتيب التشغيل فعلياً بدلاً من أن يكون مبنياً على التوقع، ويمكنها إرسال MAINPID= لتوجيه systemd إلى العملية المهمة بدلاً من برنامج التشغيل.
WatchdogSec= هو الجزء الذي يستحق الجهد. اضبطه، وعندها يجب أن ترسل الخدمة WATCHDOG=1 عبر sd_notify(3) بهذه الوتيرة على الأقل. عندما تتوقف الرسائل، ينهي systemd الخدمة باستخدام SIGABRT ويضع علامة فشل عليها، ولذلك يعيد Restart=on-failure أو Restart=on-watchdog تشغيلها. هذه هي الطريقة المضمّنة الوحيدة لإعادة تشغيل عملية ما تزال حية لكنها عالقة، وهو أمر لا يمكن لأي سياسة لحالة الخروج التقاطه.
[Service]
Type=notify
NotifyAccess=main
ExecStart=/usr/local/bin/myapp serve
WatchdogSec=30s
Restart=on-failure
RestartSec=5sيظهر انطلاق مراقب الحالة في journal على شكل myapp.service: Watchdog timeout (limit 30s)!، ثم عملية القتل. أما إذا بقيت الوحدة في activating (start) حتى تنفد TimeoutStartSec، فهذا يعني أن READY=1 لم يصل أو لم يُحتسب. إما أن البرنامج لا يتحدث البروتوكول، أو أن NotifyAccess=main يرفض إشعاراً أرسلته عملية فرعية، وهو ما يسجله journal مع كلا رقمي PID، أو أن عملية مساعدة أرسلت الرسالة ثم خرجت قبل أن يتمكن systemd من تحديد الوحدة التي صدرت الرسالة منها. تُتجاهل هذه الرسالة الأخيرة حتى مع NotifyAccess=all، ويجب إصلاح ذلك داخل البرنامج: إذ ينبغي أن يستدعي sd_notify_barrier() قبل خروج العملية المساعدة.
بالنسبة إلى البرامج التي توفّر نقطة نهاية HTTP لفحص الصحة لكنها لا تدعم sd_notify، فالخياران الصريحان هما إنشاء وحدة مؤقت صغيرة تفحص نقطة النهاية وتستدعي systemctl restart، أو ترك وقت تشغيل الحاويات ينفّذ الفحص، وهذا هو الغرض من فحوصات الصحة في Compose وسلوك إعادة التشغيل الخاص بها.
الإصلاح الثالث: تشغيل supervisor داخل الوحدة، فقط عند عدم وجود بديل
تأتي بعض البرمجيات فعلياً على شكل مجموعة من العمليات خلف مشغّل لا يمكنك فصل مكوّناته. عندها تشغّل supervisor داخل الوحدة، وتقبل النتيجة: يراقب systemd الـsupervisor، ويراقب الـsupervisor كل ما عداه، وتصبح سياسة إعادة التشغيل موزعة على ملفين.
الشكل الشائع لذلك هو runtime للحاويات. تتبع وحدة docker compose أو podman هذا النمط تماماً، إذ تُحدَّد سياسة إعادة التشغيل الخاصة بكل حاوية في ملف Compose، بينما تقتصر وحدة systemd على إبقاء الـruntime قيد التشغيل. إذا كان هذا هو وضعك، توضّح الوحدة التي تشغّل مكدس Compose عند الإقلاع النسخة العملية، بما في ذلك سبب صحة استخدام Type=oneshot مع RemainAfterExit=yes في هذه الحالة عادةً.
يظل cgroup في صالحك. فكل ما يشغّله الـsupervisor يبقى داخل cgroup الخاص بالوحدة، لذلك يظل MemoryMax= وCPUQuota= والتنظيف عند الإيقاف يشمل الشجرة بأكملها. أما قرار إعادة التشغيل وحده فيُفوَّض إلى الـsupervisor.
أياً كان الـsupervisor الذي تختاره، لا تضبط Restart=always على الوحدة الخارجية وتضع في داخلها سياسة إعادة تشغيل قوية من دون دراسة الأمر. تؤدي طبقتان من منطق إعادة التشغيل، لكل منهما آلية تراجع خاصة بها، إلى خدمة تتوقف وتُعاد محاولتها لدقائق، وإلى journal لا يوضح السبب.
لا يعني ExitType=cgroup «إعادة التشغيل عند توقف أي عملية»
ExitType= (في systemd 250 والإصدارات الأحدث، ولذلك يتوفر في Ubuntu 24.04 وDebian 12) هو الإعداد الذي يعثر عليه المستخدمون عند البحث عن هذه المشكلة، لكنه يفعل عكس ما يوحي به الاسم. القيمة الافتراضية، ExitType=main، تعني أن الخدمة تُعتبر متوقفة عند خروج العملية الرئيسية. أما ExitType=cgroup فتعني أن الخدمة تُعتبر قيد التشغيل حتى تخرج آخر عملية في cgroup.
لذلك يجعل ExitType=cgroup الوحدة أقل تأثراً بتوقف عملية واحدة، وليس أكثر تأثراً به. ويكون هذا الإعداد مناسباً لبرنامج ينشئ عملية العامل الفعلية ثم يخرج من العملية الأب من دون كتابة ملف PID، بحيث لا يستطيع Type=forking العثور على الخدمة. لكنه الإعداد الخاطئ للفشل الموضح هنا.
لا توجد قيمة Restart= تعني «إعادة تشغيل الوحدة عند توقف أي عملية في cgroup». إذا كنت تحتاج إلى هذا السلوك، فيجب تشغيل عملية واحدة لكل وحدة. وإذا تعذر تقسيم البرنامج وكنت تتحكم في البرنامج النصي المغلّف، فأقرب خيار هو wait -n، الذي يعود فور خروج أول عملية ابن:
#!/bin/bash
/usr/local/bin/myapp-web &
/usr/local/bin/myapp-worker &
wait -n
exit 1يؤدي توقف أي عملية ابن الآن إلى إنهاء البرنامج النصي المغلّف بحالة غير صفرية، ولذلك يعمل Restart=on-failure. هذا حل وسط، وليس إصلاحاً. ستظل تستخدم عداد إعادة تشغيل واحداً لبرنامجين، وتدفق سجلات واحداً، ولن تتمكن من إعادة تشغيل الجزء الفاشل وحده.
كيفية فحص ما حدث فعلياً
أربعة أوامر، بهذا الترتيب.
systemctl status myapp.service
systemd-cgls --unit myapp.service
systemctl show -p MainPID -p NRestarts -p Result -p ExecMainStatus myapp.service
journalctl -u myapp.service -b -o short-preciseيعرض systemctl status الحالة وPID الرئيسي وشجرة cgroup في شاشة واحدة. تظهر الوحدة السليمة بالحالة Active: active (running)، مع سطر Main PID: يسمّي العملية التي تتوقعها. إذا أدرجت الشجرة في الأسفل عمليات لا تتعرّف إليها، أو افتقدت عملية تتوقع وجودها، فقد عرفت السبب.
يطبع systemd-cgls --unit الشجرة نفسها من دون اقتطاع. ويصبح ذلك مهماً عندما تحتفظ الوحدة بأكثر من عدد قليل من العمليات.
يعرض systemctl show حقائق قابلة للقراءة آلياً. يمثّل NRestarts= عدّاد إعادة التشغيل، وهو أسرع طريقة للتمييز بين خدمة أعيد تشغيلها أربعين مرة وأخرى تعمل منذ الإقلاع. يحتوي Result= على سبب الفشل الأخير: exit-code أو signal أو timeout أو oom-kill أو watchdog أو start-limit-hit. يمثّل ExecMainStatus= حالة الخروج الخام لآخر عملية رئيسية.
يحتوي السجل على التسلسل الزمني. هذه هي الأسطر الثلاثة التي يجب البحث عنها:
myapp.service: Main process exited, code=exited, status=1/FAILURE
myapp.service: Failed with result 'exit-code'.
myapp.service: Scheduled restart job, restart counter is at 1.يعني code=exited, status=N أن البرنامج اختار إرجاع N، ولذلك يكون الخلل في البرنامج أو في إعداده. يعني code=killed, signal=SEGV أن البرنامج انهار. يعني code=killed, signal=TERM عادةً أن شيئاً آخر طلب منه التوقف، وهذا ليس فشلاً ولن يفعّل Restart=on-failure. يعني code=dumped أنه ترك ملف core، وستعرضه coredumpctl list عند تثبيت systemd-coredump.
عند فحص أكثر من جهاز، يكون NRestarts هو الرقم الذي يستحق جمعه وفق جدول زمني. إذا ارتفع عدّاد وحدة كل يوم، فهي تفشل كل يوم، سواء لاحظ أحد ذلك أم لا. بعد تجاوز جهازين أو ثلاثة، تحوّل طريقة متسقة لتشغيل أمر واحد على كل خادم ذلك من تخمين إلى تقرير.
FAQ
لماذا يقول systemctl إن خدمتي نشطة مع أن العملية توقفت؟
يتتبّع systemd عملية واحدة لكل وحدة خدمة، وهي العملية الرئيسية، ويقرأ Restart= حالة خروج تلك العملية فقط. تعمل كل العمليات الأخرى التي تبدأها الوحدة داخل cgroup نفسها. وسيُنهي systemd هذه العمليات عندما تتوقف الوحدة، لكنه لا يراقب خروجها. شغّل systemctl show -p MainPID myapp.service وقارن العدد مع systemd-cgls --unit myapp.service. إذا ظهرت العملية التي توقفت في الشجرة لكنها ليست MainPID، فقد تصرّف systemd وفق التصميم تماماً. الحل هو تشغيل عملية واحدة لكل وحدة، مع كتابة العلاقة بين الوحدات باستخدام BindsTo= وUpholds=.
ماذا يعني "start request repeated too quickly"؟
يعني ذلك أن الوحدة بدأت أكثر من StartLimitBurst= مرات خلال StartLimitIntervalSec=، والذي تكون قيمته الافتراضية 5 مرات بدء خلال 10 ثوانٍ، ولذلك توقف systemd عن المحاولة. هذا حد لمعدل البدء، ولا يوضح سبب فشل الخدمة. اقرأ لذلك أسطر السجل التي تسبقه. امسح الحالة باستخدام systemctl reset-failed myapp.service، ثم أصلح سبب الفشل الأساسي. إذا كانت الخدمة تنتظر مورداً بطيئاً حتى يصبح جاهزاً، فارفع قيمة RestartSec=، لأن الفاصل الافتراضي البالغ 100 ميلي ثانية يستهلك المحاولات الخمس كلها خلال أقل من ثانية.
هل أستخدم Restart=always أم Restart=on-failure؟
استخدم on-failure في معظم الحالات. فهو يعيد تشغيل الخدمة بعد التعطل، أو الخروج بحالة غير صفرية، أو انتهاء المهلة، أو تفعيل watchdog، لكنه يترك exit 0 المقصود دون إعادة تشغيل. استخدم always فقط عندما يخرج البرنامج بنجاح لأسباب خارجة عن سيطرته، مثل عميل يعيد 0 عند انقطاع الطرف المقابل. تكمن مشكلة always في أن الخدمة التي تقرأ إعداداً تالفاً، وتسجل خطأ واحداً، ثم تخرج بالحالة 0 ستُشغَّل مراراً. ومع الفاصل الافتراضي ستفشل قريباً مع start-limit-hit، أما مع RestartSec= أطول فقد تدخل في حلقة لا نهائية، بينما يرتفع NRestarts في systemctl show بوصفه العرض الوحيد الظاهر.
لماذا لا تؤدي إيقاف عمليتي يدوياً إلى إعادة تشغيلها؟
لأن systemd، باستثناء Type=oneshot، يعدّ SIGHUP وSIGINT وSIGTERM وSIGPIPE عمليات خروج سليمة، ولأن الأمر kill <pid> يرسل SIGTERM. في حالة Restart=on-failure لا يُعدّ الخروج السليم فشلاً، ولذلك لا تُعاد العملية إلى التشغيل. وقد يبدو الإعداد معطلاً رغم أنه يعمل كما هو محدد. اختبر باستخدام kill -9 <pid> أو systemctl kill -s SIGKILL myapp.service، إذ يؤدي ذلك إلى إنهاء غير سليم ويُفعّل السياسة. وتفسر القاعدة نفسها سبب عدم تعارض systemctl stop مع سياسة إعادة التشغيل.
أين أضع StartLimitIntervalSec وStartLimitBurst؟
ضعهما في قسم [Unit]. كانت المواد القديمة وإصدارات systemd القديمة تضعهما في [Service]، ولذلك تختلف الأمثلة المنسوخة عن بعضها. لا تفترض أي قسم يعتمد عليه إصدارك. بعد systemctl daemon-reload، اطلب من systemd عرض ما حمّله باستخدام systemctl show -p StartLimitBurst -p StartLimitIntervalUSec myapp.service، وتعامل مع تلك القيم باعتبارها المرجع الفعلي. يكتشف systemd-analyze verify /etc/systemd/system/myapp.service المفاتيح التي لا يتعرف عليها systemd إطلاقاً، ولا يطبع شيئاً عندما يكون الملف سليماً.