حل المشكلات

Docker لا يعمل

failed to connect to the docker API at unix:///…/docker.sock; check if the path is correct and if the daemon is running

تعرض إصدارات Docker الأقدم الرسالة "Cannot connect to the Docker daemon" بدلًا من ذلك. وفي الحالتين، محرك Docker غير مُشغَّل.

1. 01

   افتح Docker Desktop

   شغّل Docker Desktop وانتظر حتى يُظهر أن المحرك يعمل. على Linux، شغّل الخدمة: sudo systemctl start docker.
2. 02

   تحقق من أن Docker يستجيب

   الطرفيةنسخ

   docker info

   النتيجة المتوقعة: يطبع قسم Server بدلًا من رسالة خطأ.
3. 03

   شغّل أمر التشغيل مرة أخرى

   docker compose up --build للحزمة الكاملة، أو أمرَي docker build وdocker run الخاصين بك لتطبيق واحد.

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

ports are not available: exposing port TCP 0.0.0.0:3031 … bind: address already in use
Bind for 0.0.0.0:3031 failed: port is already allocated
Error: listen EADDRINUSE: address already in use :::3031

السطران الأولان يأتيان من Docker، والأخير من yarn dev. هناك برنامج آخر يستمع بالفعل على 3030 أو 3031 أو 8000: غالبًا تشغيل سابق لـ Northstack، أو خادم تطوير لمشروع آخر.

1. 01

   اعرف ما الذي يشغل المنفذ

   على macOS أو Linux، مع المنفذ الوارد في الرسالة:

   الطرفيةنسخ

   lsof -i :3031

   على Windows، في PowerShell:

   الطرفيةنسخ

   netstat -ano | findstr :3031
2. 02

   أوقفه

   أغلق ذلك البرنامج، أو أوقف التشغيل السابق: Ctrl+C في طرفيته، أو docker compose down في مجلده، أو docker stop لحاوية شغّلتها بـ docker run. ثم شغّل Northstack مرة أخرى.
3. 03

   أو شغّل Northstack على منافذ أخرى

   مع الحزمة الكاملة في Docker، أنشئ ملفًا باسم .env في المجلد northstack-full-stack بجانب docker-compose.yml يحمل المنفذ الذي تحتاج إليه. ينقل SITE_PORT الموقع، وADMIN_PORT لوحة التحكم، وAPI_PORT واجهة API؛ والعناوين التي تستخدمها التطبيقات، ومنها CORS_ORIGIN، تتبعها تلقائيًا.

   northstack-full-stack/.envنسخ

   ADMIN_PORT=3041

   ثم شغّل الأمر نفسه مرة أخرى. يكمل التشغيل الفاشل من حيث توقف. يذكر Docker منفذًا مشغولًا واحدًا في كل مرة: إذا توقف عند منفذ آخر فأضفه إلى .env أيضًا.

   الطرفيةفي northstack-full-stackنسخ

   docker compose up --build

   النتيجة المتوقعة: يجيب التطبيق على منفذه الجديد، هنا localhost:3041محلي.

فشل بناء Docker

ينزّل البناء الأول الصور الأساسية وكل الاعتماديات، ثم يبني الصور. وعندما يعترضه شيء، يتوقف بالرسالة "failed to solve" مع الخطوة التي فشلت.

• لا اتصال أو انتهت المهلة: يحتاج البناء إلى الإنترنت. شغّل الأمر مرة أخرى بعد عودة الاتصال؛ الخطوات المكتملة محفوظة في ذاكرة التخزين المؤقت.
• لا توجد مساحة كافية على الجهاز (No space left on device): حرّر مساحة في Docker Desktop، أو تحقق مما يستخدمه Docker بالأمر docker system df.
• يفشل عند الخطوة نفسها في كل مرة: أعد البناء من دون ذاكرة التخزين المؤقت، ثم شغّل التطبيقات.
• يرفض Compose الملف `docker-compose.yml` نفسه ويذكر `env_file`: إصدار Compose لديك أقدم من 2.24. حدّث Docker Desktop، أو إضافة Compose على Linux.

docker compose build --no-cache
docker compose up

لحزمة التطبيق الواحد، أضف --no-cache إلى أمر docker build الخاص بك.

