Tenant management - FailproofAI

title: “إدارة المستأجرين (المنظمات والأعضاء)” description: “وثائق إدارة المستأجرين في AgentEye (المنظمات والأعضاء).”

نشر AgentEye واحد يخدم عدة منظمات (مستأجرين) معزولة تماماً، لذا يمكن لمثيل واحد استضافة فرق مختلفة أو وحدات أعمال أو عملاء دون تعريض بيانات أي مستأجر واحد للآخر. كل صف من البيانات (الأحداث والتقييمات والجلسات والوحات البيانات والاستعلامات المحفوظة والتنبيهات ومفاتيح API والأعضاء) ينتمي إلى منظمة واحدة بالضبط. يتم فرض العزلة الأساسية في كود التطبيق: كل طلب يقتصر على منظمته بوسائط org_id صريحة. على ClickHouse — حيث تعيش الأحداث والتقييمات عالية الحجم — يتم دعم هذا بفرض قوي على مستوى المحرك: كل منظمة تحصل على مستخدم ClickHouse مخصص للقراءة فقط مع سياسة صف لكل منظمة، لذا لا يمكن لحتى استعلام SQL التحليلي غير الموثوق أن يقرأ صفوف مستأجر آخر. على PostgreSQL، يضيف الأمان على مستوى الصف دفاعاً متعدد الطبقات على مسار الاستعلام للقراءة فقط (/queries/run)، ليضيق ما يمكن لهذا المسار رؤيته حتى لو كان مرشح على مستوى التطبيق مفقوداً في يوم من الأيام؛ اتصال الكتابة الخاص بالخادم يعمل كمالك الجدول وبالتالي يعمل من خلال نفس نطاق org_id على مستوى التطبيق. دورة حياة المستأجر يتحكم بها المشغل، بينما كل شيء يفعله الأعضاء يومياً يبقى ذاتي الخدمة في لوحة المعلومات. يتم إنشاء وإدارة المنظمات وعضوياتها باستخدام CLI agenteye-orgctl، الذي يأتي داخل صورة الخادم ويعمل داخل حاوية الخادم الموجودة. يتم إبقاء إنشاء وحذف المستأجرين بشكل متعمد بعيداً عن لوحة المعلومات و HTTP API: لا يوجد لا HTTP API ولا زر لوحة معلومات لدورة حياة المستأجر، لذا فهو محمي خلف وصول الكلستر/حاوية shell بدلاً من سطح التطبيق. داخل منظمة، يعمل الأعضاء بالكامل في لوحة المعلومات و API: يقومون بالتسجيل والتنقل بين المنظمات التي ينتمون إليها وإدارة مفاتيح API الخاصة بهم وبناء لوحات المعلومات والاستعلامات المحفوظة وتكوين التنبيهات لمنظمتهم. الفصل نظيف: يقوم المشغلون بتوفير وإلغاء تشغيل المستأجرين وأعضائهم عبر CLI؛ يقوم الأعضاء بتشغيل كل شيء داخل مستأجر من خلال واجهة المستخدم.

النشرات أحادية المستأجر لا تحتاج إلى أي من هذا. يعمل التثبيت أحادي المستأجر بدون أي إجراء من المشغل. جميع البيانات والمستخدمون والمفاتيح يعيشون في منظمة default مدمجة يتم توفيرها تلقائياً. تحتاج فقط إلى هذا الدليل عندما تقرر إضافة منظمة ثانية.

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

قبل إنشاء منظمتك الثانية (لا تحتاج المنظمة المدمجة default إلى أي شيء):

