Zareian
5003b8a852
A shared guest account was hand-seeded into the production DB on 2026-09-22 so the frontend developer could see the notification and leaderboard screens before any real traffic exists: deviceId "frontend-test-device", user 6, with 24 Notification rows and 20 LeaderboardEntry rows across both periods, ordered differently per period so the ?period= parameter is visibly doing something. None of that was recorded in the repo. db.sqlite3 is gitignored, so the account existed only in the head of whoever set it up — exactly the kind of thing that disappears at a handoff. It is now in docs/frontend/README.md, where the frontend developer looks, and in docs/operations.md, where whoever runs the server looks. Verified against production before writing it down: the account still resolves to user 6 with isNewUser false, notifications return rows, and both leaderboard periods return six entries. The notifications payload is keyed "items", not "results", which is noted because it is easy to read as an empty response. The operations entry carries the warning that matters: this is hand-written data in a production database, purge_demo_data will not catch it (it only matches [SEED]/[DEMO] prefixes on Grade/Plan/Character/User), and it has to go before real users arrive or they will see invented notifications. The Swagger description now says a deviceId can be any string and that pre-seeded ones exist on request, but deliberately does not print the specific value: /api/docs/ is reachable from the public internet, and a public API reference should not advertise a shared account that anyone can sign into. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
224 lines
14 KiB
Markdown
224 lines
14 KiB
Markdown
# عملیات
|
||
|
||
دیپلوی، پیکربندی، سلامت و بازیابی. برای شروعِ توسعه‌ی محلی `README.md` را
|
||
ببینید.
|
||
|
||
## دیپلوی
|
||
|
||
```bash
|
||
ssh -t administrator@78.38.35.249 \
|
||
'cd ~/mathapp-v2 && ./deploy.sh; sudo systemctl restart zareian-mathapp'
|
||
```
|
||
|
||
دو بار رمز می‌پرسد — یک‌بار برای `ssh` و یک‌بار برای `sudo`. **منتظرِ هر پرامپت
|
||
بمانید**؛ چسباندنِ چند خط با هم، متنِ صف‌شده را به پرامپتِ رمز می‌دهد و بعد از
|
||
سه تلاش قفل می‌شوید.
|
||
|
||
`deploy.sh` به ترتیب: fetch، برگرداندنِ درخت به `origin/<branch>`، نصبِ
|
||
وابستگی‌ها، `migrate`، `seed_content`، `collectstatic`، ری‌استارت، و در پایان
|
||
poll کردنِ `/api/health`.
|
||
|
||
دو رفتارش را بدانید:
|
||
|
||
- **سرور را تعمیر می‌کند، جلویش نمی‌ایستد.** فایلِ دستی‌ویرایش‌شده قبلاً
|
||
`git pull --ff-only` را می‌شکست و چون بقیه‌ی مراحل رد می‌شدند، سرور بی‌صدا
|
||
روی کدِ قدیمی می‌ماند. حالا تغییراتِ محلی در `.deploy-backups/` به‌صورتِ
|
||
patch ذخیره و بعد با `git reset --hard` دور ریخته می‌شوند، و کار ادامه
|
||
می‌یابد. هر اجرای کامل، سرور را دقیقاً روی همان چیزی می‌گذارد که در Gitea است.
|
||
- **ری‌استارت را اثبات می‌کند.** زمانِ `ActiveEnterTimestamp` را قبل و بعد
|
||
مقایسه می‌کند و اگر عوض نشده باشد با کدِ غیرِصفر خارج می‌شود. قبلاً فقط
|
||
آدرسِ عمومی را چک می‌کرد و **پروسه‌ی قدیمی** همان `200` را می‌داد — سرور دو
|
||
روز کدِ قدیمی سرو کرد در حالی که همه‌ی فایل‌ها روی دیسک تازه بودند.
|
||
|
||
> **فایل روی دیسک، فایلِ دیپلوی‌شده نیست.** قبل از باور کردنِ هر چیزی:
|
||
> `systemctl show zareian-mathapp -p ActiveEnterTimestamp`
|
||
|
||
متغیرهای اختیاری: `SKIP_PULL=1`، `TADRISINO_SERVICE`، `TADRISINO_HEALTH_URL`،
|
||
`PIP_INDEX_URL` (وقتی pypi.org تایم‌اوت می‌دهد).
|
||
|
||
## بررسیِ سلامت
|
||
|
||
```bash
|
||
curl https://api.math.tadrisino2.ir/api/health
|
||
```
|
||
|
||
بدونِ احرازِ هویت و بدونِ SSH می‌گوید: دیتابیس سالم است یا نه، مهاجرتِ
|
||
اعمال‌نشده مانده یا نه، کش کار می‌کند یا نه، چند پایه/درس/سوال روی آن سرور
|
||
هست، کدام سرویسِ بیرونی تنظیم شده (فقط بله/خیر)، و چه هشدارهای امنیتی‌ای
|
||
فعال‌اند. `200` سالم، `503` خرابیِ واقعی. **هیچ سکرتی برنمی‌گرداند.**
|
||
|
||
مهم‌ترین بررسی‌اش «مهاجرتِ اعمال‌نشده» است: شایع‌ترین حالتِ دیپلویِ خراب این
|
||
است که کد رفته ولی `migrate` اجرا نشده — اپ بالا می‌آید و بعد زیرِ بارِ واقعی
|
||
با خطای ستونِ ناموجود می‌شکند.
|
||
|
||
تأییدِ سریعِ اینکه API واقعاً جواب می‌دهد:
|
||
|
||
```bash
|
||
curl -i https://api.math.tadrisino2.ir/api/schema/
|
||
curl -i -X POST https://api.math.tadrisino2.ir/api/auth/session \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"type":"guest","deviceId":"verify-1"}'
|
||
```
|
||
|
||
## بکاپ و بازیابی
|
||
|
||
`db.sqlite3` در گیت **نیست** و تنها نسخه‌ی داده‌ی کاربران است. `deploy.sh`
|
||
پیش از `migrate` بکاپ نمی‌گیرد؛ تا وقتی این خودکار نشده، دستی بگیرید:
|
||
|
||
```bash
|
||
cd /home/administrator/mathapp-v2
|
||
mkdir -p .deploy-backups
|
||
venv/bin/python - <<'PY'
|
||
import sqlite3, datetime
|
||
dst = ".deploy-backups/db-%s.sqlite3" % datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
|
||
src, out = sqlite3.connect("db.sqlite3"), sqlite3.connect(dst)
|
||
with out:
|
||
src.backup(out) # نسخه‌ی سازگار حتی اگر هم‌زمان کسی بنویسد
|
||
out.close(); src.close()
|
||
print("backup:", dst, sqlite3.connect(dst).execute("PRAGMA integrity_check").fetchone()[0])
|
||
PY
|
||
```
|
||
|
||
`sqlite3` به‌عنوانِ فرمانِ خط فرمان روی آن سرور نصب **نیست** — از پایتونِ خودِ
|
||
پروژه استفاده کنید، نه `cp`؛ کپیِ ساده وسطِ یک نوشتن، فایلِ نیمه‌کاره می‌دهد.
|
||
|
||
بازیابی: سرویس را بخوابانید، فایل را برگردانید، دوباره بالا بیاورید.
|
||
|
||
```bash
|
||
sudo systemctl stop zareian-mathapp
|
||
cp .deploy-backups/db-<timestamp>.sqlite3 db.sqlite3
|
||
sudo systemctl start zareian-mathapp
|
||
curl https://api.math.tadrisino2.ir/api/health
|
||
```
|
||
|
||
## متغیرهای محیطی
|
||
|
||
`.env` خودکار خوانده می‌شود (`python-dotenv`) و مقادیرش **با پیش‌فرض‌های کد
|
||
ادغام می‌شوند، نه جایگزینشان**. پس یک `.env` ناقص روی سرور دیگر باعثِ بالا
|
||
نیامدن نمی‌شود. `.env.example` توضیحِ کاملِ هر کدام را دارد.
|
||
|
||
| متغیر | اگر ست نشود چه می‌شود |
|
||
|---|---|
|
||
| `DJANGO_DEBUG` | خاموش (`0`) — که حالتِ درستِ پروداکشن است |
|
||
| `DJANGO_SECRET_KEY` | یک کلیدِ تصادفیِ قوی ساخته و در `.django_secret_key` (مجوز `0600`) ذخیره می‌شود |
|
||
| `DJANGO_ALLOWED_HOSTS` | دامنه‌های خودمان پیش‌فرض‌اند |
|
||
| `CSRF_TRUSTED_ORIGINS` · `CORS_ALLOWED_ORIGINS` · `PUBLIC_BASE_URL` | پیش‌فرضِ درست دارند |
|
||
| `CACHE_URL` | سرویس بالا می‌آید ولی نرخ بینِ workerها مشترک نیست؛ `/api/health` هشدار می‌دهد |
|
||
| `KAVENEGAR_API_KEY` | `POST /api/auth/otp/request` خطای صریحِ `503` می‌دهد، نه موفقیتِ ساختگی |
|
||
| `ZARINPAL_MERCHANT_ID` | مسیرِ پرداخت fail-closed می‌ماند (`503`) |
|
||
| `OPENAI_API_KEY` · `QDRANT_API_KEY` | `POST /api/ai/ask` همان پاسخِ stub را می‌دهد |
|
||
| `TEST_LOGIN_PHONES` | هیچ حسابِ تستی باز نیست (بخشِ بعد) |
|
||
|
||
> **`DJANGO_SECRET_KEY` توکن‌های ورود را امضا می‌کند.** بهترین حالت این است که
|
||
> اصلاً ست نشود تا خودِ تنظیمات یکی بسازد — آن‌وقت کلیدی وجود ندارد که لو
|
||
> برود. **هرگز نگذارید سرور روی fallbackِ `django-insecure-…` کار کند**: آن
|
||
> رشته در همین ریپو کامیت شده، پس هر کسی که ریپو را بخواند می‌تواند به‌جای هر
|
||
> کاربری توکن جعل کند. `manage.py check --deploy` با کدِ `security.W009`
|
||
> علامتش می‌زند.
|
||
|
||
> **`DJANGO_DEBUG` هرگز روی سرور `1` نشود.** `DEV_MASTER_OTP` (کد `0000`) را
|
||
> روشن می‌کند که هر شماره‌ای را به‌عنوانِ ورودِ معتبر می‌پذیرد، و صفحه‌های خطا
|
||
> کلِ تنظیمات را نشان می‌دهند. جایش فقط `.env` است، نه یونیتِ systemd.
|
||
|
||
## ورودِ توسعه‌دهنده‌ها (بدونِ سرویسِ پیامک)
|
||
|
||
تا وقتی `KAVENEGAR_API_KEY` ست نشده، با `DEBUG=0` هیچ‌کس نمی‌تواند با شماره
|
||
وارد شود. برای اینکه ورودِ تیم به یک نفرِ خاص وابسته نباشد، چند شماره‌ی تست با
|
||
کدِ ثابت تعریف کنید:
|
||
|
||
```bash
|
||
TEST_LOGIN_PHONES=09120000001:834512,09120000002:110947
|
||
```
|
||
|
||
برای این شماره‌ها پیامکی ارسال نمی‌شود و همان کد همیشه معتبر است. هر شماره‌ی
|
||
دیگری مسیرِ عادیِ OTP را می‌رود، بی‌هیچ تغییری.
|
||
|
||
```bash
|
||
curl -X POST https://api.math.tadrisino2.ir/api/auth/otp/request \
|
||
-H 'Content-Type: application/json' -d '{"phone":"09120000001"}'
|
||
curl -X POST https://api.math.tadrisino2.ir/api/auth/login \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"phone":"09120000001","otp":"834512"}'
|
||
```
|
||
|
||
این همان الگویی‌ست که Firebase Auth (با نامِ fictional phone numbers) و Apple
|
||
(حسابِ دمو برای بررسیِ App Store) برای همین مسئله دارند.
|
||
|
||
- **با `DEV_MASTER_OTP` یکی نیست.** آن کدِ `0000` **هر** شماره‌ای را می‌پذیرد و
|
||
فقط با `DEBUG=1` روشن می‌شود. این فقط همین چند شماره را، هرکدام با کدِ خودش.
|
||
- **کد در پاسخِ API برنمی‌گردد**، پس دانستنِ شماره برای ورود کافی نیست. سقفِ
|
||
تلاشِ ورودِ هر شماره روی این‌ها هم اعمال می‌شود، پس حدسِ کد بسته است.
|
||
- **مقدارِ نامعتبر سرویس را بالا نمی‌آورد** و پیامِ صریح می‌دهد — بی‌صدا رد
|
||
نمی‌شود. کد باید ۴ تا ۶ رقم باشد (`LoginRequestSerializer` سقفِ ۶ کاراکتر
|
||
دارد).
|
||
- **`/api/health` تا وقتی پر باشد هشدار می‌دهد** — فقط تعداد، نه شماره و نه کد.
|
||
- شماره را **دقیقاً** همان‌طور بنویسید که کلاینت می‌فرستد؛ این کدبیس شماره را
|
||
normalize نمی‌کند، پس `09121111111` و `+989121111111` دو کاربرِ جدا هستند.
|
||
- کدِ تصادفی بگذارید، نه `1234`، و پیش از باز شدنِ سرویس روی کاربرانِ واقعی
|
||
خالی‌اش کنید.
|
||
|
||
### حسابِ مهمانِ تستِ فرانت
|
||
|
||
مسیرِ مهمان (`POST /api/auth/session` با یک `deviceId`) اصلاً به پیامک کار
|
||
ندارد و همیشه کار می‌کند — هر رشته‌ای به‌عنوانِ `deviceId` یک حسابِ تازه
|
||
می‌سازد.
|
||
|
||
یک `deviceId` مشخص روی پروداکشن از قبل داده دارد:
|
||
|
||
```bash
|
||
curl -X POST https://api.math.tadrisino2.ir/api/auth/session \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"type":"guest","deviceId":"frontend-test-device"}'
|
||
```
|
||
|
||
کاربرِ شماره‌ی ۶، «حساب تست فرانت». رویش ۲۴ ردیفِ `Notification` و ۲۰ ردیفِ
|
||
`LeaderboardEntry` (هفتگی و کل، با ترتیبِ عمداً متفاوت) نشسته تا تیمِ فرانت
|
||
بتواند آن صفحه‌ها را قبل از وجودِ ترافیکِ واقعی ببیند.
|
||
|
||
⚠️ **این داده دستی روی دیتابیسِ پروداکشن نوشته شده و در گیت نیست.** پیش از باز
|
||
شدنِ سرویس روی کاربرانِ واقعی باید برود، وگرنه اعلان‌ها و لیدربردِ ساختگی را
|
||
کاربرِ واقعی می‌بیند. `purge_demo_data` این‌ها را **نمی‌گیرد** — آن فرمان فقط
|
||
دنبالِ پیشوندِ `[SEED]`/`[DEMO]` روی Grade/Plan/Character/User می‌گردد. پاک
|
||
کردن یعنی حذفِ دستیِ ردیف‌های `Notification` و `LeaderboardEntry` از پنلِ
|
||
ادمین (اول بکاپ، بخشِ بالا).
|
||
|
||
## سرور
|
||
|
||
`api.math.tadrisino2.ir` روی یک **ماشینِ مشترکِ شرکت** اجرا می‌شود
|
||
(`administrator@78.38.35.249`)، نه سروری که مالِ این پروژه باشد. روی همان ماشین
|
||
Gitea، سرویسِ ایمیل، DNS، چند دیتابیس و اپ‌های تیم‌های دیگر در حالِ کارند.
|
||
|
||
مالِ ما **دقیقاً یک دایرکتوری** است: `/home/administrator/mathapp-v2`، که با
|
||
`gunicorn-mathapp.service` سرو می‌شود. همان یونیت با نامِ `zareian-mathapp` هم
|
||
پاسخ می‌دهد و **همیشه همین نام را بنویسید**:
|
||
|
||
```bash
|
||
sudo systemctl restart zareian-mathapp # مالِ ما
|
||
sudo systemctl restart gunicorn # مالِ ما نیست — اپِ تیمِ دیگر
|
||
```
|
||
|
||
قواعدی که قابلِ مذاکره نیستند:
|
||
|
||
1. **هیچ فرمانِ مخربی بیرون از `~/mathapp-v2` اجرا نشود.** مسیر را کامل
|
||
بنویسید، به دایرکتوریِ جاری تکیه نکنید.
|
||
2. **`git clean` آنجا هرگز اجرا نشود.** `db.sqlite3`، `.env` و
|
||
`.django_secret_key` هیچ‌کدام در گیت نیستند و همان‌جا زندگی می‌کنند؛
|
||
`reset --hard` کاری با آن‌ها ندارد ولی `clean -fd` دیتابیس، پیکربندی و
|
||
همه‌ی نشست‌های فعال را نابود می‌کند.
|
||
3. **پروژه هرگز پاک و «از نو clone» نشود** — به همان دلیل. برای برگرداندنِ
|
||
درخت به حالتِ سالم از `git reset --hard origin/main` استفاده کنید.
|
||
4. **`.env` فقط از راهِ Django خوانده شود.** `cat .env` نه، و مقادیرش در هیچ
|
||
چتی paste نشود.
|
||
5. **`df -h /` را قبل از هر کارِ پرنوشت چک کنید.** دیسک مدتی‌ست حدودِ ۹۴٪ پر
|
||
است؛ پر شدنش سرویسِ ایمیل و Gitea را هم با ما پایین می‌کشد.
|
||
|
||
## لاگ‌ها
|
||
|
||
هر درخواستِ `/api/` به‌صورتِ یک شیءِ JSON در هر خط لاگ می‌شود
|
||
(`method`/`path`/`status`/`duration`/`user` — بدونِ بدنه، هدر یا سکرت) توسطِ
|
||
`config.middleware.APIRequestLoggingMiddleware`. خروجی روی stdout است و اگر
|
||
`LOG_DIR` ست باشد در `app.log` هم نوشته می‌شود.
|
||
|
||
هر خطای پیش‌بینی‌نشده همیشه پاسخِ JSON برمی‌گرداند — نه صفحه‌ی HTML پیش‌فرضِ
|
||
جنگو — و کامل با traceback لاگ می‌شود (`config/exceptions.py`).
|