التشغيل الأول الذي يبدو عالقًا يكون عادة ما زال يملأ مساحات العمل التجريبية والمؤسسات الـ732 خلف أرقام المنصة. لا يبدأ الموقع ولوحة التحكم إلا بعد أن تعلن واجهة API أنها سليمة.

يقول Yarn إن إصداره 1.22

This project's package.json defines "packageManager": "yarn@4…". However the current global version of Yarn is 1.22…

يثبّت كل تطبيق Yarn 4.8.1 عبر Corepack. تعني هذه الرسالة أن Corepack لم يُفعَّل بعد، فأجاب Yarn العام القديم بدلًا منه.

corepack enable

ثم شغّل yarn install مرة أخرى. إذا لم يكن في Node.js لديك Corepack (Node.js 25 وما بعده لا تضمه)، فثبّته أولًا بالأمر npm install -g corepack. لا يُستخدم npm ولا pnpm: كل تطبيق يأتي بملف yarn.lock خاص به.

يفشل التثبيت أو التشغيل على إصدار أقدم من Node.js

تحتاج واجهة API إلى Node.js 22.13 أو إصدار أحدث من 22، أو Node.js 24.11 أو أحدث؛ ويحتاج الموقع ولوحة التحكم وحدهما إلى Node.js 22.9 أو أحدث. وتعمل صور Docker على Node.js 24. يظهر Node.js الأقدم في صورة تثبيت يفشل في بناء حزمة، أو تطبيق يتوقف عند التشغيل.

node -v

إذا طبع إصدارًا أقدم، فثبّت Node.js 24 (أو إصدار 22 من 22.13)، وشغّل corepack enable مرة أخرى (على Node.js 25 وما بعده، شغّل npm install -g corepack أولًا)، ثم احذف مجلد node_modules للتطبيق وشغّل yarn install مرة أخرى. Node.js 23، وإصدارات 24 قبل 24.11، خارج نطاق واجهة API أيضًا. ومع Docker لا ينطبق شيء من هذا: تأتي الصور بـ Node.js الخاص بها.

تتوقف واجهة API قبل أن تبدأ

The API cannot start: JWT_SECRET is not set. Set it in back-end/.env to the output of: …
The API cannot start: JWT_SECRET is still the example value from .env.example, so anyone can sign a token for any account. …
The API cannot start: CORS_ORIGIN is not set. List the website and dashboard origins, comma separated, …

تتحقق واجهة API من إعداداتها قبل أن تبدأ، وتطبع سطرًا واحدًا لكل مشكلة. الأسباب:

• لا يوجد ملف `.env`، أو `JWT_SECRET` فارغ. أنشئ الملف في مجلد واجهة API بالأمر cp .env.example .env.
• ما زال `JWT_SECRET` بقيمة المثال مع `NODE_ENV=production`. يستطيع أي شخص توقيع رمز باستخدام المثال العام، لذا يرفضه التشغيل في وضع الإنتاج. ولّد سرًا خاصًا بك.
• `CORS_ORIGIN` فارغ مع `NODE_ENV=production`. اكتب عنوانَي الموقع ولوحة التحكم، مفصولين بفاصلة.

ولّد سرًا بالأمر:

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

مع Docker لا تحتاج إلى ذلك: الحاوية التي ليس لها JWT_SECRET خاص بها، أو التي تستخدم قيمة المثال، تولّد سرًا وتحفظه في وحدة تخزين البيانات.

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

لا أحد يستطيع تسجيل الدخول على قاعدة بيانات جديدة

من دون Docker، ينشئ yarn dev مع NODE_ENV=development الجداول عند أول تشغيل، لكنه لا ينشئ حسابًا: تأتي الحسابات ومساحات العمل التجريبية من yarn seed. أوقف واجهة API، وشغّله في مجلد واجهة API، ثم شغّل الواجهة مرة أخرى.

yarn seed
yarn dev

ينتهي بـ Seed complete. والحسابات التي تسجّل الدخول بها. وعند الفشل يطبع Seeding failed: متبوعًا بالسبب، مثل قاعدة MySQL غير موجودة بعد. تملأ صورة Docker وحدة تخزين SQLite الجديدة بنفسها؛ وعلى MySQL شغّل node dist/database/seeder.js مرة واحدة داخل الحاوية.

