متغيرات البيئة
وظيفة كل إعداد في ملفي .env لواجهة API ولوحة التحكم، وأيها تحتاج إليه، وخيارات Docker Compose.
لحزمة واجهة + خلفية
أين توجد الإعدادات
| الملف | يقرؤه | يحتوي على أسرار |
|---|---|---|
back-end/.env | واجهة API، مع yarn dev وداخل Docker Compose | نعم. لا تضفه إلى المستودع أبدًا. |
front-end/.env | لوحة التحكم. تُضمَّن قيم NEXT_PUBLIC_* فيها عند البناء | فقط WEATHER_API_KEY، الذي يبقى على خادم لوحة التحكم |
.env بجوار docker-compose.yml | Docker Compose، للتطبيقين | فقط WEATHER_API_KEY |
أنشئ ملف كل تطبيق من .env.example الموجود بجواره، وهو يشرح كل متغير: cp .env.example .env. تعمل الأمثلة كما هي في التشغيل المحلي. ولا حاجة إلى أي من الملفات مع Docker Compose.
أين توجد الإعدادات
ملف اختياري واحد، .env في مجلد لوحة التحكم. من دون ملف، تعمل لوحة التحكم على واجهة API التجريبية المدمجة. ويوجّهها .env.example إلى واجهة API على http://localhost:8000: انسخه بالأمر cp .env.example .env عندما تكون لديك واجهة.
مع Docker، تكون قيم NEXT_PUBLIC_* وسائط بناء (docker build --build-arg NAME=value)، وWEATHER_API_KEY خيار تشغيل (docker run -e WEATHER_API_KEY=...).
أساسيات واجهة API
تتحقق واجهة API من JWT_SECRET ومن CORS_ORIGIN في الإنتاج قبل أن تبدأ. وإذا كان أحدهما مفقودًا أو غير صالح، تتوقف بسطر واحد يذكر ما يجب إصلاحه. والمتغيرات المضبوطة أصلًا في العملية، من Docker أو من الاستضافة، تتغلب على الملف.
| المتغير | القيمة الافتراضية | وظيفته |
|---|---|---|
NODE_ENV | development | يُنشئ development الجداول ويحدّثها عند البدء. أما production فلا يلمس الجداول أبدًا، ويرفض البدء بقيمة المثال لـ JWT_SECRET أو من دون CORS_ORIGIN. |
PORT | 8000 | منفذ واجهة API. تشير إليه لوحة التحكم. |
DB_TYPE | sqlite | sqlite أو mysql. |
SQLITE_DATABASE | ./database.sqlite | ملف SQLite، نسبةً إلى back-end. |
JWT_SECRET | قيمة المثال | يوقّع كل جلسة تسجيل دخول. مطلوب. قيمة المثال مقبولة خارج الإنتاج فقط. |
JWT_EXPIRATION | 7d | مدة بقاء تسجيل الدخول. |
CORS_ORIGIN | http://localhost:3030 | عنوان لوحة التحكم، وتُفصل العناوين بفاصلة إذا كانت عدة عناوين. مطلوب في الإنتاج. |
FRONTEND_URL | http://localhost:3030 | العنوان الوحيد الذي يقبله التحديث الفوري للصلاحيات: عنوان لوحة التحكم. |
RATE_LIMIT_LOGIN | 10 | عدد محاولات تسجيل الدخول الفاشلة التي يجوز لعنوان واحد إجراؤها خلال 15 دقيقة قبل أن يجيب تسجيل الدخول بالرمز 429. |
TRUST_PROXY | فارغ | عدد الوكلاء العكسيين أمام واجهة API، مثل 1 خلف Nginx أو Caddy، ليحسب حد تسجيل الدخول الزوار بدلًا من الوكيل. |
ولّد JWT_SECRET خاصًا بك بالأمر:
node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"قبل الإطلاق. كل seed (yarn seed وyarn seed:prod والتشغيل الأول في Docker) ينشئ المشرفين النموذجيين بكلمات المرور المذكورة في الأدلة. غيّر كلمات مرورهم أو احذفهم، واضبط JWT_SECRET الخاص بك، قبل أن يصبح بإمكان أي شخص آخر الوصول إلى لوحة التحكم.
استخدم MySQL بدلًا من SQLite
أنشئ قاعدة بيانات فارغة، ثم اضبط برنامج التشغيل والاتصال في back-end/.env:
DB_TYPE=mysql
DB_HOST=your-mysql-host
DB_PORT=3306
DB_USERNAME=your-mysql-username
DB_PASSWORD=your-mysql-password
DB_DATABASE=your-database-nameثم نفّذ yarn seed الذي ينشئ الجداول والبيانات النموذجية. لا تنشئ واجهة API العاملة الجداول وتحدّثها بنفسها إلا مع NODE_ENV=development، لذلك مع NODE_ENV=production نفّذ yarn seed:prod مرة واحدة بعد yarn build، قبل التشغيل الأول.
لوحة التحكم
تُضمَّن كل قيمة NEXT_PUBLIC_* في كود JavaScript الذي يحمّله المتصفح، ويستطيع أي شخص يفتح الصفحة قراءتها. لا تضع فيها سرًا أبدًا، وأعد تشغيل yarn dev أو أعد البناء بعد تغيير أي منها.
| المتغير | القيمة الافتراضية | وظيفته |
|---|---|---|
NEXT_PUBLIC_API_BASE_URL | فارغ: واجهة API التجريبية | عنوان واجهة API متضمنًا /api، مثل http://localhost:8000/api. تشغّل القيمة الفارغة لوحة التحكم على واجهة API التجريبية المدمجة ببيانات نموذجية. |
NEXT_PUBLIC_WEBSOCKET_BASE_URL | عنوان واجهة API من دون /api | خادم واجهة API، للتحديث الفوري للصلاحيات. غير مستخدم على واجهة API التجريبية. |
NEXT_PUBLIC_BASE_URL | http://localhost:3030 | العنوان العام للوحة التحكم نفسها، من دون شرطة مائلة في النهاية. يُبنى منه كل من robots.txt وخريطة الموقع وعناوين البيانات الوصفية المطلقة. |
WEATHER_API_KEY | فارغ | مفتاح WeatherAPI.com لعرض الطقس في تحية النظرة العامة، ويُقرأ على خادم لوحة التحكم فقط. وتركه فارغًا يُسقط الطقس. |
PORT | 3030 | المنفذ الذي يستخدمه yarn dev وyarn start. |
BUILD_STANDALONE | غير مضبوط | true يجعل yarn build ينتج خادمًا مستقلًا بذاته، وهو ما يضبطه Dockerfile. اتركه غير مضبوط في غير ذلك. |
لا توجد مفاتيح مزوّدي الذكاء الاصطناعي في لوحة التحكم: فهي في ملف .env الخاص بواجهة API فقط.
خيارات Docker Compose
لا يلزم ضبط أي شيء للتشغيل المحلي. لتغيير شيء، ضعه في ملف .env في المجلد dashboard-2-full-stack بجوار docker-compose.yml، ثم نفّذ docker compose up --build مرة أخرى: فلوحة التحكم تضمّن عنوان واجهة API عند البناء.
| المتغير | القيمة الافتراضية | وظيفته |
|---|---|---|
DASHBOARD_PORT | 3030 | منفذ لوحة التحكم على جهازك. |
API_PORT | 8000 | منفذ واجهة API على جهازك. |
DASHBOARD_URL | http://localhost: وDASHBOARD_PORT | المكان الذي يصل منه المتصفح إلى لوحة التحكم. ومنه تُضبط CORS_ORIGIN وFRONTEND_URL في واجهة API، وعنوان لوحة التحكم نفسها. |
API_URL | http://localhost: وAPI_PORT | المكان الذي يصل منه المتصفح إلى واجهة API. تُبنى لوحة التحكم به متبوعًا بـ /api. |
WEATHER_API_KEY | فارغ | الطقس في تحية النظرة العامة. |
DASHBOARD_PORT=3040غيّر المنفذ عندما يستخدمه برنامج آخر، كما سبق. واضبط DASHBOARD_URL وAPI_URL معًا عندما تقدّم المنظومة على نطاقاتك الخاصة.
تقرأ حاوية واجهة API أيضًا الملف back-end/.env إن وُجد، فتُضبط مفاتيح الذكاء الاصطناعي وR2 ومفتاح MCP في مكان واحد لـ yarn dev ولـ Docker. ويتغلب ملف compose في القيم التي تختلف داخل الحاوية: NODE_ENV=production والمنفذ وملف SQLite في وحدة التخزين dashboard-2-data والعنوانان أعلاه ووضع العرض التجريبي الذي يُبقيه معطلًا. ومن دون JWT_SECRET خاص بك، تولّد واجهة API واحدًا وتحفظه في وحدة التخزين.
رفع الصور
تُخزَّن الصور الشخصية ومرفقات الصور في المساعد في حاوية Cloudflare R2. اضبط المتغيرات الخمسة كلها؛ ومن دونها يجيب الرفع بأنه غير مُعدّ، ويعمل كل شيء آخر.
R2_ACCESS_KEY_ID=your-r2-access-key-id
R2_SECRET_ACCESS_KEY=your-r2-secret-access-key
R2_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
R2_BUCKET_NAME=your-bucket-name
R2_PUBLIC_URL=https://your-public-url.r2.devR2_PUBLIC_URL هو العنوان العام للحاوية، لذلك يجب أن تسمح الحاوية بالقراءة العامة. كل عملية رفع صورة بحجم 10 MB على الأكثر، تُحفظ بصيغة JPEG بعرض 1920 بكسل على الأكثر، مع نسخة أصغر بجوارها.
مفاتيح المساعد الذكي
مُضمَّن مع مشترياتك. سجّل الدخول لقراءته، أو افتحه في ملف التنزيل.
المتغيرات التي تفعّل كل مزوّد ذكاء اصطناعي، وما يحدث عند ترك أحدها فارغًا.
خادم MCP
مُضمَّن مع مشترياتك. سجّل الدخول لقراءته، أو افتحه في ملف التنزيل.
السماح لوكلاء البرمجة وعملاء MCP الآخرين باستخدام أدوات المساعد: المفتاح ونقطة النهاية.
وضع العرض التجريبي
مُضمَّن مع مشترياتك. سجّل الدخول لقراءته، أو افتحه في ملف التنزيل.
تشغيل نسخة تجريبية عامة: مفاتيح العرض التجريبي، ورسائل المساعد المجانية لكل زائر، وما يستطيع الزوار تغييره.