إعداد - Twenty Documentation

نظرة عامة

هل هي المرة الأولى التي تقوم فيها بالتثبيت؟ اتبع دليل تثبيت Docker Compose لتشغيل Twenty، ثم عد هنا للإعداد.

يوفر Twenty وضعين للإعداد ليلائم احتياجات النشر المختلفة: الوصول إلى لوحة الإدارة: يمكن للمستخدمين الذين لديهم صلاحيات المسؤول (canAccessFullAdminPanel: true) فقط الوصول إلى واجهة التكوين.

1. إعداد لوحة الإدارة (افتراضي)

IS_CONFIG_VARIABLES_IN_DB_ENABLED=true  # default

يحدث أغلب التكوين عبر واجهة المستخدم بعد التثبيت:

الوصول إلى نسخة Twenty الخاصة بك (عادة http://localhost:3000)
اذهب إلى الإعدادات / لوحة الإدارة / متغيرات التكوين
اضبط التكاملات، والبريد الإلكتروني، والتخزين، والمزيد
تسري التغييرات على الفور (خلال 15 ثانية لعمليات النشر متعددة الحاويات)

نشرات متعددة الحاويات: عند استخدام إعدادات قاعدة البيانات (IS_CONFIG_VARIABLES_IN_DB_ENABLED=true)، يقوم كل من حاويات الخادم والعامل بالقراءة من نفس قاعدة البيانات. التغييرات في لوحة الإدارة تؤثر عليهما تلقائيًا، مما يلغي الحاجة إلى تكرار متغيرات البيئة بين الحاويات (باستثناء متغيرات البنية التحتية).

ما يمكنك تكوينه عبر لوحة الإدارة:

المصادقة - Google/Microsoft OAuth، إعدادات كلمة المرور
البريد الإلكتروني - إعدادات SMTP، القوالب، التحقق
التخزين - تكوين S3، مسارات التخزين المحلية
التكاملات - Gmail، تقويم Google، خدمات Microsoft
حدود التشغيل ومعدل التكنولوجيا - حدود التنفيذ، API الحد من السرعة
والمزيد من الأمور…

كل متغير موثق بوصف في لوحة الإدارة الخاصة بك في الإعدادات → لوحة الإدارة → متغيرات التكوين. بعض إعدادات البنية التحتية مثل اتصالات قاعدة البيانات (PG_DATABASE_URL)، عناوين الخوادم (SERVER_URL)، والأسرار (ENCRYPTION_KEY, FALLBACK_ENCRYPTION_KEY) يمكن ضبطها فقط عبر ملف .env.مرجع تقني كامل →

مفاتيح التشفير

تستخدم Twenty مفتاحَي تشفير يحددان حصراً عبر متغيرات البيئة:

المتغيّر	الغرض	مطلوب
`ENCRYPTION_KEY`	المفتاح الأساسي المستخدم لتشفير الأسرار أثناء التخزين (رموز OAuth، متغيرات التطبيق، المفاتيح الخاصة لمفاتيح التوقيع، أسرار TOTP، قيم الإعدادات الحساسة).	نعم في عمليات التثبيت الجديدة (قد تعتمد عمليات التثبيت القديمة بدلاً من ذلك على `APP_SECRET` — انظر أدناه)
`FALLBACK_ENCRYPTION_KEY`	مفتاح مخصص للتحقق فقط. يتم تعيينه أثناء التدوير ليكون `ENCRYPTION_KEY` السابق حتى تظل الصفوف الحالية قابلة لفك التشفير.	فقط أثناء التدوير

لضمان التوافق مع الإصدارات السابقة، إذا لم يتم تعيين ENCRYPTION_KEY، فإن Twenty تستخدم APP_SECRET كبديل لتشفير البيانات أثناء التخزين — بما يطابق سلوك الإصدارات القديمة في عمليات النشر الأقدم. يجب على عمليات التثبيت الجديدة دائماً تعيين قيمة مخصصة لـ ENCRYPTION_KEY. قم بإنشاء القيم باستخدام الأمر openssl rand -base64 32 وخزنها في مكان آمن (مثل مدير الأسرار، إعدادات مُشفَّرة، إلخ). فقدان ENCRYPTION_KEY يعني فقدان الوصول إلى كل سر مخزن في قاعدة البيانات. لتدوير ENCRYPTION_KEY بدون وقت توقف، راجع دليل تدوير المفاتيح.

2. إعداد بيئي فقط

IS_CONFIG_VARIABLES_IN_DB_ENABLED=false

جميع الإعدادات تتم إدارتها عبر ملفات .env:

قم بتعيين IS_CONFIG_VARIABLES_IN_DB_ENABLED=false في ملف .env الخاص بك
أضف جميع متغيرات الإعداد إلى ملف .env الخاص بك
أعد تشغيل الحاويات لتصبح التغييرات نافذة
ستظهر لوحة الإدارة القيم الحالية لكنها لن تتمكن من تعديلها

وضع تعدد مساحات العمل

افتراضيًا، تعمل Twenty في وضع مساحة عمل واحدة — وهو مثالي لمعظم عمليات النشر المستضافة ذاتيًا حيث تحتاج إلى مثيل واحد من نظام إدارة علاقات العملاء لمؤسستك.

وضع مساحة العمل الواحدة (الافتراضي)

IS_MULTIWORKSPACE_ENABLED=false  # default

مساحة عمل واحدة لكل مثيل من Twenty
أول مستخدم يصبح تلقائيًا مشرفًا مع صلاحيات كاملة (canImpersonate وcanAccessFullAdminPanel)
يتم تعطيل عمليات التسجيل الجديدة بعد إنشاء مساحة العمل الأولى
بنية URL بسيطة: https://your-domain.com

تمكين وضع تعدد مساحات العمل

IS_MULTIWORKSPACE_ENABLED=true
DEFAULT_SUBDOMAIN=app  # default value

قم بتمكين وضع تعدد مساحات العمل لعمليات النشر المشابهة لـ SaaS حيث تحتاج عدة فرق مستقلة إلى مساحات عمل خاصة بها على نفس مثيل Twenty. الاختلافات الرئيسية مقارنة بوضع مساحة العمل الواحدة:

يمكن إنشاء مساحات عمل متعددة على نفس المثيل
تحصل كل مساحة عمل على نطاق فرعي خاص بها (مثل: sales.your-domain.com، marketing.your-domain.com)
يسجل المستخدمون ويقومون بتسجيل الدخول عبر {DEFAULT_SUBDOMAIN}.your-domain.com (مثل: app.your-domain.com)
لا توجد صلاحيات مشرف تلقائية — أول مستخدم في كل مساحة عمل يكون مستخدمًا عاديًا
إعدادات خاصة بمساحة العمل مثل النطاق الفرعي والنطاق المخصص تصبح متاحة ضمن إعدادات مساحة العمل

إعداد خاص بالبيئة فقط: لا يمكن تكوين IS_MULTIWORKSPACE_ENABLED إلا عبر ملف .env ويتطلب إعادة تشغيل. لا يمكن تغييره عبر لوحة الإدارة.

تكوين DNS لوضع تعدد مساحات العمل

عند استخدام وضع تعدد مساحات العمل، قم بتكوين DNS لديك بسجل wildcard للسماح بإنشاء النطاقات الفرعية ديناميكيًا:

*.your-domain.com -> your-server-ip

يُمكّن هذا توجيه النطاقات الفرعية تلقائيًا لمساحات العمل الجديدة دون تكوين DNS يدوي.

تقييد إنشاء مساحات العمل

في وضع تعدد مساحات العمل، قد ترغب في تقييد من يمكنه إنشاء مساحات عمل جديدة:

IS_WORKSPACE_CREATION_LIMITED_TO_SERVER_ADMINS=true

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

تكامل Gmail و Google Calendar

إنشاء مشروع Google Cloud

اذهب إلى وحدة تحكم السحابة من Google
أنشئ مشروعًا جديدًا أو اختر أحد المشاريع الموجودة
قم بتفعيل هذه الـ APIs:

تكوين OAuth

اذهب إلى بيانات اعتماد
قم بإنشاء معرف عميل OAuth 2.0
أضف هذه الـ URIs لإعادة التوجيه:
- https://{your-domain}/auth/google/redirect (لتسجيل الدخول الفردي)
- https://{your-domain}/auth/google-apis/get-access-token (للتكاملات)

الإعداد في Twenty

اذهب إلى الإعدادات → لوحة الإدارة → متغيرات التكوين
ابحث بسهولة عن قسم Google Auth
حدد هذه المتغيرات:
- MESSAGING_PROVIDER_GMAIL_ENABLED=true
- CALENDAR_PROVIDER_GOOGLE_ENABLED=true
- AUTH_GOOGLE_CLIENT_ID={client-id}
- AUTH_GOOGLE_CLIENT_SECRET={client-secret}
- AUTH_GOOGLE_CALLBACK_URL=https://{your-domain}/auth/google/redirect
- AUTH_GOOGLE_APIS_CALLBACK_URL=https://{your-domain}/auth/google-apis/get-access-token

وضع بيئي فقط: إذا كنت قد ضبطت IS_CONFIG_VARIABLES_IN_DB_ENABLED=false، فأضف هذه المتغيرات إلى ملف .env الخاص بك بدلاً من ذلك.

النطاقات المطلوبة (يتم تكوينها تلقائيًا): انظر الشيفرة المصدرية ذات الصلة

https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/profile.emails.read

إذا كان تطبيقك في وضع الاختبار

إذا كان تطبيقك في وضع الاختبار، ستحتاج إلى إضافة مستخدمين اختباريين إلى مشروعك. تحت شاشة موافقة OAuth، أضف مستخدمي الاختبار إلى قسم “مستخدمو الاختبار”.

تكامل Microsoft 365

يجب على المستخدمين الحصول على ترخيص Microsoft 365 ليتمكنوا من استخدام تقويم API ورسائل. لن يتمكنوا من مزامنة حسابهم في Twenty دون واحد منها.

إنشاء مشروع في Microsoft Azure

ستحتاج إلى إنشاء مشروع في Microsoft Azure والحصول على بيانات الاعتماد.

تمكين APIs

على وحدة تحكم Microsoft Azure، قم بتمكين الواجهات التالية في “أذونات”:

Microsoft Graph: Mail.ReadWrite
Microsoft Graph: Mail.Send
Microsoft Graph: قراءة التقويمات وكتابتها (Calendars.ReadWrite)
Microsoft Graph: User.Read
Microsoft Graph: openid
Microsoft Graph: email
Microsoft Graph: profile
Microsoft Graph: offline_access

كل هذه الأذونات مطلوبة، حتى إذا كنت تريد مزامنة رسائل البريد الإلكتروني وأحداث التقويم فقط. يطلب Twenty دائمًا “Mail.ReadWrite” و”Mail.Send” و”Calendars.ReadWrite” عندما يربط المستخدم حسابه، لذا فإن أذونات القراءة فقط مثل “Mail.Read” أو “Calendars.Read” غير كافية.

إذا كان المستأجر الخاص بك لا يسمح للمستخدمين العاديين بالموافقة على هذه الأذونات، فسيظهر لهم الخطأ AADSTS90094 عند ربط حسابهم. يمكن للمسؤول إصلاح ذلك بالنقر فوق “Grant admin consent for ” في صفحة “API permissions” الخاصة بتسجيل التطبيق.

URIs لإعادة التوجيه المصرح بها

ستحتاج إلى إضافة URIs التالية لإعادة التوجيه إلى مشروعك:

https://{your-domain}/auth/microsoft/redirect إذا كنت تريد استخدام تسجيل الدخول الفردي في Microsoft
https://{your-domain}/auth/microsoft-apis/get-access-token

الإعداد في Twenty

اذهب إلى الإعدادات → لوحة الإدارة → متغيرات التكوين
ابحث عن قسم Microsoft Auth
حدد هذه المتغيرات:
- MESSAGING_PROVIDER_MICROSOFT_ENABLED=true
- CALENDAR_PROVIDER_MICROSOFT_ENABLED=true
- AUTH_MICROSOFT_ENABLED=true
- AUTH_MICROSOFT_CLIENT_ID={client-id}
- AUTH_MICROSOFT_CLIENT_SECRET={client-secret}
- AUTH_MICROSOFT_CALLBACK_URL=https://{your-domain}/auth/microsoft/redirect
- AUTH_MICROSOFT_APIS_CALLBACK_URL=https://{your-domain}/auth/microsoft-apis/get-access-token

وضع بيئي فقط: إذا كنت قد ضبطت IS_CONFIG_VARIABLES_IN_DB_ENABLED=false، فأضف هذه المتغيرات إلى ملف .env الخاص بك بدلاً من ذلك.

تكوين النطاقات

انظر الشيفرة المصدرية ذات الصلة

‘openid’
‘البريد الإلكتروني’
‘profile’
‘offline_access’
‘Mail.ReadWrite’
‘Mail.Send’
‘Calendars.ReadWrite’
‘User.Read’

إذا كان تطبيقك في وضع الاختبار

إذا كان تطبيقك في وضع الاختبار، ستحتاج إلى إضافة مستخدمين اختباريين إلى مشروعك. أضف مستخدمي الاختبار إلى قسم “المستخدمون والمجموعات”.

مهام الخلفية للتقويم والمراسلة

بعد إعداد تكامل Gmail، أو Google Calendar، أو Microsoft 365، تحتاج إلى بدء وظائف الخلفية التي تقوم بمزامنة البيانات. سجل الوظائف المتكررة التالية في حاوية العمل الخاصة بك:

# from your worker container
yarn command:prod cron:messaging:messages-import
yarn command:prod cron:messaging:message-list-fetch
yarn command:prod cron:calendar:calendar-event-list-fetch
yarn command:prod cron:calendar:calendar-events-import
yarn command:prod cron:messaging:ongoing-stale
yarn command:prod cron:calendar:ongoing-stale
yarn command:prod cron:workflow:automated-cron-trigger

حدود ذاكرة قائمة انتظار المهام

يعمل Redis الخاص بقائمة الانتظار باستخدام noeviction: وبمجرد امتلائه، تفشل كل عملية إدراج في قائمة الانتظار لكل مساحة عمل. لمنع مساحة عمل أو تطبيق واحد من ملئها، يجوز لكل منهما استخدام حصة من الذاكرة التي يتركها الآخرون خالية، ويُحدد حجم كل مهمة بحد أقصى.

المتغيّر	الإعداد الافتراضي	ماذا يفعل
`IS_REDIS_MEMORY_FAIRNESS_ENABLED`	`خاطئ`	ارفض المهام التي تتجاوز حد الحجم أو حصتها.
`JOB_QUEUE_MAX_JOB_SIZE_BYTES`	`5242880`	أكبر مهمة متسلسلة مقبولة.
`JOB_QUEUE_MEMORY_SHARE_BY_WORKSPACE_ID`	`0.3`	حصة الذاكرة الحرة التي يمكن لمساحة عمل واحدة الاحتفاظ بها.
`JOB_QUEUE_MEMORY_SHARE_BY_APPLICATION_UNIVERSAL_IDENTIFIER`	`0.4`	حصة الذاكرة الحرة التي يمكن لتطبيق واحد الاحتفاظ بها، عبر جميع مساحات العمل.
`JOB_QUEUE_MEMORY_RESERVE`	`0.1`	حصة من `maxmemory` لا تُمنح للمهام مطلقًا.

يتطلب حد الحصة ضبط maxmemory على Redis الخاص بقائمة الانتظار. تُسجَّل حالات الرفض وتُحتسب في job_memory_limit_refused_total حسب قائمة الانتظار واسم المهمة والسبب، ويتتبع twenty_queue_memory_used_ratio استخدام الذاكرة. إذا كان موفر الخدمة لديك يحجز جزءًا من maxmemory (على سبيل المثال reserved-memory-percent في ElastiCache)، فأدرجه في JOB_QUEUE_MEMORY_RESERVE ما لم يكن maxmemory يستثنيه بالفعل. تُحتسب تكلفة المهمة حتى تكتمل أو تفشل نهائيًا، ولا تنتهي صلاحية التكاليف. تحتفظ المهمة التي تُزال من قائمة انتظار خارج العامل (حذف من لوحة الإدارة، تنظيف قائمة الانتظار) بتكلفتها إلى أن تشغّل yarn command:prod job-memory:reconcile. يحرر الأمر رسوم كل مهمة تم إلغاؤها أو انتهت، مع التحقق مرتين بفاصل بضع ثوانٍ (--grace-seconds، القيمة الافتراضية 10) حتى لا يتم تحرير مهمة قيد الإدراج في قائمة الانتظار عن طريق الخطأ.

الاتصالات الصادرة إلى المضيفين الداخليين

بشكل افتراضي، يرفض Twenty الاتصالات الصادرة إلى عناوين IP الخاصة/الداخلية (حماية SSRF). يشمل ذلك إجراءات سير عمل HTTP، وخطافات الويب، وموفري الهوية لـ SSO، واتصالات IMAP/SMTP/CalDAV. إذا كان موفر الهوية أو خادم البريد أو التقويم لديك يعمل على شبكة خاصة، فأدرج اسم مضيفه أو عنوان IP حرفيًا:

OUTBOUND_HTTP_ALLOWED_INTERNAL_HOSTS=keycloak,mail.internal,192.168.1.10

تتم مطابقة الإدخالات بناءً على اسم المضيف فقط، من دون أحرف بدل: بالنسبة إلى مُصدر OIDC مثل http://keycloak:8080/realms/twenty، أدرج keycloak. تظل جميع العناوين الخاصة الأخرى محظورة، وحتى المضيف المسموح له لا يمكنه أبدًا الوصول إلى نطاق عناوين البيانات الوصفية للسحابة. عيّن المتغير إلى * لتعطيل الحماية بالكامل، وهذا مناسب فقط على الشبكات الموثوقة والمعزولة. OUTBOUND_HTTP_SAFE_MODE_ENABLED مهمل. أثناء تعيينه إلى false، تظل الحماية معطلة بالكامل ويتم تجاهل OUTBOUND_HTTP_ALLOWED_INTERNAL_HOSTS، لذا أزِله عند الترحيل إلى القائمة. لا تغطي هذه القائمة مرفقات ملفات الذكاء الاصطناعي: تصل الصور وملفات PDF إلى النموذج كروابط مُنشأة من SERVER_URL، يجلبها إما موفر الذكاء الاصطناعي أو AI SDK في العامل، الذي يرفض العناوين الخاصة. لكي تعمل المرفقات، يجب أن يكون SERVER_URL عامًا؛ عند استخدام localhost أو SERVER_URL خاص، تعمل محادثات ووكلاء الذكاء الاصطناعي مع النص فقط.

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

اذهب إلى الإعدادات → لوحة الإدارة → متغيرات التكوين
ابحث عن قسم Email
قم بضبط إعدادات SMTP الخاصة بك:

جيميل
أوفيس 365
smtp4dev

ستحتاج إلى توفير كلمة مرور التطبيق.

EMAIL_DRIVER=smtp
EMAIL_SMTP_HOST=smtp.gmail.com
EMAIL_SMTP_PORT=465
EMAIL_SMTP_USER=gmail_email_address
EMAIL_SMTP_PASSWORD=‘gmail_app_password’

smtp4dev هو خادم بريد إلكتروني مزيف للتطوير والاختبار.

قم بتشغيل صورة smtp4dev: docker run --rm -it -p 8090:80 -p 2525:25 rnwood/smtp4dev
الوصول إلى واجهة المستخدم smtp4dev هنا: http://localhost:8090
حدد المتغيرات التالية:
- EMAIL_DRIVER=smtp
- EMAIL_SMTP_HOST=localhost
- EMAIL_SMTP_PORT=2525

وضع بيئي فقط: إذا كنت قد ضبطت IS_CONFIG_VARIABLES_IN_DB_ENABLED=false، فأضف هذه المتغيرات إلى ملف .env الخاص بك بدلاً من ذلك.

تخزين S3

افتراضياً، تقوم Twenty بتخزين الملفات المرفوعة على نظام الملفات المحلي. بالنسبة لعمليات النشر في بيئة الإنتاج، استخدم S3 أو خدمة متوافقة مع S3 (MinIO، DigitalOcean Spaces، إلخ) لضمان بقاء الملفات عبر إعادة تشغيل الحاويات وإتاحة التوسّع عبر مثيلات خوادم متعددة.

عيّن STORAGE_TYPE=S_3 وقم بتهيئة متغيرات STORAGE_S3_* من خلال لوحة الإدارة أو .env.

المتغيّر	مطلوب	الوصف
`STORAGE_S3_REGION`	نعم	منطقة الحاوية: منطقة AWS مثل `eu-west-3`، أو معرّف خاص بموفر الخدمة مثل `fr-par` لـ Scaleway.
`STORAGE_S3_NAME`	نعم	اسم الحاوية.
`STORAGE_S3_ACCESS_KEY_ID`	لا	مفتاح الوصول لمستخدم IAM. اتركه غير محدد لاستخدام سلسلة بيانات الاعتماد الافتراضية لـ AWS (راجع بيانات الاعتماد).
`STORAGE_S3_SECRET_ACCESS_KEY`	لا	السر الخاص بمفتاح الوصول أعلاه. مطلوب عند تعيين `STORAGE_S3_ACCESS_KEY_ID`.
`STORAGE_S3_ENDPOINT`	لا	عنوان URL مخصص للواجهة النهائية. فقط للخدمات المتوافقة مع S3 مثل `http://minio:9000`، أو لواجهة VPC نهائية من AWS. اتركه غير محدد لخدمة AWS S3 الأصلية، حيث تستنتج SDK الواجهة النهائية من المنطقة.
`STORAGE_S3_PRESIGNED_URL_ENABLED`	لا	عندما تكون القيمة `true`، تُعاد توجيه التنزيلات إلى عناوين URL موقعة مسبقًا، وتُحمّل المتصفحات الملفات مباشرةً إلى الحاوية بدلًا من مرورها عبر الخادم. القيمة الافتراضية هي `false`.
`STORAGE_S3_PRESIGNED_URL_BASE`	لا	واجهة نهائية عامة لاستخدامها في عناوين URL الموقعة مسبقًا عندما يكون `STORAGE_S3_ENDPOINT` عنوانًا داخليًا لا تستطيع المتصفحات الوصول إليه، مثل MinIO داخل Docker.
`STORAGE_S3_PRESIGNED_URL_EXPIRES_IN`	لا	مدة صلاحية عناوين URL الموقعة مسبقًا بالثواني. القيمة الافتراضية هي `900`.

ملف .env بسيط لـ AWS S3 مع مستخدم IAM:

STORAGE_TYPE=S_3
STORAGE_S3_REGION=eu-west-3
STORAGE_S3_NAME=my-twenty-bucket
STORAGE_S3_ACCESS_KEY_ID=AKIA...
STORAGE_S3_SECRET_ACCESS_KEY=...

يُمرّر ملف Docker Compose المتغيرات STORAGE_TYPE وSTORAGE_S3_REGION وSTORAGE_S3_NAME وSTORAGE_S3_ENDPOINT ومتغيرَي بيانات الاعتماد من .env. عيّن متغيرات عنوان URL الموقّع مسبقًا في لوحة الإدارة، أو أضفها إلى كتلة environment لخدمتَي server وworker.

بيانات الاعتماد

عندما يكون STORAGE_S3_ACCESS_KEY_ID غير محدد، يحل الخادم بيانات الاعتماد عبر السلسلة الافتراضية لـ AWS SDK: متغيرا البيئة AWS_ACCESS_KEY_ID وAWS_SECRET_ACCESS_KEY، أو ملف بيانات اعتماد مشترك، أو دور مهمة ECS، أو دور حساب خدمة EKS ‏(IRSA)، أو ملف تعريف مثيل EC2.

ملفات تعريف مثيلات EC2 وDocker: تُقدَّم بيانات ملف تعريف المثيل من خلال خدمة بيانات تعريف المثيل، وتكون الحاوية الموجودة على شبكة الجسر الافتراضية لـ Docker على بُعد قفزة شبكة إضافية منها مقارنةً بالمضيف. مع حد القفزات الافتراضي لـ IMDSv2 البالغ 1، لا تتلقى الحاوية بيانات الاعتماد مطلقًا رغم أن AWS CLI يعمل على المضيف. ارفع الحد إلى 2 على المثيل، أو استخدم بيانات اعتماد ثابتة.

aws ec2 modify-instance-metadata-options --instance-id i-0123456789abcdef0 --http-put-response-hop-limit 2

عندما لا يمكن العثور على بيانات اعتماد، يسجل الخادم CredentialsProviderError: Could not load credentials from any providers عند أول تحميل، بينما تعرض واجهة المستخدم خطأً عامًا فقط.

أذونات الحاوية

يُكتب الملف المُحمّل أولًا إلى مسار معلّق، ثم يُتحقق منه، وبعد ذلك يُنسخ إلى مساره النهائي، ويُحذف الكائن المعلّق. لذلك تحتاج السياسة إلى أكثر من s3:PutObject:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::my-twenty-bucket"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:AbortMultipartUpload"
      ],
      "Resource": "arn:aws:s3:::my-twenty-bucket/*"
    }
  ]
}

