آموزش دیپلوی پروژه Cursor روی هاست ابری در ۵ مرحله

پروژه‌ات را داخل Cursor ساختی، روی لوکال بالا می‌آید، و حتی چند نفر از دوستانت هم دمو را دیده‌اند. قدم بعدی معمولاً همین‌جا گیر می‌کند: چطور همین اپ را با یک دامنه واقعی آنلاین کنی، بدون اینکه خودت سرور لینوکس راه بیندازی، Nginx را دستی کانفیگ کنی، یا هر بار با FTP فایل آپلود کنی؟

این مطلب مسیر مشخص دیپلوی پروژه Cursor روی هاست ابری چابکان را قدم‌به‌قدم جلو می‌برد: آماده‌سازی پروژه در ادیتور، Push به GitHub یا GitLab، ساخت سرویس PaaS، تنظیم env، انتشار، و وصل کردن دامنه با SSL. اگر قبلاً درباره استقرار خودکار خوانده‌ای، اینجا همان ایده را برای اپی که با Cursor ساخته‌ای عملی می‌کنیم؛ برای مرور مفهوم کلی می‌توانی استقرار خودکار (Auto Deployment) چیست؟ را هم ببینی.

چه چیزهایی لازم داری؟

قبل از شروع این‌ها را دم دست بگذار:

• یک پروژه قابل اجرا در Cursor (Node، Python، استاتیک یا Docker)
• حساب GitHub یا GitLab
• حساب کاربری چابکان و دسترسی به ساخت سرویس هاست ابری
• لیست متغیرهای محیطی (حداقل همان‌هایی که در لوکال در .env داری)
• اختیاری: دامنه برای مرحله نهایی

اگر پروژه هنوز فقط در چت Cursor است و روی دیسک به‌صورت فولدر منظم ذخیره نشده، اول آن را به یک پوشه واقعی با فایل‌های سورس تبدیل کن. دیپلوی از روی یک Prompt انجام نمی‌شود؛ از روی فایل‌ها و Git انجام می‌شود.

دیپلوی پروژه Cursor یعنی چه؟

وقتی می‌گوییم دیپلوی، منظورمان فقط «آپلود فایل» نیست. برای یک اپ ساخته‌شده در Cursor، دیپلوی معمولاً این زنجیره است:

• کد از مخزن Git خوانده می‌شود
• وابستگی‌ها نصب و در صورت نیاز Build گرفته می‌شود
• پروسه اجرا با دستور start مشخص بالا می‌آید
• یک URL عمومی (و بعداً دامنه خودت) به سرویس وصل می‌شود
• HTTPS با گواهی SSL فعال می‌شود

تفاوت کار با هاست ابری از نوع PaaS این است که بخش زیادی از کانفیگ سرور، ری‌استارت سرویس و مسیر انتشار داخل پنل انجام می‌شود. تو بیشتر روی خود اپ تمرکز می‌کنی؛ جزئیات زیرساخت را پلتفرم جلو می‌برد. اگر می‌خواهی همین ایده را در مقیاس ساخت SaaS ببینی، مطلب دیپلوی SaaS بدون DevOps مکمل خوبی است.

مرحله	روی لوکال (Cursor)	روی هاست ابری چابکان
اجرای اپ	npm run dev یا python app.py	دستور start / بیلد پلتفرم بعد از Deploy
متغیر محیطی	فایل .env محلی	Env در پنل سرویس (نه داخل گیت)
آدرس دسترسی	localhost:3000	URL سرویس + دامنه اختصاصی
SSL	معمولاً لازم نیست	HTTPS روی دامنه متصل
انتشار نسخه جدید	ری‌استارت دستی ترمینال	Push به Git یا chabok deploy از CI

قبل از دیپلوی: پروژه را در Cursor آماده کن

بیشتر خطاهای دیپلوی از همین مرحله می‌آیند. اپ روی لپ‌تاپت کار می‌کند، اما فرض‌هایی دارد که روی فضای ابری غلط از آب درمی‌آیند. قبل از Push، این موارد را در خود Cursor جمع‌وجور کن.

