عیب‌یابی و رفع خطاهای رایج در Docker Compose: راهنمای عملی

دنیای توسعه نرم‌افزار مدرن به سرعت در حال حرکت به سمت کانتینرسازی و استفاده از میکروسرویس‌ها است و Docker Compose به عنوان ابزاری حیاتی برای تعریف و اجرای برنامه‌های چند کانتینری در این اکوسیستم نقش محوری ایفا می‌کند. این ابزار به توسعه‌دهندگان و مهندسان DevOps این امکان را می‌دهد که با یک فایل YAML ساده، تمامی سرویس‌های مورد نیاز یک اپلیکیشن (مانند وب‌سرور، دیتابیس، کش، صف پیام و غیره) را همراه با وابستگی‌ها، شبکه‌ها و ولوم‌هایشان پیکربندی و مدیریت کنند. سهولت استفاده و قدرت بالای Docker Compose آن را به انتخابی محبوب برای محیط‌های توسعه، تست و حتی استقرار در مقیاس کوچک تبدیل کرده است.

با این حال، همانند هر ابزار پیچیده‌ای، کار با Docker Compose نیز می‌تواند با چالش‌ها و خطاهای خاص خود همراه باشد. از خطاهای نحوی ساده در فایل YAML گرفته تا مشکلات پیچیده مربوط به شبکه، دسترسی‌ها، یا وابستگی‌های سرویس‌ها، هر یک از این مسائل می‌توانند روند توسعه و استقرار را مختل کرده و زمان زیادی را برای عیب‌یابی صرف کنند. برای متخصصان سئو که به دنبال ارائه محتوای باکیفیت و تخصصی هستند، درک عمیق این خطاها و روش‌های رفع آن‌ها ضروری است تا بتوانند راهنماهای جامعی ارائه دهند که کاربران را به وب‌سایت آن‌ها جذب کند.

هدف این راهنمای جامع و عملی، بررسی دقیق رایج‌ترین خطاهایی است که ممکن است در حین کار با Docker Compose با آن‌ها روبرو شوید. ما به تفکیک به هر نوع خطا، علائم آن، دلایل ریشه‌ای و مهم‌تر از همه، راهکارهای عملی و گام به گام برای عیب‌یابی و رفع آن‌ها خواهیم پرداخت. این راهنما به شما کمک می‌کند تا با اتخاذ یک رویکرد سیستماتیک، نه تنها خطاهای موجود را برطرف کنید، بلکه با رعایت بهترین شیوه‌ها، از بروز بسیاری از آن‌ها در آینده نیز جلوگیری نمایید. با ما همراه باشید تا تسلط خود را بر Docker Compose افزایش داده و فرآیند توسعه و استقرار خود را روان‌تر و کارآمدتر سازید.

1. خطاهای نحوی در فایل Docker Compose (YAML Syntax Errors)

یکی از متداول‌ترین و در عین حال ابتدایی‌ترین خطاهایی که کاربران Docker Compose با آن مواجه می‌شوند، خطاهای نحوی در فایل docker-compose.yml است. YAML (Yet Another Markup Language) یک زبان پیکربندی حساس به فضای خالی (whitespace-sensitive) است که ساختار داده را با استفاده از ایندنتاسیون (فرورفتگی) تعریف می‌کند. یک کاراکتر فضای خالی اضافه یا کمتر، استفاده از Tab به جای Space، یا اشتباه در قرار دادن دو نقطه (:) یا خط تیره (-) می‌تواند منجر به خطای اعتبارسنجی و توقف اجرای Docker Compose شود.

علائم و نشانه‌ها:

• پیام‌های خطا از سوی Docker Compose که معمولاً شامل عباراتی مانند ERROR: yaml.scanner.ScannerError، ERROR: Invalid YAML format، ERROR: IndentationError، یا ERROR: YAMLError: while parsing a block mapping هستند.
• مشخص شدن شماره خط و ستونی که خطا در آن رخ داده است.
• ناتوانی Docker Compose در شروع یا حتی خواندن فایل پیکربندی.

دلایل ریشه‌ای:

