راهنمای ستاپ خودکار برای توسعه‌دهندگان

با گذاشتن یک فایل sourcekade.json در ریشه‌ی سورس، خریدار می‌تواند سورس شما را با یک کلیک روی سرور مجازی (SSH) یا هاست cPanel خودش نصب کند. سورس‌کده سازگاری سرور را بررسی می‌کند، پیش‌نیازها (PHP/Python/Node، افزونه‌ها، nginx، MariaDB، composer/pip/npm) را نصب می‌کند، پارامترهای شما را از خریدار می‌گیرد و داخل فایل‌ها می‌گذارد، دیتابیس را می‌سازد و import می‌کند، وب‌سرور و SSL را تنظیم می‌کند، برنامه را به سرویس دائمی تبدیل می‌کند و برای ربات تلگرام وبهوک را ثبت می‌کند.

اگر این فایل را نگذارید، سورس‌کده سعی می‌کند از روی کد حدس بزند (برچسب «تشخیص خودکار») و در تب «ستاپ خودکار» سورس‌تان یک پیش‌نویس به شما پیشنهاد می‌دهد که با یک کلیک ذخیره می‌شود. پیش‌نویس را حتماً بررسی کنید؛ حدس همیشه کامل نیست.

curl -fsSL https://sourcekade.31-15-17-184.sslip.io/docs/setup/CLAUDE.md -o CLAUDE.md

طبق CLAUDE.md این پروژه را برای ستاپ خودکار سورس‌کده آماده کن: sourcekade.json را بساز یا کامل کن، توکن‌ها و تنظیمات را به پارامتر تبدیل کن و چک‌لیست آخر فایل را انجام بده.

چه اتفاقی می‌افتد؟

1. آماده‌سازی (روی سورس‌کده): کد نسخه‌ی تأییدشده استخراج و پارامترها داخل فایل‌ها نوشته می‌شود (files، env).
2. VPS: اتصال SSH با کلید اختصاصی هر سرور → نصب پیش‌نیازها با apt (یا dnf) → ساخت کاربر لینوکسی جدا برای برنامه (sk-ID) → استقرار در /opt/sourcekade/sk-ID → دیتابیس → composer/pip/npm → install.commands و post_install با همان کاربر (نه root) → nginx + PHP-FPM یا reverse proxy → SSL → سرویس systemd → cron → بررسی سلامت.
3. cPanel: ساخت دیتابیس با API سی‌پنل → ساخت vendor روی سورس‌کده → آپلود به پوشه‌ی دامنه → یک نصب‌کننده‌ی یک‌بارمصرف PHP (کلیددار، ۲۰ دقیقه انقضا، خودش را پاک می‌کند) نسخه‌ی PHP و افزونه‌ها را چک، فایل‌ها را استخراج و SQL را import می‌کند → cron با API.
4. تلگرام: توکن با getMe بررسی می‌شود؛ برای وبهوک setWebhook با secret_token (و در حالت بدون دامنه، آپلود گواهی self-signed روی IP)، برای polling deleteWebhook.

نصب دوباره = به‌روزرسانی: نسخه‌ی قبلی بکاپ می‌شود (.bak-تاریخ، سه‌تای آخر می‌ماند)، مسیرهای persist و دیتابیس حفظ می‌شوند.

مرجع کامل فیلدها

همه‌ی فیلدهای sourcekade.json با نوع، لازم بودن، پیش‌فرض و مقدارهای مجاز. فقط type و language لازم‌اند؛ بقیه را فقط وقتی لازم دارید بنویسید. همین مرجع به‌صورت فایل JSON Schema هم هست.

نوع پارامترها

telegram_token (قالب و getMe بررسی می‌شود؛ محرمانه) · telegram_id (عدد یا چند عدد با کاما) · secret (محرمانه؛ در لاگ نمایش داده نمی‌شود) · text · int · bool (true/false) · choice · url · email · domain.

پارامترهای سیستمی (خودکار)

• {{APP_URL}} — آدرس عمومی برنامه
• {{APP_DIR}} — مسیر نصب روی سرور
• {{DOMAIN}} — دامنه (یا IP)
• {{WEBHOOK_URL}} — آدرس کامل وبهوک
• {{WEBHOOK_SECRET}} — secret_token وبهوک (هدر X-Telegram-Bot-Api-Secret-Token)
• {{PORT}} — پورت داخلی برنامه
• {{DB_HOST}} — هاست دیتابیس
• {{DB_PORT}} — پورت دیتابیس
• {{DB_NAME}} — نام دیتابیس
• {{DB_USER}} — کاربر دیتابیس
• {{DB_PASS}} — رمز دیتابیس

