تخطَّ إلى المحتوى
kazma.
البحث في كاظمه والتوثيق
EN

التحويل إلى Postgres وSaaS

تعدد مستخدمي SaaS + التحويل الكامل إلى Postgres

Section titled “تعدد مستخدمي SaaS + التحويل الكامل إلى Postgres”

ما الذي ينتقل إلى Postgres عند ضبط KAZMA_DATABASE_URL

Section titled “ما الذي ينتقل إلى Postgres عند ضبط KAZMA_DATABASE_URL”
المخزنالجدول(ات)الوحدة
الضبط / الإعدادات / مستخدمو المنصةkazma_settingsconfig_store.py
جلسات الدردشةkazma_chat_sessionssession_manager.py
مهام السرب + المقاييسkazma_swarm_tasks, kazma_swarm_worker_metricstask_store.py
نقاط تفتيش LangGraphمخطط LangGraph الداخليAsyncPostgresSaver، يفتحه kazma_core/checkpoints_pg.py (الوكيل والبوابة). يُقلَّم منذ 2026-09-27: كل دردشة تحتفظ بأحدث 200 نقطة تفتيش لها، والدردشة الخاملة منذ checkpoints.retention_days (الإعدادات ← النظام ← سجل خطوات الدردشة، الافتراضي 30؛ و0 يحتفظ بالكل) تحتفظ بأحدث 10 نقاط لها
جلسات الويبما تزال مفاتيح ConfigStore ‏(وعبر Postgres أيضًا من خلال الإعدادات)web_sessions.py

يبقى SQLite الافتراضي عند عدم ضبط عنوان قاعدة بيانات (الاختبارات، والعقدة المحلية الواحدة).

ضبط KAZMA_DATABASE_URL يرقّي أيضًا الاسترجاع الكثيف V2 من sqlite-vec إلى pgvector في القاعدة نفسها (الجدول kazma_memory — وهو ضبط memory.backends.vector.collection — وcosine، وفهرس HNSW)، إن كان ذلك الـ Postgres يستطيع حمل المتجهات. ويبقى المخزن المعرفي (memory_state.db) على SQLite حتى تضبط KAZMA_MEMORY_STATE_ROLE=primary.

لا حاجة إلى pgvector ولا إلى Qdrant: بدونهما يكون البحث المعنوي في الذاكرة دقيقًا على كل ذاكرة، محليًا (sqlite-vec أو NumPy، نحو 1 ms لكل 1,000 ذاكرة).

يجب أن يأتي الخادم بالامتداد. صورة postgres:16-alpine — وهي الصورة في docker-compose.postgres.yml وdocker-compose.ha.yml — لا تأتي به؛ استخدم pgvector/pgvector:pg16 (أو Postgres مُدارًا يقدّم pgvector).

  1. تنشئ كاظمه الامتداد والجدول عند أول استخدام عندما يسمح دورها بذلك. وإلا فبصفتك مستخدمًا أعلى: CREATE EXTENSION IF NOT EXISTS vector; في قاعدة بيانات كاظمه، وامنح الدور CREATE على مخططها.
  2. تفحص كاظمه عند الإقلاع وعند كل بحث في الذاكرة (مخزّنًا مؤقتًا دقيقة واحدة):
    • اختيار pgvector تلقائيًا (بلا اختيار صريح) على Postgres بلا الامتداد: سطر INFO واحد، وتبقى الذاكرة على sqlite-vec، وتعرض الإعدادات ← الذاكرة Vector: full (local) مع السبب.
    • pgvector مُختار في الإعدادات لكنه غير قابل للاستخدام (لا امتداد، الدور لا يستطيع إنشاءه، جدول بحجم متجه آخر، خادم متوقف): تحذير WARNING واحد يسمّي الإصلاح، ولافتة الإعدادات تقول الشيء نفسه.
    • Test vector في الإعدادات ← الذاكرة يشغّل الفحص نفسه عند الطلب. حين اختير pgvector تلقائيًا والامتداد غائب، يختبر المخزن المستخدم فعلًا (sqlite-vec المحلي) ويبلّغ Vector OK مع ملاحظة تشرح لماذا لا يُستخدم pgvector؛ أما pgvector اخترته أنت ولا يمكنه العمل فيبلّغ Vector failed مع الإصلاح.
  3. أعد بناء التضمينات مرة واحدة إن كان لديك سجل بالفعل: الإعدادات ← الذاكرة ← إعادة بناء التضمينات (upsert إلى pgvector).
  4. تغيير حجم المضمِّن: الجدول مُقاس على المضمِّن ولا يُعاد تقاسه أبدًا. وجّه memory.backends.vector.collection إلى اسم جديد، ثم أعد بناء التضمينات.
  5. مفتاح الإيقاف: KAZMA_PGVECTOR=0 ‏(sqlite-vec عمدًا، بلا فحص). وQdrant المُصرَّح به صراحةً في الإعدادات لا يُستبدل أبدًا.

