# 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: 2026-10-30
- Kaynak: https://contextator.com/tr/docs/backup-and-data/
- Dil: tr-TR
- Yazar: Muhammet Şafak

---
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:

```bash
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:

```bash
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](/tr/docs/security/#ş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:

```bash
#!/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](https://github.com/Contextator/Contextator/blob/main/README.md#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](https://github.com/Contextator/Contextator/blob/main/README.md#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](https://github.com/Contextator/Contextator/blob/main/README.md#data-and-persistence) 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:

```bash
docker exec -it contextator psql -U contextator
```

```sql
\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:

```bash
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](/tr/docs/admin-api/#projeler). `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.
