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

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

أنشئ ملف كل تطبيق من .env.example الموجود بجواره، والذي يشرح كل متغير: cp .env.example .env. تعمل الأمثلة كما هي للتشغيل المحلي، باستثناء عنواني واجهة API في لوحة التحكم، اللذين تملؤهما لترك البيانات التجريبية.

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

ملف واحد، .env في مجلد لوحة التحكم، يُقرأ عند بناء لوحة التحكم. كل قيمة فيه عامة، لذا لا يحتوي أبدًا على سر. اتركه لتعمل على البيانات التجريبية؛ وأنشئه من .env.example عندما تربط واجهة API: cp .env.example .env.

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

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

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

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

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

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

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

استخدم 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 للبيانات التجريبية، أو yarn db:sync للجداول من دون بيانات. لا تنشئ واجهة API قيد التشغيل الجداول وتحدّثها بنفسها إلا عندما يكون NODE_ENV=development، لذا مع NODE_ENV=production يُشغَّل أحد هذين الأمرين قبل التشغيل الأول (yarn db:sync:prod أو yarn seed:prod بعد yarn build)، ثم yarn db:sync:prod مرة أخرى بعد كل تحديث يغيّر المخطط. وهو يحافظ على بياناتك.

يأتي القالب بملف ترحيل لـ SQLite فقط. يحتوي back-end/src/database/migrations/mysql/README.md على الأمر الوحيد الذي يولّد ملف ترحيل MySQL، إذا أردت أن تعمل عمليات ترحيل بدء التشغيل في واجهة API على MySQL أيضًا.

لوحة التحكم

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

لا مكان هنا لأي مفتاح لمزوّد ذكاء اصطناعي. المفاتيح توجد في ملف .env الخاص بواجهة API فقط.

خيارات Docker Compose

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

تقرأ حاوية واجهة API أيضًا back-end/.env عند وجوده، لذا تُضبط مفاتيح التخزين والذكاء الاصطناعي و MCP في مكان واحد لكل من yarn dev و Docker. يتقدّم ملف compose في القيم التي تختلف داخل الحاوية: NODE_ENV=production، والمنفذ، و SQLite على /data/database.sqlite، وDEMO_MODE=false، وCORS_ORIGIN وFRONTEND_URL. من دون JWT_SECRET خاص بك، تولّد واجهة API سرًا وتحفظه في وحدة تخزين البيانات. توجد البيانات في وحدة التخزين kinora-data.

صورة Docker الخاصة بواجهة API

تبدأ الصورة في وضع الإنتاج على SQLite في /data/database.sqlite، والمنفذ 8000، مع DEMO_MODE=false وSEED_DEMO_DATA=false، وتسمح باستدعاءات المتصفح من http://localhost:3030 (CORS_ORIGIN وFRONTEND_URL). غيّر أيًا منها بـ -e في docker run، أو مرّر ملفك بـ --env-file .env.

• على وحدة تخزين جديدة تنشئ الحاوية الجداول، ولا تضيف البيانات التجريبية إلا مع SEED_DEMO_DATA=true. وتُترك قاعدة البيانات الموجودة كما هي.
• من دون JWT_SECRET، أو مع قيمة المثال، تولّد سرًا وتحفظه في /data/.jwt-secret، فتبقى جلسات تسجيل الدخول بعد إعادة التشغيل.
• مع DB_TYPE=mysql لا تنشئ شيئًا: شغّل node dist/database/sync-schema.js أو node dist/database/seeder.js في الحاوية مرة واحدة بنفسك.

تخزين الوسائط

تُرفع الصور الشخصية وصور التقدم وأغلفة المجموعات ومرفقات الرسائل إلى حاوية Cloudflare R2، أو أي حاوية متوافقة مع S3. اضبط المتغيرات الخمسة في back-end/.env وأعطِ لوحة التحكم المضيف العام للحاوية عبر NEXT_PUBLIC_MEDIA_HOSTNAME (ومع Docker Compose، MEDIA_HOSTNAME).

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

من دون حاوية، كل ما يكتبه الزرع هو مسار /assets/images/… تقدّمه لوحة التحكم من مجلدها public/assets، لذا تُعرض كل شاشة من دون رفع أي شيء. يتوقف فقط رفع الملفات الجديدة: يُرجع الرفع 400 إلى أن تُضبط الحاوية. أبقِ public/assets في لوحة التحكم ما دام أي صف لا يزال يشير إليه.

الحد الأقصى للملف 150 MB. ترسل أداة الرفع في لوحة التحكم الملفات الكبيرة على أجزاء يصل كل منها إلى 16 MB عبر POST /api/helpers/upload-chunk، تلقائيًا.

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

لا يأتي القالب بناقل بريد، لذا لا تُرسَل أي رسالة بالبريد الإلكتروني أبدًا. يجيب زر "resend verification email" في شاشة الأعضاء من دون إرسال أي شيء، وصفحتا نسيان كلمة المرور وإعادة تعيينها واجهتان فقط: لا يُرسَل أي رابط لإعادة التعيين، ولا يوجد في واجهة API أي مسار خلفهما. اربط مزوّد البريد الخاص بك، وأضف مسارات إعادة التعيين، قبل الإطلاق إذا كان أعضاؤك يحتاجون إلى أي منهما.

• "Forgot password" لا ترسل شيئًا

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

خادم MCP

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

الإطلاق

قبل النشر على أي مكان عام:

1. اضبط NODE_ENV=production وJWT_SECRET عشوائيًا وطويلًا خاصًا بك في back-end/.env.
2. اضبط CORS_ORIGIN على عنوان لوحة التحكم الخاصة بك، وFRONTEND_URL على العنوان نفسه.
3. أبقِ DEMO_MODE=false في واجهة API وNEXT_PUBLIC_DEMO_MODE=false في لوحة التحكم.
4. على قاعدة بيانات فارغة، شغّل yarn build، ثم yarn db:sync:prod مرة واحدة (أو yarn seed:prod للبيانات التجريبية)، ثم yarn start:prod.
5. وجّه فحص السلامة لدى مستضيفك إلى GET /api/health. لا يحتاج إلى رمز ولا يخضع لتحديد المعدل.
6. ابنِ لوحة التحكم مع توجيه NEXT_PUBLIC_API_BASE_URL وNEXT_PUBLIC_WEBSOCKET_BASE_URL إلى واجهة API المنشورة.
7. غيّر كلمات المرور المزروعة، أو ابدأ من جداول فارغة.

لحذف شيفرة العرض التجريبي بالكامل، شغّل yarn remove:demo في التطبيقين، على شجرة نظيفة: لا يمكن التراجع عنه من دون نظام إدارة الإصدارات. يحذف yarn remove:mock في لوحة التحكم البيانات التجريبية.