نقل قاعدة بيانات postgres:16-alpine قائمة إلى pgvector/pgvector:pg16: فرّغ ثم استرجع، ولا تكتفِ بتبديل الصورة على الوحدة نفسها. فـ Alpine تستخدم musl وصورة pgvector تستخدم glibc؛ وفهارس النص المبنية تحت ترتيب أبجدي واحد تصبح خارج الترتيب تحت الآخر. مع إيقاف كاظمه، فرّغ القاعدة كاملة من الحاوية القديمة (pg_dump -Fc)، واسترجعها بـ pg_restore داخل حاوية pgvector على وحدة تخزين جديدة، ووجّه KAZMA_DATABASE_URL إليها ثم شغّل كاظمه. أبقِ الوحدة القديمة حتى تشتغل الوحدة الجديدة مدةً من الوقت. (scripts/pg_backup.py يفرّغ جداول كاظمه نفسها فقط — وهذا صحيح لقاعدة مشتركة، لا لنقل قاعدة كاملة.)

الاسترجاع بـ Postgres أساسيًا (state.role=primary) هو ILIKE + pgvector RRF، وليس ILIKE وحده.

  1. ثبّت الإضافات: pip install -e ".[postgres]"
  2. شغّل Postgres:
    نافذة طرفيّة
    docker compose -f docker-compose.postgres.yml up -d db
  3. هاجر بـكل المخازن:
    نافذة طرفيّة
    export KAZMA_DATABASE_URL=postgresql://kazma:PASSWORD@localhost:5432/kazma
    python scripts/migrate_sqlite_to_postgres.py --data-dir kazma-data
  4. شغّل كاظمه بالعنوان نفسه (يضبطه compose تلقائيًا).
  5. فحص سريع:
    • تسجيل الدخول (مستخدم / سر / OIDC)
    • تاريخ الدردشة يبقى عبر إعادة التشغيل
    • قائمة مهام السرب
    • الإعدادات تُحفَظ
  • /login — تبويبات المستخدم · السر · SSO
  • الإعدادات ← الحساب — المستخدمون + المستأجرون (المشرف)
  • الترويسة — شارة الدور + تسجيل الخروج

إنشاء مشرف:

from kazma_core.security.platform_rbac import create_local_user
create_local_user("admin", "long-password-here", role="admin")
نافذة طرفيّة
KAZMA_DATABASE_URL=postgresql://…
KAZMA_DB_BACKEND=postgres # optional force
KAZMA_PRODUCTION=1
KAZMA_VAULT_KEY=…
KAZMA_SECRET=…
KAZMA_PUBLIC_URL=https://…
# OIDC optional
KAZMA_OIDC_ISSUER=…
KAZMA_OIDC_CLIENT_ID=…
KAZMA_OIDC_CLIENT_SECRET=…

دور قاعدة بيانات ليس مستخدمًا خارقًا

Section titled “دور قاعدة بيانات ليس مستخدمًا خارقًا”

تحتاج كاظمه إلى أن تملك جداولها وحدها لا أكثر. يستطيع تسجيل دخول المستخدم الخارق قراءة كل قاعدة بيانات على الخادم وتغييرها وتشغيل برامج على مضيف قاعدة البيانات، لذا يحذّر كل إقلاع حين تسجّل كاظمه دخولها بوصفها واحدًا منهم ([security] Kazma signs in to Postgres as kazma, a superuser). وPOSTGRES_USER في إعداد Docker هو أول مستخدم خارق على الخادم، وهكذا ينتهي أغلب التثبيتات على هذه الحال.

