دليل الترقية

إرشادات عامة

احرص دائمًا على إنشاء نسخة احتياطية لقاعدة البيانات قبل بدء عملية الترقية عن طريق تشغيل:

docker exec -it {db_container_name_or_id} pg_dumpall -U {postgres_user} > databases_backup.sql

لاستعادة النسخة الاحتياطية:

cat databases_backup.sql | docker exec -i {db_container_name_or_id} psql -U {postgres_user}

إذا كنت تستخدم Docker Compose، اتبع الخطوات التالية:

أوقف Twenty: docker compose down
غيّر قيمة TAG في ملف .env الموجود بجانب ملف docker-compose.yml
ابدأ تشغيل Twenty: docker compose up -d

يقوم الخادم بتشغيل جميع عمليات ترحيل الترقية المطلوبة تلقائيًا عند بدء التشغيل. لا حاجة إلى أي أمر يدوي.

الترقيات عبر الإصدارات (v1.23+)

بدءًا من v1.23، يدعم Twenty الترقيات عبر الإصدارات. يمكنك الانتقال مباشرةً من أي إصدار مدعوم إلى أحدث إصدار دون المرور بكل إصدار وسيط. على سبيل المثال، الترقية من v1.23 مباشرةً إلى v2.0 مدعومة بالكامل.

الترقية إلى v2.5+ — غلاف التشفير للبيانات الساكنة (at-rest)

بدءًا من v2.5، يقوم Twenty بتخزين الأسرار أثناء السكون (at-rest) — مثل رموز OAuth، ومتغيرات التطبيق، ومفاتيح التوقيع الخاصة، وقيم الإعدادات الحساسة، وأسرار TOTP — داخل غلاف ذي إصدار enc:v2: ومشفّر باستخدام ENCRYPTION_KEY (أو APP_SECRET إذا لم يتم تعيين ENCRYPTION_KEY). أول إقلاع على v2.5 يشغّل أوامر ترقية بطيئة تقوم بإجراء ملء رجعي للصفوف الموجودة داخل الغلاف الجديد. هذه الأوامر عديمة الأثر عند التكرار (idempotent) — إيقاف الخادم وإعادة تشغيله يستأنف من حيث توقّف — لكنها قد تستغرق بعض الوقت على قواعد البيانات الكبيرة. يمكنك متابعة التقدّم باستخدام upgrade:status. يجب تعيين ENCRYPTION_KEY مخصص قبل الترقية إلى v2.5 لكي يكتب الملء الرجعي الصفوف باستخدامه منذ البداية. يتطلّب تبديل المفاتيح بعد الملء الرجعي إجراء تدوير.

تدوير الأسرار ومفاتيح التوقيع

لمهام التشغيل اليومية مثل تدوير ENCRYPTION_KEY، أو تدوير مفتاح توقيع JWT، أو إبطال مفتاح توقيع تم تسريبه، راجع دليل تدوير المفاتيح (Key rotation guide).

التحقق من حالة الترقية

يتيح لك الأمر upgrade:status فحص الحالة الحالية لمثيلك وعمليات ترحيل مساحات العمل. يكون مفيدًا لاستكشاف مشكلات الترقية وإصلاحها أو عند تقديم طلب دعم. قم بتشغيله من حاوية الخادم:

docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status

مثال على المخرجات:

APP_VERSION: v1.23.0

Instance
    Inferred version: 1.23.0
    Latest command:   1.23.0_DropWorkspaceVersionColumnFastInstanceCommand_1785000000000
    Status:           Up to date
    Executed by:      v1.23.0
    At:               2026-04-16T11:43:58.823Z

Workspace
  Apple (20202020-1c25-4d02-bf25-6aeccf7ea419)
      Inferred version: 1.23.0
      Latest command:   1.23.0_UpdateGlobalObjectContextCommandMenuItemsCommand_1780000005000
      Status:           Up to date
      Executed by:      v1.23.0
      At:               2026-04-16T11:44:09.361Z

Summary
    Instance: Up to date
    Workspaces: 1 up to date, 0 behind, 0 failed (1 total)

خيارات

خيار	الوصف
`-w, --workspace-id <id>`	لتصفية حسب مساحة عمل معيّنة. يمكن تمريره عدة مرات.
`-f, --failed-only`	إخفاء مساحات العمل المحدَّثة، وعرض المتأخرة أو الفاشلة فقط.

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

إذا فشلت الترقية في بعض مساحات العمل، فلن يتجاوز الخادم الخطوة الفاشلة. إعادة تشغيل الخادم (docker compose up -d) ستعيد محاولة الترقية من حيث توقفت. لتحديد المشكلات بسرعة، قم بتشغيل:

docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status --failed-only

يعرض هذا فقط مساحات العمل المتأخرة أو التي فشلت، مع رسالة الخطأ لكل حالة فشل.

قبل v1.23

إذا كان مثيلك أقدم من v1.23، فيجب عليك الترقية تدريجيًا عبر كل إصدار رئيسي موسوم (من v1.6 إلى v1.7، ثم من v1.7 إلى v1.8، وهكذا) حتى تصل إلى v1.23. ومن هناك، يمكنك الانتقال مباشرةً إلى أحدث إصدار.

نظرة عامة

التطبيقات

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

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

المساهمة

إرشادات عامة

الترقيات عبر الإصدارات (v1.23+)

الترقية إلى v2.5+ — غلاف التشفير للبيانات الساكنة (at-rest)

تدوير الأسرار ومفاتيح التوقيع

التحقق من حالة الترقية

خيارات

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

قبل v1.23

​إرشادات عامة

​الترقيات عبر الإصدارات (v1.23+)

​الترقية إلى v2.5+ — غلاف التشفير للبيانات الساكنة (at-rest)

​تدوير الأسرار ومفاتيح التوقيع

​التحقق من حالة الترقية

​خيارات

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

​قبل v1.23

إرشادات عامة

الترقيات عبر الإصدارات (v1.23+)

الترقية إلى v2.5+ — غلاف التشفير للبيانات الساكنة (at-rest)

تدوير الأسرار ومفاتيح التوقيع

التحقق من حالة الترقية

خيارات

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

قبل v1.23