PostgreSQL 15+. مخطط عضوية المنظمة يستخدم مفتاح أجنبي ON DELETE SET NULL لقائمة الأعمدة يتطلب PostgreSQL 15+. قم بترقية PostgreSQL قبل توفير منظمة ثانية.
ORG_CH_SECRET قوي واستقر. كلمة مرور ClickHouse لكل منظمة مشتقة من HMAC(ORG_CH_SECRET, org_id)، لذا فإن القيمة الافتراضية للتطوير المدمجة المعروفة علناً ستؤدي إلى بيانات اعتماد لكل منظمة قابلة للاشتقاق علناً. agenteye-orgctl org create يرفض التشغيل بينما ORG_CH_SECRET غير محدد أو مترك في القيمة الافتراضية للتطوير المدمجة. قم بتعيين قيمتك الخاصة أولاً (انظر النشر → متغيرات البيئة وعلى Kubernetes، §2.6 من دليل Kubernetes). احتفظ بها متطابقة عبر جميع نسخ الخادم ولا تدورها بالصدفة؛ تدويرها يترك كل مستخدم ClickHouse لكل منظمة مهجوراً حتى إعادة البدء التالية إعادة توفيرهم.

تشغيل CLI

يتم شحن agenteye-orgctl في نفس صورة الخادم (جنباً إلى جنب مع agenteye-server). أنت لا نشر حاوية منفصلة أو Job أو Deployment؛ قم بتنفيذه داخل حاوية الخادم التي تعمل بالفعل، لذا فهو يقرأ نفس DATABASE_URL و CLICKHOUSE_URL و ORG_CH_SECRET الذي يستخدمه الخادم. Kubernetes:

kubectl -n agenteye exec deploy/server -- agenteye-orgctl <args>

Docker Compose:

docker compose exec server agenteye-orgctl <args>

الأمثلة أدناه تُظهر agenteye-orgctl <args> المجردة للإيجاز؛ ضع بادئة لكل مع أيهما من السطرين أعلاه يطابق نشرك.

مرجع الأوامر

المنظمات

الأمر	ما يفعله
`org create --slug <slug> --name <name>`	إنشاء منظمة جديدة. يرفض التشغيل بينما `ORG_CH_SECRET` غير محدد أو مترك في القيمة الافتراضية للتطوير المدمجة (قم بتعيين قيمتك الخاصة أولاً، انظر المتطلبات الأساسية). يوفر مستخدم ClickHouse للقراءة فقط للمنظمة + سياسة الصف.
`org list`	قائمة بجميع المنظمات (slug والاسم وحالة دورة الحياة).
`org rename --slug <slug> --name <new name>`	غيّر اسم عرض المنظمة. slug (المستخدم في URLs والمفاتيح) لم يتغير.
`org delete --slug <slug>`	حذف ناعم للمنظمة وحذف مستخدم ClickHouse الخاص بها. البيانات محتفظ بها. هذا يلغي الوصول ويحرر بيانات اعتماد ClickHouse لكل منظمة، لكنه لا يمسح الأحداث. قابلة للعكس من قبل المشغل؛ خطوة آمنة أولى قبل التطهير.
`org purge --slug <slug>`	مسح بيانات لا رجوع فيه. يجب أن تكون المنظمة مُحذوفة بالفعل `delete`. لا يُسمح به مطلقاً على المنظمة المدمجة `default`. استخدم فقط عندما تكون متأكداً من أن بيانات المستأجر يجب أن تُدمر.

الأعضاء

الأمر	ما يفعله
`member add --org <slug> --email <email> [--set <permission-set>] [--add perm1,perm2] [--remove perm3] [--protected]`	إضافة عضو إلى منظمة. يمكن اختيارياً البدء من مجموعة أذونات مدمجة، ثم إضافة/إزالة أذونات فردية. `--protected` يثبت العضو حتى لا تتمكن لوحة المعلومات من إزالته أو خفض درجته (انظر أدناه). يحصل العضو الجديد على OTP عند أول تسجيل دخول له في لوحة المعلومات.
`member list --org <slug>`	قائمة بأعضاء المنظمة. أعمدة الإخراج هي `EMAIL` و `SET` (مجموعة المدمجة التي بدأ العضو منها، أو `-`) و `PROT` (ما إذا كان العضو محمياً) و `PERMISSIONS` (أذوناته الفعلية). البريد الإلكتروني المعروض مع علامة `*` لاحقة هو مسؤول نسخة؛ لديهم وصول إلى كل منظمة.
`member update --org <slug> --email <email> [--set ...] [--add ...] [--remove ...] [--protected \| --unprotect]`	غيّر أذونات العضو و/أو علامة الحماية. `--set` يستبدل من مجموعة مدمجة؛ `--add` / `--remove` تضبط الأذونات الفردية؛ `--protected` / `--unprotect` تبديل الحماية. تمرير فقط `--protected`/`--unprotect` (بدون علامات منح) يغير الحماية وحدها ويترك الأذونات الموجودة سليمة.
`member remove --org <slug> --email <email>`	إزالة عضو من المنظمة. يرفض إذا كان العضو محمياً؛ قم بـ `--unprotect` أولاً. (يمكن لشخص أن يكون عضواً في عدة منظمات؛ هذا يؤثر فقط على المنظمة المسماة.)

