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

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

ما الذي ينتقل إلى 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)

ضبط 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=…

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

تنسخ كاظمه جداول 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)

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