254 lines
10 KiB
Markdown
254 lines
10 KiB
Markdown
# Noya — Production Deployment Runbook (راهنمای جامع استقرار ایزوله)
|
|
|
|
این سند راهنمای عملیاتی و گامبهگام برای استقرار ایمن و کاملاً ایزوله پروژه **Noya** روی سرور جدید است. این فرآیند به گونهای طراحی شده که هیچ تداخلی با سایر پروژهها، پورتها، کانتینرها و دیتابیسهای موجود روی سرور ایجاد نکند و تا زمان تأیید نهایی، هیچ نیازی به تغییر در رکوردهای DNS دامنه ندارد.
|
|
|
|
---
|
|
|
|
## ۱. پیشنیازها و ارزیابی سرور جدید (Server Preflight)
|
|
|
|
پیش از انتقال یا اجرای هر فایلی، دستورات زیر را روی سرور جدید اجرا کنید:
|
|
|
|
```bash
|
|
# ۱. بررسی فضای دیسک و حافظه رم (حداقل ۱۰ گیگابایت دیسک و ۲ گیگابایت رم آزاد پیشنهاد میشود)
|
|
df -h /
|
|
free -m
|
|
|
|
# ۲. بررسی معماری پردازنده و فلگ SSE4.2 (جهت تعیین نسخه MySQL)
|
|
lscpu | grep -E "Model name|Flags|sse4_2"
|
|
|
|
# ۳. بررسی پورتهای در حال استفاده (جهت اطمینان از آزاد بودن پورت ۳۸۰۸۰ یا انتخاب پورت دیگر)
|
|
sudo ss -tulpn | grep 38080
|
|
|
|
# ۴. بررسی کانتینرها و شبکههای فعال داکر
|
|
docker ps --format "table {{.Names}}\t{{.Ports}}\t{{.Status}}"
|
|
docker network ls
|
|
|
|
# ۵. بررسی وضعیت Reverse Proxy فعال سرور (Nginx، Caddy، Traefik یا NPM)
|
|
ps aux | grep -E 'nginx|caddy|traefik'
|
|
```
|
|
|
|
---
|
|
|
|
## ۲. روش ساخت (Build) و بستهبندی Imageها در سیستم محلی
|
|
|
|
با توجه به محدودیتهای احتمالی دانلود پکیجها و باینریهای Prisma روی سرورهای واقع در ایران، **روش پیشنهادی و پایدار**، ساخت محلی Imageها و انتقال آنها به صورت فایل فشرده است:
|
|
|
|
```bash
|
|
# در سیستم محلی (پوشه ریشه پروژه E:\P_W_A):
|
|
|
|
# الف) ساخت ایمیج فرانتاند برای معماری لینوکس x86_64
|
|
docker build --platform linux/amd64 -t noya-frontend:latest .
|
|
|
|
# ب) ساخت ایمیج بکاند برای معماری لینوکس x86_64
|
|
docker build --platform linux/amd64 -t noya-backend:latest ./backend
|
|
|
|
# ج) خروجی و فشردهسازی ایمیجها به فرمت tar.gz
|
|
docker save noya-frontend:latest | gzip > noya-frontend.tar.gz
|
|
docker save noya-backend:latest | gzip > noya-backend.tar.gz
|
|
```
|
|
|
|
> **نکته:** در صورتی که پردازنده سرور جدید ARM64 باشد (مانند سرورهای Hetzner CAX)، در دستورات فوق مقدار `--platform linux/arm64` قرار دهید.
|
|
|
|
---
|
|
|
|
## ۳. انتقال فایلها به سرور جدید
|
|
|
|
فولدر اختصاصی برای پروژه در مسیر استاندارد سرور (مثلاً `/opt/noya`) ایجاد کنید:
|
|
|
|
```bash
|
|
# روی سرور جدید:
|
|
sudo mkdir -p /opt/noya/backend
|
|
sudo chown -R $USER:$USER /opt/noya
|
|
```
|
|
|
|
سپس از سیستم محلی، فایلهای موردنیاز را با `scp` منتقل کنید:
|
|
|
|
```bash
|
|
# انتقال ایمیجهای ساختهشده:
|
|
scp noya-frontend.tar.gz noya-backend.tar.gz user@NEW_SERVER_IP:/opt/noya/
|
|
|
|
# انتقال فایل کامپوز و نمونههای کانفیگ:
|
|
scp docker-compose.prod.yml user@NEW_SERVER_IP:/opt/noya/
|
|
scp .env.production.example user@NEW_SERVER_IP:/opt/noya/.env
|
|
scp .env.mysql.example user@NEW_SERVER_IP:/opt/noya/.env.mysql
|
|
scp backend/.env.production.example user@NEW_SERVER_IP:/opt/noya/backend/.env
|
|
```
|
|
|
|
---
|
|
|
|
## ۴. بارگذاری ایمیجها و تنظیم متغیرهای محیطی روی سرور
|
|
|
|
وارد سرور شوید و مراحل زیر را انجام دهید:
|
|
|
|
### ۴.۱. لود کردن ایمیجها در Docker سرور
|
|
```bash
|
|
cd /opt/noya
|
|
docker load < noya-frontend.tar.gz
|
|
docker load < noya-backend.tar.gz
|
|
```
|
|
|
|
### ۴.۲. تنظیم فایلهای محیطی محرمانه
|
|
فایلهای `.env` را با مقادیر واقعی و امن ویرایش کنید:
|
|
|
|
1. **فایل دیتابیس (`/opt/noya/.env.mysql`):**
|
|
```ini
|
|
MYSQL_ROOT_PASSWORD=your_generated_secure_root_password_32char
|
|
MYSQL_DATABASE=noya_db
|
|
MYSQL_USER=noya_user
|
|
MYSQL_PASSWORD=your_generated_secure_user_password_32char
|
|
```
|
|
|
|
2. **فایل اصلی کامپوز (`/opt/noya/.env`):**
|
|
```ini
|
|
NOYA_WEB_PORT=38080
|
|
NOYA_IMAGE_TAG=latest
|
|
# در صورت پشتیبانی CPU از SSE4.2 میتوانید mysql:8.0 بگذارید، در غیر این صورت mysql:5.7
|
|
NOYA_MYSQL_IMAGE=mysql:5.7
|
|
```
|
|
|
|
3. **فایل بکاند (`/opt/noya/backend/.env`):**
|
|
```ini
|
|
NODE_ENV=production
|
|
PORT=3001
|
|
HOST=0.0.0.0
|
|
# توجه به رمز عبور: اگر رمز حاوی کاراکترهای خاص است باید URL-encoded باشد.
|
|
# پیشنهاد: استفاده از رمز صرفاً الفبانومریک (A-Z, a-z, 0-9) با طول ۳۲ حرف.
|
|
DATABASE_URL=mysql://noya_user:your_generated_secure_user_password_32char@noya-mysql:3306/noya_db
|
|
LOG_LEVEL=info
|
|
CORS_ORIGIN=https://your-domain.com
|
|
TRUST_PROXY=true
|
|
AUTH_SESSION_TTL_HOURS=168
|
|
ADMIN_EMAILS=admin@your-domain.com
|
|
OPENAI_API_KEY=your_production_gapgpt_or_openai_api_key
|
|
OPENAI_BASE_URL=https://api.gapgpt.app/v1
|
|
OPENAI_MODEL=gpt-4o-mini
|
|
```
|
|
|
|
---
|
|
|
|
## ۵. راهاندازی سرویسها
|
|
|
|
```bash
|
|
cd /opt/noya
|
|
docker compose -f docker-compose.prod.yml up -d
|
|
```
|
|
|
|
### بررسی وضعیت کانتینرها:
|
|
```bash
|
|
docker compose -f docker-compose.prod.yml ps
|
|
```
|
|
کانتینرهای زیر باید در حالت `Up` (و برای MySQL در وضعیت `healthy`) باشند:
|
|
- `noya-mysql`
|
|
- `noya-backend`
|
|
- `noya-frontend`
|
|
|
|
---
|
|
|
|
## ۶. تست و اعتبارسنجی پیش از تغییر DNS (Zero-Downtime Verification)
|
|
|
|
### ۶.۱. تست داخلی سرور (Localhost Health)
|
|
```bash
|
|
# بررسی سلامت وب فرانتاند
|
|
curl -I http://127.0.0.1:38080/health
|
|
# پاسخ باید HTTP 200 با متن healthy باشد
|
|
|
|
# بررسی سلامت بکاند و ارتباط موفق با MySQL (اجرای موفق مایگریشنها و سید)
|
|
curl -s http://127.0.0.1:38080/api/backend/ready
|
|
# خروجی باید شامل status: "ready" و database: "ok" باشد:
|
|
# {"success":true,"data":{"status":"ready","checks":{"database":"ok"}}}
|
|
```
|
|
|
|
### ۶.۲. اتصال به Reverse Proxy موجود سرور
|
|
یک VirtualHost مستقل برای دامنه نویا به Nginx اصلی سرور اضافه کنید (مثلاً `/etc/nginx/sites-available/noya.conf`):
|
|
|
|
```nginx
|
|
server {
|
|
listen 80;
|
|
server_name your-domain.com;
|
|
|
|
location / {
|
|
proxy_pass http://127.0.0.1:38080;
|
|
proxy_http_version 1.1;
|
|
proxy_set_header Upgrade $http_upgrade;
|
|
proxy_set_header Connection 'upgrade';
|
|
proxy_set_header Host $host;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|
proxy_connect_timeout 10s;
|
|
proxy_read_timeout 180s;
|
|
proxy_send_timeout 180s;
|
|
}
|
|
}
|
|
```
|
|
سپس فعالسازی و ریلود:
|
|
```bash
|
|
sudo ln -s /etc/nginx/sites-available/noya.conf /etc/nginx/sites-enabled/
|
|
sudo nginx -t && sudo systemctl reload nginx
|
|
```
|
|
|
|
### ۶.۳. تست با Override کلاینت (بدون دستکاری DNS)
|
|
در کامپیوتر خودتان، فایل hosts را باز کنید:
|
|
- ویندوز: `C:\Windows\System32\drivers\etc\hosts`
|
|
- لینوکس / مک: `/etc/hosts`
|
|
|
|
خط زیر را اضافه کنید:
|
|
```text
|
|
NEW_SERVER_IP your-domain.com
|
|
```
|
|
|
|
اکنون مرورگر خود را در حالت Private/Incognito باز کرده و آدرس `http://your-domain.com` را بررسی کنید:
|
|
1. ثبت نام کاربر تستی جدید.
|
|
2. ارسال پیام چت و دریافت پاسخ استریم هوش مصنوعی.
|
|
3. بررسی باز شدن جلسات آموزشی.
|
|
4. بررسی عدم بروز هرگونه خطای CORS یا دیتابیس در کنسول مرورگر (`F12`).
|
|
|
|
---
|
|
|
|
## ۷. مشاهده و بررسی لاگها (Log Inspection)
|
|
|
|
```bash
|
|
# لاگ زنده تمام سرویسهای نویا
|
|
docker compose -f docker-compose.prod.yml logs -f --tail=100
|
|
|
|
# لاگ اختصاصی بکاند
|
|
docker compose -f docker-compose.prod.yml logs -f noya-backend
|
|
|
|
# لاگ اختصاصی دیتابیس
|
|
docker compose -f docker-compose.prod.yml logs -f noya-mysql
|
|
|
|
# لاگ اختصاصی فرانتاند
|
|
docker compose -f docker-compose.prod.yml logs -f noya-frontend
|
|
```
|
|
|
|
---
|
|
|
|
## ۸. فعالسازی نهایی دامنه (Final Cutover)
|
|
|
|
پس از تأیید کامل تست مرحله ۶:
|
|
1. صدور گواهی SSL (Let's Encrypt / Certbot) روی سرور جدید:
|
|
```bash
|
|
sudo certbot --nginx -d your-domain.com
|
|
```
|
|
2. حذف خط تستی اضافه شده به فایل `hosts` سیستم محلی شما.
|
|
3. ورود به پنل مدیریت دامنه (Cloudflare، ابرآروان یا کنترلپنل دامنه) و تغییر رکورد `A` به `NEW_SERVER_IP`.
|
|
|
|
---
|
|
|
|
## ۹. برنامه بازگشت اضطراری (Rollback Plan)
|
|
|
|
در صورت بروز هرگونه مشکل یا ناپایداری غیرمنتظره پس از اتصال:
|
|
1. **بازگشت فوری DNS:** رکورد `A` در پنل DNS به IP سرور قبلی بازگردانده شود (ظرف چند دقیقه اعمال میشود).
|
|
2. **توقف امن سرویسهای نویا روی سرور جدید:**
|
|
```bash
|
|
cd /opt/noya
|
|
docker compose -f docker-compose.prod.yml stop
|
|
```
|
|
*(دادههای ثبتشده در Volume `noya_mysql_data` بدون آسیب حفظ میمانند).*
|
|
3. **غیرفعالسازی کانفیگ در Reverse Proxy سرور جدید:**
|
|
```bash
|
|
sudo rm -f /etc/nginx/sites-enabled/noya.conf
|
|
sudo nginx -t && sudo systemctl reload nginx
|
|
```
|
|
با این کار، سرور جدید دقیقاً به وضعیت پاک و اولیه خود قبل از استقرار نویا بازمیگردد.
|