راهنمای Git پیکربندی پیشرفته و عیب‌یابی

1. مقدمه

ویژگی Git Version Control در cPanel شامل تغییراتی نسبت به پیکربندی پیش‌فرض Git است. همچنین محدودیت‌هایی برای مخازن میزبانی‌شده اعمال می‌شود. این سند برای مدیران سیستم نوشته شده و شامل جزئیات پیکربندی و نکات عیب‌یابی مشکلات کاربران است.

2. محدودیت‌ها

این ویژگی محدودیت‌های زیر را برای مخازن Git در cPanel اعمال می‌کند:

• هر مخزن فقط می‌تواند یک مخزن ریموت داشته باشد. برای چند ریموت باید از خط فرمان استفاده شود.
• مسیر مخزن نباید شامل فاصله یا کاراکترهای زیر باشد:

\ * | " ' < > & @ ` $ { } [ ] ( ) ; ? : = % #

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

.cpanel, .cphorde, .htpasswds, .ssh, .trash, access-logs, cgi-bin, etc, logs, perl5, mail, spamassassin, ssl, tmp, var

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

3. تغییرات پیکربندی

• gc.auto — جمع‌آوری زباله Git برای مخازن cPanel غیرفعال شده است.
• receive.denyCurrentBranch — مقدار آن به updateInstead تغییر داده شده است.

گزینه updateInstead باعث می‌شود هنگام Push به شاخه فعلی، Working Tree به‌صورت خودکار به‌روزرسانی شود.

cPanel از بسته Git اختصاصی استفاده می‌کند که باینری‌ها را در مسیر /usr/local/cpanel/3rdparty/bin/ قرار می‌دهد.

4. Deployment

نکته مهم: توصیه می‌شود فقط از مخزن ریموت یا کلون محلی آن برای استقرار استفاده کنید. هرگز محتوای مخزن cPanel را مستقیماً تغییر ندهید.

پیش‌نیازهای استقرار:

• وجود فایل معتبر .cpanel.yml
• وجود حداقل یک شاخه
• پاک بودن Working Tree

سیستم یک post-receive hook به همه مخازن اضافه می‌کند که دستورات فایل .cpanel.yml را اجرا می‌کند.

اطلاعات تاریخچه استقرار در مسیر زیر ذخیره می‌شود:

/home/user/.cpanel/datastore/vc_deploy.sqlite

5. بررسی کلید میزبان SSH

هنگام کلون مخزن از طریق SSH، سیستم کلید عمومی میزبان را در فایل زیر بررسی می‌کند:

/home/user/.ssh/known_hosts

رفتار سیستم:

• اگر میزبان جدید باشد → درخواست تأیید
• اگر ثبت شده باشد → پیام تأیید
• اگر کلید تغییر کرده باشد → هشدار امنیتی

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

هشدار: اگر تغییر کلید قابل تأیید نیست، احتمال حمله Man-in-the-Middle وجود دارد.

برای نمایش هشدارها، گزینه Enable strict SSH host key checking باید در WHM فعال باشد.

6. عیب‌یابی

اگر کاربران با مخازن خود مشکل دارند، مراحل زیر را بررسی کنید.

6.1 مسیرهای لاگ

• /usr/local/cpanel/logs/error_log — خطاها و Stack Trace
• /home/username/.cpanel/logs/user_task_runner.log — صف وظایف
• vc_TIMESTAMP_git_create.log — مشکلات ایجاد مخزن
• vc_TIMESTAMP_git_deploy.log — مشکلات استقرار

6.2 مخازن نمایش داده نمی‌شوند

اگر مخزن در خط فرمان وجود دارد اما در cPanel نمایش داده نمی‌شود، احتمالاً مخزن از طریق خط فرمان ایجاد شده و رابط آن را نادیده می‌گیرد.

6.3 شاخه‌ها نمایش داده نمی‌شوند

• شاخه‌ها فقط در نسخه محلی یا ریموت وجود دارند، نه در مخزن cPanel
• مخزن Bare است و شاخه ندارد

6.4 مشکلات کلون

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

برای رفع مشکل کلون:

• فرآیند را متوقف کنید
• دایرکتوری .cpanel/user_tasks/ را حذف کنید

6.5 مشکلات دسترسی SSH

بررسی کنید:

• پورت 22 باز باشد
• Shell Access فعال باشد
• SSH Access & Terminal در Feature List فعال باشد
• کلیدهای SSH به‌درستی ثبت شده باشند

نکته: اگر کلون از طریق SSH خطا می‌دهد:

• از HTTPS برای کلون Read-Only استفاده کنید
• کلید SSH را به‌عنوان Deployment Key ثبت کنید

نتیجه‌گیری

این راهنما به مدیران سیستم کمک می‌کند تا پیکربندی Git در cPanel را بهتر درک کرده و مشکلات رایج کاربران را سریع‌تر رفع کنند. شناخت محدودیت‌ها، تنظیمات، رفتار Deployment و نحوه بررسی کلیدهای SSH برای مدیریت صحیح مخازن ضروری است.