يُستخدم s3:ListBucket لحذف المجلدات، مثلًا عند حذف مساحة عمل. من دونه، يرد S3 على طلبات الكائنات المفقودة برفض الوصول بدلًا من عدم العثور عليها، لذلك لا يستطيع الخادم التمييز بين ملف مفقود ومشكلة أذونات.

الواجهة النهائية والعنونة

يستخدم Twenty دائمًا عنونة بنمط المسار، لذا تذهب الطلبات إلى https://endpoint/bucket/key. بالنسبة إلى AWS S3 الأصلية، اترك STORAGE_S3_ENDPOINT غير محدد: تنشئ SDK العنوان https://s3.{region}.amazonaws.com من STORAGE_S3_REGION، ولهذا يظهر إدخال منطقة غير صحيح كخطأ DNS بدلًا من خطأ S3. عيّن الواجهة النهائية فقط للخدمات المتوافقة مع S3، أو عندما يصل الخادم إلى S3 عبر واجهة VPC نهائية.

مشاركة الموارد عبر المصادر (CORS)

عندما تكون قيمة STORAGE_S3_PRESIGNED_URL_ENABLED هي true، تتواصل المتصفحات مع الحاوية مباشرةً. التنزيلات هي طلبات GET، والتحميلات هي طلبات PUT تحمل ترويسة Content-Type، مما يجعل المتصفح يرسل طلب تحقق مسبق أولًا. لذلك يجب أن تسمح سياسة CORS الخاصة بالحاوية بمصدر Twenty الخاص بك، وكلتا الطريقتين وتلك الترويسة:

