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

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

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

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

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

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

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

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

ملف واحد هو .env في مجلد واجهة API، تقرؤه واجهة API مع yarn dev وyarn start:prod وyarn seed. يحوي أسرارًا: لا تضعه في Git أبدًا. أنشئه من .env.example الذي يشرح كل متغير ويعمل كما هو للتشغيل المحلي: cp .env.example .env.

تضبط صورة Docker قيمها الافتراضية بنفسها، فيعمل docker run من دون ملف: NODE_ENV=production، وSQLite عند /data/database.sqlite، والملفات المرفوعة في /data/uploads، وCORS_ORIGIN للواجهتين الأماميتين المحليتين، وFRONTEND_URL وDASHBOARD_URL على http://localhost:3031، وWEBSITE_URL=http://localhost:3030، وPUBLIC_API_URL=http://localhost:8000، وPUBLIC_MEDIA_URL=http://localhost:8000/media. تجاوز أيًّا منها باستخدام -e.

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

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

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

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

كل ميزة اختيارية أدناه معطّلة ما دامت متغيراتها في .env.example فارغة.

المدفوعات

مساران يتعاملان مع المال. صفحة الفوترة في لوحة التحكم تغيّر خطة اشتراك مساحة العمل، ودفع الموقع يبيع التراخيص. كلاهما يأخذ بيانات البطاقة في صفحة Stripe أو PayPal نفسها فقط (ترقية الخطة تُحصَّل من البطاقة التي تحتفظ بها Stripe أصلًا)، فلا تُكتب أبدًا في موقعك، وكلاهما يعمل من دون أي حساب عبر صفحات دفع تجريبية مدمجة لا تحصّل مبلغًا من أحد. استخدم مفاتيح الاختبار أولًا: فهي لا تنقل أي مال.

STRIPE_SECRET_KEY=sk_test_your_key
STRIPE_WEBHOOK_SECRET=whsec_your_secret
BILLING_PROVIDER=
BILLING_GRACE_DAYS=7
PAYPAL_CLIENT_ID=your-client-id
PAYPAL_CLIENT_SECRET=your-client-secret
PAYPAL_ENV=sandbox

على جهازك لا تستطيع Stripe الوصول إلى الـ webhook، لذلك تطلب صفحات العودة الجلسة من Stripe بنفسها، ويكتمل الدفع التجريبي مع ذلك. لا تُعدّ الخطة أو الترخيص مدفوعين إلا بعد أن تتحقق منهما واجهة API لدى المزوّد، وليس من عنوان العودة وحده. لا يحصّل Northstack أي ضريبة بنفسه، لذلك أعدّ الضريبة لبلدك قبل قبول مدفوعات حقيقية.

• فوترة الاشتراكات
• الدفع بالترخيص

البريد الإلكتروني

تُرسَل الدعوات وإعادة ضبط بيانات الدخول وإيصالات التراخيص ورسائل الفوترة والملخص الأسبوعي عبر SMTP بعد ضبط SMTP_HOST، كلٌّ بلغة المستلم (ولغة مساحة العمل إن لم يختر لغة). إلى ذلك الحين تُكتب كل رسالة في سجل واجهة API بدلًا من ذلك، مع الروابط، ليتبعها من ثبّت محليًا (مع Docker: docker compose logs api).

SMTP_HOST=smtp.your-provider.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-smtp-user
SMTP_PASSWORD=your-smtp-secret
SMTP_FROM=Northstack <no-reply@your-domain.com>
CONTACT_INBOX=hello@your-domain.com

SMTP_SECURE=true لخادم يتكلم TLS من البايت الأول، وغالبًا على المنفذ 465. وCONTACT_INBOX هو العنوان الذي تُحوَّل إليه رسائل نموذج التواصل في الموقع؛ وإذا تُرك فارغًا بقيت الرسائل في قاعدة البيانات فقط.

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

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

DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=your-database-secret
DB_DATABASE=northstack

