Yedekleme ve Veri

Her şeyin nerede saklandığı, neyin neyi atlattığı, ve nasıl yedekleneceği.

---

Ne nerede saklanır

Neyin neyi atlattığı

Kendi dokümantasyonunuz asla değiştirilmez: /docs salt okunur bağlanır ve yerel kaynaklar yerinde taranır.

DATABASE_URL’i harici bir PostgreSQL’e ayarlamış bir kurulumda, ilk satır buradan yedeklenecek sizin malınız değildir — komut yine de çalışır, adını verdiğiniz sunucuyu dump’lar ve bunu çıktısında söyler; o sunucunun kendi yedekleme rejimi onu gerçekten kapsayan şeydir. -slim imajında, npm run backup tamamen reddeder, çünkü o imaj hiç PostgreSQL taşımaz ve dolayısıyla hiç pg_dump taşımaz: bunun yerine aynı DATABASE_URL’i gösteren varsayılan imajdan çalıştırın.

Veriyi host dizinlerinde saklamak

Adlandırılmış volume’ler yerine:

CONTEXTATOR_PGDATA_PATH=/srv/contextator/pgdata     # Linux: put the database on a chosen disk
CONTEXTATOR_MODELS_PATH=D:/contextator/models       # Windows (forward slashes)
CONTEXTATOR_DATA_PATH=/srv/contextator/data

Dizinler ilk başlatmada oluşturulur ve sahiplikleri otomatik olarak düzeltilir. Docker Desktop’ta veritabanı için daha hızlı seçim adlandırılmış volume’ler olmaya devam eder; initdb bir host dizininde izin hataları bildiriyorsa, o bağlantıyı bir volume’e geri çevirin.

---

Yedeklemek

Tek bir komut, ve veritabanından fazlasını alır:

docker exec contextator npm run backup -- /data/backups/contextator-$(date +%F).tar.gz
docker cp contextator:/data/backups/contextator-$(date +%F).tar.gz .

Komut, kendisine verilen dizini oluşturur. Ortaya çıkan dosyayı bu makineden kopyalayın — yedeklediği şeyle aynı diskte duran bir yedek, bir yedek değil bir geri alma noktasıdır.

Arşivde ne var

SECRET_KEY bilerek arşivde değildir

Arşiv, SECRET_KEY’in bir parmak izini kaydeder — anahtarlı bir HMAC, anahtarın kendisi değil — anahtarı asla. Anahtarı taşıyan bir yedek, tek bir dosyada tüm örnek olurdu, ki kaynak tokenlarını şifrelemenin tam olarak önlemeye çalıştığı şey budur. .env’i arşivin olmadığı bir yerde tutun, ve elinizde son SECRET_KEY rotate etmenizden önce alınmış ve o arşivler bir kaynağın senkronizasyon kimlik bilgisini — özel bir git, Notion ya da Confluence token’ını — onun altında şifrelenmiş taşıyorsa, emekli edilmiş bir anahtarı yanınızda tutun — rotate etme prosedürü ve böyle bir arşivi yeni anahtar altında geri yüklemenin neden reddedildiği için bkz. wiki/Security#rotating-secret_key.

Bir çizelgeyle

Contextator’ın içinde bir zamanlayıcı yoktur — komut bir komuttur, ve onu host’unuzun cron’u (ya da bir Compose sidecar’ı) çalıştırır:

#!/usr/bin/env bash
set -euo pipefail
stamp=$(date +%F)
docker exec contextator npm run backup -- "/data/backups/contextator-$stamp.tar.gz"
docker cp "contextator:/data/backups/contextator-$stamp.tar.gz" /srv/backups/
docker exec contextator rm -f "/data/backups/contextator-$stamp.tar.gz"
find /srv/backups -name 'contextator-*.tar.gz' -mtime +14 -delete

İlk satırdaki set -e önemlidir: o olmadan, başarısız bir yedeklemeyi, onun yerine geçmesi gereken iki haftalığı silen başarılı bir find izler.

---

Geri yüklemek

docker exec contextator sh -c 'mkdir -p /data/backups'
docker cp contextator-2026-09-22.tar.gz contextator:/data/backups/