[
  {
    "AllowedOrigins": ["https://crm.example.com"],
    "AllowedMethods": ["GET", "PUT"],
    "AllowedHeaders": ["Content-Type"],
    "MaxAgeSeconds": 3000
  }
]

من دون عناوين URL الموقعة مسبقًا، تمر كل حركة مرور الملفات عبر الخادم ولا تحتاج الحاوية إلى أي إعدادات CORS.

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

تصل إخفاقات التحميل إلى واجهة المستخدم كخطأ عام. يوجد خطأ S3 الأساسي في سجلات الخادم (docker compose logs server) وفي استجابة GraphQL الظاهرة في علامة تبويب الشبكة بالمتصفح.

الوظائف المنطقية ومفسر الشيفرة

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

الإعدادات الافتراضية للأمان

في بيئة الإنتاج (NODE_ENV=production): يكون الإعداد الافتراضي لكل من الوظائف المنطقية ومفسر الشيفرة هو معطل. يجب تمكينهما صراحة باستخدام LOGIC_FUNCTION_TYPE وCODE_INTERPRETER_TYPE إذا كنت تحتاج إلى هذه الميزات. في بيئة التطوير (NODE_ENV=development): يكون الإعداد الافتراضي لكليهما LOCAL لتسهيل التشغيل محلياً.

