التحويل إلى Postgres وSaaS
تعدد مستخدمي SaaS + التحويل الكامل إلى Postgres
Section titled “تعدد مستخدمي SaaS + التحويل الكامل إلى Postgres”ما الذي ينتقل إلى Postgres عند ضبط KAZMA_DATABASE_URL
Section titled “ما الذي ينتقل إلى Postgres عند ضبط KAZMA_DATABASE_URL”| المخزن | الجدول(ات) | الوحدة |
|---|---|---|
| الضبط / الإعدادات / مستخدمو المنصة | kazma_settings | config_store.py |
| جلسات الدردشة | kazma_chat_sessions | session_manager.py |
| مهام السرب + المقاييس | kazma_swarm_tasks, kazma_swarm_worker_metrics | task_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 الافتراضي عند عدم ضبط عنوان قاعدة بيانات (الاختبارات، والعقدة المحلية الواحدة).
بحث الذاكرة (pgvector)
Section titled “بحث الذاكرة (pgvector)”ضبط 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).
- تنشئ كاظمه الامتداد والجدول عند أول استخدام عندما يسمح دورها بذلك.
وإلا فبصفتك مستخدمًا أعلى:
CREATE EXTENSION IF NOT EXISTS vector;في قاعدة بيانات كاظمه، وامنح الدورCREATEعلى مخططها. - تفحص كاظمه عند الإقلاع وعند كل بحث في الذاكرة (مخزّنًا مؤقتًا دقيقة
واحدة):
- اختيار pgvector تلقائيًا (بلا اختيار صريح) على Postgres بلا الامتداد: سطر INFO واحد، وتبقى الذاكرة على sqlite-vec، وتعرض الإعدادات ← الذاكرة Vector: full (local) مع السبب.
- pgvector مُختار في الإعدادات لكنه غير قابل للاستخدام (لا امتداد، الدور لا يستطيع إنشاءه، جدول بحجم متجه آخر، خادم متوقف): تحذير WARNING واحد يسمّي الإصلاح، ولافتة الإعدادات تقول الشيء نفسه.
- Test vector في الإعدادات ← الذاكرة يشغّل الفحص نفسه عند الطلب. حين اختير pgvector تلقائيًا والامتداد غائب، يختبر المخزن المستخدم فعلًا (sqlite-vec المحلي) ويبلّغ Vector OK مع ملاحظة تشرح لماذا لا يُستخدم pgvector؛ أما pgvector اخترته أنت ولا يمكنه العمل فيبلّغ Vector failed مع الإصلاح.
- أعد بناء التضمينات مرة واحدة إن كان لديك سجل بالفعل: الإعدادات ← الذاكرة ← إعادة بناء التضمينات (upsert إلى pgvector).
- تغيير حجم المضمِّن: الجدول مُقاس على المضمِّن ولا يُعاد تقاسه أبدًا.
وجّه
memory.backends.vector.collectionإلى اسم جديد، ثم أعد بناء التضمينات. - مفتاح الإيقاف:
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 وحده.
إجراء التحويل
Section titled “إجراء التحويل”- ثبّت الإضافات:
pip install -e ".[postgres]" - شغّل Postgres:
نافذة طرفيّة docker compose -f docker-compose.postgres.yml up -d db - هاجر بـكل المخازن:
نافذة طرفيّة export KAZMA_DATABASE_URL=postgresql://kazma:PASSWORD@localhost:5432/kazmapython scripts/migrate_sqlite_to_postgres.py --data-dir kazma-data - شغّل كاظمه بالعنوان نفسه (يضبطه compose تلقائيًا).
- فحص سريع:
- تسجيل الدخول (مستخدم / سر / OIDC)
- تاريخ الدردشة يبقى عبر إعادة التشغيل
- قائمة مهام السرب
- الإعدادات تُحفَظ
واجهة تعدد المستخدمين
Section titled “واجهة تعدد المستخدمين”/login— تبويبات المستخدم · السر · SSO- الإعدادات ← الحساب — المستخدمون + المستأجرون (المشرف)
- الترويسة — شارة الدور + تسجيل الخروج
إنشاء مشرف:
from kazma_core.security.platform_rbac import create_local_usercreate_local_user("admin", "long-password-here", role="admin")قائمة فحص البيئة
Section titled “قائمة فحص البيئة”KAZMA_DATABASE_URL=postgresql://…KAZMA_DB_BACKEND=postgres # optional forceKAZMA_PRODUCTION=1KAZMA_VAULT_KEY=…KAZMA_SECRET=…KAZMA_PUBLIC_URL=https://…# OIDC optionalKAZMA_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، وتفريغًا، وبروفة الاستعادة بالدور الجديد.
-
شغّل السكربت بالمستخدم الخارق، في قاعدة بيانات كاظمه:
نافذة طرفيّة 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فقد أمسك استعلام طويل بجدول: شغّله مجددًا حين تكون كاظمه خاملة. تواصل كاظمه عملها طوال ذلك: فهي ما تزال تسجّل دخولها بالمستخدم الخارق حتى إعادة التحميل. -
أنشئ كلمة مرور من حروف وأرقام و
-و_(أي شيء آخر يجب ترميزه بالنسبة المئوية في العنوان):نافذة طرفيّة python -c "import secrets; print(secrets.token_urlsafe(24))"وضع العنوان الجديد في
.env، مبقيًا على المضيف والمنفذ واسم قاعدة البيانات:KAZMA_DATABASE_URL=postgresql://kazma_app:<password>@127.0.0.1:5433/kazma. -
أعطِ الدور كلمة المرور نفسها، مقروءةً من
.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). -
تحقّق من تسجيل الدخول قبل إعادة التحميل، بـ 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 بلا كلمة مرور. -
إن كانت مرآة الذاكرة مفعّلة (الإعدادات -> الذاكرة -> خلفيات الذاكرة -> الحالة المشتركة مضبوطة على Postgres)، فاضبط Postgres DSN الخاص بها على العنوان نفسه واضغط حفظ الخلفيات. فهي تحتفظ بنسختها الخاصة من العنوان.
-
أعد التحميل:
python scripts/service/kazma_guard.py --reload --when-idle. -
تحقّق: لم يعد سجل الإقلاع يحمل تحذير المستخدم الخارق، ويجيب
/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/11 | winget (PostgreSQL.PostgreSQL.18، مثبّت EDB، دون تدخّل) | خدمة ويندوز postgresql-x64-18، بنوع بدء Automatic، وتُعاد عند الفشل | نعم |
| macOS | Homebrew postgresql@18 | sudo 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 يكتفي بالتقرير):
- يثبّت مشغّل Postgres الخاص بكاظمه (الحزمة الإضافية
kazma[postgres]: psycopg) في بيئة Python التي تعمل فيها كاظمه، إن لم يكن موجودًا. فمن دونه يكون لدى كاظمه عنوان ولا سبيل إلى الوصول إليه، وينتظر الخادم عند البدء قائلًا إن المشغّل غير مثبّت. والتشغيل الثاني يثبّته أيضًا. وإن لم يُثبَّت فلا يُفعل شيء بعده. - يثبّت Postgres 18 خدمةً تبدأ مع الإقلاع وتُعاد حين تفشل، وتستمع على هذا
الجهاز وحده (
listen_addresses = 'localhost')، مع تسجيل الدخول بـscram-sha-256. (والتثبيت الذي أُنشئ قبل 13 نوفمبر 2026 يشغّل Postgres 16؛ انظر “الانتقال إلى Postgres أحدث” أدناه.) - ينشئ قاعدة البيانات
kazmaوالدورkazma_app(ليس مستخدمًا خارقًا،deploy/postgres/kazma_app_role.sql). - يفعّل أرشفة WAL (أدناه).
- يكتب
KAZMA_DATABASE_URLفي.envالخاص بالتثبيت (لا يُطبع أبدًا؛ والملف مقصور على حسابك)، ويسجّل الدخول مرة واحدة كما ستفعل كاظمه. - يسجّل ما فعله في
kazma-data/setup_record.json: منه يفحصkazma doctorالخدمة، ويراقب الحارس الخدمة (يبدأ الخدمة التي توقفت مرة واحدة لكل انقطاع، وينبّه مرة واحدة إن ظلت متوقفة).
تُحفظ كلمة مرور المستخدم الخارق في <install>/.kazma/postgres_superuser.pass
(لحسابك وحده)؛ ولا توضع أي كلمة مرور في سطر أوامر، إلا كلمة المرور المؤقتة
لمثبّت ويندوز، التي تستبدلها الخطوة التالية. والتشغيل الثاني يفحص ويُصلح، ولا
يعيد التثبيت أبدًا: يُصلح Postgres الذي يسمّيه السجل (16 في تثبيت أقدم)، ولا
يثبّت آخر بجانبه أبدًا. شغّله على ويندوز من طرفية بصلاحيات مرتفعة.
الانتقال إلى Postgres أحدث. يقول kazma doctor حين تعمل قاعدة البيانات
بإصدار رئيسي أقدم مما تثبّته كاظمه الآن (16 قبل 18). وأمر واحد ينقلها، وكاظمه
تعمل:
kazma setup postgres --upgradeلا يستطيع إصدار رئيسي من Postgres أن يفتح مجلد بيانات إصدار رئيسي آخر، فالجديد خادم ثانٍ يُملأ بنسخة:
- يثبّت الإصدار الرئيسي الجديد بجانب القديم، على منفذ احتياطي (55432 أو التالي الحر)، مع دور كاظمه، وكلمة المرور التي تستعملها كاظمه من قبل، ومجلد أرشيف WAL خاص به.
- حين لا يجري أي دور محادثة، يوقف كاظمه عبر حارسها، فلا يُكتب شيء أثناء نسخ البيانات.
- ينسخ قاعدة بيانات كاظمه بأداتَي
pg_dumpوpg_restoreمن الإصدار الرئيسي الجديد (بالدورkazma_app، في معاملة واحدة)، ثم يقارن عدد صفوف كل جدول وقيمة كل تسلسل. - يبدّل الخادمين: الجديد على المنفذ القديم، والقديم يُوقف ويُزال من قائمة
الإقلاع. ويبقى
.envوكل عنوان آخر كما هو. - يسجّل الخادم الجديد (والقديم تحت
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). - التفريغ مُرشَّح حسب الجداول عمدًا — وليس تفريغ قاعدة كاملة أبدًا — فلا تتسرب بيانات أي تطبيق خارجي إلى نسخ كاظمه الاحتياطية.
التعافي من الكوارث (DR)
Section titled “التعافي من الكوارث (DR)”استخدم docs/ops/DISASTER_RECOVERY.md مع pg_dump لـ Postgres. بعد الاسترجاع، يجب أن تتطابق الأسرار (KAZMA_VAULT_KEY, KAZMA_SECRET).

