پیکربندی، محیطها و رازها
پیکربندی را از کد جدا کن، برنامه را با پیکربندی ناقص اصلاً اجرا نکن، راز را جایی نگه دار که در لاگ و image نماند و برای هر راز راه تعویض داشته باش.
بعد از این درس میتوانی
- پیکربندی را از کد جدا کند و با «آزمون انتشار کد» بسنجد که هیچ مقدار وابسته به محیط یا رازی در کد نمانده است.
- بارگذار پیکربندی بنویسد که هنگام شروع همه مقدارها را بسنجد و با پیکربندی نامعتبر اجرا نشود، بیآنکه راز را چاپ کند.
- بین متغیر محیطی، فایل راز و مدیر راز بر اساس خطر نشت انتخاب کند.
- برای هر راز مالک، دسترسی کمینه و دستورالعمل تعویض بنویسد و نشت را در مخزن پیدا کند.
چرا این درس مهم است
دستیار ایمیل برگ سبز سه نسخه داشت: روی لپتاپ، روی سرور آزمایشی و روی سرور اصلی. نشانی صندوق آزمایشی در کد نوشته شده بود و یک روز نسخه اصلی، پاسخها را به صندوق آزمایشی فرستاد. بار دیگر کلید مدل در متغیر محیطی بود و یک خطای برنامه کل محیط را در لاگ چاپ کرد؛ لاگ هم برای شرکت پشتیبانی فرستاده شد. و وقتی همکاری که کلیدها را ساخته بود رفت، هیچکس نمیدانست کدام کلید کجا استفاده میشود و چطور عوضش کنند.
پیکربندی و راز، جایی است که بیشتر سامانههای کوچک بیصدا خراب یا نشت میکنند. این درس سه عادت میسازد: پیکربندی جدا از کد و سنجیده در شروع، راز در جایی که کمترین دیدهشدن را دارد، و برای هر راز یک برنامه تعویض.
مفاهیم کلیدی
یادآوری: .env.example و .gitignore را در درس Git و جایگزینی متغیر در Compose را در درس Docker دیدی.
- Configuration (پیکربندی): هر مقداری که بین محیطها فرق میکند: نشانیها، سقفها، کلیدها؛ نه منطق برنامه.
- Environment (محیط اجرا): یک نصب مشخص از برنامه، مثل توسعه، آزمون یا تولید، با مقدارهای خودش.
- Fail-fast Validation (سنجش در شروع): بررسی همه پیکربندی هنگام راهاندازی و اجرا نشدن با پیکربندی نامعتبر.
- Secret Manager (مدیر راز): سرویسی که راز را رمزنگاریشده نگه میدارد، دسترسی را محدود و ثبت میکند و تعویض را ساده میکند.
- Secret Rotation (تعویض راز): جایگزینی راز با مقدار تازه و باطلکردن مقدار قبلی، چه دورهای چه پس از نشت.
- Least Privilege (دسترسی کمینه): هر کلید فقط همان دسترسیای را دارد که کارش لازم دارد.
مدل ذهنی
برنامه را مثل یک دستگاه قهوهساز در چند شعبه ببین. خود دستگاه (کد) در همه شعبهها یکی است. تنظیمات هر شعبه (فشار آب، اندازه فنجان) روی برچسبی کنار دستگاه است (پیکربندی). کلید صندوق پول (راز) نه روی دستگاه چسبیده و نه روی برچسب؛ در جیب مسئول شعبه است و اگر گم شد، قفل عوض میشود. دستگاه خوب اگر برچسب تنظیماتش ناقص باشد، روشن نمیشود، نه اینکه قهوه بد بدهد.
جریان پیکربندی و راز تا برنامه
این تشبیه کجا غلط است؟ کلید صندوق را میبینی که در جیب است؛ ولی راز دیجیتال بیصدا کپی میشود: در لاگ، در خروجی docker inspect، در اسکرینشات، در تاریخچه Git. پس «کجا نگه دارم» فقط نیمی از کار است؛ نیم دیگر این است که بدانی راز از کجاها ممکن است کپی شود و برای روزی که کپی شد، دستورالعمل تعویض داشته باشی.
گامبهگام
گام ۱: پیکربندی را از کد جدا کن
روش دوازدهعاملی پیکربندی را هر چیزی میداند که بین استقرارها فرق میکند، از جمله نشانی پایگاه داده و کلید سرویسهای بیرونی، و میخواهد کاملاً از کد جدا باشد. آزمون سریعش: آیا میتوانی همین حالا کد را عمومی کنی بیآنکه کلیدی لو برودsrc-12factor-config؟ همان منبع ذخیره در متغیر محیطی را پیشنهاد میکند و میگوید هر متغیر را برای هر استقرار مستقل مدیریت کن، نه در گروههای نامدار «توسعه» و «تولید» که با زیادشدن استقرارها از کنترل خارج میشوندsrc-12factor-config.
در عمل: در کد فقط نام متغیر (MAIL_API_BASE)، در .env.example نام با مقدار ساختگی، و مقدار واقعی بیرون از Git.
گام ۲: در شروع بسنج، نه وسط کار
برنامهای که با پیکربندی ناقص روشن میشود و ساعتها بعد وسط کار میشکند، بدترین حالت است. assets/settings.py همه مقدارها را هنگام شروع میسنجد: الزامیها، نشانیها، بازه عددها، و یک قاعده محیطی (در تولید فقط https). اگر حتی یک ایراد باشد، با فهرست کامل ایرادها اجرا نمیشود و کد خروج غیرصفر میدهد. راز با کلاس Secret در چاپ و لاگ فقط «تنظیم شده، N نویسه» نشان داده میشود. خروجی واقعی هر سه حالت در assets/secrets-session.txt است.
گام ۳: راز را کجا نگه داریم؟
OWASP رازها را مستلزم مدیریت متمرکز، دسترسی کمینه، چرخه عمر (ساخت، تعویض، باطلکردن) و ثبت دسترسی میداندsrc-owasp-secrets-cheatsheet. سه گزینه رایج در سامانههای کوچک:
| روش | خطر نشت | کی |
|---|---|---|
| متغیر محیطی | برای همه فرایندها دیدنی؛ ممکن است در لاگ اشکالزدایی بیایدsrc-docker-compose-secrets؛ در docker inspect دیده میشود | مقدار غیرحساس، یا راز در محیط توسعه |
فایل راز (/run/secrets/... و قرارداد _FILE) | فقط سرویسی که اجازه دارد فایل را میبیند | راز در Docker و Compose |
| مدیر راز | رمزنگاری، ثبت دسترسی و تعویض متمرکز | تیم، چند سرور، الزام حسابرسی |
مستندات Docker صریح است: برای اطلاعات حساس مثل رمز از متغیر محیطی استفاده نکن و از secrets استفاده کنsrc-docker-compose-env. Compose هر secret را در /run/secrets/<نام> سوار میکند و برخی imageهای رسمی مثل postgres با متغیر _FILE مقدار را از فایل میخوانندsrc-docker-compose-secrets. API آزمایشی برگ سبز حالا همین را دارد: MOCK_API_TOKEN_FILE. در اجرای واقعی درس، با compose-secrets.yaml خروجی docker inspect فقط نشانی فایل را نشان داد، ولی با نسخه متغیر محیطی، خود توکن دیده شد.
گام ۴: رازهایی که فراموش میشوند
بعضی رازها «کلید سرویس» نیستند ولی همانقدر حساساند:
- کلید رمزنگاری n8n: n8n در اولین اجرا یک کلید تصادفی در پوشه
~/.n8nمیسازد و Credentialها را با آن رمزنگاری میکند؛ باN8N_ENCRYPTION_KEYمیتوانی کلید خودت را بدهیsrc-n8n-encryption-key. اگر پایگاه داده را پشتیبان بگیری ولی این کلید را نه، Credentialهای پشتیبان بیاستفادهاند؛ اگر هر دو را کنار هم در یک جای عمومی بگذاری، همه Credentialها لو رفتهاند. - کلید امضای webhook و توکن ربات پیامرسان.
- فایل پشتیبان که خودش راز دارد.
گام ۵: مالک، دسترسی کمینه و تعویض
برای هر راز با قالب assets/rotation-runbook-template.md بنویس: صادرکننده، کجا استفاده میشود، کجا نگه داشته میشود، دسترسی کمینه، مالک و دوره تعویض. وقتی رازی لو رفت، ترتیب همان است که در درس Git دیدی: اول باطل و عوض، بعد بقیهsrc-github-remove-sensitive-data.
برای پیدا کردن نشت، assets/scan_secrets.py پوشه و کل تاریخچه یک مخزن Git را برای چند الگوی رایج میگردد و فقط جای یافته را نشان میدهد، نه مقدار کامل را. روی مخزن تمرینی درس Git، همان توکن ساختگی را در تاریخچه پیدا کرد. این ابزار آموزشی است؛ «چیزی پیدا نشد» یعنی این الگوها پیدا نشد، نه اینکه مخزن پاک است. سرویس میزبانی Git ممکن است اسکن و push protection خودش را داشته باشدsrc-github-push-protection.
مثالها
پیادهسازی عملی
بارگذار پیکربندی، اسکن نشت و راز در Compose. حدود ۲۵ دقیقه.
- یکی از مسیرهای پایین را برو.
- در
settings.pyیک متغیر تازه اضافه کن:APPROVER_ROLEالزامی با مقدارهای مجازsupport_lead|manager. سه حالت را بیازما یا پیشبینی کن. - برای دو راز دستیار ایمیل (
MAIL_API_TOKENوLLM_API_KEY) دستورالعمل تعویض را با قالب بنویس.
اجرای محلی
با Python و Git: python settings.py demo (فایل assets/settings.py) را اجرا کن، سپس با متغیرهای محیطی واقعی اجرایش کن. مخزن تمرینی درس Git را بساز و python scan_secrets.py barg-sabz-automation (فایل assets/scan_secrets.py) را اجرا کن. اگر Docker داری: پوشهای با assets/compose-secrets.yaml، Dockerfile درس قبل، shared/barg-sabz-mock-api.py و email_assistant.py بساز، فایل secrets/mock_api_token.txt را با مقدار آزمایشی بنویس، سرویس را بالا بیاور و خروجی docker inspect را با نسخه متغیر محیطی مقایسه کن. پوشه secrets/ را به .gitignore اضافه کن.
بدون اجرا / شبیهساز
بدون اجرا: assets/secrets-session.txt را بخوان؛ خروجی واقعی همه فرمانهاست. بنویس: (۱) چرا حالت «bad values» دو ایراد با هم گزارش میکند و این چه فایدهای دارد؛ (۲) اسکنر توکن را در پوشه پیدا کرد یا در تاریخچه، و چرا؛ (۳) تفاوت دو خروجی docker inspect چیست.
اشتباههای رایج
| اشتباه | نتیجه | کار درست |
|---|---|---|
مقدار پیشفرض واقعی در کد (or "https://prod...") | نسخه آزمایشی به تولید وصل میشود | فقط نام متغیر در کد؛ نبودنش یعنی اجرا نشدن |
| سنجش پیکربندی وسط کار | شکست ساعتها بعد، شاید پس از اقدام نیمهکاره | سنجش کامل در شروع |
| چاپ کل محیط برای اشکالزدایی | راز در لاگ | چاپ پیکربندی با راز پنهان |
| یک کلید با دسترسی کامل برای همه سرویسها | نشت یکی یعنی نشت همه | کلید جدا با دسترسی کمینه برای هر سرویس |
| پشتیبان پایگاه داده n8n بدون کلید رمزنگاری | Credentialهای پشتیبان بیاستفاده | کلید را جدا و امن پشتیبان بگیر |
| نبود مالک و دستورالعمل تعویض | پس از نشت یا رفتن همکار، سردرگمی | قالب تعویض برای هر راز |
اشکالزدایی
سرویس پس از بهروزرسانی بلافاصله با «configuration error: MAIL_API_TOKEN is required» خارج میشود.
متغیر یا فایل راز در محیط تازه تعریف نشده، یا نامش عوض شده است.
پیام خطا نام دقیق را میگوید؛ در Compose با docker compose config ببین کدام متغیر خالی است، بیآنکه خروجی را جایی منتشر کنی.
مقدار را در محل نگهداری درست بگذار؛ این شکست مطلوب است: بهتر از اجرا با پیکربندی ناقص.
پس از تعویض کلید، یک ورکفلو قدیمی با 401 شکست میخورد.
آن ورکفلو کلید را از جای دیگری میخواند (کپی در یک Credential یا فایل دیگر) که در فهرست «کجا استفاده میشود» نبود.
لاگ خطای مجوز ۲۴ ساعت پس از تعویض؛ جستوجوی نام متغیر در مخزن و Credentialها.
کلید را آنجا هم عوض کن و فهرست دستورالعمل تعویض را کامل کن.
اسکنر «no matches» میگوید ولی کلیدی در مخزن هست.
کلید الگویی دارد که اسکنر نمیشناسد، یا در فایلی است که Git ردگیری نمیکند.
جستوجوی دستی نام متغیر با git log --all -p -G 'نام'.
الگو را به اسکنر اضافه کن؛ و هرگز «نیافتن» را «پاک بودن» نخوان.
نکتههای امنیتی
تمرین کوتاه
تمرین · 10 دقیقه
هدف: جای درست هر مقدار.
گامها: برای هر مقدار بنویس کجا نگه داشته شود و چرا: (۱) نشانی صندوق ایمیل؛ (۲) کلید API مدل؛ (۳) حداکثر ایمیل در هر اجرا؛ (۴) کلید رمزنگاری n8n؛ (۵) قالب پیام پاسخ به مشتری؛ (۶) رمز پایگاه داده PostgreSQL.
معیار پذیرش: ۱ و ۳ پیکربندی غیرحساس؛ ۲، ۴ و ۶ راز در فایل راز یا مدیر راز؛ ۵ در کد یا مخزن (منطق، نه پیکربندی)؛ ۴ همراه پشتیبانگیری جدا.
راهحل نمونه
(۱) پیکربندی غیرحساس: متغیر محیطی یا .env بیرون از Git، با سنجش https در تولید. (۲) راز: فایل secret یا مدیر راز، با دسترسی کمینه و دستورالعمل تعویض. (۳) پیکربندی غیرحساس با بازه مجاز در بارگذار. (۴) راز با اهمیت ویژه: در فایل راز یا مدیر راز، و جدا از پشتیبان پایگاه داده نگهداری شود؛ بدون آن پشتیبان n8n بیاستفاده است. (۵) بخشی از منطق محصول است: در مخزن با بازبینی (اگر بین محیطها فرق ندارد، پیکربندی نیست). (۶) راز: در Compose با POSTGRES_PASSWORD_FILE و secret، یا مدیر راز.
چالش
تمرین · 30 دقیقه
موقعیت: برای یکی از پروژههای خودت (یا دستیار ایمیل اگر پروژهای نداری) سیاهه پیکربندی و راز بساز. اگر مقدارها واقعیاند، در سند فقط نام بنویس و هرجا لازم شد داده ساختگی یا ناشناسشده بگذار.
- جدول همه مقدارها: نام، حساس یا نه، محل نگهداری در هر محیط.
- بارگذار پیکربندی (با
settings.pyیا زبان خودت) که در شروع همه را بسنجد. - اسکن مخزن پروژه با
scan_secrets.pyو هر ابزاری که سرویس Git تو دارد؛ نتیجه را بنویس. - دستورالعمل تعویض برای دو راز مهمتر.
خروجی مورد انتظار: جدول پیکربندی، بارگذار، نتیجه اسکن و دو دستورالعمل تعویض.
معیار پذیرش:
- هیچ مقدار محیطی یا رازی در کد نیست (آزمون انتشار کد).
- برنامه با پیکربندی ناقص اجرا نمیشود و راز را چاپ نمیکند.
- هر راز مالک، دسترسی کمینه و دستورالعمل تعویض دارد.
پرسشهای سنجش
جمعبندی
- پیکربندی = هر چه بین محیطها فرق دارد؛ جدا از کد، و آزمون: کد را میشود عمومی کرد؟
- همه پیکربندی را در شروع بسنج و با ایراد اجرا نشو؛ راز را در چاپ و لاگ پنهان کن.
- متغیر محیطی برای راز ضعیف است؛ فایل راز با قرارداد
_FILEیا مدیر راز بهتر است. - کلید رمزنگاری n8n، کلید webhook و فایل پشتیبان هم رازند.
- هر راز: مالک، دسترسی کمینه، دستورالعمل تعویض؛ نشت: اول باطل و عوض.
- اسکنر «پیدا نشد» یعنی این الگوها پیدا نشد، نه پاک بودن.
پرسشهای سنجش
با «آزمون انتشار کد» این چهار خط را بررسی کن: کدام مشکل دارند و هرکدام کجا باید برود؟
بخشی از کد دستیار ایمیل:
MAIL_BASE = os.environ.get('MAIL_API_BASE', 'https://mail.barg-sabz.example.com')
LLM_KEY = 'sk-live-...'
MAX_PER_RUN = 20
REPLY_FOOTER = 'کتابفروشی برگ سبز'پاسخ نمونه و معیار ارزیابی
LLM_KEY: راز در کد؛ فوراً عوض شود و از فایل راز یا مدیر راز خوانده شود. MAIL_BASE: پیشفرض واقعی تولید در کد؛ اگر متغیر نباشد، نسخه آزمایشی به تولید وصل میشود؛ پیشفرض را حذف کن تا نبودنش اجرا را متوقف کند. MAX_PER_RUN: اگر بین محیطها فرق دارد پیکربندی است (متغیر با بازه مجاز)، وگرنه ثابت کد میتواند بماند. REPLY_FOOTER: منطق محصول است و میتواند در کد یا مخزن بماند.
- کلید در کد و تعویضش (1 امتیاز)
- خطر پیشفرض تولید در کد (1 امتیاز)
- تمایز پیکربندی و منطق برای دو خط آخر (1 امتیاز)
- پیشفرض بیخطر است ← پیشفرض واقعی یعنی اشتباه در پیکربندی بیصدا به تولید وصل میشود.
چه اتفاقی افتاده، چه کاری فوری است و چه چیزی را در طراحی عوض میکنی تا تکرار نشود؟
در گزارش خطایی که برای پشتیبانی یک کتابخانه فرستاده شد:
Traceback ...
KeyError: 'order_id'
Environment: {'APP_ENV': 'prod', 'LLM_API_KEY': 'sk-proj-****', 'MAIL_API_TOKEN': 'b2f9****'}پاسخ نمونه و معیار ارزیابی
کد خطا کل محیط را چاپ کرده و دو راز در گزارشی رفته که دیگران دارند. فوری: هر دو کلید را باطل و عوض کن و مصرف بازه نشت را بررسی کن. طراحی: هرگز محیط را چاپ نکن؛ پیکربندی را با بارگذاری که راز را پنهان نشان میدهد چاپ کن؛ راز را از متغیر محیطی به فایل راز ببر؛ گزارشهای خطا پیش از ارسال بیرونی بازبینی شوند.
- نشت راز از راه لاگ (1 امتیاز)
- تعویض فوری هر دو کلید (1 امتیاز)
- پنهانکردن راز در چاپ و انتقال به فایل راز (1 امتیاز)
- فقط گزارش را پس بگیر ← گزارش رفته است؛ تا کلید عوض نشود، کپیها قابل استفادهاند.
به بارگذار پیکربندی یک متغیر اضافه کن: WEBHOOK_SECRET که الزامی است، حداقل ۳۲ نویسه دارد و میتواند از WEBHOOK_SECRET_FILE هم بیاید. بنویس در SPEC و در سنجش چه تغییری میدهی و در خروجی چاپشده چه دیده میشود.
پاسخ نمونه و معیار ارزیابی
در SPEC: ("WEBHOOK_SECRET", True, "str", True, None) — الزامی و secret؛ خواندن از _FILE را تابع _raw از قبل پشتیبانی میکند. در سنجش: اگر len(v) < 32، ایراد «WEBHOOK_SECRET must be at least 32 chars» به فهرست اضافه شود (بدون چاپ مقدار). در خروجی: <secret set, N chars>.
- الزامی و secret در SPEC (1 امتیاز)
- قاعده طول بدون چاپ مقدار (1 امتیاز)
- پشتیبانی _FILE (1 امتیاز)
- مقدار را در پیام خطا بیاور ← پیام خطا به لاگ میرود؛ فقط نام و قاعده.
در Compose، توکن یک سرویس را با environment دادهای. کدام فرمان آن را برای هر کسی که به Docker میزبان دسترسی دارد نمایان میکند؟
- docker inspect روی container
- docker images
- docker volume ls
- هیچکدام؛ متغیر محیطی پنهان است
پاسخ نمونه و معیار ارزیابی
- b ← docker images فقط فهرست image است، نه پیکربندی container.
- c ← این فقط فهرست volumeهاست.
- d ← متغیر محیطی برای فرایندها و در پیکربندی container دیدنی است.
تیم دو نفره برگ سبز میگوید «تعویض دورهای کلیدها وقتگیر است؛ فقط وقتی لو رفت عوض میکنیم». موازنه را بنویس و یک سیاست کمهزینه پیشنهاد بده.
پاسخ نمونه و معیار ارزیابی
بدون تعویض دورهای هزینه عملیاتی کم است، ولی نشت بیصدا (کلیدی که در لاگ یا کپی قدیمی مانده و کسی نفهمیده) بیپایان معتبر میماند و روز نشت، دستورالعمل تمریننشده است. تعویض دورهای هزینه دارد ولی هم عمر نشت بیصدا را محدود میکند و هم دستورالعمل را آزموده نگه میدارد. سیاست کمهزینه: دستورالعمل تعویض برای هر راز؛ تعویض با رفتن هر همکار و پس از هر رخداد؛ تعویض دورهای فقط برای کلیدهای پرخطر (مالی، دسترسی گسترده)؛ و کلیدهای جدا با دسترسی کمینه تا تعویض یکی بقیه را درگیر نکند.
- ریسک نشت بیصدا و دستورالعمل تمریننشده (1 امتیاز)
- هزینه تعویض (1 امتیاز)
- سیاست مبتنی بر خطر و رویداد (1 امتیاز)
- هر هفته همه کلیدها ← سیاستی که اجرا نشود بیاثر است؛ تعویض را با خطر و رویداد متناسب کن.
فایلهای درس
بارگذار پیکربندی سختگیر با پشتیبانی _FILE و راز پنهان در چاپ
settings.pyاسکنر آموزشی راز در پوشه و کل تاریخچه Git
scan_secrets.pyAPI آزمایشی با توکن از Compose secret بهجای متغیر محیطی
compose-secrets.yamlقالب دستورالعمل تعویض و نشت هر راز
rotation-runbook-template.mdخروجی واقعی اجرای ابزارهای درس
secrets-session.txtAPI آزمایشی با پشتیبانی MOCK_API_TOKEN_FILE
barg-sabz-mock-api.pyابزارها و جایگزینها
- Python 3.9 یا بالاتر — بارگذار پیکربندی و اسکنر — مسیر بدون اجرا با خروجی نمونه
منابع
The Twelve-Factor App: III. Config 12factor.net 12factor.net, 2026-10
Secrets Management Cheat Sheet OWASP Cheat Sheet Series living doc, accessed 2026-10-16
Manage secrets securely in Docker Compose Docker Docs Docker Docs, 2026-10
Set environment variables within your container's environment Docker Docs Docker Docs, 2026-10
Set a custom encryption key n8n n8n docs, 2026-10
Removing sensitive data from a repository GitHub Docs GitHub Docs, 2026-10
About push protection GitHub Docs GitHub Docs, 2026-10