monitor v0.44.0
مراقبة في الوقت الفعلي وتحليل سجل الاستعلامات البطيئة (slowlog) لقواعد بيانات Valkey وRedis مع كشف الشذوذ وتدقيق قوائم التحكم بالوصول (ACL) وتصدير مقاييس Prometheus.
BetterDB Monitor
طبقة المراقبة التي يستحقها Valkey.
يحتفظ BetterDB بما يتخلص منه Valkey - السجلات البطيئة، وأنماط الأوامر، ونشاط العملاء، وإشارات الشذوذ - حتى تتمكن من تصحيح ما حدث في الساعة 3 صباحًا، وليس فقط ما يحدث الآن. مصمم لـ Valkey 8.x مع دعم أصلي لـ COMMANDLOG وCLUSTER SLOT-STATS ومقاييس الإدخال/الإخراج لكل خيط. متوافق مع Redis 6+ لكل ما عدا ذلك.
الموقع الإلكتروني | Docker Hub | npm | التوثيق | المدونة
تم بناء BetterDB بواسطة BetterDB Inc.، وهي شركة ذات منفعة عامة تعمل بموجب OCV Open Charter.
البدء السريع (Docker)```bash
docker run -d --name betterdb -p 3001:3001 betterdb/monitor:latest
وجّه متصفحك إلى `http://localhost:3001`. لمراقبة نسخة محددة:```bash
docker run -d \
--name betterdb \
-p 3001:3001 \
-e DB_HOST=your-valkey-host \
-e DB_PORT=6379 \
-e DB_PASSWORD=your-password \
betterdb/monitor:latest
هل تتصل بقاعدة بيانات على جهاز المضيف الخاص بك؟ داخل الحاوية
localhostهي الحاوية نفسها، وليس المضيف الخاص بك — لذا استخدمhost.docker.internalكمضيف قاعدة البيانات. على Docker Desktop (macOS/Windows) يعمل هذا مباشرةً؛ وعلى Linux أضف--add-host=host.docker.internal:host-gatewayإلى أمرdocker runحتى يُحلّ الاسم. زر "الاتصال بالنسخة المحلية" بنقرة واحدة في لوحة التحكم يكتشف هذا تلقائيًا ويملأ المضيف الصحيح نيابةً عنك.
يتم نشر نسختين من الصورة، وكلتاهما متعددة المعماريات (linux/amd64، linux/arm64):
| الوسم | ما هو |
|---|---|
latest، X.Y.Z-no-ai | الصورة الافتراضية - تتضمن كل ميزات المراقبة، دون التبعيات الخاصة بمساعد الذكاء الاصطناعي المحلي التجريبي (local-LLM AI Helper) |
X.Y.Z | تضيف مساعد الذكاء الاصطناعي التجريبي (أحضر Ollama الخاص بك؛ معطّل افتراضيًا عبر AI_ENABLED) |
راجع نشر Docker للإنتاج للتخزين الدائم، والمنافذ المخصصة، والترخيص، والإعدادات المعزولة عن الشبكة.
البدء السريع (Kubernetes / Helm)```bash
helm repo add betterdb https://docs.betterdb.com/charts
helm repo update
helm install betterdb-monitor betterdb/betterdb-monitor
--namespace betterdb --create-namespace
--set db.host=my-valkey.default.svc.cluster.local
--set db.password=yourpassword
ثم `kubectl port-forward -n betterdb svc/betterdb-monitor 3001:3001` وافتح `http://localhost:3001`، أو فعّل ingress الخاص بالـ chart. السجل المدعوم بـ PostgreSQL، وإحضار Secrets الخاصة بك، والترخيص في البيئات المعزولة (air-gapped) كلها مشروحة في [دليل Kubernetes](https://docs.betterdb.com/kubernetes) و[README الخاص بالـ chart](https://github.com/betterdb-inc/monitor/blob/master/charts/betterdb-monitor/README.md).
## البدء السريع (CLI)
شغّل BetterDB Monitor بدون Docker:```bash
npx @betterdb/monitor
عند التشغيل الأول، يرشدك معالج إعداد تفاعلي عبر اتصال قاعدة البيانات، وخلفية التخزين (SQLite أو PostgreSQL أو في الذاكرة)، وإعدادات الخادم. يتم حفظ الإعدادات في ~/.betterdb/config.json.```bash
npm install -g @betterdb/monitor # global install
betterdb --setup # re-run setup wizard
betterdb --port 8080 # override server port
betterdb --db-host 1.2.3.4 # override database host
betterdb --help # all options
يتطلب Node.js >= 20.0.0 ونسخة Valkey أو Redis للمراقبة. لتخزين SQLite، يلزم أيضًا `npm install -g better-sqlite3`.
## ما الذي تحصل عليه
### شاهد كل شيء، واحتفظ بكل شيء
- **تحليلات تاريخية** - استعلم عن slowlogs وأنماط الأوامر ونشاط العملاء وزمن الاستجابة عبر أي نطاق زمني. البيانات التي كانت تختفي بعد تدوير السجلات.
- **دعم COMMANDLOG** - حصري لـ Valkey 8.1+. الطلبات الكبيرة والردود الكبيرة، وليس فقط البطيئة منها.
- **جلسات التقاط MONITOR** - سجّل حركة المرور الفعلية عند الطلب: متابعة مباشرة، تصفية، إعادة تشغيل، تصدير إلى JSON/CSV، والربط المرجعي مع سجل الاتصالات.
- **تتبع المفاتيح الساخنة** - أعلى المفاتيح حسب تكرار الوصول مع تغيّر الترتيب بمرور الوقت. يضيف Key Analytics (Pro، مجاني في الوصول المبكر) النوع وTTL وتوزيعات الحجم من أخذ العينات المباشر.
- **رؤية العنقود** - رسوم بيانية للطوبولوجيا، خرائط حرارية لـ SLOT-STATS، وحدة المعالجة المركزية لكل فتحة وتوزيع المفاتيح.
- **مقاييس خيوط CPU وI/O** - رؤية لكل خيط لا يمكن لأي أداة Redis توفيرها.
- **تحليلات العملاء** - اعرف بالضبط أي خدمة مسؤولة عن ماذا، منسوبة حسب اسم العميل والنمط.
- **سجل تدقيق ACL** - تتبّع من وصل إلى ماذا، محفوظ للامتثال وتصحيح الأخطاء بعد الحوادث.
### افهم وتصرّف
- **كشف الشذوذ** (Pro، مجاني في الوصول المبكر) - تعلّم تلقائي لخط الأساس مع أحداث مترابطة وتشخيصات بلغة واضحة. أكثر من 20 كاشفًا، بدون عتبات يدوية.
- **التنبؤ بالسعة** - الوقت المتوقع للوصول إلى الحد الأقصى للذاكرة والعمليات/ثانية وCPU والتجزئة.
- **Webhooks** - تسليمات تنبيه موقّعة بـ HMAC مع إعادة المحاولات وسجل تسليم كامل.
- **الترحيل المباشر** - التنقل بين Redis وValkey عبر سير عمل من ثلاث مراحل: التحليل والتنفيذ والتحقق.
### مصمّم لعصر الذكاء الاصطناعي
- **مراقبة البحث المتجهي** - عمليات FT.SEARCH/ثانية وزمن الاستجابة مع صحة لكل فهرس لـ [valkey-search](https://github.com/valkey-io/valkey-search) وRediSearch. راجع [docs/vector-ai](https://github.com/betterdb-inc/monitor/blob/master/docs/vector-ai/README.md).
- **زمن استجابة الاستدلال** - p50/p95/p99 لكل فهرس، مع تنبيهات خرق SLA (Pro، مجاني في الوصول المبكر).
- **ذكاء التخزين المؤقت الدلالي** (Pro، مجاني في الوصول المبكر) - صحة معدل الإصابة، وتوصيات عتبة التشابه، وسير عمل اقتراح الموافقة/الرفض. مراقبة ذاكرة الوكيل مضمنة.
- **تتبعات الذكاء الاصطناعي** - شلالات نطاق OTLP من تطبيق الذكاء الاصطناعي الخاص بك، مترابطة مع حالة Valkey المباشرة تحت كل طلب. راجع [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md).
### يتصل بكل شيء
- **خادم MCP** - 60 أداة لـ Claude Code أو Cursor أو أي عميل MCP عبر [`@betterdb/mcp`](https://github.com/betterdb-inc/monitor/blob/master/packages/mcp).
- **نقطة نهاية Prometheus** - أكثر من 100 مقياس `betterdb_*`. راجع [docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md).
- **OpenTelemetry** - استوعب تتبعات OTLP، واعكس المقاييس والأحداث إلى أي خلفية OTLP. راجع [docs/opentelemetry.md](https://github.com/betterdb-inc/monitor/blob/master/docs/opentelemetry.md).
- **REST API** - كل شيء في واجهة المستخدم هو استدعاء API، موثّق عبر OpenAPI.
## الوصول إلى بياناتك بطريقتك
| الواجهة | التفاصيل |
|-----------|---------|
| واجهة الويب | `http://localhost:3001` |
| خادم MCP | `npx @betterdb/mcp` (stdio) - أنشئ رمزًا مميزًا تحت Settings → MCP Tokens |
| Prometheus | `http://localhost:3001/api/prometheus/metrics` |
| REST API (OpenAPI) | `http://localhost:3001/docs` |
| فحص الحالة | `http://localhost:3001/api/health` |
> **ملاحظة**: في إصدارات الإنتاج (Docker، CLI) يتم تقديم مسارات API تحت البادئة `/api`. في التطوير المحلي (`pnpm dev`) لا توجد بادئة - مثل `http://localhost:3001/health`.
## قواعد البيانات المدعومة
| قاعدة البيانات | الحد الأدنى للإصدار | الميزات المدعومة |
|----------|----------------|-------------------|
| **Valkey** | 8.0+ | جميع الميزات بما في ذلك COMMANDLOG (8.1+) وCLUSTER SLOT-STATS |
| **Redis** | 6+ | جميع الميزات باستثناء COMMANDLOG وCLUSTER SLOT-STATS الحصريين لـ Valkey |
تستخدم الواجهة الخلفية محوّلًا موحّدًا فوق عميل `iovalkey` المتوافق سلكيًا وتكتشف تلقائيًا Valkey مقابل Redis من استجابة `INFO` (`DB_TYPE=auto`). يتم اكتشاف القدرات مثل COMMANDLOG وSLOT-STATS لكل إصدار، وتتدهور واجهة المستخدم بسلاسة عندما لا تكون ميزة متاحة.
الخدمات المُدارة مدعومة أيضًا - توجد أدلة لـ AWS ElastiCache وMemoryDB وRedis Cloud وUpstash في [docs/providers](https://github.com/betterdb-inc/monitor/blob/master/docs/providers)، ويصل [`@betterdb/agent`](https://github.com/betterdb-inc/monitor/blob/master/packages/agent) إلى النسخ الموجودة داخل VPC فقط عبر WebSocket صادر.
## نشر Docker للإنتاج
تحتوي صورة Docker على تطبيق المراقبة (الواجهة الخلفية + الواجهة الأمامية). يتطلب:
1. نسخة Valkey/Redis للمراقبة
2. نسخة PostgreSQL لاستمرارية البيانات (أو استخدام تخزين الذاكرة)
### التشغيل مع تخزين PostgreSQL```bash
docker run -d \
--name betterdb-monitor \
-p 3001:3001 \
-e DB_HOST=your-valkey-host \
-e DB_PORT=6379 \
-e DB_PASSWORD=your-password \
-e STORAGE_TYPE=postgres \
-e STORAGE_URL=postgresql://user:pass@postgres-host:5432/dbname \
betterdb/monitor
التشغيل على منفذ مخصص
قم بتعيين متغير البيئة PORT وطابقه مع تعيين -p:```bash
docker run -d
--name betterdb-monitor
-p 8080:8080
-e PORT=8080
-e DB_HOST=your-valkey-host
betterdb/monitor
### التشغيل مع شبكة المضيف (الوصول إلى خدمات localhost)
إذا كان Valkey و PostgreSQL يعملان على نفس المضيف:```bash
docker run -d \
--name betterdb-monitor \
--network host \
-e DB_HOST=localhost \
-e DB_PORT=6380 \
-e DB_PASSWORD=devpassword \
-e STORAGE_TYPE=postgres \
-e STORAGE_URL=postgresql://dev:devpass@localhost:5432/postgres \
betterdb/monitor
متغيرات البيئة
| المتغير | مطلوب | الافتراضي | الوصف |
|---|---|---|---|
DB_HOST | نعم | localhost | مضيف Valkey/Redis المراد مراقبته |
DB_PORT | لا | 6379 | منفذ Valkey/Redis |
DB_PASSWORD | لا | - | كلمة مرور Valkey/Redis |
DB_USERNAME | لا | default | اسم مستخدم ACL لـ Valkey/Redis |
DB_TYPE | لا | auto | نوع قاعدة البيانات: auto أو valkey أو redis |
STORAGE_TYPE | لا | memory | الواجهة الخلفية للتخزين: memory أو postgres |
STORAGE_URL | شرطي | - | رابط اتصال PostgreSQL (مطلوب إذا كان STORAGE_TYPE=postgres) |
PORT | لا | 3001 | منفذ HTTP للتطبيق |
NODE_ENV | لا | production | بيئة Node |
ANOMALY_DETECTION_ENABLED | لا | true | تمكين اكتشاف الحالات الشاذة |
ANOMALY_PROMETHEUS_INTERVAL_MS | لا | 30000 | الفاصل الزمني لتحديث ملخص Prometheus (بالميلي ثانية) |
BETTERDB_LICENSE_KEY | لا | - | مفتاح ترخيص عبر الإنترنت (Pro/Enterprise)، يتم التحقق منه عبر الشبكة |
BETTERDB_OFFLINE_LICENSE_FILE | لا | - | مسار ملف ترخيص غير متصل موقّع .jwt للمضيفين المعزولين شبكياً (انظر أدناه) |
BETTERDB_OFFLINE_LICENSE | لا | - | رمز ترخيص غير متصل كسلسلة JWT مضمّنة |
BETTERDB_DATA_DIR | لا | /app/data | دليل حالة الترخيص المحفوظة (اربط وحدة تخزين قابلة للكتابة) |
ENCRYPTION_KEY | لا | - | مفتاح (16 حرفاً على الأقل) يُستخدم لتشفير كلمات مرور الاتصال المخزنة وأسرار نفق SSH أثناء السكون. بدونه، تُخزَّن الأسرار كنص صريح |
BETTERDB_SSH_KEY_DIR | لا | - | الدليل الذي يجب أن توجد فيه مفاتيح SSH الخاصة من جانب الخادم. يُمكّن مصدر المفتاح "مسار ملف الخادم" لـ أنفاق SSH؛ يجب أن يُحل مسار مفتاح الاتصال داخل هذا الدليل. عند عدم تعيينه، تُعطَّل المفاتيح المعتمدة على الملفات (لا تزال المفاتيح الملصقة المضمّنة تعمل) |
BETTERDB_TELEMETRY | لا | true | اضبطه على false لتعطيل القياس عن بُعد المجهول |
المرجع الكامل، بما في ذلك الذكاء الاصطناعي وضبط webhook وحدود بوابة الصحة: docs/configuration.md. لاستقبال تتبعات OTLP وتصدير المقاييس/الأحداث، انظر docs/opentelemetry.md.
أنفاق SSH
يمكن للاتصالات الوصول إلى قاعدة بيانات عبر مضيف SSH وسيط/قافز بدلاً من الاتصال مباشرة — وهو مفيد لـ Valkey/Redis في شبكة فرعية خاصة، أو ElastiCache، أو MemoryDB. مكّن Connect via SSH tunnel عند إضافة اتصال وقدّم مضيف SSH والمنفذ واسم المستخدم. يُدعم قفزة واحدة.
المصادقة إما بكلمة مرور أو بمفتاح خاص. تأتي المفاتيح الخاصة من أحد مصدرين:
- لصق المفتاح (مضمّن): يُرسَل محتوى مفتاح PEM مع الاتصال. يُخزَّن مشفّراً أثناء السكون فقط عند تعيين
ENCRYPTION_KEY(تشفير مغلّف)؛ بدون هذا المفتاح يُخزَّن كنص صريح، مثل كلمات مرور الاتصال. يعمل في كل مكان، بما في ذلك عمليات النشر المُدارة/السحابية. - مسار ملف الخادم: يوجد المفتاح بالفعل على نظام ملفات خادم المراقبة ويُشار إليه بالمسار. يتطلب ذلك تعيين متغير البيئة
BETTERDB_SSH_KEY_DIRعلى الدليل الذي يحتوي على المفاتيح المسموح بها، ويجب أن يُحل المسار المشار إليه داخل هذا الدليل، حتى لا يمكن إجبار API أبداً على قراءة ملفات عشوائية. اتركBETTERDB_SSH_KEY_DIRغير معيّن لتعطيل هذا الخيار.
اختيارياً، ثبّت بصمة مفتاح المضيف لخادم SSH (SHA256:...) على الاتصال؛ عند تعيينها، يُرفض النفق ما لم يقدّم الخادم مفتاحاً مطابقاً، مما يمنع هجمات الوسيط على مسار المضيف الوسيط. إذا تُركت فارغة، لا تُتحقق هوية الخادم (يُسجَّل تحذير).
يعيد النفق التوجيه إلى قاعدة البيانات عبر 127.0.0.1؛ عند تمكين TLS، لا تزال الشهادة تُتحقق مقابل اسم مضيف قاعدة البيانات الحقيقي. عيّن ENCRYPTION_KEY حتى تُشفَّر كلمات مرور SSH وعبارات مرور المفاتيح والمفاتيح المضمّنة أثناء السكون.
قيد معروف — طوبولوجيات العنقود/Sentinel: يُنفَّق فقط الاتصال الذي تقوم بتكوينه. تتفرّع مراقبة العنقود وSentinel إلى العقد الأخرى باستخدام العناوين التي تعلنها تلك العقد (CLUSTER NODES / Sentinel)، وتُجرى تلك الاتصالات لكل عقدة مباشرةً، وليس عبر النفق. إذا كانت العقد الأخرى قابلة للوصول فقط عبر المضيف الوسيط (مثل ElastiCache/MemoryDB في شبكة فرعية خاصة)، فلن تتوفر العروض لكل عقدة. استخدم أنفاق SSH لمراقبة العقدة الواحدة/الأساسية، أو ضع المراقب حيث يمكنه الوصول إلى عقد العنقود مباشرة.
الترخيص والدعم المعزول شبكياً
يفتح BetterDB Monitor ميزات Pro/Enterprise بإحدى طريقتين، اعتماداً على ما إذا كان المضيف لديه وصول إلى الإنترنت:
- مفتاح ترخيص عبر الإنترنت - عيّن
BETTERDB_LICENSE_KEY. يتحقق المراقب منه مقابلbetterdb.comويخزّن مؤقتاً رمزاً موقّعاً مُتحققاً منه محلياً، بحيث تستمر فئتك في العمل خلال الانقطاعات القصيرة وعمليات إعادة التشغيل. - رمز ترخيص غير متصل / معزول شبكياً - للمضيفين بدون وصول إلى الإنترنت على الإطلاق (انظر أدناه).
كيف يعمل الترخيص المعزول شبكياً
كل استحقاق هو JWT موقّع بـ RS256. يتحقق منه المراقب محلياً مقابل مفاتيح عامة مضمّنة في الصورة - لا يحتاج أبداً إلى الوصول إلى خادم ترخيص للثقة برمز. لذا يمكن لمضيف معزول شبكياً تشغيل الفئات المدفوعة بدون أي اتصال:
- على جهاز متصل بالإنترنت، سجّل الدخول في
betterdb.com/account/licenses و
نزّل رمز الترخيص غير المتصل (
.jwt، Pro/Enterprise). لا يحتوي على أي أسرار ولا يمكن التلاعب به - أي تعديل يكسر التوقيع. - انقله إلى المضيف المعزول شبكياً بأي طريقة تريدها (USB، إدارة التكوين، ربط سر Docker/Kubernetes).
- قدّمه عبر
BETTERDB_OFFLINE_LICENSE_FILE(مسار)، أوBETTERDB_OFFLINE_LICENSE(سلسلة مضمّنة)، أو الصقه في واجهة المستخدم تحت Settings → License → "Air-gapped environment? Activate an offline license."
عند تكوين رمز غير متصل وعدم تعيين BETTERDB_LICENSE_KEY،
يُجري المراقب صفر طلبات صادرة - تُعطَّل فحوصات الترخيص والقياس عن بُعد
ونبضات التحديث جميعها. يشغّل الفئة الممنوحة حتى انتهاء صلاحية الرمز (تُعاد التراخيص
الدائمة تنزيلها سنوياً)، ثم يعود إلى Community.```bash
fully offline - no network required
docker volume create betterdb-data docker run --rm -v betterdb-data:/d alpine chown 1001:1001 /d # volume writable by UID 1001 (one-time)
docker run -d --name betterdb-monitor -p 3001:3001
-e DB_HOST=your-valkey-host -e DB_PORT=6379 -e DB_PASSWORD=your-password
-v /path/to/betterdb-license.jwt:/run/secrets/betterdb-license.jwt:ro
-e BETTERDB_OFFLINE_LICENSE_FILE=/run/secrets/betterdb-license.jwt
-v betterdb-data:/app/data
betterdb/monitor
تحقق باستخدام `GET /api/license/status` → `source: offline-token`، `mode: offline`،
`airGapped: true`.
> **الاستمرارية:** قم بتركيب وحدة تخزين قابلة للكتابة على `/app/data` حتى يبقى الترخيص
> غير المتصل وشبكة الاتصال المؤقتة للانقطاع على قيد الحياة بعد إعادة التشغيل. تعمل الحاوية بمعرّف المستخدم **UID 1001**،
> لذا يجب تغيير ملكية وحدة التخزين المنشأة حديثًا إليه باستخدام `chown` (كما هو موضح أعلاه) - وإلا
> ستفشل الاستمرارية مع `EACCES … license.jwt`.
للاطلاع على التدفق الكامل، وأسبقية التحقق، ودليل تدوير المفاتيح، راجع
**[التراخيص غير المتصلة والمعزولة هوائيًا](https://github.com/betterdb-inc/monitor/blob/master/docs/offline-licenses.md)** و
**[مرجع الإعدادات](https://github.com/betterdb-inc/monitor/blob/master/docs/configuration.md#license-configuration)**.
### تفاصيل صورة Docker
- **الصورة الأساسية**: `node:20-alpine`
- **الحجم المضغوط**: ~360MB (`latest` / `-no-ai`) / ~640MB (صورة مُصدَّرة برقم إصدار مع تبعيات النموذج اللغوي المحلي الخاصة بمساعد الذكاء الاصطناعي التجريبي)
- **المنصات**: `linux/amd64`، `linux/arm64`
- **تحتوي على**: واجهة برمجة التطبيقات الخلفية + ملفات الواجهة الأمامية الثابتة (التي يقدمها Fastify)
- **مستبعد**: دعم SQLite (استخدم PostgreSQL أو تخزين الذاكرة)
### عمليات الحاوية```bash
docker logs -f betterdb-monitor # follow logs
docker stop betterdb-monitor # stop
docker rm betterdb-monitor # remove
خلفيات التخزين
يقوم BetterDB Monitor بحفظ سجل التدقيق والتحليلات وعمليات الالتقاط وبيانات الشذوذ في أحد الخلفيات الأربع التالية:
| الخلفية | حالة الاستخدام | ملاحظات |
|---|---|---|
memory | الاختبار، البيئات المؤقتة | الافتراضي في Docker؛ تُفقد جميع البيانات عند إعادة التشغيل |
postgres | الإنتاج | STORAGE_TYPE=postgres + STORAGE_URL=postgresql://user:pass@host:port/db |
turso | الإنتاج / SQLite بدون خادم | STORAGE_TYPE=turso + STORAGE_URL=libsql://... + STORAGE_AUTH_TOKEN؛ يعمل في Docker |
sqlite | التطوير المحلي / CLI | الوحدة الأصلية مُزالة من صورة Docker latest؛ STORAGE_SQLITE_FILEPATH اختياري |
مقاييس Prometheus
تُتاح المقاييس عبر GET /api/prometheus/metrics بتنسيق Prometheus النصي: تدقيق ACL، اتصالات العملاء، أنماط slowlog/commandlog، الذاكرة، معدل النقل، مساحة المفاتيح، النسخ المتماثل، إحصاءات فتحات العنقود، ومقاييس وقت تشغيل Node.js - جميعها مسبوقة بـ betterdb_.```yaml
scrape_configs:
- job_name: 'betterdb-monitor'
metrics_path: '/api/prometheus/metrics'
static_configs:
- targets: ['your-monitor-host:3001']
المرجع الكامل للمقاييس: [docs/prometheus-metrics.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-metrics.md) و[docs/prometheus-integration.md](https://github.com/betterdb-inc/monitor/blob/master/docs/prometheus-integration.md).
## التطوير
### بنية المشروع```
betterdb-monitor/
├── apps/
│ ├── api/ # NestJS backend (Fastify)
│ └── web/ # React frontend (Vite)
├── packages/ # Published packages (see below)
├── docs/ # Documentation site (Jekyll)
├── docker-compose.yml # Local Valkey (port 6380) and Redis (port 6382) for testing
└── package.json # Workspace root
الحزم
يحتوي هذا المستودع الأحادي على عدة حزم مستقلة. راجع packages/ للحصول على القائمة الكاملة.
| الحزمة | اللغة | السجل |
|---|---|---|
@betterdb/monitor | TypeScript | npm |
@betterdb/mcp | TypeScript | npm |
@betterdb/agent | TypeScript | npm |
@betterdb/semantic-cache | TypeScript | npm |
betterdb-semantic-cache | Python | PyPI |
@betterdb/agent-cache | TypeScript | npm |
betterdb-agent-cache | Python | PyPI |
cache-benchmark | Python | أداة إعادة تشغيل لقياس أداء الذاكرات المؤقتة الدلالية |
حزمة التقنيات
- الواجهة الخلفية: NestJS مع محول Fastify، و
iovalkeyلاتصالات Valkey/Redis، ووضع TypeScript الصارم. المنفذ 3001. - الواجهة الأمامية: React + TypeScript، وVite، وTailwindCSS، وRecharts. خادم التطوير على المنفذ 5173.
- المستودع الأحادي: مساحات عمل pnpm + Turborepo.
الإعداد المحلي
المتطلبات الأساسية: Node.js >= 20.0.0، وpnpm >= 9.0.0، وDocker.```bash pnpm install cp .env.example .env pnpm docker:dev # local Valkey (6380) and Redis (6382) pnpm dev # web on :5173, api on :3001
للاتصال بـ Redis بدلاً من Valkey، اضبط `DB_PORT=6382` في `.env`.```bash
pnpm dev:api # API only
pnpm dev:web # frontend only
pnpm docker:dev:down # stop local databases
pnpm build # production build
pnpm test # API tests
بناء صور Docker:```bash pnpm docker:build # local build pnpm docker:publish # multi-arch build & push (requires buildx)
### إضافة ميزات جديدة
1. أضف نقاط نهاية جديدة في `apps/api/src/`
2. أضف استدعاءات API المقابلة في `apps/web/src/api/`
3. أضف الأنواع المشتركة في `packages/shared/src/types/`
### نمط الكود
- وضع TypeScript الصارم، أنواع إرجاع صريحة، بدون `any`
- تم تكوين ESLint + Prettier
## الترخيص
- المحتوى تحت `docs/` مرخّص بموجب CC BY-SA 4.0.
- المحتوى تحت `proprietary/` مشمول بترخيص تجاري (انظر `proprietary/LICENSE`). هذه الميزات مجانية خلال الوصول المبكر.
- كل ما عدا ذلك مرخّص بموجب [MIT](https://github.com/betterdb-inc/monitor/blob/master/LICENSE).