deploy/postgres/kazma_app_role.sql ينشئ الدور kazma_app (ليس مستخدمًا خارقًا، ولا يجوز له إنشاء أدوار، ويجوز له إنشاء قواعد بيانات لنسخة بروفة الاستعادة الأسبوعية المؤقتة) ويعطيه قاعدة البيانات ومخططها وكل جدول وتسلسل ودالة. يعمل في معاملة واحدة ويمكن تشغيله مجددًا. يرفض Postgres الصيغة الأقصر REASSIGN OWNED BY <the first superuser>، لذا يسمّي السكربت كل كائن. ويشغّل tests/test_pg_app_role.py إعداد كاظمه لكل مخزن Postgres، وتفريغًا، وبروفة الاستعادة بالدور الجديد.

  1. شغّل السكربت بالمستخدم الخارق، في قاعدة بيانات كاظمه:

    نافذة طرفيّة
    docker exec -i kazma-db-win psql -U kazma -d kazma -v ON_ERROR_STOP=1 < deploy/postgres/kazma_app_role.sql

    ينتهي بـ COMMIT. وإن توقف عند lock timeout فقد أمسك استعلام طويل بجدول: شغّله مجددًا حين تكون كاظمه خاملة. تواصل كاظمه عملها طوال ذلك: فهي ما تزال تسجّل دخولها بالمستخدم الخارق حتى إعادة التحميل.

  2. أنشئ كلمة مرور من حروف وأرقام و- و_ (أي شيء آخر يجب ترميزه بالنسبة المئوية في العنوان):

    نافذة طرفيّة
    python -c "import secrets; print(secrets.token_urlsafe(24))"

    وضع العنوان الجديد في .env، مبقيًا على المضيف والمنفذ واسم قاعدة البيانات: KAZMA_DATABASE_URL=postgresql://kazma_app:<password>@127.0.0.1:5433/kazma.

  3. أعطِ الدور كلمة المرور نفسها، مقروءةً من .env حتى لا تُكتب ولا تُعرض ولا تُحفظ في سجل صدفتك (PowerShell):

    نافذة طرفيّة
    $line = (Get-Content <install>\.env | Where-Object { $_ -like 'KAZMA_DATABASE_URL=*' }) -replace '^KAZMA_DATABASE_URL=',''; $pw = ([uri]$line.Trim().Trim('"')).UserInfo.Split(':',2)[1]; "ALTER ROLE kazma_app PASSWORD '$pw';" | docker exec -i kazma-db-win psql -U kazma -d kazma -v ON_ERROR_STOP=1

    يطبع ALTER ROLE. لا تستخدم موجّه \password في psql: فكلمة المرور الملصقة فيه قد تصل فارغة، فيمسح Postgres عندئذ كلمة مرور الدور بمجرد إشعار (حيًّا، 2026-11-03).

  4. تحقّق من تسجيل الدخول قبل إعادة التحميل، بـ Python الخاص بالتثبيت (<install> هو المجلد الذي ثُبّتت فيه كاظمه):

    نافذة طرفيّة
    <install>\.venv\Scripts\python.exe <install>\scripts\check_database_login.py

    يسجّل الدخول كما ستفعل كاظمه ويطبع OK: Kazma signs in to kazma as kazma_app (not a superuser).، أو NOT OK: مع سبب Postgres. أما فحص يجري بـ psql داخل حاوية قاعدة البيانات فلا يثبت شيئًا: فالحاوية تقبل تسجيلات دخول loopback بلا كلمة مرور.

  5. إن كانت مرآة الذاكرة مفعّلة (الإعدادات -> الذاكرة -> خلفيات الذاكرة -> الحالة المشتركة مضبوطة على Postgres)، فاضبط Postgres DSN الخاص بها على العنوان نفسه واضغط حفظ الخلفيات. فهي تحتفظ بنسختها الخاصة من العنوان.

  6. أعد التحميل: python scripts/service/kazma_guard.py --reload --when-idle.

  7. تحقّق: لم يعد سجل الإقلاع يحمل تحذير المستخدم الخارق، ويجيب /health/ready بالرمز 200. وإن انتظر الخادم قاعدة بياناته بدلًا من ذلك، فسجله يسمّي سبب Postgres ([PostgresPool] Postgres refused the password for kazma_app ...).

للتراجع، أعد العنوان القديم إلى .env (وإلى مرآة الذاكرة) وأعد التحميل؛ فما يزال المستخدم الخارق يستطيع استخدام كل جدول. أبقِ المستخدم الخارق kazma في مكانه: فهو ما تدير به الخادم.

