استقرار (Deployment)

پلتفرم روی یک VPS با Docker Compose مستقر می‌شود؛ پشت یک reverse proxy مشترک (Caddy) که TLS خودکار (Let's Encrypt) می‌گیرد. این Caddy جدا از compose بالا اجرا می‌شود و از طریق شبکهٔ خارجی caddy-net به container‌ها وصل می‌شود.

سرویس‌ها

Container	نقش
`taghvimam-db`	PostgreSQL (دیتابیس تولید)
`taghvimam-api`	بک‌اند Express (پورت داخلی ۵۰۰۰)
`taghvimam-web`	اپ وب (serving استاتیک با `serve`، پورت ۸۰)
`taghvimam-docs`	این سایت مستندات (Docusaurus + Redoc)

دامنه‌ها

دامنه	مقصد
`api.taghvimam.ir`	`taghvimam-api`
`taghvimam.ir`	`taghvimam-web`
`docs.taghvimam.ir`	`taghvimam-docs`

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

DATABASE_URL, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB
JWT_SECRET, JWT_REFRESH_SECRET, JWT_ACCESS_EXPIRES_IN, JWT_REFRESH_EXPIRES_IN
KAVENEGAR_API_KEY, KAVENEGAR_SENDER
CORS_ORIGIN
SYNC_CURSOR_SECRET        # کلید HMAC برای امضای cursor همگام‌سازی
VITE_API_URL              # URL API برای build اپ وب

دستورهای استقرار

cp .env.example .env            # تمام متغیرها را پر کنید
docker compose up -d --build    # build و بالا آوردن همه‌چیز
# یا: ./deploy.sh               # همین کار + down قبلی و بررسی سلامت

برای راهنمای setup/deploy روی محیط محلی به صفحهٔ شروع به کار مراجعه کنید. ادامهٔ این صفحه چک‌لیستِ کاملِ پیش و پس از استقرار است.

چک‌لیستِ پیش از استقرار

کیفیت کد:

npm run lint                      # همهٔ فایل‌های TS از ESLint عبور کنند
npm run type-check 2>/dev/null || npm run build --workspace taghvimam-backend
npm test --workspace taghvimam-backend
npm audit                         # بدون آسیب‌پذیریِ شناخته‌شده

امنیت:

RATE_LIMIT_WINDOW_MS / RATE_LIMIT_MAX_REQUESTS برای تولید پیکربندی شده‌اند.
محدودیتِ حجمِ درخواست (مثلاً express.json({ limit: '1mb' })) اعمال شده.
.env.example به‌روز است — همهٔ متغیرهای ضروری در آن مستند شده‌اند.

دیتابیس:

npx prisma migrate deploy         # اعمالِ migration‌ها
pg_dump "$DATABASE_URL" > "backup_$(date +%Y%m%d_%H%M%S).sql"   # بک‌آپ قبل از استقرار

نقاطِ پایانیِ سلامت و پایش

curl https://api.taghvimam.ir/health           # { status: "healthy", ... }
curl https://api.taghvimam.ir/health/live      # liveness probe
curl https://api.taghvimam.ir/health/ready     # readiness probe
curl https://api.taghvimam.ir/metrics          # Prometheus metrics
curl https://api.taghvimam.ir/api-docs-json    # spec خامِ OpenAPI

پاسخِ نمونهٔ GET /health:

{
  "status": "healthy",
  "timestamp": "2026-07-31T10:00:00.000Z",
  "uptime": 3600,
  "memory": { "rss": 50000000, "heapTotal": 20000000, "heapUsed": 15000000 }
}

چک‌لیستِ پس از استقرار

curl https://api.taghvimam.ir/health → 200 OK.
احراز هویت کار می‌کند (یک OTP → verify → دسترسی به یک مسیرِ محافظت‌شده، مثلاً GET /api/sync/changes با Authorization: Bearer <token>).
header‌های cache (ETag، Cache-Control) روی یک مسیرِ محافظت‌شده حاضرند، مثلاً: curl -I -H "Authorization: Bearer <token>" https://api.taghvimam.ir/api/sync/changes.
/metrics معیارهای Prometheus را برمی‌گرداند.
لاگ‌ها بدون خطای غیرمنتظره‌اند.

روالِ بازگشت (Rollback)

# ۱) توقف نسخهٔ جدید
docker compose stop taghvimam-api

# ۲) بازگردانی تصویرِ قبلی (یا restore بیلدِ قبلی)
# ۳) در صورت نیاز، بازگردانی دیتابیس (فقط اگر migration مشکل ساخت):
psql "$DATABASE_URL" < backup_pre_deployment_*.sql

# ۴) بالا آوردن دوباره و تأیید
docker compose up -d taghvimam-api
curl https://api.taghvimam.ir/health

هشدارها و آستانه‌های پیشنهادی

نرخِ خطا > ۵٪
زمانِ پاسخ > ۲ ثانیه
مصرفِ حافظه > ۸۰٪
فضای دیسک > ۹۰٪

دستورهای پایشِ دیتابیس

# اتصال‌های فعال
psql "$DATABASE_URL" -c "SELECT count(*) FROM pg_stat_activity;"

# حجمِ دیتابیس
psql "$DATABASE_URL" -c "SELECT pg_size_pretty(pg_database_size(current_database()));"

سرویس‌ها​

دامنه‌ها​

متغیرهای محیطی ضروری​

دستورهای استقرار​

چک‌لیستِ پیش از استقرار​

نقاطِ پایانیِ سلامت و پایش​

چک‌لیستِ پس از استقرار​

روالِ بازگشت (Rollback)​

هشدارها و آستانه‌های پیشنهادی​

دستورهای پایشِ دیتابیس​