مقداردهی بدون تغییر کد (set)

لازم نیست کدتان را عوض کنید؛ کافی است بگویید کدام ثابت/متغیر چه مقداری بگیرد. سورس‌کده بسته به پسوند فایل این الگوها را پیدا و مقدار را با escape درست جایگزین می‌کند:

• PHP: define('BOT_TOKEN', '...'); · const BOT_TOKEN = '...'; · $token = '...'; (کلید با $) · 'token' => '...' در آرایه
• Python: BOT_TOKEN = "..." (سطح ماژول) — حتی BOT_TOKEN = os.getenv(...)
• JS/TS: const BOT_TOKEN = '...' · token: '...' در آبجکت
• JSON: کلید سطح اول · .env / .ini: KEY=value

برای پارامترهای int/telegram_id (یک آیدی) عدد بدون کوتیشن نوشته می‌شود؛ بقیه به‌صورت رشته با escape کامل (کوتیشن و خط جدید امن است). telegram_id می‌تواند فهرست با کاما هم باشد (111,222) که به‌صورت رشته نوشته می‌شود. اگر نامی در فایل پیدا نشود، نصب متوقف نمی‌شود و فقط در لاگ هشدار می‌آید.

متغیرهای محیطی: روی VPS همه‌ی env.vars هم در فایل .env نوشته می‌شوند و هم به پروسه‌ی run.command داده می‌شوند (پایتون/Node بدون dotenv کار می‌کنند). PHP-FPM و cPanel فایل .env را خودکار بارگذاری نمی‌کنند؛ در PHP از config.php + set استفاده کنید.

نمونه‌ها

ربات تلگرام PHP با وبهوک + MySQL

{
  "type": "telegram-webhook",
  "language": "php",
  "requires": { "php": ">=8.1", "extensions": ["curl", "mbstring", "pdo_mysql"] },
  "params": [
    { "key": "BOT_TOKEN", "label": "توکن ربات", "type": "telegram_token" },
    { "key": "ADMIN_ID", "label": "آیدی عددی ادمین", "type": "telegram_id", "help": "از @userinfobot بگیرید" },
    { "key": "CHANNEL", "label": "کانال جوین اجباری", "type": "text", "required": false, "default": "@mychannel" }
  ],
  "files": [
    { "path": "config.php", "set": {
        "BOT_TOKEN": "{{BOT_TOKEN}}", "ADMIN_ID": "{{ADMIN_ID}}", "CHANNEL": "{{CHANNEL}}",
        "$db_host": "{{DB_HOST}}", "$db_name": "{{DB_NAME}}", "$db_user": "{{DB_USER}}", "$db_pass": "{{DB_PASS}}",
        "WEBHOOK_SECRET": "{{WEBHOOK_SECRET}}" } }
  ],
  "database": { "engine": "mysql", "import": "database.sql" },
  "webhook": { "path": "bot.php", "token_param": "BOT_TOKEN" },
  "cron": [ { "schedule": "*/5 * * * *", "command": "php cron.php" } ]
}

ربات پایتون (aiogram / telebot / python-telegram-bot) با polling

{
  "type": "telegram-polling",
  "language": "python",
  "requires": { "python": ">=3.10" },
  "install": { "pip": "requirements.txt" },
  "params": [
    { "key": "BOT_TOKEN", "label": "توکن ربات", "type": "telegram_token" },
    { "key": "ADMINS", "label": "آیدی ادمین‌ها (با کاما)", "type": "telegram_id" },
    { "key": "SECRET_KEY", "label": "کلید رمزنگاری", "type": "secret", "generate": "hex32", "required": false }
  ],
  "env": { "file": ".env", "from": ".env.example", "vars": {
      "BOT_TOKEN": "{{BOT_TOKEN}}", "ADMINS": "{{ADMINS}}", "SECRET_KEY": "{{SECRET_KEY}}" } },
  "run": { "command": "python bot.py" },
  "persist": ["data"]
}

ربات پایتون با وبهوک (aiohttp / FastAPI)

