# 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-09-24
- 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 ç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 ve Confluence tokenları 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 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](https://github.com/Contextator/Contextator/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:

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

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

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

```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.

## 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.