۱) نوع اجرای پروژه را مشخص کن

هاست ابری چابکان برای استک‌های رایج سرویس جدا دارد؛ از جمله Node.js، Next.js، NestJS، Python، Flask، FastAPI، Django، Laravel، PHP، React، Vue، Angular، Go، Static و Docker. اگر پروژه را با Cursor و یک فریم‌ورک مشخص ساخته‌ای، همان نوع سرویس را انتخاب کن. وقتی استک ترکیبی است یا بیلد سفارشی می‌خواهی، سرویس Docker معمولاً مسیر شفاف‌تری است.

۲) دستور start و پورت را ثابت کن

پلتفرم باید بداند بعد از بیلد چه دستوری اپ را بالا می‌آورد. در پروژه‌های Node، اسکریپت start در package.json را جدی بگیر:

{
  "name": "cursor-demo-api",
  "scripts": {
    "dev": "node --watch src/index.js",
    "start": "node src/index.js"
  }
}

روی سرور معمولاً dev اجرا نمی‌شود؛ همان start است که بعد از Deploy صدا زده می‌شود. اپ باید به پورت اعلام‌شده توسط محیط گوش بدهد، نه فقط به یک عدد هاردکد روی لپ‌تاپ. رایج‌ترین الگو خواندن process.env.PORT (یا معادلش در پایتون) و bind روی 0.0.0.0 است، نه فقط 127.0.0.1.

۳) اگر Docker می‌روی، یک Dockerfile مینیمال بگذار

برای اپ Node ساده، چیزی شبیه این کافی است:

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
ENV NODE_ENV=production
EXPOSE 3000
CMD ["npm", "start"]

کامنت‌ها و نام فایل‌ها را انگلیسی نگه دار. داخل بلاک کد فارسی نگذار؛ بعداً در لاگ بیلد و دیباگ کمتر گیج می‌شوی.

۴) رازها را از ریپو جدا کن

کلید OpenAI، توکن دیتابیس، و رمز SMTP را داخل گیت commit نکن. فایل .env را به .gitignore اضافه کن و یک .env.example بدون مقدار واقعی بگذار تا خودت و هم‌تیمی‌ها بدانند چه متغیرهایی لازم است. مقدار واقعی را بعداً در پنل سرویس چابکان وارد می‌کنی.

اگر در Cursor از Agent یا MCP برای وصل شدن به ابزارهای خارجی استفاده می‌کنی، همان کلیدها را هم از کد جدا نگه دار. برای آشنایی با خود پروتکل می‌توانی MCP چیست؟ را بخوانی؛ و اگر مسیر ترمینال‌محور برایت جذاب است، Claude Code چیست؟ هم هم‌خانواده همین جریان DX است. خودِ دیپلوی اپ نهایی اما روی هاست ابری انجام می‌شود، نه داخل چت Agent.

کد را به GitHub یا GitLab بفرست

هاست ابری چابکان با Git حرف می‌زند. پس پروژه Cursor باید داخل یک مخزن باشد. اگر هنوز مخزن نساخته‌ای:

1. در ترمینال Cursor یک ریپوی محلی بساز و remote را به GitHub یا GitLab وصل کن
2. شاخه اصلی را مشخص کن؛ معمولاً main
3. اولین Push را بزن و مطمئن شو .env واقعاً بالا نرفته
4. اگر ریپو خصوصی است، برای کلون/دیپلوی بعداً به توکن دسترسی نیاز داری

از این لحظه، Git منبع حقیقت پروژه است. هر نسخه پایدار روی یک commit مشخص می‌نشیند و مسیر انتشار تکرارپذیر می‌شود.

برای ریپوهای تیمی، قبل از Push اول یک README کوتاه با دستور اجرای لوکال و لیست envها بگذار. نفر بعدی (یا خودت دو هفته بعد) نباید از روی حدس سرویس را بالا بیاورد. اگر از GitLab استفاده می‌کنی، مسیر CI مشابه است؛ در مستندات چابکان بخش CI/CD برای GitLab هم آمده و همان CLI @chabokan.net/cli کار Deploy را انجام می‌دهد.

