# متغيرات البيئة

> ضبط متغيرات البيئة لتطبيقات تاروت

# متغيرات البيئة

متغيرات البيئة تتيح لك ضبط تطبيقك دون تغيير الكود. استخدمها لمفاتيح API وسلاسل اتصال قاعدة البيانات وعلامات الميزات والمزيد.

## كيف تُخزَّن المتغيرات

تنتمي المتغيرات إلى تطبيق واحد. ولكل متغير:

- **المفتاح** - حروف وأرقام وشرطة سفلية، ويبدأ بحرف أو شرطة سفلية (مثل `DATABASE_URL`).
- **القيمة** - حتى 64 كيلوبايت، وتُخزَّن مشفّرة.
- **الوصف** - ملاحظة اختيارية عن الغرض من المتغير.
- **سري** - مفعّل افتراضيًا. تُخفى القيم السرية في القوائم وعمليات التصدير ما لم تطلب إظهارها صراحةً.

لا توجد قيم منفصلة لكل بيئة (مثل مجموعة للإنتاج وأخرى للتجريب). لاستخدام المتغيرات نفسها في تطبيق آخر، انسخها بالأمر `tarout env copy`.

## ضبط المتغيرات

### لوحة التحكم

1. افتح تطبيقك وانتقل إلى تبويب **المتغيرات**.
2. انقر **إضافة متغير**، وأدخل المفتاح والقيمة، ثم احفظ. ويمكنك أيضًا النقر على **استيراد .env** للصق محتوى ملف `.env` (تُستبدل قيم المفاتيح المتطابقة ويُحتفظ بالباقي)، أو التبديل إلى عرض **ملف .env** لتعديل جميع المتغيرات كمستند واحد.
3. عندما تُظهر لوحة التحكم أن إعادة التشغيل مطلوبة، انقر **إعادة التشغيل الآن** لتطبيق التغيير على التطبيق العامل.

### سطر الأوامر

كل أوامر `env` تأخذ التطبيق (المعرّف أو الاسم) أولًا:

```bash
# ضبط متغير واحد (سري افتراضيًا؛ أضف --no-secret للإعدادات العادية)
tarout env set my-app DATABASE_URL="postgres://user:pass@host:5432/db"

# قراءة القيمة من الإدخال القياسي بدل سطر الأوامر (مفيد للأسرار متعددة الأسطر)
tarout env set my-app PRIVATE_KEY < key.pem

# عرض المتغيرات (القيم مخفية ما لم تضف --reveal)
tarout env list my-app

# رفع ملف .env (يدمج افتراضيًا؛ --replace يحذف المفاتيح غير الموجودة في الملف)
tarout env push my-app --input .env

# تنزيل المتغيرات إلى ملف .env (الأسرار مخفية ما لم تضف --reveal)
tarout env pull my-app --output .env

# حذف متغير
tarout env unset my-app OLD_KEY

# نسخ المتغيرات من تطبيق إلى آخر
tarout env copy source-app target-app
```

أوامر أخرى: `env get` و`env reveal` و`env audit` و`env bulk-set` و`env bulk-delete`. شغّل `tarout env --help` للتفاصيل.

### متى تسري التغييرات

| طريقة التغيير | متى يراها التطبيق العامل |
|---|---|
| `tarout env set` (إنشاء أو تحديث متغير واحد، وكذلك عبر MCP والواجهة البرمجية) | عند النشر التالي. تُحفظ القيمة، لكن الحاوية العاملة لا تُحدَّث، وإعادة التشغيل وحدها لا تلتقطها. شغّل `tarout deploy` لتطبيقها. |
| `tarout env push` | عند إعادة التشغيل أو النشر التالي. أضف `--restart` لإعادة تشغيل التطبيق وتطبيقها فورًا. |
| `tarout env unset` | فورًا: حذف أي متغير يعيد تشغيل التطبيق دائمًا. |
| الإضافة أو التعديل أو الاستيراد من لوحة التحكم | بعد النقر على **إعادة التشغيل الآن** (أو عند النشر التالي). |

## متغيرات وقت البناء

معظم المتغيرات **لوقت التشغيل فقط**: تُحقن عند تشغيل الحاوية ولا تظهر أثناء بناء التطبيق، وهذا يُبقي الأسرار خارج سجلات البناء وطبقات الصورة.

لا يُمرَّر إلى البناء إلا هذه المتغيرات:

- المفاتيح التي تبدأ ببادئة عامة: `NEXT_PUBLIC_` أو `VITE_` أو `REACT_APP_` أو `PUBLIC_` أو `NUXT_PUBLIC_` أو `GATSBY_` أو `EXPO_PUBLIC_`.
- إعدادات أداة البناء التي تبدأ بـ `RAILPACK_` (مثل `RAILPACK_PHP_EXTENSIONS`)، إضافةً إلى `NIXPACKS_NODE_VERSION`.

قيم المتغيرات ذات البادئات العامة تنتهي عادةً في الكود الذي يصل إلى المتصفح، فلا تضع فيها أي سر. وإذا احتاجت خطوة في البناء إلى سر (مثل رمز لحزمة خاصة) وكان تطبيقك يُبنى من Dockerfile، فاستخدم قسم **معاملات البناء** في تبويب **المتغيرات** بدلًا من ذلك.

## متغيرات خاصة

| المتغير | الوصف |
|---------|-------|
| `PORT` | تحقنه تاروت بالمنفذ الذي يجب أن يستمع عليه تطبيقك. هذه القيمة تديرها تاروت: أي `PORT` تضبطه بنفسك يُستبدل عند النشر. |

## أفضل الممارسات

- لا تضع الأسرار في Git أبدًا - استخدم متغيرات البيئة بدلًا من ذلك.
- أبقِ القيم السرية خارج المفاتيح ذات البادئات العامة مثل `NEXT_PUBLIC_` و`VITE_`.
- استخدم بادئات للمتغيرات المرتبطة (مثل `SMTP_HOST`، `SMTP_PORT`، `SMTP_USER`).
- استخدم ملف `.env.example` في مستودعك لتوثيق المتغيرات المطلوبة.

---

## Every Tarout agent guide

- [Start Here (Agents)](https://tarout.sa/docs/for-ai/start.md)
- [Overview](https://tarout.sa/docs/for-ai.md)
- [Deploying an app](https://tarout.sa/docs/for-ai/deploy.md)
- [Databases](https://tarout.sa/docs/for-ai/database.md)
- [Object storage](https://tarout.sa/docs/for-ai/storage.md)
- [Custom domains](https://tarout.sa/docs/for-ai/domains.md)
- [Plans and upgrades](https://tarout.sa/docs/for-ai/billing.md)
- [Troubleshooting](https://tarout.sa/docs/for-ai/troubleshoot.md)
- [Agent Onboarding](https://tarout.sa/docs/for-ai/onboarding.md)
- [CLI Reference](https://tarout.sa/docs/for-ai/cli-reference.md)
- [CLI JSON Schema](https://tarout.sa/docs/for-ai/cli-json-schema.md)

Whole corpus in one file: https://tarout.sa/llms-full.txt · index: https://tarout.sa/llms.txt
Any docs page is raw markdown at the same URL + `.md`. Short link to the entry point: https://tarout.sa/deploy.md