ملاحظة أمنية: يقوم برنامج التشغيل المحلي (LOGIC_FUNCTION_TYPE=LOCAL أو CODE_INTERPRETER_TYPE=LOCAL) بتشغيل الشيفرة مباشرة على المضيف ضمن عملية Node.js من دون عزل. يجب استخدامه فقط للشيفرة الموثوقة أثناء التطوير. لعمليات النشر الإنتاجية التي تتعامل مع شيفرة غير موثوقة، استخدم LOGIC_FUNCTION_TYPE=LAMBDA أو CODE_INTERPRETER_TYPE=E2B (مع وضع الحماية)، أو اتركهما مُعطَّلَيْن.

الوظائف المنطقية - برامج التشغيل المتاحة

برنامج التشغيل	متغير البيئة	حالة الاستخدام	مستوى الأمان
معطل	`LOGIC_FUNCTION_TYPE=DISABLED`	تعطيل الوظائف المنطقية بالكامل	غير متاح
محلي	`LOGIC_FUNCTION_TYPE=LOCAL`	بيئات التطوير والبيئات الموثوقة	منخفض (من دون عزل)
Lambda	`LOGIC_FUNCTION_TYPE=LAMBDA`	الإنتاج مع شيفرة غير موثوق بها	مرتفع (عزل على مستوى الأجهزة)