Postgres خدمةً في نظام التشغيل

Section titled “Postgres خدمةً في نظام التشغيل”

قاعدة البيانات في حاوية Docker تحيا وتموت مع Docker Desktop، وهو برنامج لا يبدأ إلا حين يسجّل أحدٌ دخوله. في 4 نوفمبر 2026 أوقفت أداة تحديث Docker Desktop فغابت قاعدة بيانات كاظمه إحدى عشرة ساعة؛ وبعد انقطاع للكهرباء دون أن يسجّل أحد دخوله ما كانت لتبدأ أصلًا. أما قاعدة البيانات المثبّتة خدمةً في نظام التشغيل فتبدأ مع الإقلاع، ويعيد نظام التشغيل تشغيلها حين تموت.

يفعل kazma setup postgres ذلك على كل نظام تشغيل تدعمه كاظمه، بمدير الحزم الخاص بنظام التشغيل نفسه:

نظام التشغيليُثبَّت بـيبدؤهدون أن يسجّل أحد دخوله
ويندوز 10/11winget ‏(PostgreSQL.PostgreSQL.18، مثبّت EDB، دون تدخّل)خدمة ويندوز postgresql-x64-18، بنوع بدء Automatic، وتُعاد عند الفشلنعم
macOS‏Homebrew ‏postgresql@18sudo brew services start postgresql@18 (‏LaunchDaemon)نعم، إلا إن كان FileVault مفعّلًا (انظر أدناه)
Debian / Ubuntuمستودع apt الخاص بمشروع PostgreSQL، postgresql-18‏systemd، Restart=on-failureنعم
Fedora / RHELمستودع dnf الخاص بمشروع PostgreSQL، postgresql18-server‏systemd، Restart=on-failureنعم
WSL 2كما في Debian/Ubuntu، داخل التوزيعة التي تعمل فيها كاظمه، مع systemd=true في /etc/wsl.conf‏systemd في التوزيعة (وتبدأ التوزيعة نفسها مع الإقلاع بمهمة ويندوز التي تشغّل كاظمه)ما دامت تلك المهمة تعمل

ما يفعله، بالترتيب (يطبع الخطة ويسأل أولًا؛ و-y يتخطى السؤال، و--dry-run يطبع الأوامر، و--check يكتفي بالتقرير):

  1. يثبّت مشغّل Postgres الخاص بكاظمه (الحزمة الإضافية kazma[postgres]: ‏psycopg) في بيئة Python التي تعمل فيها كاظمه، إن لم يكن موجودًا. فمن دونه يكون لدى كاظمه عنوان ولا سبيل إلى الوصول إليه، وينتظر الخادم عند البدء قائلًا إن المشغّل غير مثبّت. والتشغيل الثاني يثبّته أيضًا. وإن لم يُثبَّت فلا يُفعل شيء بعده.
  2. يثبّت Postgres 18 خدمةً تبدأ مع الإقلاع وتُعاد حين تفشل، وتستمع على هذا الجهاز وحده (listen_addresses = 'localhost')، مع تسجيل الدخول بـ scram-sha-256. (والتثبيت الذي أُنشئ قبل 13 نوفمبر 2026 يشغّل Postgres 16؛ انظر “الانتقال إلى Postgres أحدث” أدناه.)
  3. ينشئ قاعدة البيانات kazma والدور kazma_app (ليس مستخدمًا خارقًا، deploy/postgres/kazma_app_role.sql).
  4. يفعّل أرشفة WAL (أدناه).
  5. يكتب KAZMA_DATABASE_URL في .env الخاص بالتثبيت (لا يُطبع أبدًا؛ والملف مقصور على حسابك)، ويسجّل الدخول مرة واحدة كما ستفعل كاظمه.
  6. يسجّل ما فعله في kazma-data/setup_record.json: منه يفحص kazma doctor الخدمة، ويراقب الحارس الخدمة (يبدأ الخدمة التي توقفت مرة واحدة لكل انقطاع، وينبّه مرة واحدة إن ظلت متوقفة).