• **Indentation (فاصله تو رفتگی):** این شایع‌ترین علت است. YAML برای تعریف ساختار سلسله مراتبی از ایندنتاسیون استفاده می‌کند. هر سطح از سلسله مراتب باید با تعداد مشخص و یکسانی از فاصله‌ها (معمولاً 2 یا 4 فاصله) به داخل رفته باشد. استفاده از Tab به جای Space (یا برعکس)، یا استفاده از تعداد متفاوتی از فاصله‌ها در یک سطح، باعث خطا می‌شود.
• **Syntax Markers (نشانگرهای نحوی):** استفاده نادرست از دو نقطه (:) برای جفت‌های key-value، خط تیره (-) برای آیتم‌های لیست، یا گیومه (" یا ') برای رشته‌ها.
• **Mapping Errors:** اشتباه در تعریف یک بلوک نگاشتی (mapping block)، مثلاً تعریف یک کلید بدون مقدار آن یا برعکس.
• **Invalid Characters:** استفاده از کاراکترهای نامعتبر یا رزرو شده.

روش‌های عیب‌یابی و رفع:

1. **بازبینی دقیق خط و ستون خطا:** پیام خطای Docker Compose معمولاً بسیار دقیق است و محل دقیق خطا را مشخص می‌کند. به خط و ستون اشاره شده بروید و اطراف آن را با دقت بررسی کنید.
2. **استفاده از ابزارهای اعتبارسنجی YAML (Linters):**
   • **ابزارهای آنلاین:** وب‌سایت‌هایی مانند YAML Validator یا YAML Lint می‌توانند فایل شما را بررسی کرده و خطاهای نحوی را با جزئیات نشان دهند.
   • **افزونه‌های IDE/ویرایشگر کد:** بیشتر IDEها و ویرایشگرهای کد (مانند VS Code با افزونه‌هایی نظیر “YAML” یا “Docker”) دارای قابلیت اعتبارسنجی YAML در لحظه هستند که می‌توانند خطاهای احتمالی را هنگام تایپ به شما گوشزد کنند. این افزونه‌ها اغلب قابلیت تبدیل Tab به Space را نیز دارند.
3. **یکسان‌سازی فضای خالی:** اطمینان حاصل کنید که از Space به جای Tab استفاده می‌کنید. بسیاری از ویرایشگرهای کد به شما امکان می‌دهند که Tab را به Space تبدیل کنید یا بالعکس. consistency در این زمینه کلید است.
4. **بررسی نمونه‌های معتبر:** فایل خود را با نمونه‌های صحیح و مستند Docker Compose مقایسه کنید تا تفاوت‌ها را بیابید.
5. **استفاده از docker-compose config:** این دستور فایل docker-compose.yml شما را اعتبارسنجی می‌کند و اگر مشکلی در ساختار آن وجود داشته باشد، خطا را گزارش می‌دهد (حتی قبل از تلاش برای راه‌اندازی سرویس‌ها).

   docker-compose config
   

   اگر فایل معتبر باشد، خروجی پیکربندی نهایی را نمایش می‌دهد؛ در غیر این صورت، خطای نحوی را گزارش می‌کند.

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

با پیروی از این مراحل، می‌توانید به سرعت و به طور موثر خطاهای نحوی YAML را شناسایی و برطرف کنید و مطمئن شوید که Docker Compose قادر به خواندن و پردازش پیکربندی شماست. این اولین گام مهم در عیب‌یابی هرگونه مشکل دیگر در یک برنامه Docker Compose است.

2. مشکلات وابستگی سرویس‌ها و ترتیب راه‌اندازی (Service Dependency & Startup Order Issues)

در یک برنامه چندکانتینری، اغلب سرویس‌ها به یکدیگر وابسته هستند. به عنوان مثال، یک سرویس وب‌اپلیکیشن ممکن است نیاز به دسترسی به یک پایگاه داده یا یک سرویس کش داشته باشد تا بتواند به درستی کار کند. نادیده گرفتن این وابستگی‌ها یا مدیریت نادرست ترتیب راه‌اندازی می‌تواند منجر به خطاهایی شود که کانتینرها با موفقیت راه‌اندازی نمی‌شوند یا بلافاصله پس از شروع به کار از کار می‌افتند.

علائم و نشانه‌ها:

• کانتینرهای وابسته (مثلاً وب‌اپلیکیشن) بلافاصله پس از راه‌اندازی از کار می‌افتند یا با خطاهایی مانند “Connection refused”، “Database not available”، “Cannot connect to Redis” مواجه می‌شوند.
• پیام‌های خطا در لاگ کانتینرها که نشان می‌دهد سرویس دیگری که به آن وابسته بوده‌اند، در دسترس نیست یا آماده پذیرش اتصال نیست.
• حلقه‌های بی‌پایان در راه‌اندازی کانتینرها (restart loops).

دلایل ریشه‌ای:

• **عدم قطعیت در ترتیب راه‌اندازی:** Docker Compose به طور پیش‌فرض سرویس‌ها را به صورت موازی راه‌اندازی می‌کند. حتی با استفاده از depends_on، Docker Compose فقط منتظر می‌ماند تا کانتینر وابسته “شروع” شود، نه اینکه “آماده” پذیرش درخواست باشد. یک سرویس پایگاه داده ممکن است راه‌اندازی شود اما هنوز در حال انجام فرآیندهای اولیه مانند ایجاد جداول یا بارگذاری داده‌ها باشد و به درخواست‌ها پاسخ ندهد.
• **نقص در پیکربندی depends_on:** استفاده نادرست از depends_on یا عدم استفاده از آن در جایی که لازم است.
• **فقدان Healthcheck:** عدم تعریف مکانیزم مناسب برای بررسی سلامت و آمادگی سرویس‌ها.
• **شرایط خاص سرویس:** برخی سرویس‌ها نیاز به زمان بیشتری برای Initialization دارند.

روش‌های عیب‌یابی و رفع:

1. **استفاده از depends_on:** این گزینه به Docker Compose می‌گوید که یک سرویس به سرویس دیگری وابسته است و باید قبل از آن راه‌اندازی شود. با این حال، به یاد داشته باشید که depends_on فقط تضمین می‌کند که کانتینر وابسته شروع شده است، نه اینکه آماده پذیرش درخواست باشد.

   version: '3.8'
   services:
     web:
       build: .
       ports:
         - "80:80"
       depends_on:
         - db # web وابسته به db است
     db:
       image: postgres:13
       environment:
         POSTGRES_DB: mydb
         POSTGRES_USER: user
         POSTGRES_PASSWORD: password
   

2. **پیکربندی Healthcheck:** این بهترین راه حل برای اطمینان از آمادگی سرویس است. شما می‌توانید یک Healthcheck برای سرویس‌های اصلی (مانند پایگاه داده) تعریف کنید و سپس سرویس‌های وابسته را طوری پیکربندی کنید که منتظر آماده شدن این سرویس‌ها بمانند.
   • **تعریف Healthcheck برای سرویس وابسته (مثلاً دیتابیس):**

     version: '3.8'
     services:
       db:
         image: postgres:13
         environment:
           POSTGRES_DB: mydb
           POSTGRES_USER: user
           POSTGRES_PASSWORD: password
         healthcheck:
           test: ["CMD-SHELL", "pg_isready -U user -d mydb"] # دستوری برای بررسی سلامت
           interval: 5s # هر 5 ثانیه یک بار بررسی شود
           timeout: 5s # اگر در 5 ثانیه پاسخ نداد، زمانش تمام شود
           retries: 5 # 5 بار تلاش مجدد
           start_period: 30s # 30 ثانیه فرصت اولیه برای شروع به کار
     

   • **استفاده از condition: service_healthy در depends_on:**

     version: '3.8'
     services:
       web:
         build: .
         ports:
           - "80:80"
         depends_on:
           db:
             condition: service_healthy # web منتظر می ماند تا db healthy شود
       db:
         image: postgres:13
         environment:
           POSTGRES_DB: mydb
           POSTGRES_USER: user
           POSTGRES_PASSWORD: password
         healthcheck:
           test: ["CMD-SHELL", "pg_isready -U user -d mydb"]
           interval: 5s
           timeout: 5s
           retries: 5
           start_period: 30s
     

3. **پیاده‌سازی اسکریپت‌های Entrypoint برای انتظار:** در مواردی که Healthcheck کافی نیست یا در نسخه‌های قدیمی‌تر Docker Compose، می‌توانید از یک اسکریپت entrypoint سفارشی در کانتینر سرویس وابسته استفاده کنید. این اسکریپت قبل از اجرای دستور اصلی برنامه، منتظر می‌ماند تا سرویس‌های مورد نیاز در دسترس و آماده باشند. ابزارهایی مانند wait-for-it.sh یا dockerize می‌توانند برای این منظور مفید باشند.

   # مثال یک اسکریپت ساده wait-for-db.sh
   #!/bin/sh
   # wait-for-db.sh
   until nc -z db 5432; do
     echo "Waiting for db service..."
     sleep 1
   done
   echo "DB service started!"
   exec "$@"
   
   # در Dockerfile
   COPY wait-for-db.sh /usr/local/bin/wait-for-db.sh
   RUN chmod +x /usr/local/bin/wait-for-db.sh
   ENTRYPOINT ["/usr/local/bin/wait-for-db.sh"]
   CMD ["python", "app.py"]
   

4. **بررسی لاگ‌ها:** همواره لاگ‌های سرویس‌هایی که از کار افتاده‌اند را بررسی کنید (docker-compose logs ) تا علت دقیق خطا را بفهمید. این می‌تواند نشانه‌ای از مشکل اتصال، پیکربندی یا سایر خطاهای زمان اجرا باشد.
5. **افزایش زمان تأخیر (در موارد خاص):** در موارد بسیار نادر و به عنوان آخرین راه حل، می‌توانید یک sleep کوتاه در entrypoint سرویس وابسته قرار دهید، اما این روش کمتر توصیه می‌شود زیرا غیرقطعی است و می‌تواند باعث تاخیر غیرضروری شود.

با ترکیب depends_on و healthcheck، می‌توانید یک استراتژی راه‌اندازی قوی و قابل اطمینان برای برنامه‌های Docker Compose خود ایجاد کنید و از خطاهای ناشی از وابستگی‌های سرویس‌ها جلوگیری نمایید.

3. چالش‌های پیکربندی شبکه (Network Configuration Problems)

شبکه‌بندی یکی از اساسی‌ترین جنبه‌های Docker Compose است که امکان ارتباط بین سرویس‌ها را فراهم می‌کند. هر سرویس در Docker Compose به طور پیش‌فرض در یک شبکه Bridge اختصاصی قرار می‌گیرد، اما سوءتفاهم در مورد نحوه عملکرد شبکه‌ها، تداخل پورت‌ها یا پیکربندی نادرست می‌تواند منجر به مشکلات ارتباطی جدی شود.

علائم و نشانه‌ها:

• سرویس‌ها نمی‌توانند به یکدیگر متصل شوند (مثلاً وب‌اپلیکیشن نمی‌تواند به پایگاه داده وصل شود).
• پیام‌های خطا مانند “Connection refused”، “Host unreachable”، “Network unreachable”، “Name or service not known” در لاگ کانتینرها.
• عدم دسترسی به سرویس‌ها از طریق پورت‌های منتشر شده از خارج کانتینرها.
• خطای “Port is already in use” هنگام راه‌اندازی سرویس.

دلایل ریشه‌ای:

• **تداخل پورت‌ها:** تلاقی پورت‌های منتشر شده کانتینر با پورت‌هایی که قبلاً توسط سرویس‌های دیگر روی هاست یا کانتینرهای دیگر اشغال شده‌اند.
• **مشکلات DNS Resolution:** سرویس‌ها نمی‌توانند نام یکدیگر را در شبکه Docker Compose ترجمه کنند. (معمولاً به دلیل مشکلات شبکه Docker داخلی).
• **پیکربندی نادرست شبکه:**
  • عدم تعریف شبکه‌های سفارشی در صورت نیاز.
  • استفاده از network_mode: "host" به صورت نادرست یا بدون درک کامل عواقب آن.
  • عدم اتصال سرویس‌ها به یک شبکه مشترک در صورت نیاز به ارتباط.
• **فایروال:** تنظیمات فایروال هاست ممکن است جلوی دسترسی به پورت‌های منتشر شده را بگیرد.

روش‌های عیب‌یابی و رفع:

1. **بررسی تداخل پورت‌ها:**
   • **در لینوکس/macOS:** از دستور netstat -tuln | grep <port_number> یا lsof -i :<port_number> استفاده کنید تا ببینید آیا پورتی که می‌خواهید منتشر کنید، قبلاً توسط فرآیند دیگری اشغال شده است یا خیر.
   • **در ویندوز:** از netstat -ano | findstr :<port_number> و سپس tasklist /fi "pid eq <PID>" استفاده کنید.
   • **راه حل:** پورت دیگری را برای کانتینر انتخاب کنید یا سرویسی که پورت را اشغال کرده، متوقف کنید.

   # مثال: تغییر پورت از 80 به 8080
   ports:
     - "8080:80" # پورت 8080 روی هاست به پورت 80 در کانتینر
   

2. **مدیریت شبکه‌های سفارشی (Custom Networks):**
   • Docker Compose به طور پیش‌فرض یک شبکه Bridge برای هر پروژه ایجاد می‌کند و سرویس‌ها می‌توانند با استفاده از نام سرویس (مثلاً db یا redis) به یکدیگر متصل شوند. این معمولاً برای بیشتر موارد کافی است.
   • اگر نیاز به ایزوله کردن سرویس‌ها یا اتصال به شبکه‌های خارجی دارید، می‌توانید شبکه‌های سفارشی تعریف کنید و سرویس‌ها را به آن‌ها متصل کنید.

     version: '3.8'
     services:
       web:
         image: nginx
         networks:
           - frontend_network
       api:
         image: my-api:latest
         networks:
           - frontend_network
           - backend_network
       db:
         image: postgres
         networks:
           - backend_network
     
     networks:
       frontend_network:
         driver: bridge
       backend_network:
         driver: bridge
     

   • **بررسی اتصالات شبکه:** از docker network ls برای مشاهده شبکه‌های موجود و docker network inspect <network_name> برای مشاهده جزئیات یک شبکه (شامل کانتینرهای متصل) استفاده کنید.
3. **عیب‌یابی DNS Resolution (ترجمه نام):**
   • اگر سرویس‌ها با نام یکدیگر را پیدا نمی‌کنند، از docker exec -it <container_name> ping <other_service_name> استفاده کنید. اگر ping با موفقیت انجام شود، مشکل از DNS نیست.
   • اگر ping ناموفق بود، ممکن است کانتینرها در یک شبکه مشترک نباشند یا مشکلی در DNS سرور داخلی Docker وجود داشته باشد. اطمینان حاصل کنید که همه سرویس‌های مربوطه در یک شبکه مشترک قرار دارند.
4. **بررسی network_mode: "host":**
   • استفاده از network_mode: "host" کانتینر را به جای استفاده از شبکه Bridge داخلی، به طور مستقیم به شبکه هاست متصل می‌کند. این کار کانتینر را از ایزوله‌سازی شبکه خارج می‌کند و می‌تواند مفید باشد اما با خطرات امنیتی و تداخل پورت بیشتر همراه است.
   • اگر از این گزینه استفاده می‌کنید، مراقب باشید که پورت‌هایی که کانتینر استفاده می‌کند مستقیماً روی هاست منتشر می‌شوند و می‌توانند با پورت‌های دیگر هاست تداخل پیدا کنند.
5. **تنظیمات فایروال هاست:** اگر از سیستم‌عامل‌های لینوکس استفاده می‌کنید، بررسی کنید که فایروال (مانند ufw یا firewalld) ترافیک به پورت‌های Docker را مسدود نکرده باشد. معمولاً Docker قوانین فایروال لازم را اضافه می‌کند، اما در برخی تنظیمات سفارشی ممکن است نیاز به تنظیم دستی باشد.

با درک صحیح نحوه عملکرد شبکه‌های Docker Compose و استفاده مناسب از پیکربندی‌ها، می‌توانید مشکلات ارتباطی بین سرویس‌های خود را به حداقل برسانید.

4. خطاهای مرتبط با Volume و Persistent Data (Volume Mounting Errors)

Docker Compose به شما امکان می‌دهد تا داده‌ها را از طریق Volumeها بین هاست و کانتینرها به اشتراک بگذارید یا آنها را به صورت Persistent ذخیره کنید. این ویژگی برای حفظ داده‌های حساس مانند پایگاه‌های داده یا فایل‌های پیکربندی بین دوره‌های راه‌اندازی کانتینرها ضروری است. با این حال، خطاهای مربوط به پیکربندی Volumeها، مسیرهای نادرست، یا مشکلات دسترسی می‌توانند منجر به از دست رفتن داده‌ها، عدم راه‌اندازی سرویس‌ها، یا رفتار نامطلوب شوند.

علائم و نشانه‌ها:

• داده‌ها پس از راه‌اندازی مجدد کانتینرها از بین می‌روند.
• کانتینرها قادر به نوشتن یا خواندن از مسیرهای مورد انتظار نیستند.
• پیام‌های خطا مانند “Permission denied”، “No such file or directory”، “Unable to create directory” در لاگ کانتینرها.
• فایل‌های پیکربندی مورد انتظار در کانتینر پیدا نمی‌شوند یا تغییرات اعمال نمی‌شوند.

دلایل ریشه‌ای:

• **مسیرهای نادرست:**
  • مسیر bind mount روی هاست وجود ندارد یا اشتباه است.
  • مسیر mount target داخل کانتینر اشتباه است.
• **مشکلات دسترسی (Permissions):**
  • کاربر کانتینر (که معمولاً root نیست) مجوز کافی برای خواندن/نوشتن در Volume mount شده را ندارد.
  • فولدر روی هاست (برای bind mount) دارای مجوزهای محدودکننده است.
• **استفاده نادرست از Named Volumes در مقابل Bind Mounts:** عدم درک تفاوت عملکردی و موارد استفاده هر یک.
• **تداخل فایل‌ها/دایرکتوری‌ها:** اگر یک bind mount روی یک دایرکتوری در کانتینر انجام شود که قبلاً حاوی فایل‌هایی است، محتوای دایرکتوری کانتینر با محتوای هاست “پوشانده” (overridden) می‌شود.

روش‌های عیب‌یابی و رفع:

1. **بررسی مسیرهای Volume:**
   • **Bind Mounts:** اطمینان حاصل کنید که مسیر منبع (سمت چپ :) روی هاست وجود دارد و صحیح است. مسیر مقصد (سمت راست :) نیز باید دقیقاً همان مسیری باشد که برنامه داخل کانتینر انتظار دارد.

     version: '3.8'
     services:
       web:
         image: nginx
         volumes:
           - ./nginx.conf:/etc/nginx/nginx.conf # ./nginx.conf باید روی هاست وجود داشته باشد
     

   • **Named Volumes:** برای Named Volumes، Docker آنها را به صورت خودکار ایجاد و مدیریت می‌کند. مشکل معمولاً در مسیر مقصد داخل کانتینر است.

     version: '3.8'
     services:
       db:
         image: postgres
         volumes:
           - db_data:/var/lib/postgresql/data # /var/lib/postgresql/data در کانتینر
     volumes:
       db_data:
     

   • **اعتبارسنجی مسیرها در کانتینر:** با استفاده از docker exec -it <container_name> bash وارد کانتینر شوید و با دستوراتی مانند ls -l /path/to/volume و pwd مسیرها را از دید کانتینر بررسی کنید.
2. **رفع مشکلات دسترسی (Permissions):**
   • **مجوزهای هاست (برای Bind Mounts):** اطمینان حاصل کنید که دایرکتوری/فایل روی هاست دارای مجوزهای خواندن/نوشتن مناسب برای کاربر Docker یا کاربری که کانتینر با آن اجرا می‌شود، است. می‌توانید از chmod و chown استفاده کنید.

     sudo chown -R 1000:1000 ./my_data_directory # فرض کنید UID/GID کاربر کانتینر 1000 است
     sudo chmod -R 755 ./my_data_directory
     

   • **کاربر داخل کانتینر:** اگر برنامه شما با یک کاربر غیر root در کانتینر اجرا می‌شود، این کاربر باید مجوز دسترسی به Volume را داشته باشد. می‌توانید user را در Docker Compose مشخص کنید.

     version: '3.8'
     services:
       app:
         image: myapp:latest
         user: "1001:1001" #UID:GID
         volumes:
           - ./data:/app/data
     

   • **Volumeهای جدید:** برای Named Volumes، Docker معمولاً آنها را با مجوزهای مناسب ایجاد می‌کند. اگر در مورد مجوزها مشکل دارید، ممکن است نیاز باشد در Dockerfile یک کاربر خاص ایجاد کنید و مالکیت دایرکتوری‌های مربوطه را به آن کاربر بدهید.
3. **بازرسی Named Volumes:** از دستور docker volume inspect <volume_name> برای مشاهده جزئیات یک Named Volume (مانند محل ذخیره‌سازی واقعی روی هاست) استفاده کنید.
4. **تفاوت Bind Mounts و Named Volumes:**
   • **Bind Mounts:** به شما کنترل کامل روی محل ذخیره‌سازی داده‌ها روی هاست می‌دهد، اما به دلیل وابستگی به ساختار فایل سیستم هاست، پایداری کمتری دارد و می‌تواند مسائل امنیتی ایجاد کند.
   • **Named Volumes:** توسط Docker مدیریت می‌شوند، پایداری بیشتری دارند و برای داده‌های Persistent (مانند دیتابیس) توصیه می‌شوند.

   مطمئن شوید که گزینه مناسب برای نیازهای خود را انتخاب کرده‌اید.

5. **حذف Volumeهای مشکل‌دار (فقط برای داده‌های غیرحساس):** در صورتی که Named Volume دچار فساد شده و حاوی داده‌های مهم نیست، می‌توانید آن را حذف کرده و اجازه دهید Docker مجدداً آن را ایجاد کند:

   docker volume rm <volume_name>
   

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

5. مشکلات متغیرهای محیطی و فایل‌های پیکربندی (Environment Variable & Configuration Issues)

متغیرهای محیطی و فایل‌های پیکربندی ابزارهایی حیاتی برای پویاسازی و تنظیم رفتار کانتینرها در محیط‌های مختلف (توسعه، تست، تولید) هستند. Docker Compose راهکارهای مختلفی برای تزریق این مقادیر ارائه می‌دهد، اما عدم درک نحوه عملکرد آن‌ها، ترتیب اولویت یا اشتباهات تایپی می‌تواند منجر به خطاهایی شود که کانتینرها با پیکربندی نادرست راه‌اندازی شده یا اصلاً شروع به کار نکنند.

علائم و نشانه‌ها:

• سرویس‌ها با مقادیر پیش‌فرض یا خالی راه‌اندازی می‌شوند، حتی اگر متغیرهای محیطی را تنظیم کرده باشید.
• پیام‌های خطا در لاگ کانتینرها که نشان می‌دهد مقادیر مورد نیاز (مانند رشته اتصال دیتابیس، کلیدهای API) یافت نشده‌اند یا نامعتبر هستند.
• رفتار غیرمنتظره برنامه به دلیل استفاده از پیکربندی اشتباه.
• خطاهایی مانند “Missing environment variable” یا “Invalid configuration value”.

دلایل ریشه‌ای:

• **اشتباهات املایی:** اشتباه در نام متغیر محیطی در فایل .env، بخش environment، یا در کدی که متغیر را می‌خواند.
• **ترتیب اولویت:** Docker Compose مکانیسم‌های مختلفی برای تعریف متغیرهای محیطی دارد و ترتیب بارگذاری آنها مهم است.
• **مسیر فایل .env یا env_file:** فایل .env در ریشه پروژه (همان جایی که docker-compose.yml قرار دارد) به طور خودکار بارگذاری می‌شود. اما اگر از env_file استفاده می‌کنید، مسیر آن باید صحیح باشد.
• **تفاوت در نحوه خواندن متغیرها:** تفاوت در نحوه دسترسی برنامه به متغیرها (مثلاً process.env.VARIABLE_NAME در Node.js یا os.getenv('VARIABLE_NAME') در Python).
• **پوشانده شدن (Overriding):** یک متغیر محیطی ممکن است به صورت ناخواسته توسط منبع دیگری با اولویت بالاتر، پوشانده شود.

روش‌های عیب‌یابی و رفع:

1. **بررسی دقیق نام متغیرها:**
   • مطمئن شوید که نام متغیر در فایل .env یا بخش environment دقیقاً با آنچه برنامه شما انتظار دارد (حتی با رعایت حروف کوچک و بزرگ) مطابقت دارد.
   • از تایپوگرافی (typos) در نام‌ها خودداری کنید.
2. **فهم ترتیب اولویت بارگذاری:**

   Docker Compose متغیرهای محیطی را به ترتیب زیر بارگذاری می‌کند (موارد بعدی، موارد قبلی را پوشش می‌دهند):

   1. متغیرهای موجود در پوسته (shell environment variables) که Docker Compose با آنها اجرا می‌شود.
   2. متغیرهایی که در فایل .env در ریشه پروژه تعریف شده‌اند.
   3. متغیرهایی که با استفاده از env_file در سرویس‌ها تعریف شده‌اند (به ترتیب فهرست).
   4. متغیرهایی که به صورت مستقیم در بخش environment سرویس‌ها تعریف شده‌اند.

   برای عیب‌یابی، ترتیب اولویت را در نظر بگیرید. متغیری که در environment سرویس تعریف شده، بر متغیری با همین نام در .env اولویت دارد.

3. **استفاده از env_file:**

   اگر چندین فایل محیطی دارید یا می‌خواهید فایل‌های محیطی را خارج از ریشه پروژه نگه دارید، از env_file استفاده کنید.

   version: '3.8'
   services:
     app:
       image: myapp:latest
       env_file:
         - ./config/.env.dev # مسیر نسبی به docker-compose.yml
         - ./config/common.env
   

   مسیر مشخص شده در env_file باید نسبت به فایل docker-compose.yml باشد. مطمئن شوید که فایل‌های ذکر شده وجود دارند.

4. **بازرسی متغیرها در کانتینر:**

   بهترین راه برای تأیید اینکه متغیرهای محیطی به درستی به کانتینر رسیده‌اند، ورود به کانتینر و بررسی آنهاست:

   docker exec -it <container_name_or_id> bash
   printenv # یا env
   

   این دستور تمامی متغیرهای محیطی که در زمان اجرای کانتینر در دسترس هستند را لیست می‌کند. اگر متغیر مورد نظر شما در اینجا نیست یا مقدار اشتباهی دارد، مشکل از پیکربندی Docker Compose است.

5. **استفاده از docker inspect:**

   شما می‌توانید از دستور docker inspect <container_name_or_id> برای مشاهده جزئیات پیکربندی یک کانتینر، از جمله متغیرهای محیطی آن، استفاده کنید. این به شما نشان می‌دهد که Docker چه متغیرهایی را به کانتینر تزریق کرده است.

   docker inspect <container_name_or_id> | grep -A 10 "Env"
   

6. **خطاهای مربوط به مقادیر خالی یا Default:**

   برنامه‌ها معمولاً در صورت عدم یافتن یک متغیر محیطی، از یک مقدار پیش‌فرض استفاده می‌کنند یا با خطا مواجه می‌شوند. اگر متغیری در دسترس نبود، مطمئن شوید که آن را در .env، env_file یا environment تعریف کرده‌اید.

   گاهی اوقات مقادیر متغیرها حاوی کاراکترهای خاصی (مانند فاصله) هستند. در این موارد، بهتر است مقدار را در گیومه ("VALUE WITH SPACE") قرار دهید.

با رویکردی منظم و بررسی دقیق هر مرحله از تزریق متغیرهای محیطی، می‌توانید به سرعت مشکلات پیکربندی را شناسایی و برطرف کنید و مطمئن شوید که برنامه‌های شما با تنظیمات صحیح اجرا می‌شوند.

6. ناتوانی در Pull یا Build کردن Imageها (Image Pulling & Building Failures)

پایه و اساس هر سرویس در Docker Compose، یک ایمیج Docker است. این ایمیج می‌تواند از یک رجیستری (مانند Docker Hub) pull شود یا به صورت محلی از یک Dockerfile ساخته شود. خطاهای مربوط به کشیدن (pull) یا ساختن (build) ایمیج‌ها می‌توانند مانع از راه‌اندازی صحیح سرویس‌ها شوند و عیب‌یابی دقیق در این زمینه بسیار مهم است.

علائم و نشانه‌ها:

• پیام‌های خطا از سوی Docker Compose یا Docker CLI مانند “Error response from daemon: pull access denied”، “Failed to fetch “، “No such image”، “Dockerfile was not found” یا “Could not resolve host”.
• توقف فرآیند docker-compose up در مرحله pull یا build.
• کانتینرها هرگز راه‌اندازی نمی‌شوند.
• پیام‌های خطای شبکه مانند “network unreachable” یا “connection timed out” هنگام تلاش برای pull کردن ایمیج‌ها.

دلایل ریشه‌ای:

• **مشکلات اتصال به شبکه:** عدم دسترسی به اینترنت یا مشکل در اتصال به رجیستری Docker (مانند Docker Hub یا رجیستری‌های خصوصی).
• **احراز هویت (Authentication) ناموفق:** تلاش برای کشیدن ایمیج از یک رجیستری خصوصی بدون احراز هویت یا با استفاده از اعتبارنامه‌های اشتباه.
• **نام ایمیج اشتباه:** اشتباه در تایپ نام ایمیج یا تگ آن (مثلاً nginx:latestt به جای nginx:latest).
• **محدودیت‌های سرعت Pull (Rate Limiting):** Docker Hub برای pull کردن ایمیج‌ها از آی‌پی‌های ناشناس محدودیت‌هایی اعمال می‌کند.
• **خطاهای Dockerfile (برای Build کردن):**
  • نقص در دستورات Dockerfile (مثلاً دستورات اشتباه، مسیرهای نادرست).
  • عدم وجود Dockerfile در مسیر مشخص شده (build context).
  • مشکلات مجوز در فایل‌ها یا دایرکتوری‌های کپی شده در Dockerfile.
  • وابستگی‌های شبکه در حین build (مثلاً npm install یا pip install که به اینترنت نیاز دارند).
• **عدم وجود Build Context:** پوشه‌ای که Dockerfile در آن قرار دارد، در مسیر build.context به درستی مشخص نشده است.

روش‌های عیب‌یابی و رفع:

1. **بررسی اتصال به شبکه:**
   • اطمینان حاصل کنید که دستگاه شما به اینترنت متصل است.
   • تلاش کنید یک ایمیج عمومی را به صورت دستی pull کنید: docker pull hello-world. اگر این دستور هم با خطا مواجه شد، مشکل از اتصال کلی Docker به رجیستری‌ها است.
2. **بررسی احراز هویت (Authentication):**
   • اگر از ایمیج‌های خصوصی استفاده می‌کنید، مطمئن شوید که با docker login <registry_url> (مثلاً docker login برای Docker Hub) وارد شده‌اید و اعتبارنامه‌های شما معتبر هستند.
   • برای رجیستری‌های خصوصی، URL رجیستری را به درستی در image یا build در Docker Compose مشخص کنید.
3. **اعتبارسنجی نام ایمیج و تگ:**
   • نام ایمیج و تگ آن را در فایل docker-compose.yml با دقت بررسی کنید. یک کاراکتر اشتباه می‌تواند باعث عدم یافتن ایمیج شود.
   • اگر از latest استفاده می‌کنید، ممکن است ایمیج مورد نظر تغییر کرده باشد یا به دلیل cache به درستی pull نشود. استفاده از تگ‌های صریح (مثلاً nginx:1.21.6) توصیه می‌شود.
4. **رسیدگی به محدودیت‌های Rate Limiting Docker Hub:**
   • برای دور زدن محدودیت‌های pull، با حساب Docker Hub خود وارد شوید (docker login). کاربران لاگین شده محدودیت‌های بالاتری دارند.
   • در محیط‌های CI/CD، از Service Accountهای اختصاصی برای pull کردن ایمیج‌ها استفاده کنید.
5. **عیب‌یابی خطاهای Dockerfile (برای سرویس‌های build):**
   • **مسیر Build Context و Dockerfile:** مطمئن شوید که build.context به دایرکتوری صحیح اشاره می‌کند و Dockerfile (یا فایل مشخص شده با dockerfile) در آن دایرکتوری وجود دارد.

     version: '3.8'
     services:
       webapp:
         build:
           context: ./frontend # دایرکتوری frontend
           dockerfile: Dockerfile.dev # نام فایل Dockerfile
         ports:
           - "80:80"
     

   • **اجرای Build به صورت دستی:** تلاش کنید ایمیج را به صورت دستی build کنید (docker build -f ./frontend/Dockerfile.dev -t myapp:dev ./frontend). این کار لاگ‌های دقیق‌تری از فرآیند build را نشان می‌دهد و به شناسایی خطای خاص در Dockerfile کمک می‌کند.
   • **بازبینی دستورات Dockerfile:** دستورات RUN، COPY، ADD و غیره را بررسی کنید. مسیرها باید نسبت به build context صحیح باشند. خطاهای نصب پکیج (مثلاً apt-get update failed یا npm install failed) نشان‌دهنده مشکلات شبکه یا پیکربندی در حین build هستند.
   • **مجوزها در Dockerfile:** اگر فایل‌ها را کپی می‌کنید، مطمئن شوید که مجوزهای کافی برای دسترسی به آنها داخل کانتینر وجود دارد.
6. **پاکسازی Cache (در صورت لزوم):** در برخی موارد، cache خراب Docker می‌تواند باعث مشکل شود. می‌توانید با دستور docker system prune -a (با احتیاط، تمام کانتینرها، ایمیج‌ها و ولوم‌های استفاده نشده را حذف می‌کند) یا docker-compose build --no-cache کش را نادیده بگیرید.

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

7. خطاهای مجوز و دسترسی در کانتینرها (Permission Errors within Containers)

خطاهای مجوز (Permission errors) یکی از دلایل رایج و گاهی اوقات گیج‌کننده برای خرابی کانتینرها یا رفتار نامطلوب آن‌ها هستند. این خطاها زمانی رخ می‌دهند که یک فرآیند در داخل کانتینر تلاش می‌کند تا به یک فایل، دایرکتوری یا منبع دیگری دسترسی پیدا کند، اما کاربر یا گروهی که کانتینر با آن اجرا می‌شود، مجوزهای لازم را ندارد. این مشکل اغلب با Volume mounts یا فایل‌های پیکربندی سفارشی‌شده رخ می‌دهد.

علائم و نشانه‌ها:

• پیام‌های خطا در لاگ کانتینرها شامل عباراتی مانند Permission denied، Access denied، Operation not permitted، mkdir: cannot create directory، No such file or directory (اگر مشکل در ایجاد فایل/دایرکتوری باشد).
• کانتینر بلافاصله پس از شروع به کار از کار می‌افتد.
• برنامه در داخل کانتینر قادر به نوشتن در یک فایل لاگ یا پایگاه داده نیست.
• نرم‌افزار نمی‌تواند به فایل‌های پیکربندی دسترسی پیدا کند.

دلایل ریشه‌ای:

• **UID/GID نامطابق:** کاربر پیش‌فرض داخل کانتینر (که ممکن است root باشد یا نباشد) UID (User ID) و GID (Group ID) متفاوتی نسبت به مالکیت فایل‌ها و دایرکتوری‌های mount شده از هاست دارد. این یکی از شایع‌ترین علل است.
• **مجوزهای restrictive روی هاست:** دایرکتوری یا فایلی که از هاست به کانتینر bind mount شده است، روی هاست مجوزهای دسترسی بسیار محدودکننده‌ای دارد که حتی کاربر root داخل کانتینر نیز نمی‌تواند به آن دسترسی پیدا کند.
• **فایل‌های ایجاد شده توسط Root:** اگر کانتینر در ابتدا با کاربر root اجرا شده و فایل‌هایی را ایجاد کرده باشد، سپس در تلاش‌های بعدی با یک کاربر غیر root اجرا شود، کاربر غیر root نمی‌تواند به آن فایل‌ها دسترسی پیدا کند.
• **عدم تعریف کاربر:** برخی ایمیج‌ها (به خصوص ایمیج‌های سفارشی) ممکن است به صراحت کاربر غیر root را تعریف نکنند، یا برنامه‌ها انتظار داشته باشند با یک کاربر خاص اجرا شوند.

روش‌های عیب‌یابی و رفع:

1. **بررسی کاربر و مالکیت فایل‌ها در کانتینر:**

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

   docker exec -it <container_name_or_id> bash
   whoami # برای دیدن کاربر فعلی
   id # برای دیدن UID و GID کاربر فعلی
   ls -l /path/to/problematic/file_or_directory # برای دیدن مالکیت و مجوزهای فایل/دایرکتوری
   

   با این اطلاعات، می‌توانید بفهمید که کاربر در کانتینر با چه UID/GID اجرا می‌شود و مالکیت فایل/دایرکتوری مورد نظر چیست.

2. **تنظیم مالکیت و مجوزها روی هاست (برای Bind Mounts):**

   اگر مشکل از یک bind mount است، باید مالکیت و/یا مجوزهای دایرکتوری/فایل روی هاست را تنظیم کنید تا با UID/GID کاربر کانتینر مطابقت داشته باشد. پیدا کردن UID/GID کاربر در کانتینر از طریق دستور id مفید است.

   # فرض کنید UID کاربر کانتینر 1000 و GID نیز 1000 است
   sudo chown -R 1000:1000 /path/on/host/to/mounted_data
   sudo chmod -R 755 /path/on/host/to/mounted_data # یا مجوزهای مناسب دیگر
   

   همچنین می‌توانید از user در Docker Compose برای مشخص کردن UID/GID استفاده کنید تا مطمئن شوید کانتینر با کاربر مورد نظر شما اجرا می‌شود:

   version: '3.8'
   services:
     app:
       image: myapp:latest
       user: "1001:1001" # UID:GID مورد نظر
       volumes:
         - ./data:/app/data
   

3. **مدیریت مجوزها در Dockerfile:**

   اگر خودتان ایمیج را می‌سازید، می‌توانید در Dockerfile یک کاربر غیر root ایجاد کنید و مالکیت دایرکتوری‌های لازم را به آن کاربر بدهید:

   # Dockerfile example
   FROM alpine:latest
   RUN addgroup -S appgroup && adduser -S appuser -G appgroup
   WORKDIR /app
   COPY . .
   RUN chown -R appuser:appgroup /app # مالکیت را به کاربر appuser بدهید
   USER appuser # کانتینر با این کاربر اجرا شود
   CMD ["./my-app"]
   

   این کار به خصوص برای افزایش امنیت توصیه می‌شود.

4. **استفاده از Volumeهای مدیریت شده توسط Docker (Named Volumes):**

   Named Volumes معمولاً توسط Docker با مجوزهای مناسب ایجاد می‌شوند و مشکلات دسترسی کمتری دارند، مگر اینکه برنامه شما در داخل کانتینر با یک کاربر بسیار محدودکننده اجرا شود. اگر برای داده‌های Persistent از Named Volumes استفاده می‌کنید، Docker بهتر می‌تواند مالکیت و مجوزها را مدیریت کند.

5. **موارد خاص SELinux/AppArmor:**

   در برخی سیستم‌عامل‌ها (مانند CentOS/RHEL با SELinux یا Ubuntu با AppArmor)، ممکن است قوانین امنیتی اضافی وجود داشته باشد که مانع دسترسی کانتینرها به Volumeهای bind mount شده می‌شود. در این موارد، ممکن است نیاز به تنظیمات خاصی در SELinux (مانند اضافه کردن :z یا :Z به mount) یا AppArmor داشته باشید. برای مثال:

   volumes:
     - ./data:/app/data:z # برای SELinux
   

   اما اینها موارد پیشرفته‌تری هستند و برای بیشتر کاربران لازم نیستند.

با درک تفاوت بین مالکیت فایل‌ها روی هاست و در کانتینر و استفاده صحیح از مکانیزم‌های Docker برای مدیریت کاربران و مجوزها، می‌توانید به طور موثر خطاهای دسترسی را در برنامه‌های Docker Compose خود برطرف کنید.

8. استراتژی‌های پیشرفته عیب‌یابی و مانیتورینگ (Advanced Troubleshooting & Monitoring Strategies)

هنگامی که خطاهای رایج را برطرف کردید و سرویس‌های شما راه‌اندازی شدند، ممکن است با مشکلات عمیق‌تری روبرو شوید که نیاز به رویکردهای پیشرفته‌تر عیب‌یابی دارند. این بخش به ابزارها و تکنیک‌هایی می‌پردازد که به شما کمک می‌کنند تا علت اصلی مشکلات پیچیده‌تر را شناسایی کرده و عملکرد کانتینرهای خود را مانیتور کنید.

ابزارهای کلیدی Docker CLI برای عیب‌یابی:

1. **docker-compose logs:**

   اولین و مهم‌ترین ابزار. این دستور لاگ‌های تمامی سرویس‌ها یا یک سرویس خاص را نمایش می‌دهد. با استفاده از فلگ -f می‌توانید لاگ‌ها را به صورت زنده دنبال کنید، و --tail به شما امکان می‌دهد تنها N خط آخر را مشاهده کنید. بررسی دقیق لاگ‌ها اغلب سرنخ‌های حیاتی برای شناسایی مشکلات در زمان اجرا (runtime) ارائه می‌دهد.

   docker-compose logs -f # دنبال کردن لاگ‌های همه سرویس‌ها
   docker-compose logs -f webapp # دنبال کردن لاگ‌های سرویس webapp
   docker-compose logs webapp --tail 100 # نمایش 100 خط آخر لاگ webapp
   

2. **docker exec:**

   این دستور به شما امکان می‌دهد تا یک دستور را در کانتینر در حال اجرا اجرا کنید. این برای ورود به کانتینر و بررسی دستی محیط آن بسیار مفید است. می‌توانید یک shell باز کنید و مانند یک سرور معمولی با آن تعامل کنید.

   docker exec -it <container_name_or_id> bash # باز کردن bash shell در کانتینر
   docker exec -it <container_name_or_id> ls -l /app # اجرای دستور ls در کانتینر
   

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

   • مجوزهای فایل‌ها را بررسی کنید (ls -l).
   • متغیرهای محیطی را مشاهده کنید (printenv).
   • اتصالات شبکه را تست کنید (ping، curl، netcat).
   • محتوای فایل‌های پیکربندی را بررسی کنید.
   • فرآیندهای در حال اجرا را مشاهده کنید (ps aux).
3. **docker inspect:**

   این دستور اطلاعات سطح پایین و کاملی از یک کانتینر، ایمیج، شبکه یا Volume را به صورت JSON نمایش می‌دهد. این اطلاعات شامل متغیرهای محیطی، تنظیمات شبکه، Volume mounts، دستورات شروع، وضعیت Healthcheck و موارد دیگر است. این یک ابزار بسیار قدرتمند برای درک نحوه پیکربندی Docker از سرویس‌های شماست.

   docker inspect <container_name_or_id> # مشاهده تمام جزئیات کانتینر
   docker inspect <container_name_or_id> | grep "IPAddress" # فیلتر کردن اطلاعات خاص
   

4. **docker top:**

   لیست فرآیندهای در حال اجرا در یک کانتینر را نمایش می‌دهد، مشابه دستور top در لینوکس. این به شما کمک می‌کند تا ببینید کدام فرآیندها در حال اجرا هستند و منابع (CPU, Memory) را مصرف می‌کنند.

   docker top <container_name_or_id>
   

5. **docker stats:**

   استفاده از منابع (CPU، RAM، I/O شبکه و دیسک) را برای تمام کانتینرهای در حال اجرا به صورت زنده نمایش می‌دهد. این ابزار برای شناسایی گلوگاه‌های عملکردی و کانتینرهای مصرف‌کننده منابع بسیار مفید است.

   docker stats
   

تکنیک‌های پیشرفته‌تر:

• **افزایش سطح لاگینگ:** بسیاری از برنامه‌ها و فریم‌ورک‌ها امکان تنظیم سطح لاگینگ (مثلاً DEBUG, INFO, WARNING, ERROR) را از طریق متغیرهای محیطی یا فایل‌های پیکربندی فراهم می‌کنند. در طول عیب‌یابی، می‌توانید سطح لاگینگ را به DEBUG افزایش دهید تا جزئیات بیشتری از عملکرد داخلی برنامه دریافت کنید.
• **مانیتورینگ خارجی:** برای محیط‌های تولید، استفاده از ابزارهای مانیتورینگ خارجی مانند Prometheus و Grafana، ELK Stack (Elasticsearch, Logstash, Kibana) یا راهکارهای تجاری (مانند DataDog, New Relic) برای جمع‌آوری و تحلیل لاگ‌ها و معیارهای عملکردی کانتینرها ضروری است. این ابزارها امکان شناسایی روندهای مشکل‌ساز و هشداردهی خودکار را فراهم می‌کنند.
• **ابزارهای Network Troubleshooting:**
  • ping، traceroute، netstat، nc (netcat) در داخل کانتینرها برای تست اتصالات شبکه.
  • tcpdump یا Wireshark روی هاست برای بررسی ترافیک شبکه بین کانتینرها و هاست.
• **استفاده از یک Volume برای Debugging:** می‌توانید یک Volume را به کانتینر mount کنید تا به فایل‌های لاگ برنامه دسترسی داشته باشید یا فایل‌های پیکربندی را به صورت زنده تغییر دهید و نتایج را مشاهده کنید.

با ترکیب این ابزارها و تکنیک‌ها، می‌توانید دید عمیقی نسبت به وضعیت کانتینرهای خود پیدا کرده و حتی پیچیده‌ترین مشکلات را در محیط Docker Compose تشخیص و برطرف کنید. مهارت در عیب‌یابی، یکی از مهم‌ترین ویژگی‌ها برای مهندسان DevOps و توسعه‌دهندگانی است که با سیستم‌های توزیع‌شده سروکار دارند.

9. بهترین شیوه‌ها برای جلوگیری از خطاهای Docker Compose

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

1. **پیکربندی واضح و خوانا (Clear and Readable Configuration):**
   • **کامنت‌گذاری:** از کامنت‌ها برای توضیح بخش‌های پیچیده یا تصمیمات طراحی خاص در فایل docker-compose.yml استفاده کنید.
   • **نام‌گذاری معنادار:** برای سرویس‌ها، شبکه‌ها و Volumeها از نام‌های معنادار و توصیفی استفاده کنید.
   • **تنظیمات پیش‌فرض را رعایت کنید:** از تغییر دادن تنظیمات پیش‌فرض Docker Compose مگر در صورت نیاز مبرم خودداری کنید، زیرا این کار می‌تواند باعث پیچیدگی و خطاهای پیش‌بینی نشده شود.
2. **اعتبارسنجی YAML (YAML Validation):**
   • **از ویرایشگرهای کد با پشتیبانی YAML استفاده کنید:** IDEها و ویرایشگرهایی مانند VS Code دارای افزونه‌های قوی برای اعتبارسنجی نحوی YAML هستند که خطاهای ایندنتاسیون و نحوی را در لحظه تشخیص می‌دهند.
   • **استفاده از docker-compose config:** قبل از راه‌اندازی سرویس‌ها، همیشه از دستور docker-compose config استفاده کنید تا فایل پیکربندی شما از نظر نحوی و منطقی اعتبارسنجی شود. این دستور یک نمای فشرده و اعتبارسنجی شده از پیکربندی نهایی را نمایش می‌دهد.

     docker-compose config
     

3. **مدیریت صحیح وابستگی‌ها و Healthcheckها:**
   • **استفاده از depends_on با condition: service_healthy:** برای تضمین ترتیب راه‌اندازی و آمادگی سرویس‌ها، از این ترکیب برای وابستگی‌های حیاتی استفاده کنید.
   • **پیاده‌سازی Healthcheckهای قوی:** برای سرویس‌های کلیدی (مانند دیتابیس‌ها و صف‌های پیام) Healthcheckهای دقیق و مطمئن تعریف کنید. این کار به Docker Compose کمک می‌کند تا وضعیت واقعی آمادگی سرویس‌ها را تشخیص دهد.
4. **مدیریت متغیرهای محیطی با دقت:**
   • **استفاده از فایل .env:** متغیرهای محیطی عمومی پروژه را در یک فایل .env در ریشه پروژه قرار دهید.
   • **تفکیک متغیرهای محیطی:** برای محیط‌های مختلف (توسعه، تست، تولید) از فایل‌های env_file جداگانه استفاده کنید.
   • **عدم commit کردن اطلاعات حساس:** هرگز اطلاعات حساس (مانند رمز عبور، کلیدهای API) را در فایل docker-compose.yml یا .env که در Git Commit می‌شوند، ذخیره نکنید. از Secretهای Docker یا Secret Managerهای اختصاصی استفاده کنید.
5. **استفاده مناسب از Volumeها:**
   • **برای داده‌های Persistent از Named Volumes استفاده کنید:** این روش برای ذخیره‌سازی داده‌های پایگاه داده یا هر داده‌ای که باید بین دوره‌های کانتینر حفظ شود، توصیه می‌شود.
   • **برای فایل‌های پیکربندی و کد منبع از Bind Mounts استفاده کنید:** Bind Mounts برای توسعه محلی و تزریق فایل‌های پیکربندی به کانتینرها مفید هستند.
   • **مجوزها را در نظر بگیرید:** همیشه به مجوزهای دسترسی به Volumeها (هم روی هاست و هم در کانتینر) توجه کنید تا از خطاهای Permission denied جلوگیری شود.
6. **تصاویر Docker (Images) بهینه و پایدار:**
   • **از تگ‌های خاص استفاده کنید:** به جای latest، از تگ‌های نسخه‌ای خاص (مثلاً postgres:13-alpine) برای ایمیج‌های خود استفاده کنید تا از تغییرات ناخواسته در ایمیج‌ها جلوگیری شود.
   • **ایمیج‌های سبک را انتخاب کنید:** برای کاهش حجم و افزایش سرعت، از ایمیج‌های پایه سبک‌تر (مانند Alpine) استفاده کنید.
   • **Dockerfileهای واضح و بهینه بسازید:** اگر ایمیج‌های خود را می‌سازید، Dockerfileها را خوانا و بهینه نگه دارید (مثلاً با کاهش تعداد لایه‌ها و استفاده از multistage builds).
7. **مدیریت منابع (Resource Management):**
   • برای کانتینرهای خود (به خصوص در محیط‌های تولید) محدودیت‌های CPU و Memory تعیین کنید تا از مصرف بیش از حد منابع و ناپایداری سیستم جلوگیری شود.
8. **بازبینی کد و تست (Code Review and Testing):**
   • **بازبینی فایل docker-compose.yml:** از سایر اعضای تیم بخواهید فایل پیکربندی شما را بازبینی کنند.
   • **تست خودکار:** تست‌های خودکار (مانند Integration Tests) را برای تأیید عملکرد صحیح سرویس‌ها و ارتباطات آن‌ها پیاده‌سازی کنید.
9. **استفاده از CI/CD:**
   • با ادغام Docker Compose در پایپلاین CI/CD، می‌توانید قبل از استقرار در محیط‌های بالاتر، مشکلات را شناسایی و برطرف کنید.

با رعایت این بهترین شیوه‌ها، نه تنها از بروز بسیاری از خطاهای رایج جلوگیری خواهید کرد، بلکه فرآیند توسعه، تست و استقرار برنامه‌های مبتنی بر Docker Compose شما به طور قابل توجهی کارآمدتر، قابل اعتمادتر و پایدارتر خواهد شد. یک فایل docker-compose.yml خوب طراحی شده، ستون فقرات یک محیط توسعه کانتینری موفق است.

نتیجه‌گیری

Docker Compose ابزاری بی‌نهایت قدرتمند و کارآمد برای مدیریت و ارکستراسیون برنامه‌های چندکانتینری است که فرآیند توسعه و استقرار را به شکلی چشمگیر ساده می‌کند. با این حال، همانطور که در این راهنمای جامع مشاهده کردید، کار با آن می‌تواند چالش‌ها و خطاهای خاص خود را به همراه داشته باشد. از خطاهای نحوی ساده در فایل‌های YAML گرفته تا مسائل پیچیده‌تر مربوط به وابستگی‌های سرویس، شبکه‌بندی، مدیریت Volumeها، متغیرهای محیطی و مشکلات ساخت یا کشیدن ایمیج‌ها، هر یک از این موارد می‌توانند روند کار را متوقف کرده و زمان زیادی را برای عیب‌یابی صرف کنند.

هدف این مقاله، ارائه یک نقشه راه عملی و سیستماتیک برای شناسایی، درک و رفع رایج‌ترین خطاهایی بود که ممکن است در حین کار با Docker Compose با آن‌ها روبرو شوید. ما به تفکیک به هر نوع خطا، علائم آن، دلایل ریشه‌ای و مهم‌تر از همه، گام‌های عملی برای عیب‌یابی و راهکارهای اجرایی پرداختیم. همچنین، استراتژی‌های پیشرفته عیب‌یابی با استفاده از ابزارهای Docker CLI و بهترین شیوه‌های طراحی فایل‌های Docker Compose را مورد بحث قرار دادیم تا به شما کمک کنیم نه تنها مشکلات موجود را حل کنید، بلکه از بروز بسیاری از آن‌ها در آینده نیز جلوگیری نمایید.

تسلط بر عیب‌یابی Docker Compose نیازمند صبر، دقت و یک رویکرد منطقی است. با درک عمیق نحوه عملکرد اجزای مختلف (سرویس‌ها، شبکه‌ها، ولوم‌ها، متغیرهای محیطی) و استفاده هوشمندانه از ابزارهای عیب‌یابی Docker، می‌توانید به سرعت مشکلات را شناسایی کرده و راه‌حل‌های پایداری برای آن‌ها پیدا کنید. به یاد داشته باشید که همیشه لاگ‌ها را بررسی کنید، پیکربندی خود را اعتبارسنجی کنید و از بهترین شیوه‌ها برای ایجاد فایل‌های docker-compose.yml قوی و قابل اطمینان پیروی کنید. با این دانش، شما قادر خواهید بود تا از پتانسیل کامل Docker Compose برای ایجاد محیط‌های توسعه و استقرار روان‌تر و کارآمدتر بهره‌مند شوید.