Contextator
ENTR

Yönetim ve güvenlik

Yedekleme ve Veri

Contextator'ın veritabanını, modellerini ve somutlaştırılmış kaynaklarını nerede sakladığı ve yerleşik yedekleme/geri yükleme komutunun bir arşivi nasıl aldığı ve denetlediği.

Güncelleme:

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

  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.

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.

Gezinmek için ok tuşları, açmak için Enter.