الوظائف المنطقية - الإعداد الموصى به

للتطوير:

LOGIC_FUNCTION_TYPE=LOCAL  # default when NODE_ENV=development

للإنتاج (AWS):

LOGIC_FUNCTION_TYPE=LAMBDA
LOGIC_FUNCTION_LAMBDA_REGION=us-east-1
LOGIC_FUNCTION_LAMBDA_ROLE=arn:aws:iam::123456789:role/your-lambda-role
LOGIC_FUNCTION_LAMBDA_ACCESS_KEY_ID=your-access-key
LOGIC_FUNCTION_LAMBDA_SECRET_ACCESS_KEY=your-secret-key
LOGIC_FUNCTION_LAMBDA_LAYER_BUCKET=your-layer-bucket

يحمّل برنامج تشغيل Lambda طبقة تبعيات كل تطبيق إلى LOGIC_FUNCTION_LAMBDA_LAYER_BUCKET، وهي حاوية تملكها في المنطقة نفسها التي توجد فيها وظائفك. عند عدم تعيينه، يستخدم برنامج التشغيل حاوية التخزين لديك (STORAGE_S3_NAME). إذا لم يتم تعيين أي منهما، تفشل الدوال المنطقية بسبب خطأ في التهيئة. لتعطيل الوظائف المنطقية:

