النشر

مسارات نشر الإنتاج لكاظمة: Docker Compose (الأساسي)، وKubernetes (خدمة المركز Hub)، والنشر الأصلي على Windows، وإدارة الخوادم. ملاحظات صادقة حول ما تنشره كل بيئة فعلًا.

1. أهداف النشر في لمحة

الهدف	ما الذي تنشره	الحالة
Docker Compose (`docker-compose.yml` + `Dockerfile`)	وكيل كاظمة الرئيسي + واجهة الويب (uvicorn).	الأساسي، جاهز للإنتاج.
النشر الأصلي على Windows (`setup.ps1`)	إقلاع بيئة افتراضية محلية للتطوير.	نشِط.
Kubernetes (`kubernetes/`)	خدمة Hub API منفصلة — ليست وكيل كاظمة الرئيسي.	راجع §4.
Cloudflare Pages / عمّال الحافة	—	غير قابل للتطبيق. كاظمة خادم Python/uvicorn وليست نشرًا على الحافة.
uvicorn مباشرةً	الوكيل الرئيسي.	`kazma serve` / `kazma-web`.

ملاحظة صادقة: ذكرت مهام أقدم «Cloudflare Pages وعمّال الحافة بلا خادم.» كاظمة خدمة Python ذات حالة (LangGraph + SQLite + ChromaDB اختياري). لم تُصمَّم للنشر بلا خادم/على الحافة. تغطي مهارات أدوات MCP في هذه البيئة Cloudflare Workers، لكنها لا علاقة لها بنشر كاظمة نفسها.

2. Docker Compose (موصى به للإنتاج)

2.1 ملف Dockerfile

FROM python:3.11-slim
WORKDIR /app

