MESA Core · v0.9.3
Operasyon ve kurtarma
Bu rehberin Türkçe ve İngilizce sürümleri aynı konuyu açıklar. Bu sayfayla ilgili kaynak bölümleri en altta yer alır.
Her veri dizininin tek yazıcısı olmalı#
Her veri dizini için tek combined V4 süreci çalıştırın. Arama görünümü ve temizlik kuyruklarını, başarısız iş kuyruğunu, takılı iş sahipliklerini ve sahipsiz kayıtları izleyin. Paylaşılan çıktıların sayısının sıfır olması gerekmez. Kuyruğun büyümesi, depodaki satırları elle değiştirmek için gerekçe değildir; nedenini araştırmanız gereken bir işletim işaretidir.
Kurtarma, sahiplik kurallarını korur#
Bir işi yeniden yürütmeden önce depo veya sağlayıcı hatasını giderin. İş sahipliğini kaybeden bir çalışan, o işi tamamlayamaz. Geri alma işleminde önce kaynağın sahiplik bağı kaldırılıp silindi işareti yazılır, ardından ikincil temizlik yapılır. Başka bir etkin kaynağın hâlâ kullandığı ortak çıktı korunur. Temizliğin BLOCKED olması, başarılı olduğu anlamına gelmez.
Yeni düzene geçmeden önce yedek alın#
Aşağıdaki kaynakta yer alan, yazıcı kilidi kontrollerini içeren çevrimdışı yedekleme ve geri yükleme adımlarını izleyin. Geri dönme olanağını koruduğunuz sürece özgün veri dizinini ve yedeği saklayın. Yedeği yeni, boş bir dizine yükleyin; mevcut dizinin üzerine yazmayın veya genel bir sürüm düşürme işlemi çalıştırmayın. Yeniden oluşturma çevrimdışıdır ve veri dizininin tamamını kapsar; tek bir üst erişim alanını çevrimiçi onarmaz.
- Troubleshooting → Sorun giderme
- Upgrading to v0.8.0 → v0.9.3 yükseltmesi
Kaynak belgedeki ilgili bölümler
Bu bölüm, kaynak belgenin bu sayfayla ilgili kısımlarını değiştirmeden gösterir. Kaynak içindeki bir bölüme giden bağlantıyı açtığınızda metin otomatik olarak görünür.
Bu runbook v4 full-cognitive release candidate için kanonik operasyon
rehberidir. Production kararı Final MVP Certification tamamlanana kadar
NO-GOdur. V3 lexical-core uyumluluk işlemleri ayrıca belirtilir.
1. Desteklenen v4 topology#
V4 aynı storage root’a yazan tek bir combined process ile çalışır. API
admission, durable consumer, validation ve SQLite/LanceDB/Kùzu projection
işleri bu process’tedir.
export MESA_RUNTIME_PROFILE=combined
export MESA_STORAGE_ROOT=/srv/mesa/v4-data
export MESA_LOAD_DOTENV=false
# Provision credentials and reviewed model/provider settings before startup.
.venv/bin/python -m mesa_memory.runtime_entrypointBu komut tek başına V4 provider kurulumu değildir. Canonical insert için
MESA_MODEL_ENABLED=true, kullanılabilir extraction/embedding ve seçili
validation policy gerekir; kurulum ve
yapılandırma ön koşullarını tamamlayın.
Aynı storage root’u ikinci API, worker veya combined process’e yazılabilir
olarak mount etmeyin. Yatay ölçekleme öncesi storage ownership protokolü
gerekir. V3 ile v4 farklı fiziksel storage root kullanmalıdır.
2. İlk credential ve ACL kurulumu#
Uygulama durdurulmuşken veya policy DB’yi kullanan tek operator olarak:
export MESA_STORAGE_ROOT=/srv/mesa/v4-data
mesa-v4-admin issue-key --principal service-api
mesa-v4-admin grant-role --principal service-api \
--tenant tenant-a --role OWNER
mesa-v4-admin grant-agent --principal service-api \
--agent agent-a --permission SESSION_CREATEİlk komut credential’ı yalnız bir kez stdout’a yazar. Secret manager’a aktarın;
log, shell history veya dokümana koymayın. Rotate edilen eski key aynı işlemde
revoke edilir:
mesa-v4-admin rotate-key --key-id KEY_ID
mesa-v4-admin revoke-key --key-id KEY_IDPurge/rollback rol ile örtük gelmez:
mesa-v4-admin grant-dataset-permission --principal service-api \
--tenant tenant-a --dataset dataset-a --permission ROLLBACK3. Projection backlog ve DLQ#
Önce /health ile status, maintenance, rebuild_state özeti ve
/health/init ile readiness kontrol edilir. /health HTTP 200 dönse de
status degraded olabilir. Aşağıdaki ayrıntılı sayaçlar /metrics üzerinden
izlenir; public /health yanıtında ayrı alanlar değildir:
mesa_v4_projection_backlogmesa_v4_projection_dead_lettermesa_v4_projection_stuck_leasesmesa_v4_cleanup_backlogmesa_v4_cleanup_blockedmesa_v4_orphan_registrymesa_v4_shared_artifacts
Backlog artıyorsa process loglarında mutation/pipeline run ID, failure class ve
lane aranır. İçerik, credential veya claim token loglanmamalıdır. Geçici hata
bounded retry ile ilerler; permanent/poison hata DLQ’ya gider.
Replay’den önce kök neden giderilir ve mutation’ın aynı tenant/dataset
kapsamında olduğu doğrulanır. Yetkili API çağrısı:
curl --fail -X POST \
-H "X-API-Key: $MESA_API_KEY" \
"http://127.0.0.1:8000/v4/mutations/$MUTATION_ID/replay"Fenced lease nedeniyle claim token’ı kaybetmiş worker sonucu finalize edemez.
Lease’e elle müdahale etmek yerine process’i yeniden başlatın ve reconciler’ın
expired claim’i almasını bekleyin.
4. Rollback ve BLOCKED#
Commit edilmemiş başarısız run rollback’i önce SQLite retrieval tombstone’u,
sonra vector/graph cleanup outbox’ı oluşturur. Yalnız ilgili
artifact_sources sahipliği kaldırılır. Başka aktif sahibi olan ortak artifact
silinmez.
Cleanup tamamlanamazsa run BLOCKED olur; bunu başarılı saymayın. Store
erişimini düzeltin, health parity’yi kontrol edin ve idempotent cleanup/replay
akışını yeniden çalıştırın. Fiziksel store’da manuel silme yapmayın; ledger ile
store daha fazla ayrışır.
5. Reconciliation#
Reconciliation tenant ve dataset sınırında iki yönlüdür:
- ledger’da olup store’da olmayan artifact yeniden project edilir;
- store’da olup ledger/owner kaydı olmayan artifact karantinaya alınır ve
cleanup kuyruğuna taşınır.
Release veya cutover öncesi projection backlog, blocked cleanup ve ownerless
orphan sıfır olmalıdır. Shared artifact sayısının sıfır olması gerekmez; ortak
sahiplik beklenen bir durumdur.
6. Backup, restore ve v4 rebuild#
Uygulamayı durdurun ve kaynak storage’ı offline hale getirin:
mesa-recovery --trusted-root /srv/mesa backup \
--source-root /srv/mesa/v4-data \
--backup-root /srv/mesa/backups/v4-2026-07-23 \
--stores-stopped
mesa-recovery --trusted-root /srv/mesa validate \
--backup-root /srv/mesa/backups/v4-2026-07-23
mesa-recovery --trusted-root /srv/mesa restore \
--backup-root /srv/mesa/backups/v4-2026-07-23 \
--restore-root /srv/mesa/restore-v4-test--stores-stopped geriye dönük uyumluluk için açık bir operator
precondition'ıdır; tek başına consistency kanıtı değildir. Backup
implementation'ı ayrıca storage-root writer lock'ını doğrular/alır, her SQLite
dosyasını SQLite'ın online backup primitive'iyle ayrı bir tutarlı snapshot
olarak kopyalar ve ancak staging doğrulamasından sonra atomik publish yapar.
SQL authoritative/canonical truth'tür. LanceDB vector ve Kùzu graph
projection'ları rebuildable derived state'tir ve yalnız exclusive writer-lock
boundary altında kopyalanır.
Restore mevcut hedefi ezmemelidir. Backup'ı yeni boş root'a, uyumlu kod ve
config ile geri yükleyip doğrulayın. V3 verisini V4'e taşımak ayrı kaynak/catalog
eşleme ve V4 ingestion çalışmasıdır; projection runner V3→V4 dönüştürücüsü
değildir. Migration rehberi V4 yükseltmesini açıklar.
Backup rollback süresi boyunca korunur.
V4 projection rebuild'inin submit → drain → stop → offline
run/resume → restart → status → automatic rollback akışı, exit code'ları ve
retained generation kuralları
`v4-rebuild-runbook.md` içinde kanonik olarak
belgelenir. Dataset/tenant-scoped rebuild veya online runner desteklenmez.
Alembic migration'ları forward-only'dir. Bir migration başarısız olursa
alembic downgrade çalıştırmayın: release'i durdurun, doğrulanmış backup'ı
yeni boş bir storage root'a restore edin, parity kontrolünü yeniden çalıştırın
ve ancak ardından cutover yapın.
Single-writer kapasite sınırı#
V4 bir storage root için yalnız bir aktif combined owner kullanır.
Worker başlangıcı aynı hostta advisory lock ile ikinci writer'ı reddeder;
çoklu host/NFS için bu bir koordinasyon mekanizması değildir. API ve
MCP process-local cache'leri yalnız performans optimizasyonudur; doğruluk
durumu SQLite ledger ve fenced lease'lerdedir. Yatay writer ölçekleme ancak
paylaşımlı lease/koordinasyon servisi tasarlanıp doğrulandıktan sonra açılır.
7. Model/provider olayı#
MESA_MODEL_ENABLED ve MESA_EXTERNAL_PROVIDER_ENABLED açıkça ayarlanır.
Provider timeout/rate-limit hatası retryable; bozuk şema permanent; sürekli
aynı toksik payload poison olarak sınıflanır. Seçili validation policy
tamamlanmadan SQL/vector/graph projection başlamaz. Provider’ı atlamak için mutation’ı doğrudan VALIDATED
duruma çekmeyin.
8. PageRank#
V4 PageRank çıktısı yalnız telemetridir. Düşük merkezilik bir memory,
assertion, vector veya source’u karantinaya alamaz. PageRank temelli
hallucination/delete davranışı görülürse deploy durdurulmalı; bu v4
sözleşmesine aykırıdır.
9. Session finalization#
Session end durable finalization kaydı oluşturur. Restart sonrası pending işler
combined consumer tarafından alınır. Uzun süre pending kalırsa session,
finalization ID, lease ve DLQ durumu kontrol edilir; FastAPI process içi
BackgroundTasks çalışmasına güvenilmez.
10. Logging ve olay kanıtı#
Production varsayılanı MESA_LOG_LEVEL=INFO ve MESA_LOG_FORMAT=json’dır.
Loglarda request/operation/mutation/pipeline run kimlikleri bulunabilir;
query, source content, payload, credential, raw model output ve claim token
bulunamaz. Docker local driver 10 MB × 5 dosya sınırı kullanır.
Incident kanıtı olarak maskelenmiş log, mutation status, health/metrics anlık
görüntüsü, image digest ve storage manifesti saklanır.
12. Release durumu#
Unit/integration/contract testlerinin geçmesi production GO değildir. Gerçek
provider ve production-benzeri store ile backup→restore→rebuild→cutover,
queue saturation, worker crash, cross-tenant concurrency ve 24 saat soak
kanıtları tamamlanana kadar karar NO-GO kalır.
