آموزش انتقال پروژه پایتون نوشته شده با آنتی گرویتی از GitHub خصوصی به cPanel و اجرای آنلاین

در این آموزش می‌خواهیم یک پروژه Python و Flask را:

• روی GitHub خصوصی قرار دهیم؛
• GitHub را به cPanel متصل کنیم؛
• فایل‌ها را روی هاست دریافت کنیم؛
• محیط مجازی Python بسازیم؛
• پکیج‌های پروژه را نصب کنیم؛
• برنامه را با Passenger آنلاین کنیم؛
• خطاهای متداول این فرایند را برطرف کنیم.

این راهنما بر اساس تجربه واقعی انتقال یک پرتال مدیریت پروژه و CRM پایتونی به هاست cPanel نوشته شده و برای افراد مبتدی کاملاً قابل اجراست. اگر به دنبال پشتیبانی حرفه‌ای سایت یا انتقال پروژه‌های خود هستید، این مقاله راهنمای کاملی برای شماست.

قبل از شروع به چه چیزهایی نیاز داریم؟

برای انجام این آموزش باید موارد زیر را داشته باشید:

• یک پروژه Python یا Flask
• یک مخزن خصوصی در GitHub
• هاست لینوکسی دارای cPanel
• دسترسی به Terminal در cPanel
• قابلیت Setup Python App
• یک دامنه یا ساب‌دامین
• فایل requirements.txt
• فایل ورودی WSGI مانند passenger_wsgi.py

ساختار اصلی پروژه ما تقریباً به شکل زیر بود:

webinew-portal/
├── app/
├── config.py
├── passenger_wsgi.py
├── requirements.txt
├── run.py
└── manage_users.py

مرحله اول: آماده‌سازی پروژه قبل از انتقال

قبل از قرار دادن پروژه روی GitHub باید مطمئن شویم فایل‌های اضافی و اطلاعات محرمانه وارد مخزن نمی‌شوند.

فایل‌هایی که نباید وارد GitHub شوند

موارد زیر معمولاً نباید در GitHub قرار بگیرند:

.env
venv/
.venv/
__pycache__/
*.pyc
instance/*.db
backups/
logs/
.pytest_cache/

برای جلوگیری از آپلود این موارد، در ریشه پروژه یک فایل به نام .gitignore بسازید:

# Environment variables
.env
.env.*

# Python virtual environments
venv/
.venv/

# Python cache
__pycache__/
*.py[cod]

# Databases
instance/*.db
instance/*.sqlite
instance/*.sqlite3

# Backups and logs
backups/
logs/
*.log

# Tests and editor files
.pytest_cache/
.idea/
.vscode/
.DS_Store

چرا نباید فایل .env را در GitHub قرار دهیم؟

فایل .env معمولاً حاوی اطلاعاتی مانند موارد زیر است:

SECRET_KEY=...
DATABASE_URL=...
SMS_API_KEY=...
GOOGLE_CLIENT_SECRET=...

مرحله دوم: ساخت فایل requirements.txt

فایل requirements.txt فهرست تمام کتابخانه‌هایی است که پروژه برای اجرا نیاز دارد. نمونه:

Flask==3.1.0
Flask-SQLAlchemy==3.1.1
Flask-Login==0.6.3
Werkzeug==3.1.3
Pillow==11.1.0
jdatetime==5.2.0
python-dotenv==1.0.1
PyMySQL==1.1.1
cryptography==44.0.1
openpyxl==3.1.5
python-docx==1.1.2

در تجربه ما، پکیج python-docx ابتدا داخل این فایل نبود. به همین دلیل برنامه هنگام اجرا با خطای زیر متوقف شد:

ModuleNotFoundError: No module named 'docx'

توجه داشته باشید که اسم پکیج قابل نصب python-docx است، اما داخل کد به شکل زیر Import می‌شود:

from docx import Document

پس اگر پروژه فایل Word تولید می‌کند، حتماً این خط را در requirements.txt قرار دهید:

python-docx==1.1.2

مرحله سوم: ساخت فایل Passenger

cPanel معمولاً پروژه‌های Python را با Passenger اجرا می‌کند. بنابراین در ریشه پروژه به یک فایل WSGI نیاز داریم. فایل زیر را بسازید:

passenger_wsgi.py

محتوای مناسب برای پروژه Flask:

import os
import sys

project_home = os.path.dirname(os.path.abspath(__file__))

if project_home not in sys.path:
    sys.path.insert(0, project_home)

from app import create_app
from app.models import db

application = create_app()

with application.app_context():
    db.create_all()

مرحله چهارم: انتقال پروژه وایب کدینگ به GitHub خصوصی

ابتدا در GitHub یک Repository جدید بسازید. پیشنهاد می‌شود برای پروژه‌های واقعی گزینه Private Repository انتخاب شود.

سپس در Terminal پروژه روی کامپیوتر خود اجرا کنید:

git init

فایل‌ها را اضافه کنید:

git add .

اولین Commit را بسازید:

git commit -m "Initial production version"

نام Branch اصلی را مشخص کنید:

git branch -M main

Repository را متصل کنید:

git remote add origin git@github.com:USERNAME/REPOSITORY.git

و پروژه را Push کنید:

git push -u origin main

به جای USERNAME و REPOSITORY مشخصات مخزن خودتان را قرار دهید.

مرحله پنجم: ساخت دامنه یا ساب‌دامین در cPanel

در cPanel وارد بخش Domains شوید و یک دامنه یا ساب‌دامین بسازید. برای مثال:

my.example.com

در این تجربه، مسیر پروژه به شکل زیر بود:

/home/CPANEL_USERNAME/my.example.com

پیشنهاد می‌شود پروژه Python را از برنامه‌های دیگر جدا نگه دارید. مثلاً اگر یک ابزار دیگر روی هاست دارید، هر پروژه باید Application Root و Virtual Environment مستقل داشته باشد. برای طراحی سایت در تهران و پروژه‌های بزرگ‌تر، این جداسازی اهمیت بیشتری پیدا می‌کند.

ساختار پیشنهادی:

/home/CPANEL_USERNAME/
├── first-python-app/
└── my.example.com/

مرحله ششم: اتصال امن cPanel به GitHub خصوصی

چون Repository خصوصی است، سرور نمی‌تواند بدون احراز هویت آن را دانلود کند. یکی از بهترین روش‌ها استفاده از Deploy Key است. Deploy Key یک کلید SSH اختصاصی است که فقط به یک Repository دسترسی دارد.

ساخت کلید SSH در cPanel

وارد Terminal سی‌پنل شوید و اجرا کنید:

mkdir -p ~/.ssh
chmod 700 ~/.ssh

سپس کلید اختصاصی پروژه را بسازید:

ssh-keygen -t ed25519 -C "cpanel-webinew" -N "" -f ~/.ssh/id_webinew

دو فایل ساخته می‌شود:

• ~/.ssh/id_webinew - فایل کلید خصوصی (هرگز برای کسی ارسال نکنید)
• ~/.ssh/id_webinew.pub - فایل کلید عمومی (این را در GitHub ثبت می‌کنیم)

مشاهده کلید عمومی

cat ~/.ssh/id_webinew.pub

خروجی تقریباً به شکل زیر است:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... cpanel-webinew

کل خط را از ssh-ed25519 تا cpanel-webinew کپی کنید.

مرحله هفتم: ثبت Deploy Key در GitHub

وارد Repository خصوصی شوید و این مسیر را باز کنید:

Repository → Settings → Deploy keys → Add deploy key

مقادیر را این‌گونه وارد کنید:

• Title: cPanel Webinew
• Key: کل خط کلید عمومی

برای دریافت کد از GitHub نیازی به فعال‌کردن گزینه Allow write access نیست، پس بهتر است آن را خاموش نگه دارید. در پایان روی Add key کلیک کنید.

مرحله هشتم: تنظیم SSH روی پورت ۴۴۳

در بعضی هاست‌ها، اتصال SSH به GitHub روی پورت ۲۲ مسدود یا تغییر مسیر داده می‌شود. این موضوع مخصوصاً در شرایط بحران و نت ملی اهمیت بیشتری پیدا می‌کند.

در تجربه ما، اجرای دستور زیر:

ssh -T git@github.com

به‌جای GitHub واقعی به یک IP غیرمرتبط متصل می‌شد و از کاربر رمز عبور می‌خواست. راه‌حل، استفاده از سرویس SSH گیت‌هاب روی پورت ۴۴۳ بود.

فایل تنظیمات SSH را با این دستور ایجاد کنید:

printf '%s\n' \
'Host github-webinew' \
'    HostName ssh.github.com' \
'    Port 443' \
'    User git' \
'    IdentityFile /home/CPANEL_USERNAME/.ssh/id_webinew' \
'    IdentitiesOnly yes' > ~/.ssh/config

به جای CPANEL_USERNAME نام کاربری cPanel خودتان را قرار دهید. سطح دسترسی فایل‌ها را تنظیم کنید:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_webinew
chmod 600 ~/.ssh/config
chmod 644 ~/.ssh/id_webinew.pub

محتوای فایل را بررسی کنید:

cat -n ~/.ssh/config

خروجی باید مشابه زیر باشد:

1  Host github-webinew
2      HostName ssh.github.com
3      Port 443
4      User git
5      IdentityFile /home/CPANEL_USERNAME/.ssh/id_webinew
6      IdentitiesOnly yes

مرحله نهم: تست اتصال GitHub

اتصال را آزمایش کنید:

ssh -T git@github-webinew

بار اول Fingerprint سرور نمایش داده می‌شود. قبل از تأیید، آن را با Fingerprint رسمی GitHub مقایسه کنید. در تجربه ما Fingerprint رسمی ECDSA این مقدار بود:

SHA256:p2QAMXNIC1TJYWeIOttrVc98/R1BUFWu3/LiyKgUfQM

بعد از تأیید، خروجی موفق باید مشابه زیر باشد:

Hi USERNAME/REPOSITORY! You've successfully authenticated, but GitHub does not provide shell access.

اگر سیستم از شما این مورد را درخواست کرد:

git@github.com's password:

هیچ رمزی وارد نکنید. درخواست پسورد یعنی Deploy Key پذیرفته نشده یا اتصال به مقصد صحیح انجام نشده است.

مرحله دهم: Clone پروژه داخل مسیر دامنه

به مسیر دامنه بروید:

cd /home/CPANEL_USERNAME/my.example.com

موقعیت را بررسی کنید:

pwd

محتویات پوشه را ببینید:

ls -la

اگر فقط موارد . و .. را دیدید، پوشه خالی است. حالا Repository را Clone کنید:

git clone git@github-webinew:USERNAME/REPOSITORY.git .

بعد از Clone بررسی کنید:

ls -la

باید فایل‌هایی مثل .git, app, config.py, passenger_wsgi.py, requirements.txt مشاهده شوند.

مرحله یازدهم: ساخت Python App در cPanel

در cPanel وارد مسیر زیر شوید:

Software → Setup Python App → Create Application

تنظیمات را به شکل زیر انجام دهید:

اگر برنامه باید در ریشه دامنه اجرا شود، کادر مسیر بعد از Application URL را خالی بگذارید.

مرحله دوازدهم: تعریف SECRET_KEY

قبل از آنلاین‌کردن برنامه باید یک کلید امنیتی تصادفی تولید کنید. در Terminal اجرا کنید:

python3 -c "import secrets; print(secrets.token_urlsafe(64))"

یک رشته طولانی تولید می‌شود. در بخش Setup Python App → Environment variables → Add Variable متغیر را اضافه کنید:

• Name: SECRET_KEY
• Value: کلید تصادفی تولیدشده

مرحله سیزدهم: فعال‌کردن Virtual Environment

بعد از ساخت Python App، cPanel یک دستور شبیه زیر نمایش می‌دهد:

source /home/CPANEL_USERNAME/virtualenv/my.example.com/3.11/bin/activate && cd /home/CPANEL_USERNAME/my.example.com

آن دستور را کپی کرده و در Terminal اجرا کنید. بعد از فعال‌شدن محیط، ابتدای خط Terminal معمولاً تغییر می‌کند:

((my.example.com:3.11))

برای اطمینان اجرا کنید:

which python

خروجی باید به Virtual Environment اشاره کند:

/home/CPANEL_USERNAME/virtualenv/my.example.com/3.11/bin/python

اگر خروجی /usr/bin/python بود، یعنی Virtual Environment فعال نشده است.

مرحله چهاردهم: نصب کتابخانه‌های پروژه

درحالی‌که Virtual Environment فعال است، اجرا کنید:

python -m pip install -r requirements.txt

منتظر بمانید تا پیام Successfully installed ... نمایش داده شود. پیام مربوط به نسخه جدید pip خطا نیست و برای راه‌اندازی اولیه نیازی نیست pip را ارتقا دهید.

مرحله پانزدهم: برطرف‌کردن خطای python-docx

اگر برنامه هنگام اجرا خطای زیر را نمایش داد:

ModuleNotFoundError: No module named 'docx'

پکیج موردنیاز را نصب کنید:

python -m pip install python-docx==1.1.2

و آن را به requirements.txt اضافه کنید:

grep -qxF 'python-docx==1.1.2' requirements.txt || echo 'python-docx==1.1.2' >> requirements.txt

البته اصلاح اصلی باید در نسخه GitHub نیز انجام شود تا در استقرار بعدی از بین نرود.

مرحله شانزدهم: مشکل حلقه بی‌نهایت passenger_wsgi.py

در بعضی نسخه‌های cPanel، هنگام ساخت Python App، محتوای passenger_wsgi.py تغییر می‌کند. ممکن است داخل آن چنین کدی قرار بگیرد:

wsgi = imp.load_source('wsgi', 'passenger_wsgi.py')

این کد باعث می‌شود فایل passenger_wsgi.py دوباره خودش را Import کند و در یک حلقه بی‌نهایت بیفتد. خطای آن معمولاً چنین است:

RecursionError: maximum recursion depth exceeded

برای رفع مشکل ابتدا بکاپ بگیرید:

cp passenger_wsgi.py passenger_wsgi.py.cpanel-backup

سپس محتوای فایل را با نسخه صحیح جایگزین کنید:

import os
import sys

project_home = os.path.dirname(os.path.abspath(__file__))

if project_home not in sys.path:
    sys.path.insert(0, project_home)

from app import create_app
from app.models import db

application = create_app()

with application.app_context():
    db.create_all()

محتوای فایل را بررسی کنید:

cat -n passenger_wsgi.py

نباید دیگر imp.load_source داخل آن باشد.

مرحله هفدهم: تست برنامه قبل از Restart

در محیط مجازی اجرا کنید:

python -c "from passenger_wsgi import application; print('APP LOADED SUCCESSFULLY')"

اگر خروجی APP LOADED SUCCESSFULLY نمایش داده شد، یعنی:

• Python درست فعال شده؛
• کتابخانه‌ها نصب شده‌اند؛
• فایل Passenger صحیح است؛
• Flask App بدون خطای Import بارگذاری شده؛
• دیتابیس اولیه قابل دسترسی است.

مرحله هجدهم: Restart و آنلاین‌کردن برنامه

به صفحه Setup Python App برگردید و روی دکمه RESTART کلیک کنید. چند ثانیه صبر کنید و سپس Application URL را باز کنید:

https://my.example.com

مرحله نوزدهم: ساخت حساب مدیر به روش امن

اگر دیتابیس جدید است، ممکن است هیچ کاربری برای ورود وجود نداشته باشد. بدون بررسی، فایل seed.py را اجرا نکنید. این فایل ممکن است:

• کاربران آزمایشی بسازد؛
• رمزهای ثابت داشته باشد؛
• اطلاعات نمونه وارد کند؛
• دیتابیس را Reset کند؛
• رمز مدیر قبلی را تغییر دهد.

اگر پروژه ابزار مدیریت کاربر دارد، ابتدا راهنمای آن را ببینید:

python manage_users.py --help

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

مرحله بیستم: روش انتشار آپدیت‌های بعدی

بعد از هر تغییر در پروژه، ابتدا تغییرات را از محیط توسعه به GitHub Push کنید. سپس در Terminal هاست:

source /home/CPANEL_USERNAME/virtualenv/my.example.com/3.11/bin/activate

به مسیر پروژه بروید:

cd /home/CPANEL_USERNAME/my.example.com

تغییرات را دریافت کنید:

git pull --ff-only

اگر requirements.txt تغییر کرده است:

python -m pip install -r requirements.txt

سپس از cPanel برنامه را Restart کنید. فرایند انتشارهای بعدی به‌صورت خلاصه:

ویرایش پروژه → Commit → Push به GitHub → ورود به Terminal هاست → git pull → نصب پکیج‌های جدید → Restart Python App

خطاهای متداول

خطای Permission denied در GitHub

Permission denied (publickey)

دلایل احتمالی:

• Deploy Key در Repository صحیح ثبت نشده؛
• کلید عمومی ناقص کپی شده؛
• مسیر IdentityFile اشتباه است؛
• سطح دسترسی فایل کلید اشتباه است؛
• اتصال پورت ۲۲ مسدود شده است.

راه‌حل پیشنهادی، استفاده از ssh.github.com روی پورت ۴۴۳ است.

درخواست پسورد GitHub

git@github.com's password:

GitHub برای Git از رمز SSH معمولی استفاده نمی‌کند. این پیام معمولاً یعنی کلید پذیرفته نشده است. پسورد وارد نکنید.

خطای RecursionError

RecursionError: maximum recursion depth exceeded

فایل passenger_wsgi.py احتمالاً خودش را Import می‌کند. محتوای فایل را اصلاح کنید.

خطای No module named

ModuleNotFoundError: No module named 'PACKAGE'

یعنی یک پکیج در requirements.txt ثبت نشده است. نام صحیح پکیج را پیدا کنید، نصب کنید و سپس آن را به requirements.txt نسخه GitHub اضافه کنید.

خطای 500 بعد از Restart

موارد زیر را بررسی کنید:

• Error Log در cPanel
• فایل passenger_wsgi.py
• فعال بودن Virtual Environment
• نصب کامل requirements.txt
• صحیح بودن SECRET_KEY
• مجوز نوشتن روی پوشه دیتابیس و Uploadها
• موجود بودن تمام Environment Variableها

نکات امنیتی مهم

قبل از عمومی‌کردن برنامه این موارد را بررسی کنید:

• .env داخل GitHub نباشد.
• دیتابیس واقعی داخل Repository نباشد.
• رمز مدیر داخل seed.py نوشته نشده باشد.
• Deploy Key فقط Read-only باشد.
• سایت دارای SSL معتبر باشد.
• SECRET_KEY تصادفی باشد.
• Debug Mode در محیط Production خاموش باشد.
• فایل‌های Upload کنترل شوند.
• کوکی‌ها با Secure و HttpOnly تنظیم شوند.
• قبل از هر Deployment از دیتابیس بکاپ گرفته شود.
• رمز کاربران به‌صورت متن ساده ذخیره نشود.

جمع‌بندی

برای نصب پروژه پایتون روی cPanel از GitHub خصوصی، باید ابتدا پروژه را برای محیط Production آماده کنیم. سپس با یک Deploy Key محدود و امن، cPanel را به Repository خصوصی متصل کنیم. بعد از Clone پروژه، از طریق Setup Python App یک محیط Python مستقل می‌سازیم، کتابخانه‌ها را داخل Virtual Environment نصب می‌کنیم و برنامه را با فایل passenger_wsgi.py اجرا می‌کنیم.

در این فرایند دو خطای مهم تجربه شد:

1. اتصال SSH پورت ۲۲ به GitHub به مقصد اشتباه هدایت می‌شد که با استفاده از پورت ۴۴۳ رفع شد.
2. cPanel فایل Passenger را طوری تغییر داده بود که خودش را Import می‌کرد و باعث RecursionError می‌شد.

بعد از رفع این موارد و نصب کتابخانه جاافتاده python-docx، برنامه Flask با موفقیت روی دامنه اختصاصی آنلاین شد. برای مشاهده نمونه کارهای طراحی سایت و نمونه کارهای سئو ما، می‌توانید به بخش نمونه کارها مراجعه کنید.

سؤالات متداول