استكشاف الأخطاء وإصلاحها

إذا واجهت أي مشكلة أثناء إعداد البيئة للتطوير، أو ترقية النسخة الخاصة بك، أو استضافتها ذاتيًا، إليك بعض الحلول للمشاكل الشائعة.

استضافة ذاتية

التثبيت الأولي ينتج عنه فشل المصادقة على كلمة المرور للمستخدم “بوستجريس”

🚨 هام: هذا الحل فقط للتثبيتات الجديدة 🚨 إذا كان لديك تطبيق Twenty موجود يحتوي على بيانات إنتاج، لا تتبع هذه الخطوات لأنها ستحذف قاعدة البيانات الخاصة بك بشكل دائم! أثناء تثبيت Twenty لأول مرة، قد ترغب في تغيير كلمة المرور الافتراضية لقاعدة البيانات. كلمة المرور التي تعيّنها أثناء التثبيت الأول يتم تخزينها بشكل دائم في حجم قاعدة البيانات. إذا حاولت لاحقًا تغيير هذه الكلمة في التكوين بدون إزالة الحجم القديم، ستحصل على أخطاء المصادقة لأن قاعدة البيانات لا تزال تستخدم كلمة المرور الأصلية. ⚠️ تحذير: اتباع الخطوات التالية سيقوم بحذف جميع بيانات قاعدة البيانات بشكل دائم! ⚠️ قم بالإجراء فقط إذا كان هذا تثبيتًا جديدًا بدون بيانات مهمة. لتحديث `PG_DATABASE_PASSWORD’، تحتاج إلى:

# Update the PG_DATABASE_PASSWORD in .env
docker compose down --volumes
docker compose up -d

تم العثور على فواصل الخط CR [نظام Windows]

يحدث هذا بسبب أحرف Windows التي تنتهي خط مع تكوين Git الخاص بك. حاول تشغيل:

git config --global core.autocrlf false

ثم قم بحذف المستودع واستنساخه مرة أخرى.

مخطط البيانات الوصفية مفقود

أثناء تثبيت Twenty، تحتاج إلى توفير قاعدة بيانات بوستجريس الخاصة بك بالمخططات والإضافات والمستخدمين الصحيحة. إذا نجح تشغيل هذا التخصيص، يجب أن تحتوي قاعدة البيانات لديك على المخططات default وmetadata. إذا لم تقم بذلك، تأكد من أنه ليس لديك أكثر من مثيل بوستغريس QL يعمل على جهاز الكمبيوتر الخاص بك.

لا يمكن العثور على الوحدة النمطية ‘twenty-emails’ أو إعلانات نوعها المقابلة.

يجب عليك بناء حزمة ‘20 البريد الإلكتروني’ (npx nx run 20 emails:build’) قبل تشغيل تهيئة قاعدة البيانات.

حزمة twenty-x مفقودة

تأكد من تشغيل yarn في الدليل الجذر ثم تشغيل npx nx server:dev twenty-server. إذا لم يعمل ذلك، حاول بناء الحزمة المفقودة يدوياً.

التحقق من العمليات عند الحفظ لا يعمل

هذا يجب أن يعمل تلقائيًا مع تثبيت إضافة Oxc (oxc.oxc-vscode). إذا كان هذا لا يعمل، حاول إضافة هذا إلى إعدادات رمز VS الخاص بك (نطاق حاوية dev):

"editor.codeActionsOnSave": {

  "source.fixAll.oxc": "explicit"

}

أثناء تشغيل `npx nx start` أو `npx nx start 20 front`، يتم إلقاء خطأ خارج الذاكرة

تشغيل الخدمات التي تحتاجها فقط، بدلاً من ‘npx nx start. على سبيل المثال، إذا كنت تعمل على الخادم، قم بتشغيل npx nx worker twenty-server` فقط إذا لم يعمل ذلك: إذا حاولت تشغيل npx nx run twenty-server:start فقط على WSL وفشل مع خطأ الذاكرة أدناه: FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory يتم تشغيل الأمر التالي في المحطة الطرفية الخاصة بك، أو إضافته إلى الملف الشخصي .bashrc الخاص بك بحيث يتم تطبيقه تلقائياً: export NODE_OPTIONS="--max-old-space-size=8192" علامة —max-old-space-size=8192 تحدد حداً أقصى للذاكرة الخاصة بـ Node.js بحد أقصى 8GB؛ الاستخدام يتزايد بطلبات التطبيق. المرجع: https://stackoverflow.com/questions/56982005/where-do-i-set-node-options-max-old-space-size-2048 إذا لم يعمل ذلك: تحقق من العمليات التي تستهلك معظم ذاكرة الوصول العشوائي (RAM) في جهازك. في العشرين، لاحظنا بعض ملحقات رمز VS كانت تأخذ الكثير من ذاكرة الوصول العشوائي، لذلك قمنا بتعطيلها مؤقتاً. إذا كان لا يعمل: إعادة تشغيل جهازك يساعد على تنظيف عمليات الشبح.

