Her şeyin nerede saklandığı, neyin neyi atlattığı, ve nasıl yedekleneceği.
Ne nerede saklanır
| Ne | Konteynerdeki yol | Varsayılan volume | Geçersiz kılma |
|---|---|---|---|
| Veritabanı: projeler, dokümanlar, gömmeler, çalışma geçmişi | /var/lib/postgresql/data |
contextator-pgdata |
CONTEXTATOR_PGDATA_VOLUME ya da CONTEXTATOR_PGDATA_PATH |
| İndirilmiş gömme modelleri | /app/.cache/models |
contextator-models |
CONTEXTATOR_MODELS_VOLUME / ..._PATH |
| Somutlaştırılmış kaynaklar: yüklemeler, git checkout’ları, Notion, Confluence, doküman sitesi, S3, Google Drive ve GitHub çekimleri | /data |
contextator-data |
CONTEXTATOR_DATA_VOLUME / ..._PATH |
| Kendi dokümantasyonunuz | /docs (salt okunur) |
– | DOCS_HOST_PATH |
Neyin neyi atlattığı
| Eylem | Veri |
|---|---|
docker compose down |
Korunur |
docker compose pull && docker compose up -d |
Korunur |
docker rm contextator, imaj yükseltmeleri |
Korunur |
docker compose down -v |
Silinir |
docker volume rm contextator-pgdata |
Silinir |
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
database.dump |
Her proje, kaynak, doküman, parça, gömme, hesap, oturum, MCP token’ı, audit olayı ve loglanmış arama — şifrelenmiş git, Notion, Confluence ve GitHub tokenları, S3 anahtar çiftleri ve Google Drive anahtarları dahil |
data/… |
Her upload kaynağının dosyaları. Yüklemeler için bu var olan tek kopyadır; git checkout’ları ve Notion çekimleri burada değildir çünkü yeniden klonlanabilir ve yeniden çekilebilirler |
manifest.json |
Arşivin ne olduğu, içinde ne olduğu, ve hangi SECRET_KEY’e ihtiyaç duyduğu. İlk girdidir, bu yüzden geri kalanı açmadan okunabilir |
README.txt |
Aynı şeyin düz metin hali, arşivi bir yıl sonra açacak kişi için |
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, Confluence ya da GitHub token’ını, bir S3 anahtar çiftini ya da bir Google Drive anahtarını — onun altında şifrelenmiş taşıyorsa,
emekli edilmiş bir anahtarı yanınızda tutun — rotate etme prosedürü için bkz.
Şeyleri değiştirmek, böyle bir arşivi yeni anahtar altında geri
yüklemenin neden reddedildiği için de aşağıdaki geri yükleme adımlarına.
Bir çizelgeyle
Contextator’ın yedekler için yerleşik bir zamanlayıcısı 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
Geri yükleme komutları README’nin Data and persistence bölümündedir ve onların tek kopyası odur: çalıştırdığınız kod sürümüyle birlikte gelir. Önce oradaki --check satırını çalıştırın — manifest’i okur, her reddi değerlendirir ve hiçbir şey yazmaz.
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, Confluence ya da GitHub token’ını, bir S3 anahtar çiftini ya da bir Google Drive anahtarı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 (kontrolleri ve geri alma adımlarıyla birlikte adım adım prosedür, README’deki Upgrading PostgreSQL across a major version bölümündedir): 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
Düz pg_dump ve pg_restore komutları hâlâ çalışır ve aynı README bölümünde yer alır. 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
npm run backupve arşivi karşıya kopyalayın..env’i (SECRET_KEYdahil) ve dokümantasyonunuzu kopyalayın. Arşivin altında alındığı anahtar olmalıdır — arşivi aldıktan sonraSECRET_KEY’i rotate ettiyseniz, bunun yerine emekli edilmiş anahtarla geri yükleyin, ya da önce yeni bir yedek alın.- Yeni host’ta Contextator’ı başlatın, sonra geri yükleyin: konteynerde
mkdir -p /data/backups, arşividocker cpile içeri alın,npm run restore -- <dosya> --check, sonranpm run restore -- <dosya>, sonra yeniden başlatın. - 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.
Bir projeyi taşımak
Tüm instance yerine tek bir projeyi taşımak için bir proje manager’ı, belgelerini, chunk’larını ve kaynak
ayarlarını tutan tek bir .tar.gz olan GET /api/projects/:id/export’u indirir ve bir instance admin’i onu
POST /api/projects/import ile diğer instance’a gönderir; proje orada oluşturulur. Bkz.
Admin API. DATA_DIR, DATA_DIR_MIN_FREE_BYTES artı arşiv boyutunun dört katını
tutamıyorsa (gömülü veritabanıyla, veri dizini için de aynısı) hiçbir şey açılmadan önce içe aktarım 507 insufficient_disk ile reddedilir; harici veritabanında yalnızca DATA_DIR ölçülür. Denetim danışma niteliğindedir ve
DATA_DIR_MIN_FREE_BYTES=0 onu kapatır.
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.