يمكن لشخص أن يكون عضواً في أكثر من منظمة واحدة مع أذونات مختلفة في كل منها، مثل مسؤول في منظمة واحدة وقراءة فقط في منظمة أخرى. يتم إدارة كل عضوية بشكل مستقل لكل منظمة: منح أو تغيير أذونات شخص في منظمة واحدة ليس له تأثير على عضويتهم في أي منظمة أخرى.

الأعضاء المحميون (مسؤول منظمة غير قابل للإزالة)

تضمن الحماية أن المنظمة لا تقفل نفسها عرضياً عن إدارة ذاتية. بشكل افتراضي، يمكن لمسؤولي المنظمة الخاصة بها إضافة وإزالة بعضهم البعض من خلال صفحة المستخدمين ذاتية الخدمة لوحة المعلومات، لذا يمكنهم إزالة آخر مسؤول وترك المنظمة بدون أي شخص قادر على إدارتها.

صفحة المستخدمين: بطاقة لكل مستخدم لوحة معلومات ببريده الإلكتروني والأذونات الممنوحة وعناصر التحكم بالتعديل/التعطيل

لمنع ذلك، ضع علامة على عضو واحد محمي:

kubectl -n agenteye exec deploy/server -- \
  agenteye-orgctl member add --org acme --email owner@acme.example --set admin --protected

لا يمكن إزالة أو خفض درجة عضو محمي من خلال لوحة المعلومات؛ تلك الإجراءات ترجع خطأ. فقط المشغل يمكنه تغييرهم، وفقط عبر هذا CLI: قم بتشغيل member update --org acme --email owner@acme.example --unprotect أولاً، ثم أزل أو اخفض الدرجة. هذا يضمن أن كل منظمة تحافظ على مسؤول واحد على الأقل أعضاؤها لا يمكنهم قفله، مع الحفاظ على التحكم في المستأجر بطريقة المشغل. الحماية لكل منظمة؛ حماية شخص ما في منظمة واحدة ليس لها تأثير على عضويتهم في منظمة أخرى.

مجموعات الأذونات المدمجة

يقبل --set إحدى ثلاث مجموعات مدمجة، مطبقة لكل منظمة:

المجموعة	المقصود بها
`admin`	وصول كامل داخل المنظمة، بما في ذلك إدارة مفاتيح API والمستخدمين في المنظمة.
`standard`	الاستخدام اليومي: استعلامات القراءة والتشغيل وبناء لوحات المعلومات والإقرار بالحوادث.
`read-only`	وصول العرض فقط إلى بيانات ولوحات معلومات المنظمة.

ابدأ من مجموعة بـ --set، ثم قم بالتعديل الدقيق بـ --add / --remove باستخدام رموز الأذونات الفردية المدرجة في مفاتيح API. رموز الأذونات نفسها متطابقة مع تلك المستخدمة في مفاتيح API.

مثال عملي

توفير مستأجر acme جديد وإضافة أول مسؤول له والسماح له بصك مفتاح ثم إيقاف تشغيل المنظمة. 1. إنشاء المنظمة (يجب أن يكون ORG_CH_SECRET محدداً بالفعل لقيمة قوية واستقرار، ليس غير محدد أو القيمة الافتراضية للتطوير المدمجة):

kubectl -n agenteye exec deploy/server -- \
  agenteye-orgctl org create --slug acme --name "Acme Corp"

