فرض کنید یک برنامه Node.js، Python یا سرویس اختصاصی را روی سرور لینوکس راهاندازی کردهاید. سرویس برای چند ثانیه اجرا میشود، ناگهان از دسترس خارج میشود و دوباره بالا میآید. وقتی دستور systemctl status را بررسی میکنید، پیامهایی مانند activating (auto-restart)، Failed with result ‘exit-code’ یا Start request repeated too quickly را مشاهده میکنید.
در چنین شرایطی معمولاً اولین راهکاری که به ذهن میرسد، Restart کردن سرویس یا افزایش مقدار RestartSec است. اما این کار لزوماً مشکل را برطرف نمیکند؛ زیرا ممکن است برنامه بهدلیل فایل تنظیمات معیوب، دسترسی ناکافی، مسیر اجرایی اشتباه، نبود متغیر محیطی یا آمادهنبودن یک سرویس وابسته، بلافاصله بعد از اجرا بسته شود.
برای رفع مشکل systemd restart loop باید تفاوت سه موضوع را بدانیم: علت خاتمه پردازش، سیاست راهاندازی مجدد systemd و محدودیت تعداد تلاشهای Start.
در این مقاله یاد میگیریم چگونه با journalctl، systemctl show، systemd-analyze و بررسی فایل Unit، علت واقعی Restart مداوم سرویس را پیدا کنیم. همچنین خطاهای رایج ExecStart، Exit Codeهای مهم، EnvironmentFile، Dependencyها و روش اصلاح ایمن Restart Policy در Ubuntu، Debian و سایر توزیعهای مبتنی بر systemd را بررسی میکنیم.
Restart Loop در systemd چیست؟
Restart Loop زمانی رخ میدهد که یک سرویس بهطور مکرر اجرا و متوقف شود و systemd طبق سیاست تعریفشده، دوباره برای شروع آن تلاش کند.
برای مثال، ممکن است یک سرویس دارای تنظیم زیر باشد:
[Service]
Restart=on-failure
RestartSec=3s
این تنظیم به systemd میگوید در شرایطی که سرویس مطابق قواعد systemd شکست میخورد، پس از تأخیری مشخص برای راهاندازی مجدد تلاش کند.
اما اگر علت شکست، مثلاً نبود فایل تنظیمات برنامه باشد، تلاش بعدی نیز معمولاً با همان خطا مواجه میشود.
با تکرار این فرایند، ممکن است محدودیت Start Rate نیز فعال شود و systemd از تلاشهای بیشتر جلوگیری کند.
نکته مهم: Restart Loop همیشه ناشی از Crash برنامه نیست. اگر برای یک سرویس با اجرای طولانی، Restart=always تعریف شده باشد، خاتمه موفق پردازش اصلی نیز ممکن است باعث Restart شود.
سه لایهای که باید هنگام عیبیابی systemd بررسی کنیم
| لایه | سؤال اصلی | ابزار بررسی |
|---|---|---|
| اجرای برنامه | چرا پردازش اصلی متوقف شده است؟ | journalctl، Exit Code، لاگ برنامه |
| پیکربندی Unit | آیا ExecStart، Environment و Dependency درست هستند؟ | systemctl cat، systemd-analyze verify |
| سیاست Restart | چرا systemd دوباره Start میکند یا متوقف میشود؟ | Restart، RestartSec، StartLimit |
این تفکیک مانع میشود خطای اصلی برنامه را با تغییر مداوم سیاست Restart پنهان کنیم.
مرحله اول: وضعیت سرویس را بدون تغییر تنظیمات بررسی کنید
فرض میکنیم نام سرویس موردنظر myapp.service است. این نام در تمام مثالها باید با Unit واقعی جایگزین شود.
برای مشاهده وضعیت:
systemctl status myapp.service --no-pager -l
در خروجی به چند بخش توجه کنید:
- Loaded: آیا فایل Unit پیدا و بارگذاری شده است؟
- Active: وضعیت فعلی سرویس چیست؟
- Main PID: شناسه پردازش اصلی، در صورت وجود.
- Process: نتیجه فرمانهای اجرایی ثبتشده.
- Result: نتیجه کلی آخرین رخداد شکست یا وضعیت سرویس.
- status: کد خروج یا سیگنال خاتمه فرایند.
برای مثال، اگر سرویس در وضعیت activating (auto-restart) قرار دارد، systemd ممکن است منتظر پایان RestartSec برای تلاش بعدی باشد.
اگر وضعیت failed و نتیجه start-limit-hit ثبت شده باشد، محدودیت تعداد Startها فعال شده است؛ اما علت اولیه معمولاً باید در رویدادهای قدیمیتر جستوجو شود.
مرحله دوم: پیدا کردن اولین خطای واقعی با journalctl
مهمترین قسمت عیبیابی، پیدا کردن اولین پیام خطا پیش از شروع تکرارهای Restart است.
برای مشاهده ۱۵۰ خط آخر لاگ سرویس در Boot فعلی:
sudo journalctl -u myapp.service \
-b -n 150 --no-pager -o short-iso
اگر زمان شروع خرابی مشخص است:
sudo journalctl -u myapp.service \
--since "2026-11-22 08:00:00" \
--until "2026-11-22 08:30:00" \
--no-pager -o short-iso
تاریخ و ساعت نمونه باید با زمان واقعی خرابی جایگزین شود.
برای مشاهده زنده پیامها، در صورت نیاز:
sudo journalctl -fu myapp.service
اگر مشکل قبل از آخرین Reboot رخ داده و Journalهای قبلی نگهداری شدهاند، میتوان ابتدا فهرست Bootها را مشاهده کرد:
journalctl --list-boots
سپس Boot قبلی را بررسی کرد:
sudo journalctl -u myapp.service \
-b -1 --no-pager
اگر Journal پایدار فعال نباشد، ممکن است لاگ بوت قبلی وجود نداشته باشد.
نکته: فقط آخرین پیام start-limit-hit را نخوانید. چند خط یا چند تلاش قبلتر ممکن است دلیل اصلی مانند Permission denied، فایل Config نامعتبر یا Port already in use ثبت شده باشد.
مرحله سوم: بررسی Result، Exit Code و تعداد Restartها
خروجی کوتاه systemctl status همیشه برای تشخیص دقیق کافی نیست. برای مشاهده ویژگیهای مهم سرویس از systemctl show استفاده کنید.
systemctl show myapp.service \
-p ActiveState \
-p SubState \
-p Result \
-p ExecMainCode \
-p ExecMainStatus \
-p ExecMainPID \
-p NRestarts \
-p Restart \
-p RestartUSec
تفسیر این فیلدها:
| فیلد | مفهوم |
|---|---|
| ActiveState | وضعیت اصلی Unit مانند active یا failed |
| SubState | وضعیت جزئیتر مانند auto-restart |
| Result | نتیجه ثبتشده برای سرویس، مانند exit-code یا timeout |
| ExecMainCode | نوع پایان پردازش اصلی، مانند خروج عادی یا سیگنال |
| ExecMainStatus | کد خروج یا شماره سیگنال مربوط |
| ExecMainPID | شناسه پردازش اصلی ثبتشده |
| NRestarts | شمارنده Restartهای خودکار ثبتشده توسط Manager |
| Restart | سیاست Restart سرویس |
| RestartUSec | تأخیر Restart در قالب ویژگی داخلی systemd |
مقدار فعلی ExecMainStatus ممکن است پس از شروع مجدد سرویس تغییر کند. برای تحلیل دقیق یک خرابی قدیمی، لاگ همان Invocation اهمیت بیشتری دارد.
همچنین NRestarts نباید بدون بررسی زمان بارگذاری Unit و نسخه systemd بهعنوان تعداد کل Restartها در تمام عمر سرور تفسیر شود.
مرحله چهارم: معنی Exit Codeهای مهم systemd
وقتی در لاگ عبارتی مانند زیر مشاهده میکنید:
Main process exited, code=exited, status=1/FAILURE
این پیام نشان میدهد پردازش اصلی با کد خروج ۱ خاتمه پیدا کرده است. اما علت دقیق، به برنامه و لاگ آن وابسته است.
از طرف دیگر، بعضی کدهای خروج توسط خود systemd برای خطاهای آمادهسازی محیط اجرای برنامه تعریف شدهاند.
| کد یا وضعیت | تفسیر رایج | چه چیزی بررسی شود؟ |
|---|---|---|
| 0/SUCCESS | خاتمه موفق پردازش | آیا سرویس باید دائماً اجرا شود؟ Restart=always فعال است؟ |
| 1/FAILURE | شکست عمومی برنامه | لاگ خود برنامه و پارامترهای اجرای آن |
| 2 | خطای تعریفشده توسط برنامه یا ابزار | مستندات همان برنامه |
| 200/CHDIR | شکست تغییر WorkingDirectory | وجود مسیر و مجوز دسترسی |
| 203/EXEC | شکست اجرای فرمان تنظیمشده | مسیر، مجوز اجرا، Interpreter و فایل اجرایی |
| 217/USER | شکست آمادهسازی هویت کاربر | User و وضعیت حساب مربوط |
| signal=KILL | خاتمه با SIGKILL | OOM، مدیر سیستم یا عامل دیگر |
| Result=timeout | پایان ناموفق بهعلت Timeout مربوط به Unit | TimeoutStartSec، Startup و سرویس وابسته |
| Result=start-limit-hit | عبور از محدودیت تعداد Start | خطاهای قبلی و StartLimit |
جدول فوق برای تشخیص اولیه است. بسیاری از کدهای خروج برنامهها اختصاصی هستند و معنی آنها باید از مستندات همان برنامه استخراج شود.
برای مشاهده شرح کدهای خروج، در نسخههای پشتیبانیکننده systemd:
systemd-analyze exit-status 203
منبع:
مستندات systemd.exec و Process Exit Codes.
تفاوت Result با ExecMainStatus چیست؟
این دو فیلد یک معنا ندارند.
ExecMainStatus درباره نتیجه پایان پردازش اصلی اطلاعات میدهد؛ اما Result نتیجه کلی وضعیت سرویس را نشان میدهد.
برای مثال، ممکن است برنامه با کد خروج ۱ متوقف شود و Result برابر exit-code ثبت شود.
در سناریوی دیگر، برنامه چند بار با خطا خاتمه مییابد، systemd تلاش به Restart را تکرار میکند و در نهایت محدودیت Start فعال میشود. در این حالت ممکن است Result فعلی برابر start-limit-hit باشد.
پس برای تحلیل دقیق، نتیجه آخرین وضعیت سرویس را همراه با Exit Code و لاگ زمان اولین خرابی بررسی کنید.
مرحله پنجم: خطای Start request repeated too quickly چیست؟
این پیام معمولاً نشان میدهد تعداد تلاشهای Start سرویس در یک بازه زمانی از محدودیت تعیینشده عبور کرده است.
دو تنظیم مهم در بخش Unit عبارتاند از:
[Unit]
StartLimitIntervalSec=60s
StartLimitBurst=5
در این مثال، تعداد Startها در بازه مشخص محدود میشود. این اعداد نمونه هستند و به معنی پیشفرض ثابت در همه نسخههای systemd نیستند.
StartLimit فقط برای Restart خودکار نیست؛ شروعهای دستی نیز ممکن است تحت تأثیر همین محدودیت قرار بگیرند.
نکته مهم: این تنظیمات معمولاً در بخش [Unit] قرار میگیرند؛ درحالیکه Restart و RestartSec مربوط به بخش [Service] هستند.
منبع:
systemd.unit – StartLimitIntervalSec و StartLimitBurst.
مرحله ششم: بررسی مقدار مؤثر StartLimit
برای مشاهده مقادیر فعلی Unit:
systemctl show myapp.service \
-p StartLimitIntervalUSec \
-p StartLimitBurst \
-p StartLimitAction \
-p Restart \
-p RestartUSec
اگر StartLimit در فایل Unit اصلی تنظیم نشده باشد، ممکن است مقدار مؤثر از تنظیمات Manager یا پیکربندی دیگری به دست آمده باشد.
برای دیدن تنظیمات تعریفشده در Unit و Drop-inها:
systemctl cat myapp.service
این خروجی را قبل از انتشار عمومی بررسی کنید؛ زیرا ممکن است Unit شامل Environment یا آرگومانهایی با اطلاعات حساس باشد.
آیا systemctl reset-failed مشکل را حل میکند؟
دستور زیر در شرایط مناسب میتواند وضعیت Failed و شمارنده محدودیت Start را بازنشانی کند:
sudo systemctl reset-failed myapp.service
اما این دستور فایل اجرایی معیوب، تنظیمات نادرست یا وابستگی از دسترس خارجشده را اصلاح نمیکند.
اگر علت اصلی همچنان باقی باشد، تلاش بعدی Start نیز ممکن است شکست بخورد و Restart Loop دوباره آغاز شود.
روش صحیح: ابتدا علت شکست را پیدا و اصلاح کنید. سپس، در صورت نیاز، با reset-failed شمارنده را پاک کنید و سرویس را بهصورت کنترلشده Start کنید.
از اجرای خودکار و مکرر reset-failed توسط Cron برای پنهانکردن خرابی برنامه خودداری کنید.
مرحله هفتم: تفاوت Restart=always و Restart=on-failure
مقدار Restart مشخص میکند systemd در چه شرایطی برای راهاندازی مجدد سرویس تلاش کند.
| مقدار | رفتار کلی | کاربرد |
|---|---|---|
| no | Restart خودکار انجام نمیشود | سرویسهایی که بازیابی خودکار نمیخواهند |
| on-success | Restart پس از خاتمه موفق طبق قواعد systemd | کاربردهای خاص |
| on-failure | Restart پس از شکست تعریفشده | بسیاری از سرویسهای بلندمدت |
| on-abnormal | Restart در برخی پایانهای غیرعادی مانند سیگنال یا Timeout | سیاستهای خاص بازیابی |
| on-abort | Restart در شرایط خاتمه با سیگنالهای خاص | نیازمند بررسی دقیق |
| on-watchdog | Restart در شرایط شکست Watchdog | سرویسهای دارای Watchdog |
| always | Restart در دامنه گستردهای از خاتمهها، حتی خروج موفق | برنامههای دائمی با نیاز مشخص |
رفتار دقیق هر گزینه، استثناها و تعامل آن با SuccessExitStatus یا RestartPreventExitStatus باید با نسخه systemd بررسی شود.
همچنین توقف صریح سرویس با systemctl stop معمولاً نباید با Restart ناشی از Crash اشتباه گرفته شود.
اگر یک اسکریپت کوتاه بعد از انجام کار با کد صفر خاتمه مییابد، تعریف Restart=always برای آن ممکن است باعث اجرای تکراری و ناخواسته کار شود.
منبع:
systemd.service – Restart Policy.
مرحله هشتم: تنظیم RestartSec چه کمکی میکند؟
RestartSec مدت انتظار قبل از تلاش مجدد برای Start سرویس را کنترل میکند.
برای مثال:
[Service]
Restart=on-failure
RestartSec=5s
این تنظیم میتواند از تکرار بسیار سریع Start جلوگیری کند، فشار تلاشهای متوالی را کاهش دهد و فرصت کوتاهی برای بازیابی یک وابستگی فراهم کند.
اما اگر برنامه به دلیل خطای ثابت Config بسته میشود، افزایش RestartSec فقط فاصله بین شکستها را تغییر میدهد.
همچنین در نسخههای جدیدتر systemd گزینههای پیشرفتهتری برای مدیریت فاصله Restart وجود دارد. پشتیبانی این قابلیتها باید با نسخه نصبشده بررسی شود.
پیشنهاد عملی: RestartSec را براساس زمان بازیابی واقعی سرویس، حساسیت Workload و سیاست مانیتورینگ انتخاب کنید؛ نه صرفاً برای حذف هشدارها.
مرحله نهم: بررسی ExecStart؛ یکی از رایجترین علتهای Restart Loop
گزینه ExecStart فرمان اصلی اجرای سرویس را مشخص میکند.
اگر مسیر فایل اجرایی اشتباه باشد، برنامه وجود نداشته باشد، Interpreter قابل دسترسی نباشد یا مجوز اجرا تنظیم نشده باشد، سرویس ممکن است پیش از اجرای موفق برنامه شکست بخورد.
برای مشاهده ExecStart مؤثر:
systemctl show myapp.service -p ExecStart
systemctl cat myapp.service
مثال یک سرویس Python:
[Service]
Type=simple
User=myapp
WorkingDirectory=/opt/myapp
ExecStart=/opt/myapp/venv/bin/python /opt/myapp/app.py
Restart=on-failure
RestartSec=5s
این Unit فقط یک نمونه آموزشی است. فرض میکند کاربر myapp، محیط مجازی Python، فایل برنامه و مسیر کاری از قبل بهدرستی ایجاد شدهاند.
اگر Python در مسیر دیگری نصب شده یا برنامه بهروزرسانی شده باشد، ExecStart باید با ساختار واقعی محیط تطبیق داده شود.
خطای status=203/EXEC در systemd چگونه رفع میشود؟
کد 203/EXEC معمولاً نشان میدهد systemd نتوانسته فرمان موردنظر را در مرحله اجرای پردازش راهاندازی کند.
برای نمونه، اگر ExecStart به مسیر زیر اشاره میکند:
/opt/myapp/start.sh
ابتدا وضعیت مسیر را بررسی کنید:
ls -l /opt/myapp/start.sh
file /opt/myapp/start.sh
head -n 1 /opt/myapp/start.sh
namei -l /opt/myapp/start.sh
در بررسی خطای 203/EXEC موارد زیر اهمیت دارند:
- فایل اجرایی واقعاً وجود داشته باشد.
- مجوز مناسب برای اجرای فایل تعریف شده باشد.
- تمام پوشههای مسیر برای کاربر سرویس قابل پیمایش باشند.
- مسیر Interpreter در Shebang معتبر باشد.
- فایل از نظر قالب اجرایی و معماری با سیستم سازگار باشد.
- محدودیتهایی مانند Mount با گزینه noexec بررسی شوند.
- در صورت استفاده از RootDirectory یا sandbox، فایل اجرایی داخل محیط اجرا قابل دسترسی باشد.
اگر فایل روی ویندوز تهیه شده است، پایان خط CRLF نیز ممکن است باعث مشکل در تشخیص Interpreter یک اسکریپت Shell شود.
نکته: همه خطاهای 203/EXEC با chmod +x حل نمیشوند. ابتدا باید پیام دقیق Journal و دلیل شکست execve بررسی شود.
خطای status=200/CHDIR؛ مشکل WorkingDirectory
اگر در Unit مقدار WorkingDirectory تعریف شده، systemd باید پیش از اجرای برنامه به آن مسیر دسترسی پیدا کند.
برای مثال:
[Service]
WorkingDirectory=/opt/myapp
اگر این مسیر وجود نداشته باشد یا شرایط دسترسی مناسب نباشد، ممکن است کد 200/CHDIR ثبت شود.
برای بررسی:
ls -ld /opt/myapp
namei -l /opt/myapp
systemctl show myapp.service -p WorkingDirectory
وجود مسیر کافی نیست؛ کاربر سرویس باید بتواند به آن وارد شود. همچنین در Unitهایی با RootDirectory یا RootImage، مسیر کاری نسبت به محیط اجرای تعریفشده تفسیر میشود.
خطای status=217/USER؛ بررسی حساب کاربری سرویس
اگر systemd نتواند اطلاعات کاربر تعیینشده برای اجرای سرویس را بهدرستی آماده کند، ممکن است خطای USER ثبت شود.
ابتدا مقدار User و Group را بررسی کنید:
systemctl show myapp.service \
-p User \
-p Group \
-p DynamicUser
اگر Unit از کاربر ثابت myapp استفاده میکند:
getent passwd myapp
id myapp
اگر کاربر وجود ندارد، پیکربندی اشتباه است یا سرویس به منابع هویتی خارجی وابسته است، باید علت را بررسی کرد.
حذف User از فایل Unit برای اجرای برنامه بهصورت Root، راهکار امنی برای رفع این خطا نیست.
مرحله دهم: بررسی Environment و EnvironmentFile
بسیاری از برنامهها برای شروع به متغیرهایی مانند آدرس دیتابیس، مسیر Config، نام محیط اجرایی یا کلیدهای اتصال نیاز دارند.
اگر برنامه هنگام اجرای دستی از ترمینال درست کار میکند اما داخل systemd بسته میشود، تفاوت محیط اجرا یکی از موارد مهم برای بررسی است.
در یک Unit ممکن است تنظیم زیر وجود داشته باشد:
[Service]
Environment=APP_ENV=production
EnvironmentFile=/etc/myapp/myapp.env
اگر فایل محیطی موردنیاز وجود نداشته باشد، امکان دارد سرویس پیش از اجرای موفق برنامه با شکست مواجه شود.
برای مشاهده مسیر فایل EnvironmentFile:
systemctl show myapp.service \
-p EnvironmentFiles \
-p WorkingDirectory \
-p User
اگر فایل محیطی در مسیر زیر قرار دارد، وجود و مجوز آن را بدون چاپ محتوای محرمانه بررسی کنید:
sudo stat -c '%n %a %U:%G' \
/etc/myapp/myapp.env
یک نکته مهم این است که تنظیم EnvironmentFile=-/path/file با وجود علامت منفی در ابتدای مسیر، نبود فایل را در شرایط مربوط نادیده میگیرد. بنابراین باید مشخص شود فایل اختیاری است یا واقعاً برای اجرای برنامه ضروری است.
در مورد Secretها، استفاده از قابلیتهای مناسب Credential Management در systemd و سازوکار امن برنامه باید بررسی شود. قرار دادن رمزهای عبور در Unit و نمایش خروجی کامل Environment برای عیبیابی عمومی مناسب نیست.
چرا برنامه دستی اجرا میشود اما با systemd نه؟
اجرای دستی برنامه از Shell معمولاً با محیطی متفاوت از محیط systemd انجام میشود.
برای مثال، ممکن است کاربر شما هنگام Login دارای PATH، Virtual Environment، متغیرهای Shell یا مسیر کاری متفاوتی باشد.
در مقابل، systemd سرویس را طبق مقادیر Unit و سیاستهای خودش اجرا میکند.
پس وقتی برنامه دستی موفق اما سرویس ناموفق است، موارد زیر را مقایسه کنید:
- مسیر واقعی فایل اجرایی.
- کاربر و گروه اجراکننده.
- WorkingDirectory.
- متغیرهای محیطی ضروری.
- مجوز خواندن فایلهای برنامه و Config.
- امکان دسترسی به Socket یا Port موردنیاز.
- محدودیتهای Security و Sandbox تعریفشده برای Unit.
اجرای برنامه با sudo و حساب Root فقط برای اینکه «کار کند»، آزمایش معادلی با محیط واقعی سرویس نیست و ممکن است ریسک امنیتی ایجاد کند.
مرحله یازدهم: بررسی Dependencyهای systemd
گاهی برنامه بلافاصله پس از Boot شروع میشود، اما دیتابیس، شبکه یا سرویس دیگری هنوز آماده پاسخگویی نیست.
در این شرایط، برنامه ممکن است با خطای Connection refused، Timeout یا خطای داخلی خودش خاتمه یابد و Restart Loop آغاز شود.
برای مشاهده وابستگیهای Unit:
systemctl show myapp.service \
-p Wants \
-p Requires \
-p After \
-p Before
برای مشاهده درخت وابستگیها:
systemctl list-dependencies myapp.service
تفاوت مهم این گزینهها:
| گزینه | کاربرد کلی |
|---|---|
| After= | ترتیب اجرای Jobها را مشخص میکند |
| Wants= | وابستگی ضعیف برای فعالکردن Unitهای دیگر |
| Requires= | وابستگی قویتر با قواعد مشخص شکست یا توقف |
| Before= | ترتیب اجرای Job را در جهت مقابل مشخص میکند |
نکته بسیار مهم: وجود After=network.target یا After=postgresql.service بهتنهایی تضمین نمیکند شبکه خارجی یا دیتابیس از دید برنامه آماده پاسخگویی باشد.
آمادهبودن واقعی یک Dependency ممکن است به Health Check، سازوکار Retry داخل برنامه یا Unit مناسبتری مانند Type=notify وابسته باشد.
مثال: سرویس بهدلیل آمادهنبودن دیتابیس Restart میشود
فرض کنید برنامه با شروع کار تلاش میکند به PostgreSQL متصل شود. اگر دیتابیس هنوز آماده نیست، برنامه با کد خروج ۱ خاتمه پیدا میکند.
برای شروع عیبیابی:
systemctl status postgresql.service --no-pager
journalctl -u myapp.service -b -n 100 --no-pager
journalctl -u postgresql.service -b -n 100 --no-pager
در سیستمهایی که PostgreSQL بهصورت Cluster یا Unit اختصاصی مدیریت میشود، نام سرویس واقعی ممکن است متفاوت باشد.
اگر لاگ برنامه خطای اتصال به دیتابیس را نشان میدهد، باید وضعیت سرویس مقصد، آدرس، Port، Credential و زمان آمادهشدن آن بررسی شود.
اضافهکردن After=postgresql.service ممکن است بخشی از مشکل ترتیب راهاندازی را حل کند، اما جایگزین مکانیزم Retry سالم در خود برنامه نیست.
مرحله دوازدهم: بررسی ExecStartPre و سایر فرمانهای Unit
در بعضی Unitها، پیش از اجرای برنامه اصلی، دستورهایی با ExecStartPre تعریف شدهاند.
برای مثال، ممکن است یک دستور پیشنیاز برای ایجاد پوشه، آمادهسازی تنظیمات یا اعتبارسنجی اجرا شود.
اگر همان دستور شکست بخورد، ممکن است برنامه اصلی هرگز اجرا نشود.
برای بررسی وضعیت فرمانها:
systemctl show myapp.service \
-p ExecCondition \
-p ExecStartPre \
-p ExecStart \
-p ExecStartPost
در این شرایط نباید بهصورت خودکار فرض کرد ExecMainStatus علت تمام شکستها را توضیح میدهد؛ زیرا ممکن است خطا پیش از شروع پردازش اصلی رخ داده باشد.
همچنین رفتار ExecCondition با ExecStartPre یکسان نیست و بعضی خروجیهای ExecCondition میتوانند باعث ردشدن شروع سرویس بدون علامتگذاری آن بهعنوان Failed شوند.
مرحله سیزدهم: آیا Type سرویس بهدرستی تنظیم شده است؟
گزینه Type مشخص میکند systemd چگونه شروع و آمادهشدن سرویس را تشخیص دهد.
بعضی مقادیر پرکاربرد عبارتاند از:
| Type | کاربرد معمول |
|---|---|
| simple | برنامههای بلندمدت که پردازش اصلی آنها در پیشزمینه میماند |
| exec | مشابه simple با گزارش دقیقتر برخی خطاهای مرحله اجرای فرمان |
| forking | برنامههایی که طبق الگوی Daemon قدیمی Fork میکنند |
| oneshot | فرمانهایی که یک کار مشخص انجام میدهند و پایان مییابند |
| notify | برنامههایی که آمادهبودن خود را با پروتکل اعلان systemd گزارش میکنند |
اگر یک برنامه کوتاهمدت را بهعنوان سرویس دائمی با Restart=always تعریف کنید، ممکن است پس از خاتمه موفق، دوباره اجرا شود.
در مقابل، اگر برنامهای باید در پیشزمینه باقی بماند اما خودش Daemonize شود، ممکن است systemd پردازش اصلی را بهدرستی دنبال نکند.
برای بررسی:
systemctl show myapp.service \
-p Type \
-p MainPID \
-p PIDFile \
-p RemainAfterExit
Type مناسب باید براساس رفتار واقعی برنامه و مستندات آن انتخاب شود.
مرحله چهاردهم: بررسی OOM، محدودیت RAM و Resource Limits
گاهی برنامه بهدلیل کمبود منابع یا محدودیت حافظه سرویس متوقف میشود و systemd دوباره آن را اجرا میکند.
برای بررسی مصرف و محدودیت حافظه:
systemctl show myapp.service \
-p MemoryCurrent \
-p MemoryMax \
-p MemoryHigh \
-p OOMPolicy \
-p Result
برای بررسی پیامهای مربوط به OOM:
sudo journalctl -k -b --no-pager |
grep -Ei 'out of memory|oom-kill|killed process'
اگر پردازش با SIGKILL خاتمه یافته، لزوماً نمیتوان نتیجه گرفت OOM Killer عامل آن است؛ باید Kernel Journal و وضعیت cgroup نیز بررسی شوند.
این موضوع در مقاله مستقل «رفع مشکل OOM Killer در لینوکس با وجود RAM آزاد» بهصورت کامل بررسی شده است.
مرحله پانزدهم: بررسی Port، Permission و فایلهای موردنیاز
یک سرویس ممکن است بهدلیل اشغالبودن پورت موردنیاز، مجوز ناکافی برای فایل یا پوشه، یا نبود فایل Config بلافاصله بسته شود.
برای مثال، اگر برنامه باید روی پورت 8080 اجرا شود:
sudo ss -lntp '( sport = :8080 )'
اگر پورت از قبل توسط برنامه دیگری استفاده میشود، باید مشخص شود آن پردازش قانونی است یا نمونه قدیمی همین سرویس.
برای بررسی فایل Config نمونه:
ls -l /etc/myapp/config.yml
namei -l /etc/myapp/config.yml
این مسیر نمونه است و باید با فایل واقعی برنامه جایگزین شود.
اگر سرویس دارای محدودیتهای ProtectSystem، ReadWritePaths، PrivateTmp یا سایر گزینههای Sandbox است، باید تأثیر آنها بر مسیرهای لازم نیز بررسی شود.
برای رفع خطا، مجوز 777 یا اجرای برنامه با Root را بهصورت عمومی پیشنهاد نمیکنیم؛ دسترسی باید بهاندازه نیاز واقعی سرویس باشد.
مرحله شانزدهم: اعتبارسنجی فایل Unit پیش از اعمال تغییرات
اگر مشخص شد پیکربندی Unit باید اصلاح شود، بهتر است ابتدا از روشهای پشتیبانیشده systemd برای مشاهده و ویرایش استفاده کنید.
برای بررسی فایل اصلی و Drop-inها:
systemctl cat myapp.service
systemctl show myapp.service \
-p FragmentPath \
-p DropInPaths
برای بررسی برخی خطاهای پیکربندی Unit:
systemd-analyze verify myapp.service
این دستور میتواند بعضی اشکالات فایل Unit و وابستگیها را پیدا کند؛ اما موفقیت آن تضمین نمیکند برنامه، دیتابیس، فایلهای Config یا شبکه هنگام اجرا سالم باشند.
همچنین اگر تنظیمات توسط بسته سیستمعامل مدیریت میشود، بهتر است بهجای ویرایش مستقیم فایل اصلی بسته، از Drop-in مناسب استفاده شود.
مرحله هفدهم: نمونه تنظیم ایمن Restart Policy با Drop-in
در این مرحله فرض میکنیم علت اصلی شکست برنامه پیدا و اصلاح شده است و فقط لازم است سیاست Restart سرویس متناسب با نیاز عملیاتی تنظیم شود.
برای ایجاد Drop-in سرویس، در صورت مجازبودن تغییرات:
sudo systemctl edit myapp.service
نمونه تنظیم آموزشی:
[Unit]
StartLimitIntervalSec=60s
StartLimitBurst=5
[Service]
Restart=on-failure
RestartSec=5s
این مقادیر برای همه سرویسها مناسب نیستند و باید براساس نوع برنامه، زمان راهاندازی و سیاست مانیتورینگ تعیین شوند.
پس از ویرایش، در صورت نیاز به اعمال تغییرات و با داشتن دسترسی بازیابی:
sudo systemctl daemon-reload
systemd-analyze verify myapp.service
اگر علت خرابی برطرف شده و شرایط Start امن است، میتوان بعد از بررسی وضعیت، سرویس را بهصورت کنترلشده اجرا کرد:
sudo systemctl reset-failed myapp.service
sudo systemctl start myapp.service
systemctl status myapp.service --no-pager -l
هشدار: قبل از اجرای این دستورها روی سرور عملیاتی، وابستگیها، حساسیت برنامه و امکان بازیابی را بررسی کنید. هر Start میتواند اثر عملیاتی داشته باشد؛ برای مثال اجرای دوباره Job، مصرف منابع یا تلاش مجدد اتصال به سرویس خارجی.
چگونه مطمئن شویم Restart Loop واقعاً برطرف شده است؟
فعالشدن سرویس برای چند ثانیه کافی نیست. باید بررسی شود برنامه در بازه مناسب پایدار مانده و دوباره Restart نشده است.
برای مشاهده وضعیت و شمارنده Restart:
systemctl show myapp.service \
-p ActiveState \
-p SubState \
-p Result \
-p MainPID \
-p NRestarts
در صورت داشتن Health Check رسمی برنامه، آن را نیز اجرا کنید. سرویس ممکن است از دید systemd در حالت active باشد اما هنوز درخواستهای واقعی را بهدرستی پاسخ ندهد.
اگر علت خرابی قبلاً آمادهنبودن دیتابیس یا سرویس دیگر بوده، وضعیت عملکرد برنامه بعد از Reboot و در شرایط راهاندازی عادی نیز باید بررسی شود.
اسکریپت یکپارچه و کمریسک عیبیابی systemd Restart Loop
اسکریپت زیر اطلاعات اصلی Unit، وضعیت Restart، Result، Exit Code، مسیر ExecStart، محدودیت Start و پیامهای اخیر Journal را جمعآوری میکند.
این نسخه هیچ سرویسی را Start، Stop یا Restart نمیکند؛ شمارندهها را Reset نمیکند و فایلهای پیکربندی را تغییر نمیدهد.
برای جلوگیری از انتشار Secretهای موجود در Environment، مقادیر متغیرهای محیطی چاپ نمیشوند. همچنین باید توجه کرد که آرگومانهای بعضی فرمانهای اجرایی یا لاگ خود برنامه ممکن است حاوی داده حساس باشند.
#!/usr/bin/env bash
set -u
SERVICE="${1:-}"
if [ -z "$SERVICE" ]; then
echo "Usage: $0 service-name.service"
exit 1
fi
echo "===== DATE ====="
date --iso-8601=seconds
echo "===== SYSTEMD VERSION ====="
systemctl --version | head -n 1
echo "===== UNIT LOAD STATE ====="
systemctl show "$SERVICE" \
-p LoadState \
-p FragmentPath \
-p DropInPaths
echo "===== SERVICE STATUS ====="
systemctl status "$SERVICE" \
--no-pager -l || true
echo "===== MAIN PROCESS RESULT ====="
systemctl show "$SERVICE" \
-p ActiveState \
-p SubState \
-p Result \
-p ExecMainCode \
-p ExecMainStatus \
-p ExecMainPID \
-p MainPID \
-p NRestarts
echo "===== RESTART POLICY ====="
systemctl show "$SERVICE" \
-p Restart \
-p RestartUSec \
-p StartLimitIntervalUSec \
-p StartLimitBurst \
-p StartLimitAction
echo "===== EXECUTION SETTINGS ====="
systemctl show "$SERVICE" \
-p Type \
-p User \
-p Group \
-p WorkingDirectory \
-p ExecStart
echo "===== DEPENDENCIES ====="
systemctl show "$SERVICE" \
-p Wants \
-p Requires \
-p After \
-p Before
echo "===== MEMORY LIMITS ====="
systemctl show "$SERVICE" \
-p MemoryMax \
-p MemoryHigh \
-p OOMPolicy
echo "===== RECENT JOURNAL ====="
journalctl -u "$SERVICE" \
-b -n 120 \
--no-pager -o short-iso || true
echo "===== DIAGNOSTICS FINISHED ====="
echo "No service state was changed."
فایل را با نام systemd-restart-check.sh ذخیره کنید و پس از بررسی محتوا، نام Unit را بهعنوان آرگومان بدهید.
این اسکریپت برای جمعآوری شواهد اولیه طراحی شده است. اگر سرویس در بوت قبلی خراب شده باشد، لازم است Journal مربوط به همان Boot بهصورت جداگانه بررسی شود.
جدول تشخیص سریع علت Restart مداوم سرویس
| پیام یا وضعیت | علت محتمل | اقدام مناسب |
|---|---|---|
| status=203/EXEC | مشکل اجرای فایل اصلی | بررسی مسیر، مجوز، Shebang و Interpreter |
| status=200/CHDIR | WorkingDirectory نامعتبر یا غیرقابلدسترسی | بررسی مسیر و مجوز پوشهها |
| status=217/USER | مشکل حساب کاربری اجرای سرویس | بررسی User، Group و سیستم هویت |
| status=1/FAILURE | خطای داخلی برنامه | بررسی نخستین Error در Journal و لاگ برنامه |
| Result=start-limit-hit | عبور از محدودیت Start | رفع خطای اولیه و سپس reset-failed در صورت نیاز |
| Result=timeout | تکمیلنشدن عملیات در زمان مجاز | بررسی Timeout و مرحله Startup |
| code=killed, signal=KILL | خاتمه با SIGKILL | بررسی OOM، منابع و عامل خاتمه |
| status=0/SUCCESS و Restart مداوم | Restart=always یا طراحی اشتباه Unit | بررسی Type و رفتار برنامه کوتاهمدت |
| Connection refused هنگام Startup | آمادهنبودن سرویس وابسته یا تنظیم اتصال اشتباه | بررسی Dependency، Port و Health Check |
| Permission denied در لاگ برنامه | مجوز نامناسب فایل یا Sandbox | بررسی User، مسیر و سیاستهای امنیتی Unit |
| Environment file missing | فایل محیطی موردنیاز پیدا نشده | بررسی EnvironmentFile و مسیر فایل |
| Program runs manually, fails in systemd | تفاوت محیط اجرا یا کاربر | مقایسه ExecStart، PATH، WorkingDirectory و Environment |
۱۰ اشتباه رایج هنگام رفع systemd Restart Loop
۱. افزایش StartLimit بدون پیدا کردن علت شکست
این کار ممکن است فقط اجازه دهد سرویس دفعات بیشتری با همان خطا متوقف شود.
۲. استفاده از reset-failed بهعنوان راهکار دائمی
reset-failed خطای برنامه یا تنظیمات Unit را اصلاح نمیکند.
۳. تغییر Restart=always برای تمام سرویسها
ممکن است باعث اجرای تکراری برنامههایی شود که باید پس از اتمام کار متوقف شوند.
۴. بررسی نکردن اولین خطای Journal
آخرین پیام معمولاً نتیجه چندین شکست قبلی است، نه دلیل اولیه.
۵. اجرای سرویس با Root برای رفع Permission
این کار ممکن است مشکل را پنهان کرده و سطح دسترسی غیرضروری ایجاد کند.
۶. فرض اینکه status=203/EXEC همیشه مشکل chmod است
مسیر نامعتبر، Interpreter، معماری و گزینههای Mount نیز میتوانند نقش داشته باشند.
۷. نادیده گرفتن EnvironmentFile و WorkingDirectory
محیط سرویس systemd الزاماً شبیه Shell تعاملی مدیر سرور نیست.
۸. تصور اینکه After= آمادهبودن واقعی سرویس وابسته را تضمین میکند
ترتیب Start با Health Check برنامه متفاوت است.
۹. تغییر Unit بدون اعتبارسنجی
systemd-analyze verify میتواند بخشی از خطاهای پیکربندی را پیش از اعمال تغییرات شناسایی کند.
۱۰. تأیید موفقیت فقط براساس active شدن لحظهای
باید پایداری سرویس و عملکرد واقعی آن در بازه مناسب بررسی شود.
سؤالات متداول درباره systemd Restart Loop
چرا سرویس systemd مدام Restart میشود؟
ممکن است برنامه بهدلیل خطای اجرا، تنظیمات معیوب، وابستگی آمادهنشده یا محدودیت منابع بسته شود و سیاست Restart باعث اجرای مجدد آن شود.
خطای Start request repeated too quickly چیست؟
این خطا نشان میدهد تعداد تلاشهای Start از محدودیت تعریفشده در بازه زمانی مربوط عبور کرده است.
تفاوت StartLimitBurst و RestartSec چیست؟
StartLimitBurst تعداد شروعهای مجاز در بازه مربوط را محدود میکند؛ RestartSec فاصله زمانی بین تلاشهای Restart را تنظیم میکند.
دستور reset-failed چه کاری انجام میدهد؟
وضعیت شکست Unit و شمارنده محدودیت Start را بازنشانی میکند، اما علت اصلی خطا را برطرف نمیکند.
چگونه Exit Code سرویس را ببینیم؟
از systemctl status و systemctl show با فیلدهای ExecMainCode، ExecMainStatus و Result استفاده کنید.
خطای 203/EXEC در systemd چیست؟
معمولاً نشان میدهد اجرای فرمان تنظیمشده شکست خورده و باید مسیر فایل اجرایی، مجوز، Interpreter و محیط اجرا بررسی شود.
خطای 200/CHDIR چیست؟
به شکست تغییر مسیر کاری تعریفشده در WorkingDirectory مربوط است.
چرا برنامه دستی اجرا میشود ولی بهعنوان سرویس systemd نه؟
ممکن است کاربر اجراکننده، PATH، متغیرهای محیطی، مسیر کاری یا مجوزهای فایلها متفاوت باشند.
آیا افزایش RestartSec مشکل را حل میکند؟
اگر علت شکست موقتی باشد ممکن است کمک کند، اما خطاهای ثابت Config یا فایل اجرایی را برطرف نمیکند.
چگونه بفهمیم مشکل systemd Service واقعاً رفع شده است؟
علاوه بر بررسی active شدن Unit، باید شمارنده Restart، Journal و Health Check واقعی برنامه را در بازه مناسب کنترل کرد.
جمعبندی؛ Restart Loop را از ریشه برطرف کنیم
اگر سرویس systemd مدام Restart میشود، ابتدا باید علت خاتمه پردازش اصلی را پیدا کنید. بررسی Result، ExecMainStatus و Journal کمک میکند مشخص شود خطا مربوط به اجرای برنامه، مجوزها، Environment، Dependency یا منابع سیستم است.
اگر پیام Start request repeated too quickly نمایش داده میشود، باید بدانید که این محدودیت معمولاً نتیجه تلاشهای ناموفق قبلی است. افزایش StartLimit یا اجرای مداوم reset-failed بدون رفع خطای اصلی، راهکار پایداری نیست.
بعد از شناسایی مشکل، فایل Unit را بهصورت کنترلشده اصلاح کنید، پیکربندی را اعتبارسنجی کنید و تنها در صورت مناسببودن شرایط، سرویس را مجدداً اجرا کنید.
در پایان، علاوه بر وضعیت active، سلامت واقعی برنامه، پاسخگویی سرویس و توقف روند Restartهای غیرضروری را بررسی کنید.
اصل نهایی: در عیبیابی systemd restart loop، اول علت شکست برنامه را اصلاح کنید و بعد سیاست Restart را تنظیم کنید؛ نه برعکس.






دیدگاهها (۰)