تُحفظ كلمة مرور المستخدم الخارق في <install>/.kazma/postgres_superuser.pass (لحسابك وحده)؛ ولا توضع أي كلمة مرور في سطر أوامر، إلا كلمة المرور المؤقتة لمثبّت ويندوز، التي تستبدلها الخطوة التالية. والتشغيل الثاني يفحص ويُصلح، ولا يعيد التثبيت أبدًا: يُصلح Postgres الذي يسمّيه السجل (16 في تثبيت أقدم)، ولا يثبّت آخر بجانبه أبدًا. شغّله على ويندوز من طرفية بصلاحيات مرتفعة.

الانتقال إلى Postgres أحدث. يقول kazma doctor حين تعمل قاعدة البيانات بإصدار رئيسي أقدم مما تثبّته كاظمه الآن (16 قبل 18). وأمر واحد ينقلها، وكاظمه تعمل:

نافذة طرفيّة
kazma setup postgres --upgrade

لا يستطيع إصدار رئيسي من Postgres أن يفتح مجلد بيانات إصدار رئيسي آخر، فالجديد خادم ثانٍ يُملأ بنسخة:

  1. يثبّت الإصدار الرئيسي الجديد بجانب القديم، على منفذ احتياطي (55432 أو التالي الحر)، مع دور كاظمه، وكلمة المرور التي تستعملها كاظمه من قبل، ومجلد أرشيف WAL خاص به.
  2. حين لا يجري أي دور محادثة، يوقف كاظمه عبر حارسها، فلا يُكتب شيء أثناء نسخ البيانات.
  3. ينسخ قاعدة بيانات كاظمه بأداتَي pg_dump وpg_restore من الإصدار الرئيسي الجديد (بالدور kazma_app، في معاملة واحدة)، ثم يقارن عدد صفوف كل جدول وقيمة كل تسلسل.
  4. يبدّل الخادمين: الجديد على المنفذ القديم، والقديم يُوقف ويُزال من قائمة الإقلاع. ويبقى .env وكل عنوان آخر كما هو.
  5. يسجّل الخادم الجديد (والقديم تحت previous)، ويبدأ كاظمه، ويرى أنها سجّلت دخولها، ويأخذ أول نسخة احتياطية أساسية للخادم الجديد.

يُبقى الخادم القديم، متوقفًا، ببياناته وأرشيفه ونسخه الأساسية: فهو طريق العودة، والخادم الذي تقرأ منه الاستعادة إلى وقت سابق للنقل. أزله بمزيله الخاص حين تتيقن. وتُكتب كل مرحلة في kazma-data/setup_record.json أولًا. والتشغيل الذي يتوقف في أي موضع يمكن تشغيله مرة أخرى بأمان: فقبل التبديل ما زالت كاظمه تستعمل الخادم القديم، ولا يحوي الجديد إلا نسخة (لا تُستبدل إلا ما دامت كاظمه لم تبدأ عليها قط)؛ والتبديل الذي لم يكتمل يُتراجع عنه أولًا (يعود الخادم القديم إلى منفذه وإلى قائمة الإقلاع). والنسخة غير الكاملة، أو الخادم الجديد الذي لا يجيب على المنفذ القديم، يعيدان كاظمه إلى الخادم القديم دون تغيير. ويترك مراقِب قاعدة البيانات لدى الحارس الخدمتين وشأنهما ما دام تبديل جاريًا، 15 دقيقة على الأكثر. وقد جُرّب ذلك على ويندوز؛ أما خطوات Debian وFedora وmacOS فمختبرة على أوامر مديري حزمها، لا على جهاز بعدُ.

الانتقال عن حاوية Docker. أمر واحد ينقل كاظمه، وكاظمه تعمل:

نافذة طرفيّة
kazma setup postgres --port 5432 --move-from-container kazma-db-win

يُعدّ الخادم الجديد، ثم، حين لا يجري أي دور محادثة، يوقف كاظمه عبر حارسها، فلا يُكتب شيء في الحاوية أثناء نسخها. ينسخ قاعدة بيانات الحاوية (pg_dump داخل الحاوية، وpg_restore بالدور kazma_app)، ويقارن عدد صفوف كل جدول من جداول كاظمه، ولا يكتب العنوان الجديد في .env إلا بعد ذلك. ثم تبدأ كاظمه على قاعدة البيانات الجديدة؛ وما إن يُرى أنها سجّلت دخولها هناك حتى تُوقف الحاوية وتُحفظ (ولا تبدأ من جديد من تلقاء نفسها). والحاوية هي طريق العودة (شغّلها، وأعد العنوان القديم)؛ أزلها بـ docker rm حين تتيقن. أما كاظمه التي تعمل دون حارس يوقفها فيُرفض طلبها قبل أن يُفعل أي شيء: أوقفها بنفسك، ثم شغّل الأمر.