# System deps for ChromaDB + sentence-transformers
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential curl \
    && rm -rf /var/lib/apt/lists/*

COPY . .

# RAG extras (chromadb + sentence-transformers)
RUN pip install --no-cache-dir -e ".[rag]"

# Non-root user (least-privilege)
RUN useradd -r -m -d /home/kazma -s /bin/bash kazma \
    && mkdir -p /app/kazma-data /home/kazma/.kazma/vector_memory \
    && chown -R kazma:kazma /app /home/kazma
USER kazma

EXPOSE 8000

# host=0.0.0.0 is required inside Docker so the port mapping reaches the service.
# Docker's network isolation provides the security boundary.
CMD ["python", "-m", "uvicorn", "kazma_ui.app:create_app", "--factory", \
     "--host", "0.0.0.0", "--port", "8000", "--timeout-graceful-shutdown", "15"]

النقاط الرئيسية:

يُثبِّت .[rag] (ChromaDB + sentence-transformers) — مطلوب للذاكرة المتجهة.
يعمل كمستخدم غير جذر kazma (أقل امتياز).
الخيار --host 0.0.0.0 مطلوب داخل الحاوية كي يصل المنفذ المنشور إلى الخدمة. عزل شبكة Docker هو حدّ الأمان (التعليق داخل Dockerfile يوضّح ذلك).
الخيار --timeout-graceful-shutdown 15 يمنح الطلبات الجارية 15 ثانية لتفريغها.

2.2 docker-compose.yml

version: "3.8"
services:
  kazma:
    build: .
    container_name: kazma
    ports:
      - "8000:8000"
    volumes:
      - kazma_data:/app/kazma-data
      - kazma_vectors:/root/.kazma/vector_memory
    env_file:
      - .env
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/api/gateway/status"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

volumes:
  kazma_data:
    driver: local
  kazma_vectors:
    driver: local

وحدتا تخزين مسمّاتان تبقيان مخازن SQLite ومتجهات ChromaDB.
يضرب فحص الصحة المسار /api/gateway/status كل 30 ثانية.
الخيار restart: unless-stopped يصمد أمام إعادة تشغيل المضيف.

تحذير بشأن مسار وحدة التخزين: تُحمِّل وحدة التخزين kazma_vectors المسار /root/.kazma/vector_memory، لكن الحاوية تعمل كمستخدم kazma (مجلد المنزل /home/kazma). إن اعتمدت على المسار الافتراضي KAZMA_VECTOR_PATH (~/.kazma/vector_memory)، فتأكد أن ~ يُحَلّ إلى /home/kazma للمستخدم kazma، أو اضبط KAZMA_VECTOR_PATH=/app/kazma-data/vector_memory صراحةً ليطابق وحدة تخزين البيانات.

2.3 خطوات النشر

cp .env.example .env
# Edit .env: set OPENAI_API_KEY, KAZMA_SECRET, any platform tokens
# Generate a strong secret:
#   openssl rand -hex 32   # → put in KAZMA_SECRET

docker compose up -d --build
docker compose logs -f kazma

للتحقق:

curl -s http://localhost:8000/health/live

2.4 `.dockerignore`

يستثني archive/، و__pycache__/، و.venv/، و.git/، وtests/، وkazma-data/، وkubernetes/، وdocs/، و*.md، و.env، و*.db، وذاكرات البناء — لإبقاء الصورة خفيفة وإبعاد الأسرار.

3. uvicorn مباشرةً (دون Docker)

# Development / single-host
pip install -e ".[rag]"
kazma serve                 # 127.0.0.1:8000
# or explicit:
python -m uvicorn kazma_ui.app:create_app --factory --host 127.0.0.1 --port 8000

لمضيف عام مواجه للجمهور خلف وكيل عكسي:

# ONLY with KAZMA_SECRET set does `kazma serve` bind 0.0.0.0
KAZMA_SECRET=$(openssl rand -hex 32) kazma serve

لا تعرّض 0.0.0.0 أبدًا دون ضبط KAZMA_SECRET. إذ ستكون نقطة نهاية الموافقة البشرية في الحلقة (HITL) غير مُصادَقة وإلا. ضع كاظمة خلف nginx/Caddy/Traefik مع TLS ودع الوكيل العكسي يحمل المقبس العام.

4. Kubernetes (خدمة المركز Hub فقط — اقرأ بعناية)

يحتوي الدليل kubernetes/ على بيانين:

kubernetes/hub-deployment.yaml — يعرف Namespace، وDeployment (3 نسخ متماثلة)، وService، وIngress لصورة باسم kazma/hub-api:latest.
kubernetes/hub-secrets.yaml — يعرّف Secret يحوي database-url (PostgreSQL) وredis-url.

spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: hub-api
        image: kazma/hub-api:latest
        ports:
        - containerPort: 8000
        env:
        - name: DATABASE_URL       # PostgreSQL — NOT used by the main Kazma agent
          valueFrom:
            secretKeyRef: { name: hub-secrets, key: database-url }
        - name: REDIS_URL          # Redis — NOT used by the main Kazma agent
          valueFrom:
            secretKeyRef: { name: hub-secrets, key: redis-url }
        livenessProbe:
          httpGet: { path: /api/v1/health, port: 8000 }

تحذيرات جوهرية

هذه تنشر خدمة المركز (Hub)، وليس وكيل كاظمة الرئيسي. الصورة kazma/hub-api:latest غير مبنية من Dockerfile هذا المستودع وغير منشورة منه.
البنية التحتية المُشار إليها لا تتطابق مع قاعدة الشيفرة الرئيسية. يستخدم وكيل كاظمة الرئيسي SQLite (WAL) في كل مكان (ConfigStore، والنقطة المرجعية checkpointer، وTaskStore، واللقطات snapshots، والذاكرة المتجهة عبر ChromaDB). هو لا يقرأ DATABASE_URL أو REDIS_URL، ولا يملك أي عميل PostgreSQL أو Redis. هذه المتغيرات البيئية تخصّ خدمة Hub API منفصلة (طموحة أو خارجية).
مسار فحص الصحة /api/v1/health يختلف عن مسارات التطبيق الرئيسي /health/live و/health/ready (kazma-ui/.../health.py:94,104).
حدود الموارد (256Mi–512Mi، 250m–500m) معقولة لواجهة برمجية عديمة الحالة، لكنها أصغر من اللازم للوكيل الرئيسي إن حمِّلت ChromaDB + sentence-transformers (هذه وحدها قد تتجاوز 512 ميبيبايت).

التوصية: تعامل مع kubernetes/ كنقطة انطلاق لنشر خدمة Hub API منفصلة. لنشر وكيل كاظمة الرئيسي على Kubernetes، اكتب بيانًا جديدًا يستخدم Dockerfile المستودع، ومسبار /health/live، وقيمة KAZMA_SECRET صريحة، وPVC لكل من kazma-data/ ومسار المتجهات، وحدود موارد كافية لإضافات RAG (≥1 جيجابايت للذاكرة).

5. النشر الأصلي على Windows (`setup.ps1`)

السكربت setup.ps1 هو إقلاع Windows حتمي وسريع الفشل ومُكتفٍ ذاتيًا (PowerShell 5.0+). يقوم بـ:

التحقق من صحة البيئة (Python 3.11+، وuv، وkazma.yaml).
مزامنة البيئة الافتراضية من pyproject.toml.
تشغيل فحص سلامة للأساس (الاستيرادات الأساسية + جمع الاختبارات).

.\setup.ps1
.\setup.ps1 -Debug     # verbose

قاعدة PowerShell (من AGENTS.md): لا تسلسل الأوامر باستخدام && أو ||. استخدم ; وتحقق من $LASTEXITCODE. أداة Bash في هذه البيئة تستخدم Git Bash، وليس PowerShell.

6. إدارة الخادم (من AGENTS.md)

النمط القياسي لإيقاف الخادم وإعادة تشغيله (PowerShell):

# Kill any existing Kazma uvicorn server
Get-Process -Name python -ErrorAction SilentlyContinue |
  Where-Object { (Get-CimInstance Win32_Process -Filter ('ProcessId=' + $_.Id)).CommandLine -like '*uvicorn*kazma*' } |
  ForEach-Object { Stop-Process -Id $_.Id -Force }

# Start (background), dev port 8090
cd 'G:\GitHubRepos\kazma'
& '.venv\Scripts\python.exe' -m uvicorn kazma_ui.app:create_app --factory --host 127.0.0.1 --port 8090

7. نقاط نهاية فحص الصحة

نقطة النهاية	الغرض	الموقع
`GET /health/live`	الحياة (Liveness)	`health.py:94`
`GET /health/ready`	الجاهزية (Readiness)	`health.py:104`
`GET /health/details`	صحة تفصيلية	`health.py:148`
`GET /api/gateway/status`	حالة البوابة/المحوّلات (يستخدمها فحص صحة Docker + `kazma status`)	موجّه البوابة

8. قائمة فحص الإنتاج

9. اعتبارات الموارد (إعدادات 24 جيجابايت VRAM)

تذكر ملاحظات المستودع «قيود الموارد على إعدادات 24 جيجابايت VRAM.» إرشادات عملية:

مكتبة sentence-transformers (all-MiniLM-L6-v6-v2) ملائمة للـ CPU (~90 ميبيبايت) — لا تحتاج GPU. VRAM ذو صلة فقط إذا وجّهت كاظمة نحو خادم نموذج محلي على GPU (Ollama/LM Studio/vLLM).
للاستدلال بنموذج لغة محلي، يملك خادم النموذج (لا كاظمة) ميزانية الـ VRAM. كاظمة نفسه مجرد عميل httpx خفيف تجاه ذلك الخادم.
ChromaDB معتمِدة على ملفات معيّنة في الذاكرة؛ اعتمد حجم وحدة تخزين المتجهات وفقًا لذلك.

ملاحظات تدقيق الوثائق

kubernetes/ تنشر خدمة Hub API، وليست الوكيل الرئيسي، وتُشير إلى PostgreSQL + Redis اللذين لا تستخدمهما قاعدة الشيفرة الرئيسية. تم تمييز ذلك بوضوح لمنع النشر الخاطئ.
عدم تطابق مسار وحدة التخزين (/root/.kazma/... مقابل مجلد منزل المستخدم kazma) في docker-compose.yml — اضبط KAZMA_VECTOR_PATH صراحةً على سبيل الاحتياط.
لا مسار للنشر على Cloudflare/الحافة. كاظمة خدمة Python ذات حالة؛ لا تحاول التغليف بلا خادم.
يختلف مسار فحص الصحة بين بيان Kubernetes (/api/v1/health) والتطبيق الفعلي (/health/live).