103 lines
11 KiB
Markdown
103 lines
11 KiB
Markdown
# مشخصات درس‌نامه: پیکربندی متغیرهای محیطی پروداکشن در پنل‌های ابری (Environment Variables)
|
||
- **شناسه در سیلابس:** `L12.6`
|
||
- **فصل:** فصل ۱۲: انتشار روی اینترنت (Ch 12)
|
||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||
- **زمان تقریبی مطالعه:** ۱۶ دقیقه
|
||
- **پیش‌نیازهای مستقیم:** `L12.5` (استقرار عملی پروژه پورتفولیو در لیارا و ورسل)
|
||
|
||
---
|
||
|
||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||
- [ ] **درک کند (Understand):** چرا ۹۵٪ خطاهای ناگهانی صفحه سفید یا کرش سرور پس از استقرار اولیه (خطای ۵۰۰)، ناشی از غیبت متغیرهای محیطی در سرور ابری است و چرا فایل `.env.local` هرگز به همراه کدها به سرور فرستاده نمی‌شود.
|
||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** تفاوت‌های حیاتی میان مقادیر متغیرها در محیط لوکال و محیط واقعی (به‌ویژه متغیر `NEXT_PUBLIC_APP_URL` برای آدرس‌های بازگشت زرین‌پال و اوت‌اوت گوگل) را ارزیابی کند.
|
||
- [ ] **به‌کار ببندد (Apply):** تمام متغیرهای محیطی پروژه پورتفولیو (کلیدهای سوپابیس، کاوه‌نگار، لیارا SMTP، زرین‌پال، Upstash و OpenRouter) را در بخش تنظیمات متغیرهای کنسول لیارا و Vercel تزریق نماید.
|
||
- [ ] **ایجاد کند (Create):** چرخه بازاستقرار (Trigger Redeploy) را پس از ذخیره متغیرها اجرا کرده و پایداری کامل برنامه در محیط پروداکشن را راستی‌آزمایی کند.
|
||
|
||
---
|
||
|
||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||
|
||
### آنچه باید پوشش داده شود (In-Scope):
|
||
1. **معمای سرور گیج: «من کلیدها را از کجا بخوانم؟»:**
|
||
* شما به درستی `.env.local` را در `.gitignore` گذاشتید تا فاش نشود؛ در نتیجه سرور ابری پروژه‌ای خالی از کلید دریافت کرده است!
|
||
2. **کالبدشکافی تزریق متغیرها در داشبورد لیارا:**
|
||
* ورود به برنامه پورتفولیو در پنل Liara.ir $\rightarrow$ بخش «تنظیمات» $\rightarrow$ تب «متغیرها».
|
||
* امکان افزودن تکی یا پیست کردن دسته‌ای (Bulk Paste) تمام خطوط `.env`.
|
||
* راه‌اندازی مجدد (Restart) برنامه برای خوانده شدن متغیرهای جدید توسط کانتینر.
|
||
3. **کالبدشکافی تزریق متغیرها در داشبورد Vercel:**
|
||
* ورود به پروژه در Vercel $\rightarrow$ تب Settings $\rightarrow$ انتخاب Environment Variables.
|
||
* تفکیک محیط‌ها: Production، Preview و Development.
|
||
* لزوم زدن دکمه Redeploy برای اعمال متغیرها در مرحله بیلد.
|
||
4. **تغییرات کلیدی متغیرها از لوکال به پروداکشن:**
|
||
* متغیر شماره یک: `NEXT_PUBLIC_APP_URL`
|
||
- در لوکال: `http://localhost:3000`
|
||
- در پروداکشن: `https://my-portfolio.liara.run` یا دامنه شخصی شما.
|
||
- چرا این متغیر حیاتی است؟ زرین‌پال کاربر را بعد از پرداخت به این آدرس برمی‌گرداند؛ تگ‌های Open Graph عکس‌های شبکه‌های اجتماعی را از این آدرس می‌خوانند!
|
||
5. **بررسی چک‌لیست کامل متغیرهای پروژه پورتفولیو:**
|
||
* جدول جامع تمام متغیرها: `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY`, `KAVENEGAR_API_KEY`, `SMTP_HOST`, `ZARINPAL_MERCHANT_ID`, `UPSTASH_REDIS_REST_URL`, `OPENROUTER_API_KEY`, `ADMIN_EMAIL`.
|
||
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||
* کال‌اوت بنفش (`<details class="violet">`): مفهوم تزریق در زمان بیلد (Build-time Inlining) برای متغیرهای با پیشوند `NEXT_PUBLIC_` و چرایی نیاز به بیلد مجدد پس از تغییر آن‌ها.
|
||
* کال‌اوت سبز (`<details class="green">`): قابلیت کپی-پیست یکجای کل محتوای فایل `.env` در پنل متغیرهای لیارا در ۲ ثانیه.
|
||
* کال‌اوت قرمز (`<details class="red">`): تله راه‌اندازی مجدد نکردن؛ تغییر متغیرها بدون ری‌استارت برنامه در پنل ابری هیچ اثری نخواهد داشت.
|
||
|
||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||
- استفاده از سرویس‌های مدیریت متغیرهای توزیع‌شده بین‌سازمانی (Doppler یا Infisical).
|
||
- رمزنگاری کلیدها با کلیدهای نامتقارن PGP در خط فرمان.
|
||
|
||
---
|
||
|
||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||
|
||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||
| :--- | :--- | :--- |
|
||
| Production Environment Variable | متغیر محیطی پروداکشن | تنظیمات پیکربندی و کلیدهای حساسی که مستقیماً در پنل هاست ابری برای سرور واقعی تعریف می‌شوند |
|
||
| Build-time Inlining | جایگذاری در زمان بیلد | فرآیندی که در آن کامپایلر Next.js مقادیر عمومی (NEXT_PUBLIC_) را در هنگام بیلد داخل کدهای فرانت‌اند حک می‌کند |
|
||
| Bulk Import | بارگذاری یکپارچه دسته‌ای | امکان کپی کردن همزمان تمام خطوط فایل تنظیمات در پنل ابری بدون نیاز به ثبت دانه به دانه |
|
||
| App Restart / Redeploy | راه‌اندازی مجدد / استقرار دوباره | متوقف کردن و اجرای مجدد کانتینر سرور به منظور بارگذاری مقادیر جدید متغیرهای محیطی در حافظه |
|
||
| Root URL Dynamic Mapping | نگاشت پویای آدرس ریشه | تنظیم هوشمند آدرس اصلی سایت به گونه‌ای که لینک‌های بازگشتی با دامنه واقعی محیط همگام باشند |
|
||
|
||
---
|
||
|
||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||
|
||
1. **تصویر کاور درس:** `images/cover.png`
|
||
* **موضوع:** نمایش پنل تنظیمات دیجیتال مدرن با فیلدهای کلیدهای رمزی و دکمه‌های سوئیچ سبز در داشبورد سرور ابری.
|
||
2. **مسیر تزریق متغیرها در کنسول لیارا:** `images/liara-environment-variables-panel.png`
|
||
* **موضوع:** اسکرین‌شات از تب متغیرها در پنل لیارا با دکمه بارگذاری دسته‌ای و لیست کلیدهای سوپابیس و کاوه‌نگار.
|
||
3. **تنظیم متغیرها در داشبورد Vercel با انتخاب محیط:** `images/vercel-environment-variables-setup.png`
|
||
* **موضوع:** اسکرین‌شات از بخش Settings ورسل با تیک‌باکس‌های Production و Preview برای هر متغیر.
|
||
4. **اثر حیاتی متغیر `NEXT_PUBLIC_APP_URL` بر درگاه پرداخت و سئو:** `images/app-url-importance-flow.png`
|
||
* **موضوع:** اینفوگرافیک مقایسه‌ای: مقدار اشتباه (هدایت کاربر بانک به صفحه خراب localhost:3000) در برابر مقدار صحیح (هدایت کاربر به دامنه زنده پورتفولیو).
|
||
|
||
---
|
||
|
||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||
|
||
1. **تیتر اصلی:** `# پیکربندی متغیرهای محیطی پروداکشن در پنل‌های ابری (Environment Variables)`
|
||
2. **مقدمه:** سایت بالا آمد اما به محض کلیک روی دکمه‌ها ارور ۵۰۰ می‌دهد؟ نفس عمیق بکشید؛ این طبیعی‌ترین اتفاق بعد از اولین دیپلوی است!
|
||
3. **جدول کاور درس**
|
||
4. **چرا فایل `.env.local` شما در سرور ابری وجود ندارد؟**
|
||
* یادآوری امنیت گیت؛ ما عمداً کلیدها را به گیت‌هاب نفرستادیم تا هک نشویم، اکنون باید آن‌ها را دستی به سرور برسانیم.
|
||
5. **آموزش تصویری تزریق متغیرها در پنل لیارا (Liara):**
|
||
* رفتن به تنظیمات $\rightarrow$ بخش متغیرها $\rightarrow$ کپی کردن محتوای تمیز `.env` $\rightarrow$ ذخیره و راه‌اندازی مجدد.
|
||
6. **آموزش تزریق متغیرها در پنل Vercel:**
|
||
* انتخاب Environment Variables $\rightarrow$ تنظیم اسکوپ Production $\rightarrow$ زدن دکمه Redeploy.
|
||
7. **شاه‌کلید تمام آدرس‌های بازگشتی: تنظیم `NEXT_PUBLIC_APP_URL`:**
|
||
* چرا این متغیر را باید با آدرس واقعی سایت (دامنه لیارا، ورسل یا دامنه اختصاصی) پر کنید.
|
||
8. **جدول چک‌لیست نهایی تمام متغیرهای پروژه پورتفولیو:**
|
||
* مروری بر ۸ متغیر ضروری: Supabase, Kavenegar, Liara SMTP, ZarinPal, Upstash, OpenRouter, Admin Email.
|
||
9. **باکس نکته Quera (`<details class="violet">`):** چرا تغییر متغیرهای عمومی کلاینتی حتماً نیازمند بیلد دوباره (Redeploy) است در حالی که متغیرهای سروری با یک Restart ساده اعمال می‌شوند.
|
||
10. **باکس هشدار Quera (`<details class="red">`):** هرگز فاصله‌های اضافی (Space) قبل یا بعد از کلیدها در کادر پنل نگذارید؛ این خطای پنهان ساعت‌ها وقت شما را می‌گیرد!
|
||
11. **باکس رضایت‌بخش Quera (`<details class="green">`):** رفرش کردن سایت زنده پس از تنظیم متغیرها و مشاهده لود شدن آنی پروژه‌ها از دیتابیس Supabase و سلامت کامل سیستم.
|
||
12. **جمع‌بندی درس‌نامه:** تثبیت کامل مغز متغیرهای ابری؛ ورود به گام باشکوه پایانی فصل: ثبت و اتصال دامنه اختصاصی، DNS و CDN در درس بعدی.
|
||
|
||
---
|
||
|
||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||
- [ ] علت بروز خطاهای پس از دیپلوی ناشی از نبود متغیرهای محیطی به زبان ساده تبیین شود.
|
||
- [ ] شیوه تزریق متغیرها در هر دو پنل لیارا و ورسل به صورت گام‌به‌گام تشریح گردد.
|
||
- [ ] اهمیت تغییر متغیر `NEXT_PUBLIC_APP_URL` از لوکال به دامنه واقعی پروداکشن تحلیل شود.
|
||
- [ ] جدول چک‌لیست تمام کلیدهای مورد نیاز پروژه پورتفولیو در متن ارائه گردد.
|