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

أين توجد الإعدادات

أنشئ ملف كل تطبيق من .env.example الموجود بجانبه، وهو يشرح كل متغير: cp .env.example .env. تعمل الأمثلة كما هي للتشغيل المحلي، ولا يحتاج تشغيل Docker Compose إلى أي ملف.

أين توجد الإعدادات

ملف واحد هو .env في مجلد الموقع، يُقرأ عند بناء الموقع. كل قيمة فيه عامة، فلا يحوي سرًا أبدًا. أنشئه من .env.example الذي يشير إلى واجهة API على http://localhost:8000: cp .env.example .env. مع Docker مرّر القيم نفسها بـ --build-arg.

أين توجد الإعدادات

ملف واحد هو .env في مجلد لوحة التحكم، يُقرأ عند بناء لوحة التحكم. كل قيمة فيه عامة، فلا يحوي سرًا أبدًا: مفاتيح المزودين في .env الخاص بواجهة API. أنشئه من .env.example الذي يشير إلى واجهة API على http://localhost:8000: cp .env.example .env. مع Docker مرّر القيم نفسها بـ --build-arg.

أين توجد الإعدادات

ملف واحد هو .env في مجلد واجهة API، تقرؤه واجهة API عند yarn dev، وتقرؤه الحاوية عندما تضيف --env-file .env -e NODE_ENV=production إلى docker run. يحوي أسرارًا: لا تضفه إلى المستودع أبدًا. أنشئه من .env.example الذي يشرح كل متغير ويعمل كما هو للتشغيل المحلي: cp .env.example .env.

تضبط صورة Docker قيمها الافتراضية بنفسها، لذلك يعمل docker run بدون ملف: SQLite في /data/database.sqlite، والملفات المرفوعة في /data/uploads، وCORS_ORIGIN للواجهتين الأماميتين المحليتين، وFRONTEND_URL=http://localhost:3031 وPUBLIC_MEDIA_URL=http://localhost:8000/media وSEED_DEMO_DATA=false. غيّر أيًّا منها بـ -e.

أساسيات واجهة API

تتحقق واجهة API من JWT_SECRET، ومن CORS_ORIGIN في الإنتاج، قبل أن تبدأ. إذا كان أحدهما ناقصًا أو غير صالح، تتوقف وتطبع سطرًا واحدًا يوضح ما يجب إصلاحه.

ولّد JWT_SECRET خاصًا بك بالأمر:

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

كل ميزة اختيارية أدناه تبقى متوقفة ما دامت أسطرها في .env.example معلّقة كتعليقات.

استخدم MySQL بدلًا من SQLite

أنشئ قاعدة بيانات فارغة، ثم اضبط المشغّل والاتصال في ملف .env الخاص بواجهة API:

DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=
DB_DATABASE=velra

ثم شغّل yarn seed للوكالة التجريبية، أو yarn db:sync للجداول بلا بيانات. لا تنشئ واجهة API العاملة الجداول ولا تحدّثها بنفسها إلا عندما يكون NODE_ENV=development، لذلك مع NODE_ENV=production يجب تشغيل أحد هذين الأمرين قبل التشغيل الأول (yarn seed:prod أو yarn db:sync:prod بعد yarn build).

الصور والملفات المرفوعة

تقدّم واجهة API الصور الأولية بنفسها، من public/media/velra، على /media/velra/…. أما الملفات المرفوعة من لوحة التحكم (صور العقارات، وصور الغرف للاستوديو، والمعاينات المؤثثة، وصور الملفات الشخصية) فتُخزَّن على قرص واجهة API تحت MEDIA_UPLOAD_DIR وتُقدَّم على /media/uploads/…، ما لم تُضبط حاوية تخزين.

PUBLIC_MEDIA_URL=http://localhost:8000/media
MEDIA_UPLOAD_DIR=./public/media/uploads

PUBLIC_MEDIA_URL هو العنوان الذي يُوصَل إلى /media منه من المتصفح. يُبنى منه عنوان كل صورة، وتنقل واجهة API المخزَّن منها إليه عند بدئها، لذلك ينقل تحريك واجهة API كل الصور معها. على الخادم وجّه MEDIA_UPLOAD_DIR إلى تخزين دائم؛ ومع Docker يكون في وحدة البيانات.

لإرسال الملفات المرفوعة إلى Cloudflare R2 أو أي حاوية متوافقة مع S3، اضبط المتغيرات الخمسة كلها. أعطِ الواجهتين الأماميتين المضيف العام للحاوية عبر NEXT_PUBLIC_MEDIA_HOSTNAME (مع Docker Compose هو MEDIA_HOSTNAME) ليغيّر Next.js أحجام تلك الصور.

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.dev

تُعاد ترميز الصور عند الرفع بعرض لا يتجاوز 1920 بكسل، مع نسخة أصغر لبطاقات العقارات. تُقبل مقاطع الفيديو بصيغة MP4 أو WebM أو MOV أو M4V، حتى 150 ميغابايت.

الموقع العام ولوحة تحكم الوكالة

كل قيمة NEXT_PUBLIC_* تُضمَّن في كود JavaScript الذي يحمّله المتصفح، ويستطيع أي شخص يفتح الصفحة قراءتها. لا تضع أي سر في هذه الملفات أبدًا، وأعد البناء بعد تغيير أي قيمة.

أوسمة التسويق في الموقع هي أيضًا قيم NEXT_PUBLIC_*: Google Tag Manager وGA4 وMeta وTikTok وSnapchat وPinterest، ويُفعَّل كل منها بمعرّف واحد.

• أوسمة التحليلات والتتبع

خيارات Docker Compose

لا تحتاج إلى ضبط أي شيء للتشغيل المحلي. لتغيير شيء، ضعه في ملف .env بجوار docker-compose.yml وشغّل docker compose up --build مرة أخرى: تُضمِّن الواجهات الأمامية هذه القيم.

غيّر المنفذ عندما يستخدمه برنامج آخر، مثل ADMIN_PORT=3041. تُبنى كل من CORS_ORIGIN وFRONTEND_URL وPUBLIC_MEDIA_URL في واجهة API، وعنوانا واجهة API والموقع في الواجهتين الأماميتين، من المنافذ والعناوين الثلاثة، فتتبعها تلقائيًا.

تقرأ حاوية واجهة API الملف back-end/.env أيضًا عند وجوده، لذلك تُضبط المفاتيح الاختيارية في مكان واحد لـ yarn dev ولـ Docker معًا. ويتغلب ملف compose في القيم التي تختلف داخل الحاوية: مسار قاعدة البيانات، ومجلد الملفات المرفوعة، والمنفذ، وNODE_ENV=production والعناوين أعلاه. وقاعدة البيانات والملفات المرفوعة في وحدة التخزين velra-data.

ميزات الذكاء الاصطناعي

خادم MCP

وضع العرض التجريبي