استقرار روی cPanel،
ساده، قابل‌تکرار و کنترل‌شده.

شروع سریع

برای اولین Deploy فقط این مسیر را برو. جزئیات فنی را فعلاً لازم نیست بخوانی.

اجرای سریع

chmod +x rahsepar.sh
./rahsepar.sh --dry-run
./rahsepar.sh

.\rahsepar.cmd --dry-run
.\rahsepar.cmd

رهسپار چطور کار می‌کند؟

کلاینت و سرور دو نقش جدا دارند. کلاینت فایل Release را می‌سازد و می‌فرستد؛ extract.php روی هاست، صحت فایل را بررسی و Release را امن‌تر Publish می‌کند.

راه‌اندازی هاست

۱. آپلود فایل سرور

extract.php را در ریشه‌ی مقصد Deploy قرار بده. اسکریپت هنگام اجرا پوشه‌های داخلی خودش را می‌سازد.

۲. ایجاد Token

# file: .deploy-token
YOUR_LONG_RANDOM_SECRET

کلاینت Token را با Header به نام X-Deploy-Token می‌فرستد. اگر فایل Token وجود نداشته باشد یا خالی باشد، API با خطای TOKEN_NOT_CONFIGURED پاسخ می‌دهد.

۳. Health خود API

Action health وضعیت PHP، ZipArchive، writable بودن ریشه و تنظیم بودن Token را بررسی می‌کند.

curl -H "X-Deploy-Token: YOUR_TOKEN" \
  "https://example.com/extract.php?action=health"

نصب و اجرا در Linux / macOS

نسخه Shell به Bash، jq، curl و zip نیاز دارد. برای Watch Mode در Linux به inotifywait نیز نیاز است.

chmod +x rahsepar.sh
./rahsepar.sh --dry-run
./rahsepar.sh

نصب و اجرا در Windows

نسخه Windows با PowerShell 5.1+ یا PowerShell 7+ اجرا می‌شود و برای انتقال فایل از curl.exe استفاده می‌کند. فایل rahsepar.cmd ابتدا pwsh.exe و در صورت نبودن آن powershell.exe را اجرا می‌کند.

.\rahsepar.cmd --dry-run
.\rahsepar.cmd

نسخه PowerShell برای ساخت ZIP از System.IO.Compression استفاده می‌کند و از نظر مراحل Deploy با نسخه Shell هم‌ساختار است.

فایل config.json

هر دو نسخه Linux و Windows از یک Schema مشترک استفاده می‌کنند. اگر ProjectRoot نسبی باشد، نسبت به محل فایل کانفیگ Resolve می‌شود.

{
  "ProjectRoot": ".",
  "BuildFolder": "dist",
  "ZipFileName": "politest.ir.zip",
  "FtpHost": "ftp.example.com",
  "RemoteUser": "cpanel-user",
  "FtpPassword": "",
  "RemotePath": "public_html",
  "ExtractScriptUrl": "https://example.com/extract.php",
  "Token": "",
  "HealthUrl": "https://example.com/",
  "BuildCommand": "bun run build",
  "UploadRetries": 3,
  "RequestTimeoutSeconds": 300,
  "HealthTimeoutSeconds": 20,
  "StatusPollSeconds": 2,
  "StatusTimeoutSeconds": 330,
  "KeepLocalArchive": false,
  "AllowInsecureHttp": false
}

متغیرهای محیطی

برای اینکه Password و Token داخل config.json ذخیره نشوند، می‌توانی آن‌ها را با Environment Variable بدهی. این مقادیر بر config اولویت دارند.

دستورها و فلگ‌ها

چرخه کامل Deploy

Watch Mode

Watch Mode برای توسعه مناسب است. با مشاهده‌ی تغییر فایل‌ها یک اجرای Deploy جداگانه آغاز می‌شود.

./rahsepar.sh --watch

.\rahsepar.cmd --watch

نسخه Linux از inotifywait و نسخه Windows از FileSystemWatcher استفاده می‌کند. مسیرهای Build، node_modules، .git و داده‌های داخلی Deploy از Watch کنار گذاشته می‌شوند.

Rollback

رهسپار قبل از Publish از نسخه قبلی Backup می‌سازد. اگر Health Check پس از Deploy Fail شود، کلاینت برای همان Deploy ID درخواست Rollback می‌فرستد.

./rahsepar.sh --rollback
.\rahsepar.cmd --rollback

./rahsepar.sh --rollback --deploy-id=YOUR_ID
.\rahsepar.cmd --rollback --deploy-id=YOUR_ID

لاگ‌ها

هر Run یک Log محلی مستقل می‌سازد. Secretها در خروجی کانفیگ Mask می‌شوند و Debug Mode هم برای تشخیص جزئیات بیشتر وجود دارد.

╭────────────────────────────────────────────────────────────╮
│ 1/6 · Build                                                │
╰────────────────────────────────────────────────────────────╯
[20:17:31] ● INFO     Cleaning previous build output…
[20:17:31] ● INFO     Running: bun run build
[20:17:36] ✔ SUCCESS  Build completed in 5s.

╭────────────────────────────────────────────────────────────╮
│ 4/6 · Remote deployment                                    │
╰────────────────────────────────────────────────────────────╯
[20:17:44] ● INFO     Deploy ID: 5758fee9-...
[20:17:47] ✔ SUCCESS  Server applied the release successfully.

مسیر Log محلی:

سمت سرور نیز رویدادها در .deploy-server.log ثبت و در صورت بزرگ شدن Rotate می‌شوند.

API فایل extract.php

نسخه فعلی API مقدار api_version = 2.0 برمی‌گرداند. تمام Actionها بعد از احراز هویت Token اجرا می‌شوند.

فرمت پاسخ

{
  "ok": true,
  "api_version": "2.0",
  "message": "Deployment completed successfully.",
  "data": { ... },
  "timestamp": "..."
}

Stateهای Deploy

هر Deploy ID یک State مستقل دارد. کلاینت هنگام قطع شدن درخواست اولیه می‌تواند با Action status نتیجه واقعی را Poll کند.

Stateهای میانی نشان‌دهنده مرحله فعلی هستند. completed پایان موفق، failed شکست، و failed_rolled_back یعنی Deploy Fail شده اما Rollback خودکار سمت سرور موفق بوده است.

فایل‌ها و پوشه‌های داخلی

نکات امنیتی

Exit Codeهای مهم

عیب‌یابی سریع