LOGIC_FUNCTION_TYPE=DISABLED  # default when NODE_ENV=production

مفسر الشيفرة - برامج التشغيل المتاحة

برنامج التشغيل	متغير البيئة	حالة الاستخدام	مستوى الأمان
معطل	`CODE_INTERPRETER_TYPE=DISABLED`	تعطيل تنفيذ الشيفرة بالذكاء الاصطناعي	غير متاح
محلي	`CODE_INTERPRETER_TYPE=LOCAL`	للتطوير فقط	منخفض (من دون عزل)
E2B	`CODE_INTERPRETER_TYPE=E_2_B`	الإنتاج مع تنفيذ ضمن صندوق رمل معزول	مرتفعة (صندوق رمل معزول)

عند استخدام LOGIC_FUNCTION_TYPE=DISABLED أو CODE_INTERPRETER_TYPE=DISABLED، سترجع أي محاولة للتنفيذ خطأً. يكون هذا مفيدًا إذا كنت ترغب في تشغيل Twenty من دون هذه الإمكانات.

واجهة برمجة التطبيقات (API) والواجهة الأمامية على مضيفين منفصلين

ينطبق فقط إذا كنت لا تدع الواجهة الخلفية تقوم بخدمة الواجهة الأمامية. عمليات النشر ذات الأصل نفسه لا تحتاج إلى أي شيء هنا. صرّح بجميع أصول المتصفحات التي تتواصل مع واجهة برمجة التطبيقات (API)، مفصولة بفواصل. SERVER_URL وFRONTEND_URL موثوق بهما بالفعل. يقوم الخادم بتسجيل تحذير عندما يتصل به متصفح من مصدر غير مصرح به.

