النشر

نموذجا النشر

محلياً: Docker Compose

يأتي مستودع الإطار مع حزمتين كاملتين — التطبيق، وPostgreSQL (مع pgvector)، وRedis، وVault، وحزمة لقابلية المراقبة:

docker compose -f compose-grafana.yml up --build      # Grafana stack
docker compose -f compose-opensearch.yml up --build   # OpenSearch Dashboards stack

تحصل المشاريع المُولَّدة على ملف compose.yml خاص بها (app + postgres + redis + vault) — راجع وكيلك الأول.

الإنتاج: Kubernetes مع Terraform

يوفّر Agent-Lab سكربتات Terraform تنشر التطبيق وتبعياته على Kubernetes. يستخدم هذا الشرح عنقود Minikube لأغراض مرجعية — استخدم عنقوداً جاهزاً للإنتاج في عمليات النشر الفعلية.

المتطلبات الأساسية

• Terraform
• kubectl
• jq

إعداد عنقود Kubernetes

Minikube (Linux) — خصّص موارد كافية (فالحزمة المرجعية كثيفة الاستهلاك):

minikube start --memory=20g --cpus=4

احصل على عنوان IP للعنقود واربط نطاقات الخدمات به:

minikube ip
# 192.168.49.2

192.168.49.2 vault.my-domain.com kibana.my-domain.com elasticsearch.my-domain.com agent-lab.my-domain.com litellm.my-domain.com

Docker Desktop (Mac / Windows) — فعّل Kubernetes المضمّن:

مع Docker Desktop، تُحَلّ النطاقات عبر localhost:

127.0.0.1 vault.my-domain.com kibana.my-domain.com elasticsearch.my-domain.com agent-lab.my-domain.com litellm.my-domain.com

تجهيز التبعيات

توجد كل الوحدات أدناه في terraform/ — طبّقها باستخدام terraform init && terraform apply في كل مجلد، بهذا الترتيب:

نسخة Keycloak (09_keycloak-instance/)، ثم احصل على كلمة مرور المسؤول:

echo "$(kubectl --namespace keycloak get secret/keycloak-initial-admin -o go-template='{{index .data "password" | base64decode}}')"

اضبط اتصال OIDC وفق المصادقة باستخدام Keycloak، أو دع الوحدة 12_agent-lab-auth-realm/ تتولى ذلك (أدناه).

تهيئة Vault (بعد تطبيق 08_vault-instance/) — نفّذ التهيئة وفك الختم (unseal):

kubectl --namespace vault exec vault-0 -- vault operator init \
    -key-shares=1 \
    -key-threshold=1 \
    -format=json > cluster-keys.json

export VAULT_UNSEAL_KEY=$(jq -r ".unseal_keys_b64[]" cluster-keys.json)
kubectl --namespace vault exec vault-0 -- vault operator unseal $VAULT_UNSEAL_KEY

قابلية المراقبة (اختيارية لكن يُوصى بها) — منصات قابلية مراقبة LLM التي تستخدمها حزمة المحاكاة والواجهات الخلفية للتتبّع:

استرجع بيانات اعتماد Elastic:

echo "$(kubectl --namespace elastic get secret elasticsearch-es-elastic-user -o=jsonpath='{.data.elastic}' | base64 --decode)"

echo "$(kubectl --namespace elastic get secret/elastic-eck-apm-server-apm-token \
    -o go-template='{{index .data "secret-token" | base64decode}}')"

OpenTelemetry Collector (11_otel-instance/) — نقطة نهاية OTLP التي يصدّر التطبيق إليها (قابلية المراقبة).

بوابة LiteLLM (17_litellm-instance/) — بوابة LLM ذاتية الاستضافة متوافقة مع OpenAI، مع مفاتيح افتراضية وتتبّع للإنفاق وواجهة إدارة (/ui):

echo "$(kubectl --namespace litellm get secret/litellm-masterkey -o go-template='{{index .data "masterkey" | base64decode}}')"

curl -s https://<litellm_fqdn>/health/readiness

نشر Agent-Lab

تربط ثلاث وحدات كل شيء معاً:

cd terraform/12_agent-lab-auth-realm/ && terraform init && terraform apply
cd terraform/15_agent-lab-dependencies/ && terraform init && terraform apply
cd terraform/16_agent-lab-instance/ && terraform init && terraform apply

ملاحظة حول الأسرار: يقرأ النشر إعداداته من Vault عند بدء التشغيل (secret/app_secrets) — ومفاتيح الحمولة مدرجة في مرجع الإعدادات.

مخطط Helm

يأتي المستودع أيضاً مع مخطط Helm باسم charts/agent-lab، يحزم نشر التطبيق مع الحاويات المرافقة (sidecars): Chrome بلا واجهة (CDP) لوكلاء الويب، وHPA، والدخول (ingress)، والإعدادات، وحساب الخدمة. استخدمه عندما تكون لديك تبعياتك الخاصة قيد التشغيل مسبقاً وتريد تثبيت التطبيق فقط.

قائمة التحقق

قبل اعتبار العمل منجزاً، تحقّق مما يلي:

• يُرجع GET /status/liveness وGET /status/readiness الرمز 200
• يُعرض GET /docs ويستجيب GET /agents/list (مع رمز مميز عند تفعيل المصادقة)
• تصل التتبّعات إلى نقطة نهاية OTLP الخاصة بك (راجع قابلية المراقبة)
• يحتوي Vault على secret/app_secrets مع جميع مفاتيح الحمولة
• يحتوي الـ realm في Keycloak على عميل وحساب خدمة