أثناء تشغيل `npx nx start` تظهر سجلات غريبة [0] و [1]

هذا متوقع حيث أن الأمر npx nx start يقوم بتشغيل المزيد من الأوامر خلف الكواليس

لا يتم إرسال الرسائل الإلكترونية

غالبًا، يكون السبب هو أن “العامل” لا يعمل في الخلفية. حاول التشغيل

npx nx worker twenty-server

لا يمكن ربط حساب مايكروسوفت 365 بـ 20

غالبًا، يكون السبب في ذلك هو أن المسؤول الخاص بك لم يقم بتمكين رخصة Microsoft 365 لحسابك. تحقق من https://admin.microsoft.com/. إذا تلقيت رمز الخطأ AADSTS50020، فهذا يعني أنه ربما تستخدم حساب Microsoft شخصي. هذا غير مدعوم حتى الآن. المزيد من المعلومات هنا

أثناء تشغيل “yarn”، تظهر التحذيرات في وحدة التحكم

التحذيرات تخبر عن سحب تبعيات إضافية ليست مذكورة صراحة في package.json، طالما لم تظهر أي أخطاء تكسر العمل، ينبغي أن يعمل كل شيء كما هو متوقع.

عندما يصل مستخدم إلى صفحة تسجيل الدخول، يظهر خطأ حول مستخدم غير مصرح له يحاول الوصول إلى مساحة عمل في السجلات

هذا متوقع لأن المستخدم غير مصرح به عند تسجيل الخروج، لأنه لم يتم التحقق من هويته.

كيف يمكنك التأكد من عمل العامل الخاص بك؟

اذهب إلى webhook-test.com ونسخ عنوان URL الخاص بك.

افتح تطبيق Twenty الخاص بك، انتقل إلى /settings، وفعل التبديل المتقدم في الجزء السفلي الأيسر من الشاشة.
إنشاء ويب هوك جديد.
الصق عنوان URL الفريد لخطّاف الويب الخاص بك في الحقل عنوان URL لنقطة النهاية في Twenty. اضبط عوامل التصفية على Companies وCreated.

انتقل إلى /objects/companies وأنشئ سجلاً جديدًا للشركة.
ارجع إلى webhook-test.com وتحقق مما إذا كانت هناك طلب POST جديد تم استلامه.

إذا تم استلام طلب POST، فهذا يعني أن العامل يعمل بنجاح. وإلا، ستحتاج إلى استكشاف الأخطاء وإصلاحها لعامل التشغيل الخاص بك.

فشل في بدء و إرجاع الخطأ TS5042: الخيار ‘مشروع’ لا يمكن خلطه مع ملفات المصدر على سطر الأوامر

قم بالتعليق على المكون الإضافي الخاص بالمدقق في packages/٢ui/vite-config.ts، كما هو مبين في المثال أدناه:

plugins: [
      react({ jsxImportSource: 'react' }),
      tsconfigPaths(),
      svgr(),
      dts(dtsConfig),
      // checker(checkersConfig),
      wyw({
        include: [
          '**/OverflowingTextWithTooltip.tsx',
          '**/Chip.tsx',
          '**/Tag.tsx',
          '**/Avatar.tsx',
          '**/AvatarChip.tsx',
        ],
        babelOptions: {
          presets: ['@babel/preset-typescript', '@babel/preset-react'],
        },
      }),
    ],