{
  "type": "telegram-webhook",
  "language": "python",
  "install": { "pip": "requirements.txt" },
  "params": [ { "key": "BOT_TOKEN", "label": "توکن ربات", "type": "telegram_token" } ],
  "env": { "vars": { "BOT_TOKEN": "{{BOT_TOKEN}}", "WEBHOOK_SECRET": "{{WEBHOOK_SECRET}}", "PORT": "{{PORT}}" } },
  "webhook": { "path": "webhook", "token_param": "BOT_TOKEN" },
  "web": { "port": 8080 },
  "run": { "command": "python main.py" }
}

ربات Node.js (Telegraf / grammY)

{
  "type": "telegram-polling",
  "language": "node",
  "requires": { "node": ">=20" },
  "install": { "npm": true },
  "params": [ { "key": "BOT_TOKEN", "label": "توکن ربات", "type": "telegram_token" } ],
  "env": { "vars": { "BOT_TOKEN": "{{BOT_TOKEN}}" } },
  "run": { "command": "node index.js" }
}

سایت لاراول (یا هر سایت PHP با composer)

{
  "type": "web",
  "language": "php",
  "requires": { "php": ">=8.2", "extensions": ["mbstring", "xml", "pdo_mysql", "bcmath", "intl"] },
  "install": { "composer": true },
  "params": [
    { "key": "ADMIN_EMAIL", "label": "ایمیل مدیر", "type": "email" },
    { "key": "APP_KEY", "label": "کلید برنامه", "type": "secret", "generate": "laravel_key", "required": false }
  ],
  "env": { "file": ".env", "from": ".env.example", "vars": {
      "APP_URL": "{{APP_URL}}", "APP_ENV": "production", "APP_DEBUG": "false",
      "DB_HOST": "{{DB_HOST}}", "DB_PORT": "{{DB_PORT}}", "DB_DATABASE": "{{DB_NAME}}",
      "DB_USERNAME": "{{DB_USER}}", "DB_PASSWORD": "{{DB_PASS}}", "ADMIN_EMAIL": "{{ADMIN_EMAIL}}",
      "APP_KEY": "{{APP_KEY}}" } },
  "database": { "engine": "mysql" },
  "web": { "root": "public" },
  "post_install": ["php artisan migrate --force", "php artisan storage:link"],
  "cron": [ { "schedule": "* * * * *", "command": "php artisan schedule:run" } ],
  "persist": ["storage"]
}

سایت/API با Node.js (Express) یا Flask

{
  "type": "web",
  "language": "node",
  "install": { "npm": true },
  "params": [ { "key": "API_KEY", "label": "کلید API سرویس پرداخت", "type": "secret" } ],
  "env": { "vars": { "PORT": "{{PORT}}", "API_KEY": "{{API_KEY}}", "BASE_URL": "{{APP_URL}}" } },
  "web": { "port": 3000 },
  "run": { "command": "npm start" }
}

نکته‌ها و امنیت

• ربات وبهوک را با هدر X-Telegram-Bot-Api-Secret-Token برابر {{WEBHOOK_SECRET}} بررسی کنید تا درخواست جعلی پردازش نشود.
• ربات polling نباید هم‌زمان وبهوک داشته باشد؛ ستاپ خودش deleteWebhook می‌زند.
• برنامه‌ی پایتون/Node وب باید روی 127.0.0.1:$PORT گوش دهد؛ nginx درخواست‌ها را می‌فرستد.
• فایل‌های .env، .sql، .sqlite، vendor/ و فایل‌های نقطه‌دار از وب قابل دانلود نیستند (nginx می‌بندد). روی cPanel خودتان با .htaccess محافظت کنید.
• دستورهای install.commands، post_install، run و cron با کاربر محدود برنامه اجرا می‌شوند، به خریدار قبل از شروع نشان داده می‌شوند و مثل بقیه‌ی کد در بررسی نسخه توسط مدیر دیده می‌شوند.
• symlink داخل سورس پشتیبانی نمی‌شود (هنگام ستاپ حذف می‌شود). فایل SQL با کاربر محدود دیتابیس import می‌شود.
• هاست اشتراکی cPanel پروسه‌ی دائمی ندارد: ربات‌های polling، پایتون و Node فقط روی VPS نصب می‌شوند.
• قبل از انتشار، از تب «ستاپ خودکار» سورس خودتان گزینه‌ی تست ستاپ روی شاخه را روی یک سرور تست اجرا کنید.