Yükseltme rehberi

Genel kılavuzlar

Yükseltme işlemine başlamadan önce veritabanınızı her zaman yedekleyin; bunun için şunu çalıştırın:

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

Yedekten geri yüklemek için:

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

Docker Compose kullanıyorsanız, aşağıdaki adımları izleyin:

Twenty’yi durdurun: docker compose down
docker-compose.yml dosyanızın yanındaki .env dosyasında TAG değerini değiştirin
Twenty’yi başlatın: docker compose up -d

Sunucu, başlatma sırasında gerekli tüm yükseltme migrasyonlarını otomatik olarak çalıştırır. Manuel bir komut gerekmez.

v2.34+ sürümüne yükseltme — En az PostgreSQL 15

Twenty v2.34, PostgreSQL 15 veya daha yeni bir sürüm gerektirir. Resmî Docker Compose yapılandırması PostgreSQL 16 kullanır. Örneğiniz haricî olarak yönetilen bir veritabanına bağlanıyorsa v2.34 sunucusunu başlatmadan önce onu yükseltin.

Sürümler arası yükseltmeler (v1.23+)

Twenty, v1.23 sürümünden itibaren sürümler arası yükseltmeleri destekler. Desteklenen herhangi bir sürümden, ara sürümlerin her birine tek tek geçmeden doğrudan en son sürüme atlayabilirsiniz. Örneğin, v1.23’ten doğrudan v2.0’a yükseltme tamamen desteklenir.

v2.5+ sürümüne yükseltme — bekleme hâlindeki şifreleme zarfı

v2.5 ile birlikte, Twenty beklemede olan gizli verileri (OAuth belirteçleri, uygulama değişkenleri, imzalama için kullanılan özel anahtarlar, hassas yapılandırma değerleri, TOTP sırları) sürümlendirilmiş ve ENCRYPTION_KEY (veya ENCRYPTION_KEY ayarlı değilse APP_SECRET) ile şifrelenmiş bir enc:v2: zarfının içinde saklar. v2.5 sürümündeki ilk açılış, mevcut satırları yeni zarfa geri dolduran yavaş yükseltme komutlarını çalıştırır. Bunlar idempotandır — sunucuyu durdurup yeniden başlattığınızda kaldığı yerden devam eder — ancak büyük veritabanlarında biraz zaman alabilirler. İlerlemeyi upgrade:status ile izleyebilirsiniz. Geri doldurmanın, en başından itibaren satırları onun altında yazabilmesi için, v2.5 yükseltmesinden önce özel bir ENCRYPTION_KEY ayarlamalısınız. Geri doldurmadan sonra anahtarları değiştirmek bir anahtar döndürme gerektirir.

Gizli verilerin ve imzalama anahtarlarının döndürülmesi

ENCRYPTION_KEY döndürme, JWT imzalama anahtarını döndürme veya sızdırılmış bir imzalama anahtarını iptal etme gibi günlük operasyonel görevler için özel Anahtar döndürme kılavuzu bölümüne bakın.

Yükseltme durumunu kontrol etme

upgrade:status komutu, örneğinizin ve çalışma alanı migrasyonlarının mevcut durumunu incelemenizi sağlar. Yükseltme sorunlarında hata ayıklamak veya bir destek talebi oluştururken kullanışlıdır. Sunucu konteynerinden çalıştırın:

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

Örnek çıktı:

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)

Seçenekler

Bayrak	Açıklama
`-w, --workspace-id <id>`	Belirli bir çalışma alanına göre filtreleme yapar. Birden çok kez verilebilir.
`-f, --failed-only`	Güncel çalışma alanlarını gizler, yalnızca geride kalan ve başarısız girdileri gösterir.

Sorun Giderme

Yükseltme bazı çalışma alanlarında başarısız olursa, sunucu başarısız olan adımın ötesine geçmez. Sunucuyu yeniden başlatmak (docker compose up -d), yükseltmeyi kaldığı yerden yeniden dener. Sorunları hızlıca belirlemek için şunu çalıştırın:

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

Bu, yalnızca geride kalan veya başarısız olan çalışma alanlarını ve her bir başarısızlık için hata iletisini gösterir.

v1.23’ten önce

Örneğiniz v1.23’ten eskiyse, v1.23’e ulaşana kadar her ana etiketli sürümden (v1.6’dan v1.7’ye, ardından v1.7’den v1.8’e vb.) kademeli olarak yükseltmeniz gerekir. Bundan sonra, doğrudan en son sürüme geçebilirsiniz.

Genel Bakış

Uygulamalar

API

Kendi Kendine Barındırma

Katkıda Bulunun

Genel kılavuzlar

v2.34+ sürümüne yükseltme — En az PostgreSQL 15

Sürümler arası yükseltmeler (v1.23+)

v2.5+ sürümüne yükseltme — bekleme hâlindeki şifreleme zarfı

Gizli verilerin ve imzalama anahtarlarının döndürülmesi

Yükseltme durumunu kontrol etme

Seçenekler

Sorun Giderme

v1.23’ten önce

​Genel kılavuzlar

​v2.34+ sürümüne yükseltme — En az PostgreSQL 15

​Sürümler arası yükseltmeler (v1.23+)

​v2.5+ sürümüne yükseltme — bekleme hâlindeki şifreleme zarfı

​Gizli verilerin ve imzalama anahtarlarının döndürülmesi

​Yükseltme durumunu kontrol etme

​Seçenekler

​Sorun Giderme

​v1.23’ten önce

Genel kılavuzlar

v2.34+ sürümüne yükseltme — En az PostgreSQL 15

Sürümler arası yükseltmeler (v1.23+)

v2.5+ sürümüne yükseltme — bekleme hâlindeki şifreleme zarfı

Gizli verilerin ve imzalama anahtarlarının döndürülmesi

Yükseltme durumunu kontrol etme

Seçenekler

Sorun Giderme

v1.23’ten önce