لوحة الإدارة غير قابلة للوصول

تشغيل ‘UPDATE core.”user” مجموعة “canAccessFullAdminPanel” = TRUE WHERE البريد الإلكتروني = ‘you@yourdomain.com’؛ في حاوية قاعدة البيانات للحصول على الوصول إلى لوحة المسؤول.

عند تشغيل سير العمل، يفشل تشغيل سير العمل مع الرسالة “تم تعطيل تنفيذ دوال المنطق. عيّن LOGIC_FUNCTION_TYPE إلى LOCAL أو LAMBDA لتمكين ذلك.”

في بيئة الإنتاج، يتم تعطيل دوال المنطق افتراضيًا. قم بتعيين متغير البيئة LOGIC_FUNCTION_TYPE إلى LOCAL أو LAMBDA لتمكينها. يمكن تكوين ذلك عبر متغيرات البيئة أو من خلال متغيرات قاعدة البيانات في لوحة الإدارة. راجع دليل إعداد دوال المنطق للحصول على التفاصيل.

عندما أكتب رسالة في دردشة الذكاء الاصطناعي ، فإنها لا تجيب على الفور ويجب علي تحديث الصفحة لمشاهدة الإجابة

هذا يعني أن البروكسي العكسي الخاص بك يفتقر إلى التهيئة لاستجابات API القائمة على البث. فيما يلي مثال على تكوين Nginx:

location ~* ^/api/.*stream|\/graphql\/stream {
proxy_pass http://twenty_backend;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering off;
proxy_request_buffering off;
proxy_cache off;
gzip off;
#chunked_transfer_encoding off;
add_header X-Accel-Buffering no always;
}

إنشاء Docker بنقرة واحدة

غير قادر على تسجيل الدخول

إذا كنت لا تستطيع تسجيل الدخول بعد الإعداد:

قم بتشغيل الأوامر التالية:

docker exec -it twenty-server-1 yarn
docker exec -it twenty-server-1 npx nx database:reset  --configuration=no-seed

إعادة تشغيل حاويات Docker:

docker compose down
docker compose up -d

لاحظ أن أمر “قاعدة البيانات: إعادة الضبط” سيمسح قاعدة البيانات الخاصة بك بالكامل وسيعيد إنشاءها من الصفر.

مشاكل الاتصال خلف بروكسي عكسي

إذا كنت تستخدم Twenty خلف بروكسي عكسي وواجهت مشاكل في الاتصال:

تأكد من SERVER_URL: تأكد من أن SERVER_URL في ملف .env يتطابق مع عنوان الوصول الخارجي الخاص بك، بما في ذلك https إذا كان SSL مفعلاً.
التحقق من إعدادات البروكسي العكسي:
- تأكد من أن البروكسي العكسي يقوم بتمرير الطلبات بشكل صحيح إلى خادم Twenty.
- تأكد من أن رؤوس مثل X-Forwarded-For وX-Forwarded-Proto تم ضبطها بشكل صحيح.
إعادة تشغيل الخدمات: بعد إجراء التغييرات، أعد تشغيل كل من البروكسي العكسي وحاويات Twenty.

خطأ عند تحميل صورة - تم رفض الإذن

تغيير ملكية مجلد البيانات على المضيف من الجذر إلى مستخدم ومجموعة آخرين يحل هذه المشكلة.

خطأ “لم يتم العثور على الملف” أثناء اختبار دالة Logic في سير العمل.

شغّل الأمر yarn command:prod application:rebuild-default-deps في حاوية twenty-server لديك لإصلاح مشكلة التبعيات المفقودة.

الحصول على المساعدة

إذا واجهت مشكلات لم يتم تغطيتها في هذا الدليل:

تفقد السجلات: اعرض سجلات الحاوية للرسائل الخطأ:
docker compose logs
الدعم المجتمعي: تواصل مع مجتمع Twenty أو قنوات الدعم للحصول على المساعدة.

⌘I

نظرة عامة

التطبيقات

واجهة برمجة التطبيقات

الاستضافة الذاتية

المساهمة

استكشاف الأخطاء وإصلاحها