قاعدة البيانات التي بدأت فارغة (yarn schema، أو Docker مع SEED_SAMPLE_DATA=false ومن دون ADMIN_EMAIL وADMIN_PASSWORD) لا حساب فيها أيضًا، عن قصد. أنشئ أول مسؤول منصة بـ yarn admin:create (بعد البناء: yarn admin:create:prod؛ وفي Docker: docker compose exec -u node api node dist/database/create-admin.js)، فيسأل عن البريد وبيانات تسجيل الدخول.

فشل تسجيل الدخول

That email and password do not match an account. Try again.
Too many failed sign-in attempts. Wait 15 minutes, then try again.

• تحقق من الحساب. كل حساب يسجّل الدخول في لوحة التحكم، على المنفذ 3031؛ وليس للموقع تسجيل دخول خاص به، وأزرار «جرّب العرض الحي» فيه تفتح تسجيل الدخول إلى لوحة التحكم. الحسابات التجريبية وكلمة المرور في صفحة التثبيت.
• ترد الرسالة نفسها على كلمة مرور خاطئة وبريد غير معروف وقاعدة بيانات لم تُملأ قط. تحقق مما كتبته؛ وعلى قاعدة بيانات جديدة ينشئ yarn seed في مجلد واجهة API الحسابات.
• «محاولات تسجيل دخول فاشلة كثيرة. انتظر 15 دقيقة ثم حاول مرة أخرى.» عشر محاولات دخول فاشلة من عنوان واحد خلال 15 دقيقة ترفض كل محاولة أخرى منه، حتى بكلمة المرور الصحيحة، إلى أن يمضي 15 دقيقة على أقدم فشل. انتظر، أو أعد تشغيل واجهة API: فالعدّ محفوظ في ذاكرتها. ويغيّر RATE_LIMIT_LOGIN في .env الخاص بواجهة API هذا الرقم.
• «التسجيلات الجديدة مغلقة على هذه المنصة حاليًا.» في صفحة إنشاء الحساب أو في الإعداد الأولي: أوقف فريق المنصة التسجيلات الجديدة في إعدادات المنصة. الحسابات الموجودة ما زالت تسجّل الدخول.
• غيّرت بيانات الدخول ولم تعد تملكها: ابدأ من جديد ببيانات تجريبية جديدة، أدناه.
• سجّلت الدخول لكن الصفحة تعرض إشعار «بيانات تجريبية»: لم تستطع لوحة التحكم الوصول إلى واجهة API فأجابت من بياناتها التجريبية. راجع المشكلة التالية.

• الحسابات التجريبية

فشل تسجيل الدخول

• تحقق من الحساب والمسار. كل حساب يسجّل الدخول عبر POST /api/auth/login؛ والحسابات التجريبية وكلمة المرور في صفحة التثبيت. ويجيب تسجيل الدخول الفاشل بـ 401 وبالرسالة نفسها سواء كان البريد أو كلمة المرور خاطئًا.
• لا يعمل أي حساب إطلاقًا: أُنشئت قاعدة البيانات من دون البيانات التجريبية. شغّل yarn seed للحسابات التجريبية، أو yarn admin:create لمسؤول منصة خاص بك، كما في المشكلة أعلاه.
• الرد `429` يعني أن عنوانًا واحدًا فشل في 10 محاولات دخول خلال 15 دقيقة. يزول عندما يمضي 15 دقيقة على أقدم محاولة فاشلة، أو عند إعادة تشغيل واجهة API. يغيّر RATE_LIMIT_LOGIN هذا العدد.

• الحسابات التجريبية

إشعار «بيانات تجريبية» أسفل كل صفحة

No API is connected, so this dashboard runs on built-in sample data and your changes stay in this browser. …
The API at http://localhost:8000/api is not answering, so this dashboard is showing built-in sample data, not your workspace's. …

يقول الموقع الشيء نفسه بكلماته. تحمل كل واجهة أمامية بيانات تجريبية مدمجة وتجيب منها في حالتين:

• «لا توجد واجهة برمجية متصلة»: بدأ التطبيق أو بُني وقيمة NEXT_PUBLIC_API_BASE_URL فارغة، أو من دون .env أصلًا. هكذا تعمل حزمة الواجهة الأمامية الواحدة وحدها. لاستخدام واجهة API، اضبطها في .env على عنوانها مع /api (http://localhost:8000/api، كما في .env.example)، ثم أعد تشغيل yarn dev أو ابنِ مرة أخرى؛ ومع Docker ابنِ من دون --build-arg NEXT_PUBLIC_API_BASE_URL=.
• «الواجهة البرمجية على … لا تستجيب»: عُيّن عنوان لكن المتصفح لا يصل إليه. واجهة API لا تعمل، أو تعمل على عنوان آخر، أو لا تدرج عنوان هذا التطبيق في CORS_ORIGIN (راجع المشكلة التالية). تحقق من أن localhost:8000/api/healthمحلي يجيب، ثم أعد تحميل الصفحة. يجرب التطبيق واجهة API مرة أخرى بنفسه.

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

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

يقول المتصفح «blocked by CORS policy»

Access to XMLHttpRequest at 'http://localhost:8000/api/…' from origin 'http://localhost:3041' has been blocked by CORS policy

تعرض وحدة تحكم المتصفح هذا السطر عندما تعمل واجهة أمامية على عنوان لا تقبله واجهة API. يُعدّ الطلب المرفوض كأن واجهة API لا تجيب، فتلجأ الواجهة الأمامية إلى بياناتها التجريبية في المتصفح: تعرض لوحة التحكم إشعار «بيانات تجريبية»، ويعرضه الموقع كذلك في yarn dev. تجيب واجهة API المتصفحات من العناوين الموجودة في CORS_ORIGIN فقط، وقيمتها الافتراضية http://localhost:3030 وhttp://localhost:3031. الموقع أو لوحة التحكم المنقولان إلى منفذ آخر، أو المقدَّمان على نطاقك الخاص، يُرفضان حتى تضيف عنوانيهما إلى القائمة.

CORS_ORIGIN=http://localhost:3030,http://localhost:3041
FRONTEND_URL=http://localhost:3041
DASHBOARD_URL=http://localhost:3041

• اكتب كل عنوان تمامًا كما يعرضه المتصفح، مع البروتوكول والمنفذ ومن دون شرطة مائلة في النهاية، مفصولة بفواصل. ثم أعد تشغيل واجهة API.
• FRONTEND_URL هو عنوان لوحة التحكم، وتتصل منه تحديثات الصلاحيات المباشرة الخاصة بها. وDASHBOARD_URL هو العنوان المكتوب في روابط الدعوة وإعادة الضبط. غيّر الاثنين مع لوحة التحكم، وغيّر WEBSITE_URL مع الموقع.
• لحاوية واجهة API، مرّر القيم نفسها باستخدام -e، مثل -e CORS_ORIGIN=http://localhost:3030,http://localhost:3041.
• مع الحزمة الكاملة في Docker لا تعدّل هذه القيم: تضبطها SITE_PORT وADMIN_PORT وSITE_URL وADMIN_URL في ملف .env بجوار docker-compose.yml.
• الواجهة الأمامية التي لا تصل إلى واجهة API إطلاقًا، لأنها متوقفة أو على عنوان آخر، تفشل بالطريقة نفسها من دون سطر CORS. تحقق من أن localhost:8000/api/healthمحلي يجيب، ومن أن NEXT_PUBLIC_API_BASE_URL في الواجهة الأمامية يشير إلى واجهة API تلك.

• انشرها

يتأخر تحميل إيصال الدفع في Docker

يقرأ خادم الموقع نفسه خيارات الدفع وإيصال الطلب أثناء عرض تلك الصفحات. داخل الحاوية يعني localhost الحاوية نفسها، لذلك لا يستطيع ذلك الخادم الوصول إلى واجهة API على جهازك عند http://localhost:8000. تكتمل الصفحات في المتصفح مع ذلك، لأنه يصل إلى واجهة API مباشرة.

شغّل حاوية الموقع مع عنوان واجهة API كما يراه الخادم:

docker run -p 3030:3030 -e API_INTERNAL_URL=http://host.docker.internal:8000/api --add-host=host.docker.internal:host-gateway northstack-website

تضبطه لك الحزمة الكاملة في Docker (http://api:8000/api). بدون Docker لا حاجة إليه.

لا تصل دعوة أو رسالة إعادة ضبط

لا يُرسَل أي بريد إلى أن تضبط SMTP_HOST في ملف .env الخاص بواجهة API. تذكر واجهة API ذلك عند بدء التشغيل، وتُكتب كل رسالة (الدعوات والملخصات الأسبوعية وإعادة ضبط بيانات الدخول وإيصالات التراخيص ورسائل الفوترة ورسائل التواصل المحوّلة) في سجلها بدلًا من ذلك، مع الروابط:

Mail is not set up (SMTP_HOST is empty): invitations, weekly digests, billing emails, password resets, licence receipts and forwarded contact messages are written to this log instead of being sent.
Message to …: …

• الحزمة الكاملة في Docker: شغّل docker compose logs api في مجلد الحزمة وافتح الرابط من أحدث رسالة.
• من دون Docker: اقرأ الرابط في الطرفية التي تشغّل yarn dev لواجهة API.
• حاوية واجهة API: استخدم docker logs مع معرّف الحاوية (يعرضه docker ps).
• لإرسال بريد حقيقي، اضبط SMTP_HOST وقيم SMTP_* الأخرى، ثم أعد تشغيل واجهة API. تُسجَّل الرسالة التي يرفضها الخادم بعبارة Could not send مع السبب.
• تدوم الدعوة سبعة أيام؛ وبعدها تقول صفحتها «انتهت صلاحية هذه الدعوة.» أرسل دعوة جديدة من صفحة الفريق.
• لا يصل بريد الفوترة (دفعة فاشلة، أو تجربة منتهية، أو تغيير خطة): يذهب إلى مالك مساحة العمل وأعضاء الفوترة وبريد الفوترة فقط، ولا يُرسل إلا ما دام إشعارات البريد مفعّلة في إعدادات مساحة العمل، قسم الإشعارات.
• لم يصل الملخص الأسبوعي بعد: يُرسَل أيام الاثنين من الساعة 08:00 بتوقيت UTC، ما دام الملخص الأسبوعي مفعّلًا. أول تشغيل في تثبيت جديد يحدد الأسبوع الحالي فقط، وأول ملخص لمساحة عمل جديدة يغطي أول أسبوع كامل لها.

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

عملية دفع تفتح صفحة الدفع التجريبية

يفتح مساران للدفع صفحة دفع تجريبية مدمجة ما دام لا مفاتيح لهما في واجهة API، ولا يحصّل أي منهما مبلغًا من أحد:

• تغيير الخطة في صفحة الفوترة بلوحة التحكم يفتح صفحة الدفع التجريبية «تأكيد خطة …» إلى أن تُضبط STRIPE_SECRET_KEY (أو دائمًا مع BILLING_PROVIDER=simulator). وعندها تقول إدارة وسيلة الدفع: «الدفع التجريبي لا يحفظ أي بطاقة، فلا توجد وسيلة دفع لإدارتها.»
• الدفع بالترخيص في الموقع يقول «وضع الاختبار: تمر المدفوعات عبر صفحة الدفع التجريبية لهذا الموقع ولا يُحصَّل أي مبلغ.» ويفتح صفحة الدفع التجريبية الخاصة به. تستخدم البطاقة Stripe بعد ضبط STRIPE_SECRET_KEY، ويستخدم PayPal بعد ضبط PAYPAL_CLIENT_ID وPAYPAL_CLIENT_SECRET.
• مفتاح اختبار Stripe يعرض «وضع الاختبار: لا تنتقل أي أموال حقيقية.» في صفحة Stripe، ادفع بالبطاقة 4242 4242 4242 4242 مع أي تاريخ قادم وأي رمز تحقق CVC.
• «جارٍ تأكيد الدفع...» أو إيصال يقول إن الدفع ما زال قيد التأكيد: تسأل واجهة API خدمة Stripe عن الجلسة بينما تنتظر الصفحة، وعلى الخادم يؤكدها الـ webhook عند /api/billing/webhooks/stripe فورًا. لا تتغير الخطة إلا بعد تأكيد الدفع.
• «انتهت صلاحية عملية الدفع. ابدأ من جديد من «تغيير الخطة».» جلسة دفع تُركت مفتوحة وقتًا طويلًا؛ ابدأ جلسة جديدة.
• تنجح مدفوعات Stripe لكن التجديدات أو الدفعات الفاشلة أو الإلغاءات لا تظهر على الخادم: القيمة STRIPE_WEBHOOK_SECRET فارغة أو خاطئة. يقول سجل واجهة API STRIPE_WEBHOOK_SECRET is empty عند بدء التشغيل، وتعرض لوحة Stripe كل إرسال مرفوضًا برمز 400. اضبطها على سر التوقيع الخاص بنقطة الـ webhook وأعد تشغيل واجهة API.

• إعدادات الدفع

أخطاء بعد التحديث

بعد تحديث الكود على قاعدة بيانات تحتفظ بها، قد تفشل الطلبات بسبب جدول أو عمود ناقص في سجل واجهة API، مثل no such column في SQLite أو Unknown column في MySQL. لا توجد migrations، وفي الإنتاج لا تغيّر واجهة API الجداول بنفسها أبدًا، لذلك حدّثها مرة واحدة لتطابق الكود الجديد. انسخ قاعدة البيانات احتياطيًا أولًا: يحذف التحديث أيضًا عمودًا لم يعد الكود يستخدمه.

yarn build
yarn schema:prod

مع Docker، شغّله داخل حاوية واجهة API العاملة: docker compose exec -u node api node dist/database/schema.js.

• التحديث

يرى الجميع «مغلق للصيانة.»

إعداد المنصة وضع الصيانة مفعّل. إلى أن يُطفأ، لا يستطيع استخدام لوحة التحكم إلا طاقم المنصة، وتجيب واجهة API الجميع بالرمز 503. في شاشة الصيانة اضغط دخول طاقم المنصة، وسجّل الدخول بحساب مسؤول المنصة، ثم أطفئ maintenance_mode من صفحة إعدادات المنصة. يستمر نموذج التواصل في الموقع والدفع بالترخيص في العمل خلال ذلك.

• إعدادات المنصة

تغيير ملف .env للواجهة الأمامية لا يُحدث أي أثر

كل قيمة NEXT_PUBLIC_* في ملف .env للموقع ولوحة التحكم تُدمج في JavaScript الذي يحمّله المتصفح عند بناء التطبيق، لذلك لا يغيّر تعديل الملف شيئًا حتى يُبنى التطبيق من جديد.

• مع `yarn dev`: أوقفه ثم شغّل yarn dev مرة أخرى.
• مع `yarn build` و`yarn start`: شغّل yarn build مرة أخرى.
• مع Docker Compose: ضع القيمة في ملف .env بجوار docker-compose.yml (المنافذ وSITE_URL وADMIN_URL وAPI_URL)، وليس في مجلد التطبيق، ثم شغّل docker compose up --build.
• لصورة تطبيق واحد: ابنِها مرة أخرى مع القيمة بصيغة --build-arg.

ملف .env الخاص بواجهة API يحتاج إلى إعادة تشغيل فقط. تُقرأ PORT للوحة التحكم وAPI_INTERNAL_URL للموقع عند بدء التطبيق.

المساعد يطلب مفتاحًا، أو مزوّد يرفض الطلب

Use your own API key
The server has no key for this provider. Add your own and the assistant works fully. …

يجيب المساعد باستخدام Google Gemini أو OpenAI أو DeepSeek، وليس في .env الخاص بواجهة API مفتاح مزوّد حتى تضيف واحدًا، فلا يُحاسَب أحد على شيء. تذكر واجهة API ذلك عند بدء التشغيل (No AI provider key is set)، ويفتح إرسال رسالة استخدم مفتاح API الخاص بك. أضف مفتاحك هناك، وهو يبقى في متصفحك ويُستخدم لطلباتك فقط، أو أعطِ الخادم مفتاحًا:

• أضف GOOGLE_API_KEY أو OPENAI_API_KEY أو DEEPSEEK_API_KEY إلى .env الخاص بواجهة API وأعد تشغيل واجهة API.
• مع Docker Compose، انسخ back-end/.env.example إلى back-end/.env أولًا، وأضف المفتاح، ثم شغّل docker compose up --build مرة أخرى.
• يُستخدم مفتاح القارئ نفسه قبل مفتاح الخادم، فيُحاسَب القارئ الذي أضاف مفتاحًا عليه حتى لو كان للخادم مفتاح.

… has no requests left on this API key right now. Pick a different model from the list above the chat, or try again in a few minutes.

يعني هذا الرد أن المزوّد رفض الطلب بسبب حدوده الخاصة. اختر نموذجًا آخر من القائمة، أو انتظر ثم اضغط حاول مرة أخرى. أي رفض آخر، مثل مفتاح لم يقبله المزوّد، يعرض رسالة المزوّد نفسها. وعلى البيانات التجريبية وحدها لا يجيب المساعد إطلاقًا: يقول إنه يحتاج إلى واجهة API.

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

في وضع العرض التجريبي يطلب المساعد مفتاح الزائر نفسه

يقول نموذج التواصل أو الدفع إن عليك المحاولة لاحقًا

You have sent several messages in the last hour. Try again later.
Too many attempts from this address. Try again in an hour.

يستطيع كل عنوان إرسال خمس رسائل تواصل وبدء عشر عمليات دفع بالترخيص في الساعة؛ ويسمح تسجيل الحساب في لوحة التحكم بعشر محاولات في الساعة، وطلبات إعادة ضبط بيانات الدخول بخمس خلال 15 دقيقة. تذكر إجابة 429 من واجهة API الإجراء ومدة الانتظار، مثل «Too many sign-ups from this address. Wait an hour, then try again.» انتظر، أو أعد تشغيل واجهة API أثناء الاختبار، لأن العدّادات محفوظة في ذاكرتها. خلف وكيل عكسي اضبط TRUST_PROXY=1 في .env الخاص بواجهة API، وإلا يتشارك كل الزوار حصة الوكيل الواحدة؛ والأمر نفسه ينطبق على حد تسجيل الدخول.

ترفض MySQL ملء البيانات

يُنشئ yarn seed مع DB_TYPE=mysql الجداول في قاعدة بيانات موجودة مسبقًا؛ ولا ينشئ القاعدة نفسها. تعني Seeding failed: متبوعة بـ Unknown database أنها غير موجودة، وتعني Access denied أن DB_USERNAME أو DB_PASSWORD خاطئ.

mysql -u root -p -e "CREATE DATABASE northstack"

ثم شغّل yarn seed مرة أخرى. صورة Docker تملأ SQLite فقط: مع MySQL شغّل node dist/database/seeder.js (أو node dist/database/create-admin.js للبدء فارغًا) مرة واحدة في حاوية واجهة API بالبيئة نفسها.

• استخدم MySQL بدلًا من ذلك

يفشل أمر فك الضغط أو يبدو المجلد مختلفًا

caution: filename not matched:  …zip

يعني هذا أن في المجلد ملفَّي ZIP للحزمة نفسها، مثل تنزيل أقدم بجانب الجديد، وأن العلامة * في unzip -q northstack-full-stack-*.zip طابقتهما معًا. احذف ملف ZIP الأقدم وشغّل الأمر مرة أخرى، أو اكتب اسم الملف كاملًا.

• إذا لم يكن unzip موجودًا، فك ضغط ملف ZIP في مدير الملفات. تضيف بعض الأدوات مجلدًا إضافيًا باسم ملف ZIP: ادخل إلى المجلد الداخلي.
• تُفك الحزمة الكاملة إلى northstack-full-stack، وفيه back-end وdashboard وwebsite وdocker-compose.yml.
• تُفك الحزم المنفردة إلى northstack-website وnorthstack-dashboard وnorthstack-backend، ولكل منها Dockerfile خاص به.

ابدأ من جديد ببيانات تجريبية جديدة

مع الحزمة الكاملة في Docker، في مجلد northstack-full-stack:

docker compose down -v
docker compose up

مع حاوية واجهة API وحدها، احذف الحاوية (docker rm -f مع اسمها)، ثم وحدة التخزين، وشغّلها مرة أخرى:

docker volume rm northstack-api-data
docker run -p 8000:8000 -v northstack-api-data:/data northstack-api

من دون Docker، أوقف واجهة API وشغّل هذا في مجلدها (في PowerShell: Remove-Item database.sqlite*; yarn seed):

rm -f database.sqlite* && yarn seed

على MySQL شغّل yarn reset (يفرغ كل الجداول)، ثم yarn seed.

تشغيل yarn seed على قاعدة بيانات تحتفظ بها ليس إعادة ضبط: فما دامت القاعدة فيها حسابات لا يضيف حسابًا ولا مساحة عمل، ويعيد فقط صلاحياتها إلى أدوار المنصة المدمجة.