Commit Message را هم جدی بگیر. وقتی بعداً در پنل یا Actions بخواهی بدانی کدام تغییر سرویس را خراب کرد، «update» خالی کمکت نمی‌کند. یک خط درباره رفتار کاربر کافی است؛ مثلاً افزودن health check یا تغییر start script.

سرویس هاست ابری بساز و دیپلوی کن

حالا سراغ پنل چابکان برو. مسیر کلی این است:

1. یک سرویس جدید از نوع استک پروژه‌ات بساز (مثلاً Node.js یا Docker)
2. منابع اولیه (CPU / RAM / دیسک) را متناسب با دمو یا ترافیک واقعی انتخاب کن؛ برای MVP معمولاً پلن کوچک کافی است
3. متغیرهای محیطی را در تنظیمات سرویس وارد کن
4. کد را از Git به سرویس برسان و یک‌بار ری‌استارت/Deploy بزن تا بیلد و استارت اجرا شود

مسیر اول: استقرار از Git داخل سرویس

طبق مستند استقرار از طریق Git می‌توانی از کنسول سرویس، مخزن را کلون کنی، فایل‌ها را به مسیر پیش‌فرض منتقل کنی و سرویس را ری‌استارت کنی تا چابکان پیکربندی را انجام دهد (نصب پکیج‌ها و آماده‌سازی اجرا). برای ریپوی خصوصی، طبق مستند Private Git از توکن در URL کلون استفاده می‌شود.

این مسیر برای بار اول و پروژه‌های سبک شفاف است. اگر حجم فایل‌ها از حدود ۱۰۰ مگابایت بیشتر شود، مستندات چابکان مسیر FTP را پیشنهاد می‌کند.

مسیر دوم: CI/CD با GitHub Actions و CLI چابکان

اگر می‌خواهی هر Push به main خودش دیپلوی کند، مسیر CI/CD گیت‌هاب مناسب‌تر است. ایده ساده است: در Actions، CLI چابکان نصب می‌شود، با توکن API لاگین می‌کند، و سرویس را دیپلوی می‌کند.

name: deploy-chabokan
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: "24"
      - name: update-chabokan
        env:
         CHABOKAN_TOKEN: ${{ secrets.CHABOKAN_TOKEN }}
        run: |
          npm install -g @chabokan.net/cli
          chabok login -t "$CHABOKAN_TOKEN"
          chabok deploy -s my-service

به‌جای my-service همان نام سرویسی را بگذار که در پنل ساخته‌ای. توکن را از بخش کلید دسترسی API چابکان بگیر و در GitHub به‌صورت Secret با نام CHABOKAN_TOKEN ذخیره کن؛ داخل کد نگذار. نمونه رسمی هم در ریپوی chabokan/ci-cd-example هست.

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

بعد از ساخته شدن سرویس، قبل از وصل دامنه عمومی، URL داخلی/پیش‌فرض چابکان را باز کن. اگر همان‌جا خطای ۵۰۲ یا صفحه خالی دیدی، هنوز سراغ DNS نرو؛ اول لاگ استارت را بخوان. ترتیب درست این است: بیلد سبز → پروسه در حال اجرا → پاسخ ۲۰۰ روی مسیر سلامت → بعد دامنه.

برای اپ‌هایی که به دیتابیس وصل می‌شوند، ابتدا سرویس دیتابیس را بساز یا Connection String آماده را در env بگذار، بعد اپ را Deploy کن. برعکس این ترتیب معمولاً باعث می‌شود کانتینر چند بار Crash کند و فقط بعد از تنظیم env پایدار شود.

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

دامنه و SSL را وصل کن