وإن شُغّل الأمر مرة أخرى فلا يستبدل نسخة سابقة على الخادم الجديد إلا إن لم تبدأ كاظمه عليها قط (فآخر بدء لها هناك ليس أحدث من بدئها على الحاوية) ولم يكن شيء متصلًا بها؛ وقاعدة البيانات التي بدأت عليها كاظمه لا يُكتب فوقها أبدًا. وعلى خدمة سليمة يسمّي .env عنوانها من قبل، يكون التشغيل الثاني نقلًا فحسب ولا يحتاج إلى طرفية بصلاحيات مرتفعة. وتحتفظ مرآة الذاكرة بعنوانها الخاص (memory.backends.state.url، وmemory.backends.vector.url): يوجّه النقل كل عنوان منها يسمّي الحاوية إلى الخادم الجديد، وكاظمه متوقفة. والعنوان المحفوظ نصًّا صريحًا بدل الخزنة يُسمّى، لتغيّره أنت في الإعدادات.

أقراص تطلب كلمة مرور عند الإقلاع. جهاز Mac مفعَّل عليه FileVault، وحاسوب ويندوز يطلب BitLocker فيه رمز PIN، وقرص Linux مشفّر بـ LUKS لا يُفتح بـ TPM: كلها تتوقف قبل أن يبدأ نظام التشغيل، فلا يبدأ شيء حتى يكتبها أحد. والجهاز الذي يجب أن يعود وحده بعد انقطاع الكهرباء يحتاج إلى الفتح بـ TPM (ويندوز وLinux)، أو إلى إطفاء FileVault (أو إعادة تشغيل مخطَّطة بـ fdesetup authrestart) على Mac.

أرشفة WAL والاستعادة إلى نقطة زمنية

Section titled “أرشفة WAL والاستعادة إلى نقطة زمنية”

قد يفقد التفريغ الذي يجري كل 6 ساعات أدناه ما يصل إلى ست ساعات. ومع أرشفة سجل الكتابة المسبقة (WAL) يُحفظ كل تغيير، ويمكن أن تتوقف الاستعادة عند أي دقيقة. يفعّلها kazma setup postgres: ‏archive_mode = on، ومقطع كل 5 دقائق على الأقل ما دام شيء يُكتب (archive_timeout = 300)، ويُنسخ كل مقطع مكتمل إلى مجلد الأرشيف (ويندوز C:\ProgramData\Kazma\pg_wal_archive-18، وDebian /var/lib/postgresql/18/wal_archive، وFedora /var/lib/pgsql/18/wal_archive، وmacOS kazma-data/backups/pg/wal-18؛ والتثبيت الذي أُنشئ قبل 18 يُبقي المجلد الذي يسمّيه سجلّه). ولكل إصدار رئيسي أرشيفه ونسخه الأساسية وأسماؤه خارج الموقع: فالإصدار الرئيسي الجديد يرقّم مقاطعه من البداية من جديد، فبجانب نسخة أساسية لإصدار رئيسي أقدم كان التقليم سيحسب مقاطع الإصدار الجديد مقاطع قديمة.

يقرأ مرور الصيانة “WAL archive” أرقام الخادم نفسه (pg_stat_archiver): المؤرشِف الذي يفشل، أو عدم أرشفة أي مقطع 15 دقيقة، ينبّه بـ backup.wal_archive_stale. ويأخذ نسخة احتياطية أساسية كل أسبوع (pg_basebackup في kazma-data/backups/pg/base-18/، ويُحتفظ باثنتين؛ وbase/ في تثبيت أُنشئ قبل 18)، ويقلّم WAL المؤرشف الذي لم تعد الأقدم تحتاج إليه، ويرسل المقاطع الجديدة والنسخ الأساسية إلى مزوّد النسخ الاحتياطي خارج الموقع (الذي يستخدمه النسخ الاحتياطي الشامل). ويقول kazma doctor هل الأرشيف محدَّث.

للاستعادة إلى وقت ما، في مجلد جديد (لا تُمسّ قاعدة البيانات الحية أبدًا):

