# راهنمای نصب بتای محدود FTG2 روی سرور لینوکس + Docker

## پیش‌نیازها

سرور با Docker و Docker Compose v2، دامنه واقعی، باز بودن 80/443، SMTP واقعی، DNS معتبر، و دسترسی بکاپ امن. از دیتابیس **جدید و اختصاصی** با نامی آغازشونده با `ftg2_beta_` استفاده کن. **هرگز `football_game` یا `ftg2_test_20261017` را به سرور وصل نکن.**

## قدم‌ها

1. سورس جاری همراه `deploy/beta` و `config/release_settings.py` را روی سرور آماده کن. فایل `.env` ویندوز، دامپ، بکاپ و اطلاعات ورود آزمایشی را کپی نکن. Docker context با allowlist سورس محدود شده است؛ نسخه آرشیوی قدیمی را مبنای استقرار جدید قرار نده.
2. داخل `deploy/beta`، فایل `.env.server.example` را به `.env.server` کپی کن و تمامی مقادیر `REPLACE_*` را با رمزهای **مستقل و قوی** جایگزین کن. رمزها را در Git یا گفتگو قرار نده. نام دامنه واقعی را برای FTG_DOMAIN، DJANGO_ALLOWED_HOSTS، لینک تأیید حساب و ایمیل فرستنده وارد کن. `FTG_BETA_REGISTRATION_CODE` باید تصادفی و با کلید Django متفاوت باشد.
3. از ریشه پروژه، `python deploy/beta/release_audit.py` اجرا کن؛ باید `CONFIG AUDIT OK` باشد. این ابزار آفلاین است و به DB دست نمی‌زند.
4. از پوشه `deploy/beta` (روی سرور Linux) دستورات زیر را به‌ترتیب اجرا کن:

```
docker compose --env-file .env.server -f compose.yaml config --quiet
docker compose --env-file .env.server -f compose.yaml build web worker
docker compose --env-file .env.server -f compose.yaml up -d db cache clamav
# برای دیتابیس تازه و بدون دیتا:
docker compose --env-file .env.server -f compose.yaml run --rm web python manage.py shell -c "from django.db import connection; assert connection.settings_dict['NAME'].startswith('ftg2_beta_'); print('DB OK:', connection.settings_dict['NAME'])"
docker compose --env-file .env.server -f compose.yaml run --rm web python manage.py migrate --noinput

docker compose --env-file .env.server -f compose.yaml run --rm web python manage.py prepare_game_world
docker compose --env-file .env.server -f compose.yaml run --rm web python manage.py collectstatic --noinput
docker compose --env-file .env.server -f compose.yaml --profile setup run --rm frontend-build
docker compose --env-file .env.server -f compose.yaml up -d web worker match-worker friendly-worker infrastructure-beat caddy
```

5. بعد از روشن‌شدن Worker:

```
docker compose --env-file .env.server -f compose.yaml exec web python manage.py check --deploy
docker compose --env-file .env.server -f compose.yaml exec web python manage.py runtime_preflight --production
docker compose --env-file .env.server -f compose.yaml exec web python manage.py verify_full_system --production --broker-roundtrip
```

تست HTTPS در مرورگر و از خارج سرور: `https://YOUR_DOMAIN/health/live/` و `https://YOUR_DOMAIN/health/ready/` و صفحه ثبت‌نام با کد دعوت، سپس ورود و ساخت کارت رایگان. پاسخ readiness باید HTTP 200 باشد و Worker حاضر باشد. ایمیل تأیید را عملاً دریافت کن.

سرویس `infrastructure-beat` از ابتدا heartbeat، ارسال ایمیل، outbox و اعلان‌ها را زمان‌بندی می‌کند. این سرویس مسابقه، بازار یا حقوق را جلو نمی‌برد. برای تازه‌شدن readiness تا یک چرخه ۳۰ثانیه‌ای فرصت بده. گزینه `--broker-roundtrip` ارتباط واقعی کارگر را هم بررسی می‌کند.

6. **فقط پس از** تأیید چندکاربره و آماده‌بودن جهان بازی، زمان‌بند چرخه‌های بازی را به‌صورت آگاهانه روشن کن:

```
docker compose --env-file .env.server -f compose.yaml --profile scheduler up -d beat
```

برای توقف پیشروی جهان، فقط `beat` را متوقف کن؛ `infrastructure-beat` باید برای ایمیل، سلامت و تحویل رخدادها فعال بماند. دو سرویس به‌ترتیب با `FTG_SCHEDULER_MODE=infrastructure` و `world` اجرا می‌شوند و schedule مشترک ندارند. یک Beat سوم با mode پیش‌فرض `all` کنار این دو اجرا نکن.

## اسکن مدارک و نشست مرورگر