2. إضافة أول عضو كمسؤول منظمة:

kubectl -n agenteye exec deploy/server -- \
  agenteye-orgctl member add --org acme --email alice@acme.example --set admin

تتلقى Alice كود OTP في المرة الأولى التي تسجل فيها الدخول إلى لوحة المعلومات. من هنا فصاعداً، تعمل بالكامل في واجهة المستخدم تحت بادئة URL الخاصة بمنظمتها (مثلاً /acme/sessions). 3. صك مفتاح API لكل منظمة (في لوحة المعلومات): المشغل لا يصك مفاتيح بيانات لكل منظمة من CLI. تقوم Alice (أو أي عضو منظمة يمتلك keys:create) بإنشاء مفاتيح المجمع / لوحة المعلومات لمنظمة acme من صفحة Keys في لوحة المعلومات. كل مفتاح تنشئه يتم ختمه تلقائياً مع منظمتها ولا يمكن أبداً قراءة أو كتابة بيانات سوى acme. انظر مفاتيح API. 4. تعديل عضو لاحقاً:

kubectl -n agenteye exec deploy/server -- \
  agenteye-orgctl member update --org acme --email alice@acme.example --add alerts:write

kubectl -n agenteye exec deploy/server -- \
  agenteye-orgctl member list --org acme

5. حذف ناعم للمنظمة (إلغاء الوصول + حذف مستخدم ClickHouse الخاص بها؛ البيانات محتفظ بها):

kubectl -n agenteye exec deploy/server -- \
  agenteye-orgctl org delete --slug acme

6. تطهير المنظمة (لا رجوع فيه؛ فقط بعد حذف ناعم؛ لا أبداً المنظمة default):

kubectl -n agenteye exec deploy/server -- \
  agenteye-orgctl org purge --slug acme

على Docker Compose، استبدل كل بادئة kubectl -n agenteye exec deploy/server -- بـ docker compose exec server.

تقسيم المسؤوليات

كل شيء يحتاجه عضو المنظمة يومياً هو خدمة ذاتية في لوحة المعلومات و API، محصور تلقائياً إلى منظمتهم الحالية:

مفاتيح API لكل منظمة يتم إنشاؤها وإدارتها من قبل أعضاء المنظمة في لوحة المعلومات (أو عبر مفاتيح API مع مفتاح يحمل keys:create). لا يصك CLI مفاتيح بيانات. انظر مفاتيح API.
تبديل المنظمة مدمج في لوحة المعلومات؛ يتبديل الأعضاء بين المنظمات التي ينتمون إليها من مفتاح المنظمة، وتعيش صفحات نطاق المنظمة تحت /<org-slug>/….
لوحات المعلومات والاستعلامات المحفوظة والتنبيهات وجميع استخدام البيانات تحدث بالكامل في واجهة المستخدم و API، محصور إلى منظمة العضو الحالية.

المشغل، باستخدام agenteye-orgctl، يملك فقط دورة الحياة للمنظمة والعضو: إنشاء / إعادة تسمية / حذف / تطهير منظمة وإضافة / قائمة / تحديث / إزالة عضو.

انظر أيضاً

النشر: ORG_CH_SECRET وبقية بيئة الخادم.
نشر Kubernetes: §2.6 ينشئ Secret agenteye-org-ch-secret قبل أول منظمة متعددة المستأجرين الخاصة بك.
مفاتيح API: نموذج المفتاح لكل منظمة ورموز الأذونات المستخدمة بـ --add / --remove.
استكشاف الأخطاء: توفير متعدد المستأجرين ومشاكل عزل ClickHouse.

​title: “إدارة المستأجرين (المنظمات والأعضاء)” description: “وثائق إدارة المستأجرين في AgentEye (المنظمات والأعضاء).”

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

​تشغيل CLI

​مرجع الأوامر

​المنظمات

​الأعضاء

​الأعضاء المحميون (مسؤول منظمة غير قابل للإزالة)

​مجموعات الأذونات المدمجة

​مثال عملي

​تقسيم المسؤوليات

​انظر أيضاً