URL پیش‌فرض سرویس برای تست خوب است، اما برای محصول واقعی دامنه می‌خواهی. در پنل سرویس دامنه را اضافه کن، رکورد DNS را به آدرسی که چابکان می‌دهد اشاره بده، و صبر کن تا Propagate شود. بعد از اتصال، HTTPS را فعال کن تا مرورگر قفل امن را نشان بدهد.

اگر دامنه را هم از چابکان گرفته‌ای، مدیریت DNS معمولاً ساده‌تر جلو می‌رود. برای دامنه خارجی فقط حواست به TTL و درست بودن رکورد A یا CNAME باشد.

برای تست سریع می‌توانی فعلاً روی همان زیرساخت پیش‌فرض بمانی و دامنه را مرحله بعد اضافه کنی. وقتی دامنه را وصل کردی، در تنظیمات اپ هر جایی که آدرس مطلق داشتی (مثلاً APP_URL، callback پرداخت، یا آدرس وبهوک) را به دامنه جدید به‌روز کن و یک Deploy دیگر بزن. خیلی از ربات‌های تلگرام و OAuthها دقیقاً همین‌جا می‌شکنند: کد هنوز به localhost یا URL موقت اشاره می‌کند.

خطاهای رایجی که بعد از دیپلوی پروژه Cursor می‌بینی

این‌ها را قبل از اینکه نیم‌ساعت در لاگ غرق شوی چک کن:

• دستور start اشتباه: روی لوکال npm run dev زده‌ای، روی سرور همان را گذاشته‌ای. برای پروداکشن باید start یا CMD داکر درست باشد.
• نادیده گرفتن PORT: اپ همیشه روی 3000 گوش می‌دهد، در حالی که پلتفرم پورت دیگری تزریق می‌کند.
• Listen فقط روی localhost: سرویس داخل کانتینر بالا می‌آید ولی از بیرون دیده نمی‌شود، چون به 127.0.0.1 بایند شده.
• env جاافتاده: کلید API یا آدرس دیتابیس فقط در .env لوکال بوده و به پنل منتقل نشده.
• بیلد ناقص: برای Next یا فرانت‌های بیلددار، مرحله build در مسیر استقرار دیده نشده و فقط سورس خام اجرا شده.
• فایل‌های ضروری در .gitignore: گاهی پوشه لازم برای اجرا را هم ignore کرده‌ای.
• فرض دسترسی به اینترنت آزاد برای همه پکیج‌ها:</strong اگر dependency خصوصی یا رجیستری خاص داری، آن را در بیلد سرویس هم تعریف کن.
• Node version متفاوت: روی لپ‌تاپ Node 22 داری و سرویس روی ۱۸ بیلد می‌گیرد. نسخه را در تنظیمات سرویس یا ایمیج Docker قفل کن.
• فراموش کردن health check: اگر مسیر /health نداری، برای مانیتورینگ بعدی سخت‌تر می‌شود. یک پاسخ ساده JSON کافی است.
• آپلود secrets داخل چت Cursor: کلید را در Prompt نگذار که بعداً در تاریخچه بماند؛ مستقیم در پنل env وارد کن.

یک عادت خوب: بعد از هر Deploy، همان مسیر شاد کاربر را یک‌بار با دامنه واقعی تست کن؛ صفحه اول، لاگین، و یک درخواست API. لوکال با پروداکشن در CORS، کوکی Secure و آدرس callback فرق دارد.

چه زمانی هاست ابری، چه زمانی سرور ابری؟

اگر اپ استاندارد است، می‌خواهی سریع آنلاین شوی و حوصله نگهداری سیستم‌عامل نداری، هاست ابری / PaaS انتخاب منطقی برای خروجی Cursor است. وقتی به کرنل سفارشی، سرویس‌های سیستمی خاص، یا کنترل کامل شبکه نیاز داری، سراغ سرور ابری (VPS) برو. برای اکثر دموهای Agent، ربات تلگرام، API نود، و فرانت بیلدشده، PaaS مسیر کوتاه‌تری است.

یک بار مسیر را تا آخر برو