AUTH_COOKIE_ALLOWED_ORIGINS=https://app.example.com

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

إذا كان المضيفان على نطاقات قابلة للتسجيل مختلفة (وليس مجرد نطاقات فرعية مختلفة)، قم أيضًا بتعيين AUTH_COOKIE_SAME_SITE=none، والذي يتطلب HTTPS. مع تمكين ميزة تعدد مساحات العمل، لا تُدرِج كل نطاق فرعي لكل مساحة عمل هنا. بدلًا من ذلك، قم بتوجيه مسارات واجهة برمجة التطبيقات (API) (/graphql، /metadata، /rest، /auth/، /client-config، /file) إلى الواجهة الخلفية على كل اسم مضيف لمساحة عمل، بحيث تبقى كل مساحة عمل من نفس المصدر (same-origin) — هكذا تعمل Twenty Cloud.

⌘I

​نظرة عامة

​1. إعداد لوحة الإدارة (افتراضي)

​مفاتيح التشفير

​2. إعداد بيئي فقط

​وضع تعدد مساحات العمل

​وضع مساحة العمل الواحدة (الافتراضي)

​تمكين وضع تعدد مساحات العمل

​تكوين DNS لوضع تعدد مساحات العمل

​تقييد إنشاء مساحات العمل

​تكامل Gmail و Google Calendar

