متغیرهای محیطی و رازها چیست؟ راهنمای ساده
یک متغیر محیطی یک تنظیم نام‌دار است — مثل DATABASE_URL یا STRIPE_SECRET_KEY — که هنگام اجرای برنامه به آن داده می‌شود، به‌جای اینکه در کد نوشته شود. یک راز متغیر محیطی‌ای است که مقدارش باید خصوصی بماند: یک کلید API، یک رمز عبور، یک کلید امضا. نگه داشتن این مقادیر بیرون از کد یعنی می‌توانید بدون ویرایش برنامه آن‌ها را عوض کنید، برای آزمایش و برای مشتریان واقعی مقادیر متفاوتی داشته باشید، و وقتی کدتان را به اشتراک می‌گذارید یا منتشر می‌کنید، جلوی لو رفتنشان را بگیرید.
چرا وقتی با هوش مصنوعی می‌سازید اهمیت دارد
لحظه‌ای که برنامه‌تان کار مفیدی با سرویس دیگری انجام می‌دهد — پرداخت می‌گیرد، ایمیل می‌فرستد، یک مدل هوش مصنوعی را صدا می‌زند — به کلید نیاز دارد. سازنده‌های برنامه با هوش مصنوعی مرتب برای گرفتن این کلیدها درخواست می‌کنند و محلی که کلید در نهایت در آن قرار می‌گیرد تعیین می‌کند برنامه امن است یا نه.
دو اشتباه رایج در برنامه‌های ساخته‌شده با هوش مصنوعی وجود دارد:
- کلید در چت یا کد چسبانده می‌شود. در این حالت در تاریخچه چت، فایل‌های پروژه و هر خروجی یا مخزن کد باقی می‌ماند. هر کسی که آن‌ها را ببیند می‌تواند از حساب شما استفاده کند.
- کلید در مرورگر استفاده می‌شود. اگر کدی که Stripe یا OpenAI را صدا می‌زند در صفحه اجرا شود، کلید برای هر بازدیدکننده فرستاده می‌شود. مردم واقعاً نگاه می‌کنند — و اسکنرهای خودکار دائماً دنبال کلیدهای لو رفته می‌گردند.
فهمیدن متغیرهای محیطی به شما کمک می‌کند هر دو را تشخیص دهید و درباره رفعشان درخواست درست بدهید.
یک تشبیه روزمره: گاوصندوق هتل
کد برنامه شما مثل اتاق هتل است. مهمانان (و نظافتچی‌ها، و هر کسی که کارت ورود به اتاق را به او داده‌اید) از آن رد می‌شوند. پاسپورتتان را روی میز نمی‌گذارید.
متغیرهای محیطی گاوصندوق داخل اتاق‌اند. اتاق می‌داند گاوصندوقی هست و چطور وقتی لازم است بازش کند، اما پاسپورت روی میز نیست. و اگر به اتاق دیگری بروید — مثلاً از تنظیمات آزمایشی به سایت زنده — پاسپورت دیگری در گاوصندوق همان اتاق می‌گذارید، بدون اینکه دکوراسیون را عوض کنید.
طرز کار
کد شما به یک نام اشاره می‌کند، نه به یک مقدار. در جاوااسکریپت روی سرور این شکل است: process.env.STRIPE_SECRET_KEY. وقتی برنامه شروع می‌شود، پلتفرمی که روی آن اجرا می‌شود مقدار آن نام را پر می‌کند. مقدار را در تنظیمات پلتفرم تغییر دهید، برنامه را دوباره راه‌اندازی یا منتشر کنید، و برنامه از مقدار جدید استفاده می‌کند — بدون تغییر کد.
مقادیر بسته به محل اجرای برنامه از جای متفاوتی می‌آیند:
| جایی که اجرا می‌شود | جایی که مقادیر نگه داشته می‌شوند |
|---|---|
| روی لپ‌تاپ توسعه‌دهنده | یک فایل محلی که معمولاً .env نام دارد و هرگز نباید در git ثبت شود |
| در پیش‌نمایش یک سازنده برنامه با هوش مصنوعی | پنل رازها یا تنظیمات پروژه |
| روی یک پلتفرم میزبانی | بخش متغیرهای محیطی همان پلتفرم |
| در GitHub Actions یا سایر خودکارسازی‌ها | فضای رازهای رمزگذاری‌شده خود آن سرویس |
متغیرهای عمومی در برابر رازها
همه متغیرهای محیطی راز نیستند. کمک می‌کند آن‌ها را در دو گروه بگذارید:
| نوع | نمونه‌ها | آیا مرورگر می‌تواند آن را ببیند؟ |
|---|---|---|
| پیکربندی عمومی | نام سایت، شناسه تحلیل عمومی، کلید قابل انتشار Stripe، کلیدهای فعال‌سازی قابلیت‌ها | بله، اشکالی ندارد |
| رازها | کلید محرمانه Stripe، کلید API مربوط به OpenAI یا Anthropic، رشته اتصال پایگاه داده، کلید ارائه‌دهنده ایمیل، راز امضای وب‌هوک | هرگز |
چارچوب‌های وب این تفکیک را آشکار می‌کنند. در Vite فقط متغیرهایی که نامشان با VITE_ شروع می‌شود در کد مرورگر قرار می‌گیرند؛ در Next.js پیشوند NEXT_PUBLIC_ است. این یک قابلیت امنیتی است: هر چیزی که این پیشوندها را داشته باشد در فایل‌هایی قرار می‌گیرد که هر بازدیدکننده دانلود می‌کند، پس یک راز هرگز نباید چنین پیشوندی بگیرد.
یک مثال کامل: دکمه خلاصه‌سازی با هوش مصنوعی
می‌خواهید دکمه‌ای با عنوان «این یادداشت را خلاصه کن» داشته باشید که یک مدل هوش مصنوعی را صدا می‌زند.
نسخه ناامن: کد دکمه، که در مرورگر اجرا می‌شود، مستقیماً به ارائه‌دهنده هوش مصنوعی وصل می‌شود و کلید API در آن نوشته شده است. در پیش‌نمایش کار می‌کند. اما یعنی هر کسی می‌تواند ابزارهای توسعه‌دهنده مرورگر را باز کند، کلید را کپی کند و هزینه‌ای را روی حساب شما بالا ببرد.
نسخه امن:
- کلید را نزد ارائه‌دهنده هوش مصنوعی می‌سازید و آن را به‌عنوان راز با نامی مثل
OPENAI_API_KEY(یا مشابه) در تنظیمات پروژه ذخیره می‌کنید. - بک‌اند یک مسیر
POST /api/summariseدارد کهprocess.env.OPENAI_API_KEYرا می‌خواند، بررسی می‌کند کاربر وارد شده باشد و سپس ارائه‌دهنده را صدا می‌زند. - دکمه به مسیر خودتان درخواست می‌دهد، نه به ارائه‌دهنده. مرورگر هرگز کلید را نمی‌بیند.
- همان راز را به تنظیمات برنامه منتشرشده هم اضافه می‌کنید و دوباره منتشر می‌کنید تا سایت زنده هم آن را داشته باشد.
این الگو — مرورگر از سرور شما درخواست می‌کند، سرور کلید را نگه می‌دارد و سرویس را صدا می‌زند — برای پرداخت، ایمیل، نقشه و هر API پولی دیگری کاربرد دارد. راهنمای استفاده از LLM APIها حالت هوش مصنوعی را عمیق‌تر پوشش می‌دهد.
اصطلاحات کلیدی
- فایل
.env: یک فایل متنی با سطرهایNAME=valueکه در توسعه محلی استفاده می‌شود. آن را در.gitignoreقرار دهید تا در git ثبت نشود. .env.example: نسخه‌ای با نام متغیرها اما بدون مقدار واقعی که ثبت می‌شود تا دیگران بدانند چه متغیرهایی را باید تنظیم کنند.- چرخاندن (Rotate): جایگزین کردن یک راز با راز جدید و باطل کردن راز قدیمی.
- محدوده / دسترسی‌ها: بسیاری از ارائه‌دهندگان به شما اجازه می‌دهند کلیدهایی بسازید که فقط بتوانند کارهای مشخصی انجام دهند. کلیدی که فقط می‌تواند ایمیل بفرستد کم‌خطرتر از کلیدی است که همه کار می‌تواند بکند.
- کلیدهای آزمایشی در برابر واقعی: ارائه‌دهندگانی مثل Stripe کلیدهای جدا برای آزمایش و برای پول واقعی می‌دهند. تا زمان راه‌اندازی از کلیدهای آزمایشی استفاده کنید.
- راز امضا: رازی که برای بررسی اینکه یک پیام، مثلاً یک وب‌هوک، واقعاً از فرستنده درست آمده استفاده می‌شود.
اشتباهات رایج و باورهای غلط
- «مخزن من خصوصی است، پس گذاشتن کلید داخلش اشکالی ندارد.» مخازن خصوصی هم به اشتراک گذاشته، فورک، خروجی گرفته و روی لپ‌تاپ‌ها کلون می‌شوند. کلیدها هنوز جای آنجا نیستند. اگر پروژه‌ای را به GitHub وصل می‌کنید، بررسی کنید فایل
.envدر آن نباشد. - «حذفش کردم، پس از بین رفته.» git تاریخچه را نگه می‌دارد و تاریخچه چت هم پیام‌ها را. اگر کلیدی یک بار لو رفته، آن را بچرخانید.
- استفاده از پیشوند عمومی برای یک راز.
VITE_OPENAI_KEYکلید شما را در بسته مرورگر قرار می‌دهد. - فراموش کردن انتشار مجدد. تغییر یک متغیر در تنظیمات معمولاً فقط بعد از راه‌اندازی مجدد یا انتشار دوباره برنامه اعمال می‌شود.
- یک کلید برای همه چیز. کلیدهای جدا برای آزمایش و واقعی، و برای هر برنامه، باعث می‌شود بتوانید یکی را باطل کنید بدون آنکه بقیه از کار بیفتند.
- نداشتن سقف هزینه. برای APIهای پولی، یک بودجه یا محدودیت در داشبورد ارائه‌دهنده تنظیم کنید، برای حالتی که کلید لو برود.
از سازنده هوش مصنوعی‌تان چه بخواهید
- «کلید محرمانه Stripe را از متغیر محیطی‌ای به نام
STRIPE_SECRET_KEYبخوان. فقط روی سرور از آن استفاده کن.» - «مطمئن شو هیچ رازی در کد سمت کلاینت استفاده نمی‌شود و پیشوند
VITE_یاNEXT_PUBLIC_نمی‌گیرد.» - «یک
.env.exampleبساز که همه متغیرهای لازم برنامه را بدون مقدار فهرست کند، و مطمئن شو.envدر git نادیده گرفته می‌شود.» - «فایل‌های فرانت‌اند ساخته‌شده را برای هر رشته‌ای که شبیه کلید API است بررسی کن.»
چک‌لیست امنیتی ما برای برنامه‌های ساخته‌شده با هوش مصنوعی رازها را کنار سایر بررسی‌های لازم قبل از راه‌اندازی پوشش می‌دهد.
رازها در Mythex
در Mythex، رازها متغیرهای محیطی پروژه‌اند که هم در محیط پیش‌نمایش و هم در برنامه منتشرشده تزریق می‌شوند. آن‌ها را زیر تنظیمات پروژه ← Secrets یا با دستور /secrets در چت اضافه می‌کنید. وقتی عامل به کلیدی نیاز داشته باشد، یک کارت رازها در چت نشان می‌دهد، پس مقدار در یک فیلد فرم وارد می‌شود و در متن گفتگو باقی نمی‌ماند. اگر رازی را برای یک برنامه زنده تغییر دهید، دوباره منتشر کنید تا استقرار آن را بردارد. خروجی گرفتن از پروژه رازها را حذف می‌کند و فایل‌های .env وارد شده پاک می‌شوند تا دوباره در تنظیمات اضافه‌شان کنید. مستندات را در متغیرهای محیطی و رازها و رازها در چت ببینید.
پرسش‌ها
متغیر محیطی چیست؟
متغیر محیطی یک تنظیم نام‌دار است، مثل STRIPE_SECRET_KEY یا DATABASE_URL، که هنگام اجرای برنامه به آن داده می‌شود و در خود کد نوشته نمی‌شود. به این ترتیب همان کد می‌تواند در محیط توسعه و در محیط واقعی از مقادیر متفاوتی استفاده کند.
تفاوت متغیر محیطی با راز چیست؟
راز متغیر محیطی‌ای است که مقدارش باید خصوصی بماند، مثل کلید API، رمز پایگاه داده یا کلید امضای وب‌هوک. سایر متغیرهای محیطی، مثل نام سایت یا کلید فعال‌سازی یک قابلیت، می‌توانند عمومی باشند.
گذاشتن کلید API در فرانت‌اند امن است؟
خیر. هر چیزی که در کد فرانت‌اند باشد برای مرورگر هر بازدیدکننده دانلود می‌شود و قابل خواندن است. کلیدهای محرمانه فقط باید روی سرور استفاده شوند. مرورگر باید از سرور شما درخواست بدهد و سرور شما هم با ارائه‌دهنده تماس بگیرد.
اگر کلید API من لو برود چه کنم؟
فوراً آن را در سمت ارائه‌دهنده باطل یا تعویض کنید، یک کلید جدید بسازید، آن را در جایی که برنامه رازهایش را نگه می‌دارد به‌روز کنید و دوباره منتشر کنید. حذف کلید از کد یا از تاریخچه چت کافی نیست، چون ممکن است رونوشت‌هایی از آن وجود داشته باشد.