ثم شغّل yarn seed، الذي ينشئ الجداول والبيانات التجريبية. لا تنشئ واجهة API العاملة الجداول وتحدّثها بنفسها إلا عندما يكون NODE_ENV=development، لذلك مع NODE_ENV=production شغّل yarn admin:create:prod مرة واحدة بعد yarn build للجداول وأول مسؤول منصة (yarn seed:prod للتثبيت التجريبي)، ثم yarn schema:prod بعد كل تحديث. تنشئ صورة Docker القاعدة بنفسها على SQLite فقط: على MySQL شغّل node dist/database/create-admin.js (أو node dist/database/seeder.js) بنفسك مرة واحدة في الحاوية.

الملفات المرفوعة والوسائط

تقدّم واجهة API ملفات هوية الطقم بنفسها عند /media. أما ملفات المشاريع والصور المرفوعة من لوحة التحكم، بحد أقصى 10 MB للملف، فتُخزَّن على قرص واجهة API تحت MEDIA_UPLOAD_DIR وتُقدَّم عند /media/uploads/…، ما لم يُضبط bucket.

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

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

لإرسال الملفات المرفوعة إلى bucket في Cloudflare R2، اضبط المتغيرات الخمسة كلها. مع أقل من خمسة تبقى الملفات على القرص. يذكر سجل واجهة API التخزين الذي يستخدمه عند البدء: Media storage: R2 bucket متبوعة باسم الـ bucket، أو Media storage: local folder متبوعة بالمجلد.

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

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

كل قيمة NEXT_PUBLIC_* تُدمج في JavaScript الذي يحمّله المتصفح، ويستطيع أي شخص يفتح الصفحة قراءتها. لا تضع فيها سرًا أبدًا، وأعد البناء (أو أعد تشغيل yarn dev) بعد تغيير أي منها. مع Docker مرّرها بصيغة --build-arg.

NEXT_PUBLIC_API_BASE_URL يحدد من أين تأتي بيانات كل واجهة أمامية. إذا كان فارغًا، أو من دون .env أصلًا، يعمل التطبيق على بياناته التجريبية المدمجة ولا يستدعي أي واجهة API. وإذا ضُبط على عنوان واجهة API متضمنًا /api (http://localhost:8000/api في .env.example وفي صور Docker)، يستخدم تلك الواجهة، ويلجأ إلى البيانات التجريبية في المتصفح فقط ما دامت لا تجيب.

• البيانات التجريبية

إعدادات الموقع

منفذ الموقع هو 3030، مكتوب في سكربتات package.json. لمنفذ آخر شغّل yarn next dev -p 3040 (أو yarn next start -p 3040 بعد yarn build).

إعدادات لوحة التحكم

لا يوضع هنا أي مفتاح مزوّد ذكاء اصطناعي أو دفع: قيمة NEXT_PUBLIC_* ظاهرة لكل من يفتح الصفحة. ويمكن استخدام مزوّد لا تملك واجهة API مفتاحه بمفتاح يضيفه القارئ في المساعد نفسه.

خيارات Docker Compose

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

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

• المنفذ مستخدم بالفعل

تقرأ حاوية واجهة API أيضًا ملف back-end/.env إن وُجد، فتُضبط المفاتيح الاختيارية (Stripe وPayPal والبريد وR2 والذكاء الاصطناعي وMCP) في مكان واحد لـ yarn dev ولـ Docker معًا. ويغلب docker-compose.yml في القيم التي تختلف داخل الحاوية: NODE_ENV=production والمنفذ ومسار قاعدة البيانات ومجلد الملفات المرفوعة والعناوين أعلاه. من دون JWT_SECRET خاص بك، أو مع قيمة المثال، تولّد واجهة API واحدًا وتحفظه في وحدة تخزين البيانات. وتعيش قاعدة البيانات والملفات المرفوعة في وحدة التخزين northstack-data.

مفاتيح المساعد الذكي

خادم MCP

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