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

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

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

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

ملف واحد هو .env في مجلد الموقع، يُقرأ عند بناء الموقع. كل قيمة NEXT_PUBLIC_* فيه عامة، فلا يحتوي سرًا أبدًا. أنشئه من .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 وSITE_URL=http://localhost:3030 و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 معلّقة كتعليقات.

المدفوعات

بدون أي من هذه يقبل المحاكي المرفق كل حجز بالبطاقة أو PayPal، فيعمل إتمام الطلب كله بلا حساب تاجر، ويقول سجل بدء واجهة API Payment simulator active ما دام يعمل. يؤكد تلك الحجوزات دون أخذ أي مال، لذا اضبط Stripe أو PayPal أو الاثنين قبل استقبال حجوزات حقيقية: عندها يتوقف المحاكي، ولا يعرض إتمام الطلب إلا الطرق المضبوطة مع الدفع عند الوصول، وتُرفض الطريقة التي ليس لها معالج. يبيّن تبويب المدفوعات في إعدادات لوحة التحكم أي المعالجات مضبوطة، وهل مفاتيحها تجريبية أم حقيقية، وهل المحاكي قيد الاستخدام، ولا يعرض المفاتيح نفسها أبدًا.

STRIPE_SECRET_KEY=your-stripe-secret-key
STRIPE_WEBHOOK_SECRET=your-stripe-webhook-signing-secret
PAYPAL_CLIENT_ID=your-paypal-client-id
PAYPAL_CLIENT_SECRET=your-paypal-client-secret
PAYPAL_WEBHOOK_ID=your-paypal-webhook-id
PAYPAL_ENV=sandbox

الدفع عند الوصول لا يحتاج إلى مفتاح: هو مفتاح التبديل allow_pay_on_arrival في تبويب المدفوعات في لوحة التحكم، ومفعّل في البيانات الأولية.

• الحجوزات والمدفوعات

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

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

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

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

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

تخدم واجهة API الصور الأولية بنفسها، من public/media/hollina، على /media/hollina/…. وتُخزَّن الملفات المرفوعة من لوحة التحكم (صور الإقامات، وأغلفة الوجهات، والصور الشخصية) على قرص واجهة 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

تُعاد ترميز الصور عند الرفع بصيغة JPEG، بعرض أقصاه 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 وSITE_URL وPUBLIC_MEDIA_URL في واجهة API، وعنوانا واجهة API والموقع في الواجهتين الأماميتين، فكلها تُبنى من المنافذ والعناوين الثلاثة، فتتبعها من تلقاء نفسها.

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

المساعد الذكي

خادم MCP

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