اگر همین حالا یک پروژه Cursor روی سیستم داری، کوتاه‌ترین مسیر عملی این است: اسکریپت start و env را مرتب کن، روی GitHub Push بزن، در چابکان یک سرویس هم‌استک بساز، کد را Deploy کن، دامنه تست را باز کن. برای شروع می‌توانی از هاست ابری چابکان و اعتبار رایگان حساب جدید استفاده کنی و جزئیات را از docs.chabokan.net دنبال کنی. تمرین را وقتی تمام‌شده حساب کن که همان اپِ داخل ادیتور، روی یک URL واقعی پاسخ بدهد.

اگر هنوز بین «همین الان دیپلوی» و «بعداً سرور می‌گیرم» مرددی، یک دموی کوچک را تا دامنه پیش ببر. هزینه یادگرفتن مسیر روی یک پروژه واقعی، کمتر از دوباره‌کاری وقتی ترافیک می‌آید تمام می‌شود. پنل چابکان، CLI و مستندات برای همین کار کنار هم گذاشته شده‌اند؛ از سرویس هاست ابری شروع کن و فقط وقتی به کنترل سیستم‌عامل نیاز داشتی سراغ سرور ابری برو.

سوالات پرتکرار درباره دیپلوی پروژه Cursor

آیا باید حتماً Docker بلد باشم؟

خیر. اگر استک‌ات در لیست سرویس‌های هاست ابری هست (مثلاً Node یا Python)، همان سرویس اختصاصی کافی است. Docker وقتی مفید است که بیلد سفارشی داری یا وابستگی‌های غیرمعمول.

می‌توانم مستقیماً از پوشه لوکال و بدون Git دیپلوی کنم؟

برای کار جدی، Git را پیشنهاد می‌کنیم؛ هم نسخه داری، هم CI/CD، هم برگشت به commit قبلی. آپلود دستی برای فایل‌های خیلی حجیم یا وضعیت‌های خاص در مستندات آمده، اما مسیر اصلی تیم‌ها Git است.

تفاوت این مطلب با آموزش استقرار خودکار چیست؟

آن مطلب مفهوم Auto Deployment و فاصله گرفتن از FTP را توضیح می‌دهد. اینجا روی سناریوی مشخص «اپ ساخته‌شده در Cursor → هاست ابری چابکان» متمرکزیم: آماده‌سازی ادیتور، start/PORT، و دو مسیر Git و GitHub Actions.

پروژه با Cursor و Claude/ChatGPT ساخته شده؛ باز هم همین مسیر است؟

بله. tooling تولید کد عوض می‌شود، ولی خروجی همان ریپوی Git است. آنچه پلتفرم می‌بیند، کد و دستور اجراست؛ نه اینکه کدام Agent آن را نوشته.

چطور نسخه جدید را بعد از اولین دیپلوی منتشر کنم؟

اگر CI/CD را با chabok deploy وصل کرده باشی، Push به شاخه متصل کافی است. اگر مسیر کنسول Git را رفته‌ای، pull گرفتن آخرین تغییرات و ری‌استارت سرویس،

برای جزئیات ساخت مخزن، راهنمای رسمی GitHub را هم ببین.

نسخه جدید را می‌آورد.

برای دیتابیس چه کار کنم؟

دیتابیس را داخل همان کانتینر اپ «برای همیشه» نگذار. برای داده پایدار، از دیتابیس ابری چابکان یا سرویس جدا استفاده کن و فقط Connection String را به‌صورت env به اپ بده.

آیا می‌توانم چند سرویس از یک ریپو دیپلوی کنم؟

بله، اگر مونوریپو داری. معمولاً برای هر اپ یک سرویس جدا می‌سازی و در CI با مسیر یا نام سرویس متفاوت chabok deploy می‌زنی. سعی نکن فرانت و API و Worker را داخل یک پروسه نگه داری مگر اینکه واقعاً یک باینری واحد باشند.

برای فایل‌های آپلودی کاربر چه باید کرد؟

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