​إنشاء مشروع Google Cloud

​تكوين OAuth

​الإعداد في Twenty

​إذا كان تطبيقك في وضع الاختبار

​تكامل Microsoft 365

​إنشاء مشروع في Microsoft Azure

​تمكين APIs

​URIs لإعادة التوجيه المصرح بها

​الإعداد في Twenty

​تكوين النطاقات

​إذا كان تطبيقك في وضع الاختبار

​مهام الخلفية للتقويم والمراسلة

​حدود ذاكرة قائمة انتظار المهام

​الاتصالات الصادرة إلى المضيفين الداخليين

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

​تخزين S3

​بيانات الاعتماد

​أذونات الحاوية

​الواجهة النهائية والعنونة

​مشاركة الموارد عبر المصادر (CORS)

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

​الوظائف المنطقية ومفسر الشيفرة

​الإعدادات الافتراضية للأمان

​الوظائف المنطقية - برامج التشغيل المتاحة

​الوظائف المنطقية - الإعداد الموصى به

​مفسر الشيفرة - برامج التشغيل المتاحة

​واجهة برمجة التطبيقات (API) والواجهة الأمامية على مضيفين منفصلين

نظرة عامة

1. إعداد لوحة الإدارة (افتراضي)

مفاتيح التشفير

2. إعداد بيئي فقط

وضع تعدد مساحات العمل

وضع مساحة العمل الواحدة (الافتراضي)

تمكين وضع تعدد مساحات العمل

تكوين DNS لوضع تعدد مساحات العمل

تقييد إنشاء مساحات العمل

تكامل Gmail و Google Calendar

إنشاء مشروع Google Cloud

تكوين OAuth

الإعداد في Twenty

إذا كان تطبيقك في وضع الاختبار

تكامل Microsoft 365

إنشاء مشروع في Microsoft Azure

تمكين APIs

URIs لإعادة التوجيه المصرح بها

الإعداد في Twenty

تكوين النطاقات

إذا كان تطبيقك في وضع الاختبار

مهام الخلفية للتقويم والمراسلة

حدود ذاكرة قائمة انتظار المهام

الاتصالات الصادرة إلى المضيفين الداخليين

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

تخزين S3

بيانات الاعتماد

أذونات الحاوية

الواجهة النهائية والعنونة

مشاركة الموارد عبر المصادر (CORS)

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

الوظائف المنطقية ومفسر الشيفرة

الإعدادات الافتراضية للأمان

الوظائف المنطقية - برامج التشغيل المتاحة

الوظائف المنطقية - الإعداد الموصى به

مفسر الشيفرة - برامج التشغيل المتاحة

واجهة برمجة التطبيقات (API) والواجهة الأمامية على مضيفين منفصلين