فایل آپلودی در release تا تکمیل اسکن در وضعیت PENDING می‌ماند و قابل دانلود نیست. کار `evidence-scan` هر ۳۰ ثانیه فایل‌های منتظر را با پروتکل [INSTREAM رسمی ClamAV](https://docs.clamav.net/manual/Usage/ClamdProtocol.html) به سرویس داخلی `clamav` می‌فرستد؛ پاسخ خطا، قطع ارتباط یا عدم تطابق SHA-256 هیچ‌کدام فایل را CLEAN نمی‌کنند. نتیجه اسکن و هش در زنجیره تحویل مدرک ثبت می‌شود. پورت ۳۳۱۰ را روی میزبان منتشر نکن.

برای سرویس اسکن منابع کافی و به‌روزرسانی signatureها لازم است؛ مطابق [راهنمای Docker ClamAV](https://docs.clamav.net/manual/Installing/Docker.html)، مصرف حافظه آن را جداگانه ظرفیت‌سنجی کن. روی محیط آزمایشی، یک فایل پاک و فایل تست استاندارد EICAR را بررسی کن و سپس وضعیت اسکن و مجوز دانلود را کنترل کن. استقرار واقعی این سرویس باید روی میزبان Docker تأیید شود.

فرانت‌اند جدید از `/api/v1/users/browser/` استفاده می‌کند: refresh فقط در کوکی HttpOnly/Secure در محیط انتشار و access فقط در حافظه نگهداری می‌شود. ورود، refresh و خروج نیازمند CSRF هستند. پراکسی همان origin را حفظ می‌کند و CSP فعال است. کلاینت‌های غیرمرورگری همچنان API قدیمی JWT را دارند. پس از ارتقای فرانت، کاربران نسخه قدیمی یک بار دوباره وارد می‌شوند؛ توکن‌های ذخیره‌شده قدیمی از localStorage حذف می‌شوند.

## بکاپ، بازیابی و نکات امنیتی

دستورهای نگهداری، پایش و آزمون‌های پذیرش در [گزارش آمادگی سرور](../../docs/SERVER_READINESS_FA_20261105.md) آمده‌اند. برای ارتقا با حفظ توقف نوشتن تا پایان میگریشن، روی Linux از `bash stage.sh /absolute/private/backup-root` استفاده کن. این دستور زمان‌بند جهان را روشن نمی‌کند؛ شکست میگریشن نیازمند بررسی اپراتور است. اسکریپت‌های Docker باید ابتدا روی Staging آزموده شوند.

- هر بار قبل از Migration جدید، از PostgreSQL **همان محیط بتا** بکاپ داشته باش. روی میزبان لینوکس: `docker compose --env-file .env.server -f compose.yaml exec -T db pg_dump -U ftg2_beta -d ftg2_beta_new -Fc > ftg2_beta_backup.dump` (نام کاربر و DB واقعی از env را جایگزین کن). فایل را رمزگذاری و خارج از سرور کپی کن.
- **حتماً یک بار بازیابی بکاپ را در دیتابیس آزمایشی مستقل تست کن**؛ فقط گرفتن فایل بکاپ کافی نیست.
- Redis، PostgreSQL و Media هیچ پورتی روی اینترنت ندارند؛ مسیر media خصوصی به Caddy وصل نشده. در صورت نیاز به دانلود مدارک محرمانه، API مجوزدار جداگانه لازم است.
- Caddy با گواهی TLS خودکار کار می‌کند؛ DNS دامنه باید قبل از استارت درست باشد. HTTPS proxy-only و HSTS کوتاه بتا را حفظ کن.
- برای هزینه‌های واقعی FTG و NFT on-chain فعلاً استفاده تجاری نکن. آزمون اعتبار کیف پول در DB تست به معنی پرداخت واقعی نیست.
- اگر اپلیکیشن بعد از Deploy خطا داشت، ابتدا `docker compose --env-file .env.server -f compose.yaml logs --tail=100 web worker caddy` را بررسی کن؛ `.env.server` یا رمزها را در گزارش عمومی کپی نکن.

### واریز و برداشت توکن

چرخه درخواست و حساب امانی مستقل در سورس آماده است؛ اتصال شبکه واقعی هنوز انتخاب و فعال نشده است. تنظیمات `FTG_BRIDGE_*` در نمونه محیط سرور پیش‌فرض غیرفعال‌اند. قبل از فعال‌سازی، migrationهای economy، تطبیق دفترکل و امانت، تأیید پشتوانه موجودی فعلی و آزمون crash/restart آداپتر را روی مقصد مستقل انجام دهید. worker پروفایل `tokenization` فقط صف `token-bridge` را مصرف می‌کند؛ آن را به worker مسابقه اضافه نکنید. [معماری، دستورها و مرز NFT](../../docs/TOKEN_WALLET_ARCHITECTURE_FA.md) مرجع این مرحله است.

### وضعیت تأیید استقرار

Compose و Dockerfile در اینجا تولید شده‌اند، ولی Docker daemon و دیتابیس/Redis تولیدی برای آزمون واقعی در محیط ساخت در دسترس نبود. این فایل‌ها **طرح استقرار قابل اجرا** هستند، نه گواهی اینکه سرور هم‌اکنون GO است.