نافذة طرفيّة
kazma restore postgres --to "2026-11-20 14:05" --into D:\pg-restore

يضع أحدث نسخة أساسية، ويُعدّها لإعادة تشغيل WAL المؤرشف حتى ذلك الوقت، ويطبع الخطوات الباقية: شغّلها على منفذ احتياطي، وافحصها، ثم بدّل. والوقت السابق لانتقال إلى Postgres أحدث يُستعاد من الخادم الذي حلّ محله ذلك الانتقال (فقد أُبقي أرشيفه ونسخه الأساسية)، ويُشغَّل ببرامج ذلك الإصدار الرئيسي نفسه؛ ويقول الأمر أيّها. ولا تؤرشف النسخة المستعادة أبدًا (archive_mode = 'off')، فلا تستطيع الكتابة في الأرشيف الحي.

افحص الاستعادة بالاتصال بها، لا بجواب pg_ctl: فقد يقول pg_ctl start -w إن خادمًا بدأ بينما فشل تعافيه بعد لحظة. والخادم الذي فشل يقول السبب في سجلّه (recovery ended before configured recovery target was reached يعني أن مقطعًا احتاجه لم يُعثر عليه). وقبل 2026-11-14 كانت كل استعادة إلى نقطة زمنية على ويندوز تفشل على هذا النحو: فقد أمر النسخ شرطاته المائلة العكسية. أعد الاستعادة بكاظمه محدَّثة.

ولتثبت أن نسخك الاحتياطية تعمل دون أن تمسّ شيئًا، استعِد إلى وقت قبل بضع دقائق (أحدث مقطع مؤرشف عمره 5 دقائق على الأكثر)، وشغّل النسخة على منفذ احتياطي وقارن جداولها بقاعدة البيانات الحية؛ ثم أوقفها واحذف المجلد. وحين فُعل ذلك على تثبيت المالك في 2026-11-14، طابقت النسخة النسخة الحية جدولًا بجدول (24 جدولًا، 99,935 صفًّا).

النسخ الاحتياطي والتعافي من الكوارث

Section titled “النسخ الاحتياطي والتعافي من الكوارث”

تنسخ كاظمه جداول Postgres الخاصة بها احتياطيًا بشكل آلي (أُضيف ذلك بعد حادثة 2026-08-14 التي حذف فيها تطبيق آخر جداول كاظمه من قاعدة بيانات مشتركة):

  • كل 6 ساعات، آلي: تُفرِغ حلقة النسخ/التصدير الجداول المذكورة في kazma_core.db.pg_backup.KAZMA_PG_TABLES بالضبط إلى {kazma-data}/backups/pg/pg_shared_<epoch>.dump (صيغة -Fc المخصصة، كتابة ذرّية، تحقق بالبصمة السحرية؛ يُحتفظ بثلاثة تفريغات محلية، وrestic يحفظ التاريخ → backups.pg.retention / KAZMA_PG_BACKUP_RETENTION). أول تفريغ بعد ~2 دقيقة من الإقلاع. التمرين العميق الأسبوعي يسترجع أحدثها إلى قاعدة بيانات مؤقتة، ويفحصها ثم يُسقطها (مفعّل افتراضيًا منذ 2026-09-27؛ التعافي من الكوارث).
  • تفريغ يدوي الآن: python scripts/pg_backup.py backup
  • الاسترجاع: python scripts/pg_backup.py restore --latest (--file <name>، و--dry-run، وlist). يسترجع جداول كاظمه نفسها فقط — لا يُمَسّ تطبيق خارجي يشارك القاعدة أبدًا.
  • حارس الإقلاع: إن غاب جدول مطلوب عند الإقلاع، يسجّل الخادم CRITICAL مع أمر الاسترجاع بدل العرج مع أخطاء UndefinedTable.
  • مفتاح الإيقاف: KAZMA_PG_BACKUP_ENABLED=0 (أو backups.pg.enabled=false).
  • التفريغ مُرشَّح حسب الجداول عمدًا — وليس تفريغ قاعدة كاملة أبدًا — فلا تتسرب بيانات أي تطبيق خارجي إلى نسخ كاظمه الاحتياطية.

استخدم docs/ops/DISASTER_RECOVERY.md مع pg_dump لـ Postgres. بعد الاسترجاع، يجب أن تتطابق الأسرار (KAZMA_VAULT_KEY, KAZMA_SECRET).