# Reads the manifest and every refusal, writes nothing:
docker exec contextator npm run restore -- /data/backups/contextator-2026-09-22.tar.gz --check
docker exec contextator npm run restore -- /data/backups/contextator-2026-09-22.tar.gz
docker compose restart contextator

Bir geri yükleme orada olanın yerine geçer. Yepyeni bir kurulumda doğru şey, ve çalışan birinde yıkıcı bir şeydir, ve komut sormaz — önce bakmanın yolu --check’tir. Bir bayt yazmadan önce arşivin türünü ve sürümünü, pg_restore’un mevcut olduğunu, ve sunucunun PostgreSQL major sürümünün dump’ın alındığı sürümden eski olmadığını doğrular — burada herhangi bir uyumsuzluk, bir açıklamayla birlikte, yarı yüklenmiş bir örnek bırakmak yerine tamamen reddeder. SECRET_KEY denetimi daha dardır: yalnızca uyumsuzluk bir senkronizasyon kimlik bilgisini — bu tarafta hiçbir şeyin yeniden veremeyeceği bir git, Notion ya da Confluence token’ını — kaybettirecekse reddeder. Yanlış bir anahtar altındaki bir webhook secret’ı bunlardan biri değildir; yeniden üretilebilir, bu yüzden geri yükleme onu sayar, bildirir ve devam eder.

Bir düşürme — daha yeni bir PostgreSQL major’ünden alınmış bir dump’ı daha eski bir sunucuya geri yüklemek — tamamen reddedilir. Diğer yönde, 16’dan 17’ye gitmek, belgelenen yükseltme yoludur: npm run backup çalıştırın, yeni major’ü boş bir volume’e karşı başlatın, sonra arşivi npm run restore ile onun içine geri yükleyin.

Yalnızca veritabanını istiyorsanız

Alttaki iki komut değişmemiştir ve hâlâ çalışır:

docker exec contextator pg_dump -U contextator -Fc contextator > contextator.dump
docker exec -i contextator pg_restore -U contextator -d contextator --clean --if-exists < contextator.dump

Upload dosyalarını taşımazlar ve SECRET_KEY’i denetlemezler — npm run backup ve npm run restore’un var olma nedeni budur.

Veritabanını incelemek

Gömülü PostgreSQL yayımlanmaz, bu yüzden konteyner üzerinden gidin:

docker exec -it contextator psql -U contextator

\dt                                        -- tables
SELECT name, status, document_count, chunk_count FROM projects;
SELECT name, type, status, document_count FROM document_sources;
SELECT relative_path, title, chunk_count FROM documents ORDER BY relative_path LIMIT 20;

Veritabanı parolasını değiştirmek

POSTGRES_PASSWORD yalnızca küme ilk oluşturulduğunda uygulanır. Sonrasında:

docker exec -it contextator psql -U contextator -c "ALTER USER contextator PASSWORD 'new-password'"

Sonra bir sonraki başlatmadan önce .env’i güncelleyin.

Başka bir makineye taşımak

1. npm run backup ve arşivi karşıya kopyalayın.
2. .env’i (SECRET_KEY dahil) ve dokümantasyonunuzu kopyalayın. Arşivin altında alındığı anahtar olmalıdır — arşivi aldıktan sonra SECRET_KEY’i rotate ettiyseniz, bunun yerine emekli edilmiş anahtarla geri yükleyin, ya da önce yeni bir yedek alın.
3. Yeni host’ta Contextator’ı başlatın, sonra geri yükleyin: konteynerde mkdir -p /data/backups, arşivi docker cp ile içeri alın, npm run restore -- <dosya> --check, sonra npm run restore -- <dosya>, sonra yeniden başlatın.
4. Agent’larınızın işaret ettiği URL’leri güncelleyin — ya da PUBLIC_BASE_URL’i ayarlayın ve onları bir proxy’nin arkasında sabit tutun.

Disk kullanımı

• Gömme modeli: bir kez, ~470 MB (fp32) ya da ~120 MB (q8).
• Veritabanı: ağırlıklı olarak vektörlerden oluşur — parça başına 384 float artı parça metni. Birkaç bin doküman tipik olarak yüzlerce megabayttadır.
• Somutlaştırılmış kaynaklar: yüklemelerin, checkout’ların ve Notion sayfalarının kendileri kadar büyüktür.