في الموقع

لتثبيت Ideanote في بيئتك الخاصة، استخدم Ideanote Helm Chart.
يحتوي هذا المخطط على جميع المكونات المطلوبة للبدء، ويمكن توسيع نطاقه لعمليات نشر كبيرة.

يأتي Ideanote Helm Chart مزودًا بكل ما يلزم، وقد صُمم ليكون سهل التثبيت والتهيئة.
يتضمن المخطط مخططات فرعية متعددة وتهيئة افتراضية يمكن تخصيصها لتناسب احتياجاتك.
يُرجى الاطلاع على قسم البنية لمزيد من المعلومات حول المكونات المضمنة في مخطط Helm.

البنية

يتألف Ideanote من مكونات متعددة تُنشر في عنقود Kubernetes بمساعدة Ideanote Helm Chart.
يوضح الرسم التخطيطي التالي بنية هذه المكونات وكيفية تفاعلها بعضها مع بعض.

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

قبل نشر Ideanote في عنقود Kubernetes، يجب تحديد المتطلبات الأساسية التالية واستيفاؤها:

1. أنشئ عنقودًا Kubernetes عنقودًا.

2. ثبّت kubectl.

3. ثبّت Helm.

4. احصل على ZIP-folder من فريق Ideanote مع الرموز المطلوبة للوصول إلى مخطط Helm وصور Docker.

5. صادِق باستخدام Ideanote Helm registry

6. اختر كيفية تقديم core services

7. اختر الطريقة التي تريد بها تنفيذ load balancing

8. اختر كيفية تنفيذ backups

9. اختر كيفية تنفيذ monitoring

10. أنشئ رموزًا للتكاملات

11. حدّث الإعدادات في ملف values.yaml

1. أنشئ عنقودًا Kubernetes cluster

يوصى بعنقود يضم ما لا يقل عن 4 وحدات معالجة مركزية افتراضية و10 GB من ذاكرة الوصول العشوائي.
يرجى الرجوع إلى تعليمات موفري الخدمات السحابية لمعرفة كيفية إنشاء عنقود Kubernetes.

2. ثبّت kubectl

لتثبيت kubectl، راجع وثائق تثبيت Kubernetes. تغطي الوثائق معظم أنظمة التشغيل.

بعد إنشاء المجموعة، يجب أن تُهيّئ kubectl قبل أن تتمكن من التفاعل مع المجموعة من سطر الأوامر.

3. ثبّت Helm

يستخدم هذا الدليل أحدث إصدار من Helm v3 (v3.15.4 أو أحدث). لتثبيت Helm، راجع وثائق تثبيت Helm.

4. ZIP-folder من فريق Ideanote

لطلب الوصول إلى مخطط Helm الخاص بـ Ideanote، ستحتاج إلى التواصل مع فريق Ideanote على hello@ideanote.io.
يلزم الحصول على ترخيص Ideanote للحصول على رمز الوصول هذا.

سيزوّدك Ideanote بـ ZIP-folder يُسمى ideanote-on-premise.zip ويحتوي على ما يلي:

• ملف values.yaml يتضمن الإعدادات الافتراضية. يحتوي هذا الملف أيضًا على أسرار السجل اللازمة لمجموعة Kubernetes لسحب صور Docker. يُرجى قراءة هذا الدليل لمزيد من المعلومات حول كيفية تهيئة مخطط Helm للإنتاج.
• ملف helm-access-token.json يحتوي على رمز الوصول إلى سجل Helm.

5. صادِق باستخدام Ideanote Helm registry

يُرجى تشغيل الأمر التالي للمصادقة لدى سجل Helm باستخدام helm-access-token.json الوارد من Ideanote ZIP-folder:

# Linux/MacOS
cat helm-access-token.json | helm registry login -u _json_key --password-stdin europe-west3-docker.pkg.dev

# Windows (Command Prompt)
type helm-access-token.json | helm registry login -u _json_key --password-stdin europe-west3-docker.pkg.dev

# Windows (PowerShell)
Get-Content helm-access-token.json | helm registry login -u _json_key --password-stdin europe-west3-docker.pkg.dev

اختياري: يمكنك تشغيل الأمر التالي للتحقق من مصادقتك لدى سجل Helm.
سيؤدي هذا إلى تنزيل Ideanote Helm Chart إلى جهازك المحلي.

helm pull oci://europe-west3-docker.pkg.dev/ideanote/charts/ideanote --version 1.0.0

6. اختر كيفية تقديم الخدمات الأساسية

يتضمن Ideanote Helm Chart مخططين فرعيين لخدمات قواعد البيانات والتخزين المؤقت، يتم تثبيتهما كجزء من عملية التثبيت:

• PostgreSQL الذي يُستخدم كقاعدة البيانات الأساسية
• Redis الذي يُستخدم كخدمة للتخزين المؤقت

ومع ذلك، نوصي في بيئات الإنتاج باستخدام خدمات مُدارة خارجيًا بدلًا من ذلك لـ Redis وPostgreSQL، وتقديم تفاصيل الاتصال عند تثبيت مخطط Helm.

لذلك، قبل تثبيت Ideanote Helm Chart، يجب أن تختار أحد الخيارين التاليين:

1. المخططات الفرعية المضمّنة: دع مخطط Helm يثبّت تلقائيًا Redis وPostgreSQL في مجموعتك. هذا هو الخيار الافتراضي. اقرأ المزيد عن كيفية تهيئة هذه الخدمات الأساسية المضمّنة هنا.
2. الخدمات الأساسية المُدارة: استخدم خدمات مُدارة لـ Redis و/أو PostgreSQL. يتطلب هذا الخيار تقديم تفاصيل الاتصال بالخدمات المُدارة عند تثبيت مخطط Helm. يُرجى اتباع هذا الدليل لمزيد من المعلومات حول تهيئة خدماتك المُدارة.

7. اختر الطريقة التي تريد بها تنفيذ load balancing

يتضمن Ideanote Helm Chart مخططين فرعيين لإدارة موازنة التحميل وشهادات SSL:

• ingress-nginx وحدة تحكم Ingress/موازن التحميل المستخدمة لتوجيه حركة المرور إلى خدمات Ideanote.
• cert-manager تُستخدم لإصدار شهادات SSL تلقائيًا لخدمات Ideanote باستخدام Let’s Encrypt.

لذلك، عند تثبيت Ideanote Helm Chart، يجب عليك الاختيار بين الخيارين التاليين:

1. المخططات الفرعية المضمّنة: دع مخطط Helm يثبّت تلقائيًا ingress-nginx لموازنة التحميل وcert-manager في مجموعتك. هذا هو الخيار الافتراضي. يتطلب هذا الخيار امتلاك نطاق يمكنك إضافة سجل DNS إليه. ويمكن أن يكون هذا نطاقًا فرعيًا مثل poc.domain.com. يجب أن تتمكن خوادم Let’s Encrypt من تحليل عنوان IP الخاص بمجموعة Kubernetes لديك لإصدار الشهادات. اقرأ المزيد عن كيفية تهيئة موازن التحميل المضمّن هنا.
2. موازن تحميل مُدار: اختر حل موازنة التحميل الخاص بك، سواء باستخدام وحدة تحكم Ingress/موازن تحميل مُدارة خاصة بك أو موازن تحميل من موفر خدمة سحابية. اقرأ المزيد حول كيفية إعداد موازن تحميل مخصص خاص بك هنا.

بغض النظر عما تختاره أعلاه، عند تثبيت مخطط Helm، يجب تزويد Ideanote بعنوان URL الذي ستستخدمه للوصول إلى خدمات Ideanote.
يجب إضافة عنوان URL هذا إلى الملف values.yaml ضمن المسار global.ideanote.ingress.url.

global:
  ideanote:
    ingress:
      url: https://<your-domain>

إذا اخترت استخدام وحدة تحكم Ingress/موازن التحميل المضمّنة nginx والمخططات الفرعية cert-manager، فيجب عليك أيضًا إدخال عنوان بريدك الإلكتروني في الملف values.yaml.
يستخدم Let’s Encrypt عنوان البريد الإلكتروني هذا لإصدار شهادات SSL لخدمات Ideanote.

cert-manager:
  email: <your-email-address>

8. اختر كيفية تنفيذ backups

لا يتضمن Ideanote Helm Chart حاليًا حلًا مدمجًا للنسخ الاحتياطي.
نوصي بشدة بإعداد جدول زمني للنسخ الاحتياطي لعمليات النشر الإنتاجية.

بناءً على المخططات الفرعية التي تختار تثبيتها، ستنشئ ideanote عدد 3 من PVCs (مطالبات وحدات التخزين الدائمة) في مجموعتك، مع وحدات تخزين يجب عليك جميعها نسخها احتياطيًا:

• وحدة تخزين قاعدة بيانات PostgreSQL: data-<release>-postgresql-0 (لا تُنشأ عند استخدام PostgreSQL مُدارة)
• وحدة تخزين قاعدة بيانات Redis: redis-data-<release>-redis-master-0 (لا تُنشأ عند استخدام Redis مُدار)
• وحدة تخزين تحميلات Ideanote: <release>-storage-data

9. اختر كيفية تنفيذ monitoring

لا يتضمن Ideanote Helm Chart حاليًا حلًا مدمجًا للمراقبة.
نعمل على إضافة دعم لـ Prometheus وGrafana مستقبلًا.

تكتب خدمات Ideanote السجلات إلى stdout وstderr.
ثم يلتقط بيئة تشغيل الحاويات هذه السجلات، ويمكن الوصول إليها باستخدام أدوات Kubernetes مثل kubectl logs.
لكن هذه السجلات، افتراضيًا، مرتبطة بدورة حياة الـ pod، لذا تُفقد سجلاته عند إنهاء الـ pod ما لم تُحفَظ في مكان آخر.

لذلك، لإعداد مراقبة مناسبة لخدمات Ideanote، يجب تثبيت حل مراقبة يمكنه جمع هذه السجلات من الحاويات قيد التشغيل في مجموعة Kubernetes.

10. أنشئ رموزًا مميزة لعمليات التكامل

تتطلب الوظائف الاختيارية التالية إنشاء رموز للتكاملات (الخارجية) وتهيئتها. وكلها اختيارية.

• OpenAI تكامل لتوفير وظائف الذكاء الاصطناعي. اضبط قيمة ideanote.api.openai.key على مفتاح صالح لـ OpenAI API. اقرأ المزيد حول كيفية إعداد التكامل OpenAI هنا.
• Sendgrid تكامل لتوفير وظائف إشعارات البريد الإلكتروني. اضبط قيمة ideanote.api.sendgrid.key على مفتاح صالح لـ Sendgrid API. اقرأ المزيد حول كيفية إعداد التكامل Sendgrid هنا.
• SAML تكامل لتسجيل الدخول الأحادي. اقرأ المزيد عن كيفية تهيئة تكامل SAML هنا.
• LDAP تكامل لتوفير وظائف تسجيل الدخول الأحادي. اقرأ المزيد حول كيفية إعداد التكامل LDAP هنا.

11. حدّث التهيئة في الملف values.yaml

يحتوي values.yaml المضمّن في ZIP-folder الذي قدّمه فريق Ideanote على الإعدادات الافتراضية لـ Ideanote Helm Chart.

الإعدادات الافتراضية غير مخصصة لبيئة الإنتاج، ويمكن استخدامها نقطة انطلاق لتخصيص مخطط Helm بما يلائم احتياجاتك.

القيم المطلوبة:

• global.ingress.url (مطلوب): عنوان URL الذي ستعمل عليه Ideanote. أمثلة: https://domain.com، https://poc.domain.com، http://192.0.2.0. اقرأ المزيد عن load-balancing هنا.
• cert-manager.email (مطلوب عند اختيار موازن التحميل ومدير الشهادات الافتراضيين): عنوان بريدك الإلكتروني لكي يتمكن Let’s Encrypt من إصدار شهادة. اقرأ المزيد عن cert-manager هنا.

تثبيت Ideanote

قبل تثبيت مخطط Helm، يجب استيفاء جميع المتطلبات المسبقة الـ11 المذكورة أعلاه.

لتثبيت Ideanote Helm Chart، نفّذ الأمر التالي.
يفترض ذلك أنك هيّأت values.yaml وفقًا للمتطلبات الأساسية واحتياجاتك.

helm install ideanote oci://europe-west3-docker.pkg.dev/ideanote/charts/ideanote --version 1.0.0 --create-namespace --namespace ideanote --wait --timeout 10m -f values.yaml

سيؤدي هذا إلى تثبيت خدمات Ideanote في مجموعة Kubernetes لديك ضمن مساحة أسماء جديدة تُسمى ideanote وباسم إصدار ideanote.
يُرجى الانتظار بضع دقائق حتى يتم تخصيص جميع الموارد وبدء الخدمات.

يمكنك التحقق من حالة كل حاوية بود بتنفيذ الأمر التالي:

kubectl get pods -n ideanote --watch

اتبع هذه الخطوات لإكمال التثبيت

تفترض هذه الخطوات أنك تثبّت Ideanote Helm Chart مع مخططي ingress-nginx موازن التحميل وcert-manager الفرعيين المضمّنين.

1․ اجمع عنوان IP الذي تم تخصيصه ديناميكيًا لـ NGINX Ingress المثبّت:

kubectl get ingress -l "app.kubernetes.io/part-of"=ideanote --namespace ideanote

2․ أضف عنوان IP هذا إلى سجلات DNS الخاصة بنطاقك الذي حددته في الملف values.yaml.

3․ انتظر بضع دقائق حتى تنتشر سجلات DNS وحتى تصدر cert-manager شهادات SSL. تحقّق من حالة الشهادات بتشغيل الأوامر التالية:

kubectl describe certificate -l "app.kubernetes.io/part-of"=ideanote --namespace ideanote

kubectl get certificaterequest -n ideanote
kubectl describe CertificateRequest ideanote-tls-1 -n ideanote

4․ أخيرًا، انتقل إلى عنوان URL الذي حددته في الملف values.yaml لإعداد Ideanote.

إعداد مساحة عمل Ideanote

بعد تثبيت Ideanote في مجموعة Kubernetes لديك، تتمثل الخطوة الأخيرة في إعداد مساحة عمل Ideanote.
يمكنك الوصول إلى مساحة عمل Ideanote بزيارة عنوان URL الذي حددته في الملف values.yaml واتباع التعليمات الظاهرة على الشاشة.

يمكنك اختيار إعداد مساحة عملك بإحدى طريقتين:

• البدء من الصفر: يمكنك اختيار إعداد مساحة عمل من الصفر. وسيرشدك ذلك خلال عملية إنشاء حساب مالك Ideanote ومساحة عمل.
• استيراد البيانات: إذا كنت قد استخدمت Ideanote على ideanote.io سابقًا، فيمكنك اختيار استيراد مساحة العمل بأكملها إلى بيئتك المحلية. للقيام بذلك، يُرجى التواصل مع فريق Ideanote الذي سيزوّدك بملف TAR-folder يتضمن جميع بيانات مساحة العمل. ينبغي استيراد هذا الملف TAR-file أثناء عملية إعداد مساحة العمل عند ظهور المطالبة بذلك.

عمليات النشر النموذجية

يحتوي هذا القسم على أمثلة حول كيفية نشر Ideanote لدى مزودي الخدمات السحابية وفي بيئات مختلفة.
يمكن أن يكون ذلك مصدر إلهام لكيفية نشر Ideanote في بيئتك الخاصة.
يمكنك تثبيت Ideanote لدى مزود خدمات سحابية من اختيارك، لكننا نوصي باستخدام AWS، Azure، أو Google Cloud Platform.
يمكنك أيضًا تثبيت Ideanote على مجموعة Kubernetes محلية باستخدام Minikube.

تفترض جميع عمليات النشر التوضيحية أنك اتبعت المتطلبات الأساسية وأعددت الملف values.yaml وفقًا لاحتياجاتك.

Minikube

سيؤدي إعداد Minikube إلى تعطيل المخطط الفرعي المضمّن لموازنة التحميل nginx، واستخدام إضافة التوجيه الأصلية التي يوفرها minikube بدلًا من ذلك.

لتثبيت Ideanote على Minikube، اتبع الخطوات التالية:

1․ ثبّت Docker

2․ ثبّت Minikube

3․ ابدأ Minikube باستخدام الأمر التالي. سيخصص ذلك 4 وحدات معالجة مركزية و8 GB من الذاكرة العشوائية للمجموعة:

minikube start --cpus 4 --memory 8192

4․ فعّل الإضافات المطلوبة:

minikube addons enable metrics-server
minikube addons enable ingress

5․ تأكد من تعيين التهيئة التالية في الملف values.yaml:

global:
  ideanote:
    ingress:
      # `minikube tunnel` will expose the load balancer on this IP
      url: "http://127.0.0.1"
      tls:
        enabled: false

# Disable both cert-manager and nginx because Minikube is using its own routing addon
cert-manager:
  install: false

ingress-nginx:
  install: false

6․ ثبّت مخطط Helm الخاص بـ Ideanote:

helm install ideanote oci://europe-west3-docker.pkg.dev/ideanote/charts/ideanote --version 1.0.0 --create-namespace --namespace ideanote --wait --timeout 10m -f values.yaml

7․ ابدأ نفق Minikube (ولوحة المعلومات):

minikube tunnel
minikube dashboard

8․ انتقل إلى: http://127.0.0.1 وأعد إعداد مثيل Ideanote الخاص بك.

Azure Kubernetes Service (AKS)

سيستخدم تكوين Azure nginx متحكم Ingress المضمّن وcert-manager اللذين يوفرهما Ideanote Helm Chart.
إذا اخترت بدلاً من ذلك استخدام routing add-on الأصلي من Azure لـ Kubernetes، فيمكنك فعل ذلك باتباع هذه التعليمات وتعطيل الخدمات المضمّنة nginx وcert-manager (اطّلع هنا على كيفية تعطيل هذه الخدمات).

1․ أنشئ مجموعة Azure Kubernetes Service (AKS) بسعة لا تقل عن 2 vCPU و8 GB من الذاكرة (على سبيل المثال، باستخدام Standard_DS2_v2). اقرأ هذا الدليل لمزيد من المعلومات حول إنشاء مجموعة Azure Kubernetes.

2․ ثبّت Azure CLI على جهازك المحلي. اقرأ هذا الدليل لمزيد من المعلومات.

3․ شغّل الأمر التالي لتهيئة kubectl للاتصال بمجموعة AKS الخاصة بك:

az aks get-credentials --resource-group Ideanote --name Ideanote

4․ هيّئ values.yaml وفقًا للمتطلبات المسبقة واحتياجاتك. عيّن global.ingress.url إلى اسم النطاق الذي تريد استخدامه مع Ideanote. ستحتاج إلى إعداد سجل DNS لهذا النطاق لاحقًا في هذا الدليل.

5․ ثبّت مخطط Helm الخاص بـ Ideanote:

helm install ideanote oci://europe-west3-docker.pkg.dev/ideanote/charts/ideanote --version 1.0.0 --create-namespace --namespace ideanote --wait --timeout 10m -f values.yaml

6․ انتظر بضع دقائق حتى تبدأ جميع الخدمات، ثم اجمع عنوان IP الذي خصصته Azure ديناميكيًا لـ NGINX Ingress المثبّت:

kubectl get ingress -l "app.kubernetes.io/part-of"=ideanote --namespace ideanote

7․ أضف عنوان IP هذا إلى سجلات DNS الخاصة بنطاقك الذي حددته في الملف values.yaml.

8․ انتظر بضع دقائق حتى تنتشر سجلات DNS، ثم انتقل إلى عنوان URL الذي حددته في الملف values.yaml لإعداد Ideanote. يُرجى قراءة دليل استكشاف الأخطاء وإصلاحها إذا واجهت مشكلات في عنوان URL/عنوان IP.

تهيئة وحدة تحكم الدخول nginx من نوع موازن التحميل لـ Azure

إذا كنت بحاجة إلى تهيئة المضمّنة LoadBalancer nginx وحدة تحكم Ingress لـ Azure، يمكنك القيام بذلك عن طريق إضافة هذه التعليقات التوضيحية إلى الملف values.yaml.
يمكنك أيضًا استخدام هذه التعليقات التوضيحية لتعيين عنوان IP ثابت إلى LoadBalancer باتباع هذا الدليل.
على سبيل المثال:

ingress-nginx:
  controller:
    service:
      annotations:
        "service.beta.kubernetes.io/azure-load-balancer-resource-group": "MC_Ideanote_Ideanote_francecentral"
        "service.beta.kubernetes.io/azure-pip-name": "public-cluster-load-balancer-ip"

استخدام عُقد Azure الفورية

يرجى إضافة ما يلي إلى ملف values.yaml لتشغيل جميع عمليات النشر على عُقد Azure الفورية:

tolerationsAndAffinity: &tolerationsAndAffinity
  affinity:
    nodeAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms:
          - matchExpressions:
              - key: "kubernetes.azure.com/scalesetpriority"
                operator: In
                values:
                  - "spot"
  tolerations:
    - key: "kubernetes.azure.com/scalesetpriority"
      operator: "Equal"
      value: "spot"
      effect: "NoSchedule"

postgresql:
  primary:
    <<: *tolerationsAndAffinity

redis:
  master:
    <<: *tolerationsAndAffinity

ingress-nginx:
  controller:
    <<: *tolerationsAndAffinity

cert-manager:
  <<: *tolerationsAndAffinity
  cainjector:
    <<: *tolerationsAndAffinity
  webhook:
    <<: *tolerationsAndAffinity
  startupapicheck:
    <<: *tolerationsAndAffinity

global:
  ideanote:
    <<: *tolerationsAndAffinity

Google منصة الحوسبة السحابية (GKE)

يوضح لك هذا المثال كيفية إعداد Ideanote على مجموعة GKE Autopilot في GCP.
ستكون المجموعة جاهزة للإنتاج باستخدام PostgreSQL مُدار وLoadBalancer مُدار، بما في ذلك التخزين المؤقت CDN للأصول.

المتطلبات المسبقة:

• اتبع جميع المتطلبات المسبقة الأساسية
• يجب أن تمتلك نطاقًا يمكنك إضافة سجل DNS إليه
• يجب أن يكون لديك حساب على Google Cloud Platform

1․ إنشاء شبكة VPC جديدة
2․ إنشاء مجموعة Kubernetes Autopilot جديدة

• إرفاق شبكة VPC التي أنشأتها في الخطوة 1

3․ إنشاء مثيل PostgreSQL جديد

• إرفاق شبكة VPC التي أنشأتها في الخطوة 1
• أنشئ قاعدة بيانات جديدة باسم ideanote
• أنشئ مستخدمًا جديدًا باسم ideanote ودوّن كلمة المرور

4. تثبيت gcloud cli وتسجيل الدخول إلى حساب GCP الخاص بك
5. تهيئة kubectl للاتصال بمجموعة GCP الخاصة بك

gcloud container clusters get-credentials <cluster> --region <region> --project <project>

6. إنشاء عنوان IP ثابت جديد لـ LoadBalancer وتدوين عنوان IP:

gcloud compute addresses create ideanote-global --global
gcloud compute addresses list --project ideanote-sa

7. انتقل إلى موفر DNS وأضف سجل A للنطاق الذي تريد استخدامه مع Ideanote. وجّه سجل A إلى عنوان IP الثابت الذي أنشأته في الخطوة 6.

8. هيّئ الملف values.yaml بالقيم التالية. أدخل قيمًا لكل من global.ideanote.psql.host وglobal.ideanote.psql.passwordSecret.password وglobal.ideanote.ingress.url وglobal.ideanote.gke.ingress.staticIPName.

global:
  # This will create GKE-specific resources such as selecting the native GCP ingress controller, creating backend/frontend configs and activating CDN caching for assets
  cloudProvider: GKE

  gke:
    ingress:
      staticIPName: "<static-google-cloud-ip-name>"

  ideanote:
    ingress:
      url: "https://<your-domain>"

    autoscaling:
      enabled: true

    resources:
      enabled: true

    psql:
      database: "ideanote"
      username: "ideanote"
      host: "<google-cloud-sql-ip>"
      passwordSecret:
        password: "<google-cloud-sql-password>"

    storage:
      persistence:
        size: "50Gi"

cert-manager:
  install: false

ingress-nginx:
  install: false

postgresql:
  install: false

redis:
  install: true
  master:
    persistence:
      size: 5Gi

9. (اختياري) صحّح فئة التخزين الافتراضية باستخدام allowVolumeExpansion: true، ما يتيح تغيير حجم مطالبات PVC بسهولة:

kubectl patch storageclass standard-rwo -p '{"allowVolumeExpansion": true}'

10. ثبّت مخطط Helm الخاص بـ Ideanote:

helm install ideanote oci://europe-west3-docker.pkg.dev/ideanote/charts/ideanote --version 1.0.0 --create-namespace --namespace ideanote --wait --timeout 10m -f values.yaml

11. انتظر حتى تصبح المجموعة جاهزة، ثم زُر عنوان URL المحدد في values.yaml. قد تستغرق مجموعات Autopilot وقتًا طويلًا لتخصيص الموارد في البداية. بالإضافة إلى ذلك، يُرجى الانتظار لمدة تصل إلى 1 ساعة حتى تُصدر Google Cloud شهادة SSL.

اجعل مجموعة GKE جاهزة للإنتاج

12. صحّح مطالبات وحدة التخزين باستخدام persistentVolumeReclaimPolicy: Retain لمنع فقدان البيانات عند حذف إصدار Helm:

kubectl patch pvc -n ideanote ideanote-storage-data -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'
kubectl patch pvc -n ideanote redis-data-ideanote-redis-master-0 -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'

13. أعدّ نسخًا احتياطية لقاعدة بيانات PostgreSQL. يمكنك استخدام نسخ Cloud SQL الاحتياطية أو حل نسخ احتياطي تابع لجهة خارجية.

14. أعدّ نسخًا احتياطية لمجموعة Kubernetes بأكملها، بما في ذلك VPCs (مطالبات وحدات التخزين الدائمة)، باتباع هذا الدليل.

استخدام عُقد GCP الفورية

يُرجى إضافة ما يلي إلى values.yaml لتشغيل عمليات النشر على الآلات الافتراضية الفورية من GCP:

nodeSelector: &nodeSelector
  nodeSelector:
    cloud.google.com/gke-spot: "true"

redis:
  master:
    <<: *nodeSelector

global:
  ideanote:
    <<: *nodeSelector

Ubuntu 24 مع MicroK8s (مثيل AWS EC2، مجموعة بعقدة واحدة)

سيعرض لك هذا الدليل كيفية تثبيت Ideanote على مجموعة Kubernetes ذات عقدة واحدة باستخدام MicroK8s على مثيل AWS EC2.
وتستخدم الإضافات المضمّنة MicroK8snginx لموازنة الأحمال، كما تستخدم الإضافة hostpath-storage للتخزين.
فكّر في استبدال هذه الإضافات بحل جاهز للاستخدام في بيئة الإنتاج، مثل openebs للتخزين وAWS ELB لموازنة الأحمال في بيئة إنتاج.

1. أنشئ مثيل EC2 جديدًا بنظام Ubuntu 24

• ما لا يقل عن 4 وحدات معالجة مركزية و8 GB من ذاكرة الوصول العشوائي (على سبيل المثال، باستخدام نوع المثيل t1.large).
• ما لا يقل عن 30 GB من مساحة التخزين.
• تحقق من Allow HTTPS traffic from the internet
• تحقق من Allow HTTP traffic from the internet
• أنشئ زوج المفاتيح والقيم، واربطه، ثم نزّله للوصول عبر SSH.

2. اربط عنوان IP للمثيل باسم نطاق

دوّن عنوان IP العام للمثيل واربطه باسم نطاق تملكه، وذلك بإضافة سجل A إلى إعدادات DNS الخاصة بالنطاق.
على سبيل المثال: ideanote.your-domain.com أو your-domain.com.

3. اتصل بالمثيل عبر SSH

4. ثبّت MicroK8s

# Update the system
sudo apt update && sudo apt upgrade -y

# Install MicroK8s
sudo snap install microk8s --classic --channel=1.31

# Join the `microk8s` group
sudo usermod -a -G microk8s ubuntu
sudo chown -R ubuntu ~/.kube
newgrp microk8s

# Wait for all services to be running
microk8s status --wait-ready
microk8s kubectl get nodes
microk8s kubectl get services

# Alias `kubectl` to `microk8s kubectl`
alias kubectl='microk8s kubectl'

# Alias 'helm' to 'microk8s helm'
alias helm='microk8s helm'

# Add the above aliases to the `.bashrc` file
echo -e "\n# Alias kubectl to microk8s kubectl\nalias kubectl='microk8s kubectl'\n# Alias helm to microk8s helm\nalias helm='microk8s helm'" >> ~/.bashrc && source ~/.bashrc

5. فعّل الإضافات

# Required addons
microk8s enable ingress
microk8s enable hostpath-storage # Consider using "openebs" in production environment

# Optional addons
microk8s enable dashboard
microk8s enable metrics-server

6. حمّل ZIP-folder الذي زوّدك به فريق Ideanote إلى المثيل

# Run this on your local machine
chmod 400 <key>.pem
scp -i <key>.pem ideanote-on-premise.zip ubuntu@<instance ip address>:/home/ubuntu

7. فك ضغط ZIP-folder على مثيل EC2 وسجّل الدخول إلى سجل Helm

sudo apt install unzip
cd /home/ubuntu
unzip ideanote-on-premise.zip
cat helm-access-token.json | helm registry login -u _json_key --password-stdin europe-west3-docker.pkg.dev

8. حدّث الملف values.yaml بالقيم التالية

cert-manager:
  install: true
  email: <your-email-address>

# Don't install the included `nginx` Ingress controller as we are using the MicroK8s `ingress` addon
ingress-nginx:
  install: false

global:
  ideanote:
    ingress:
      url: "https://your-domain.com"

9. ثبّت مخطط Helm الخاص بـ Ideanote

helm install ideanote oci://europe-west3-docker.pkg.dev/ideanote/charts/ideanote --version 1.0.0 --create-namespace --namespace ideanote --wait --timeout 10m -f values.yaml

10. انتظر بضع دقائق حتى تبدأ جميع الخدمات ويصدر cert-manager

kubectl get deployments -n ideanote --watch
kubectl get certificaterequest -n ideanote --watch

11. أخيرًا، انتقل إلى https://your-domain.com لإعداد مساحة عمل Ideanote الخاصة بك

تهيئة values.yaml

يسرد الجدول التالي المعلمات القابلة للتهيئة في مخطط Ideanote وقيمها الافتراضية.

تهيئة المخططات الفرعية المضمّنة

تهيئة المخطط الفرعي المضمّن postgresql

يثبّت Ideanote Helm Chart مخطط Bitnami PostgreSQL chart بوصفه مخططًا فرعيًا افتراضيًا.
وهذا يهيئ قاعدة بيانات PostgreSQL لخدمة Ideanote.

يمكنكم تهيئة المخطط الفرعي PostgreSQL بتغيير القيم في الملف values.yaml ضمن المفتاح postgresql.
يرجى الاطلاع على قائمة القيم المسموح بها للمخطط الفرعي المضمّن PostgreSQL هنا
مثال على التهيئة:

postgresql:
  install: true
  primary:
    persistence:
      size: 5Gi
    resources:
      requests:
        memory: 1Gi
        cpu: 250m
      limits:
        memory: 2Gi
        cpu: 500m

كلمة المرور

سينشئ المخطط الفرعي المضمّن PostgreSQL تلقائيًا سرًا يتضمن كلمة المرور لمستخدم قاعدة البيانات والمسؤول.
يمكنكم استبدال كلمة المرور المُنشأة تلقائيًا لقاعدة البيانات بتعيين القيمة global.ideanote.psql.passwordSecret.password في الملف values.yaml.

الاتصال بقاعدة بيانات postgresql من خارج المجموعة

للاتصال بقاعدة البيانات من خارج المجموعة، نفّذوا الأوامر التالية:

kubectl get secret -n ideanote ideanote-postgres-password -o jsonpath="{.data.postgres-password-user}" | base64 -d

kubectl exec -it -n ideanote svc/ideanote-postgresql -- psql -U ideanote -d ideanote
# or
kubectl port-forward -n ideanote svc/ideanote-postgresql 5432:5432 &
psql --host 127.0.0.1 -d postgres -p 5432 -U postgres

تهيئة المخطط الفرعي المضمّن redis

يثبّت Ideanote Helm Chart مخطط Bitnami Redis chart بوصفه مخططًا فرعيًا افتراضيًا.
وهذا يهيئ قاعدة بيانات Redis لخدمة Ideanote.

يمكنكم تهيئة المخطط الفرعي Redis بتغيير القيم في الملف values.yaml ضمن المفتاح redis.
يرجى الاطلاع على قائمة القيم المسموح بها للمخطط الفرعي المضمّن Redis هنا.
مثال على التهيئة:

redis:
  install: true
  master:
    persistence:
      size: 5Gi
    resources:
      requests:
        memory: 1Gi
        cpu: 250m
      limits:
        memory: 2Gi
        cpu: 500m

الاتصال بقاعدة البيانات redis من خارج المجموعة

للاتصال بقاعدة بيانات redis من خارج المجموعة، نفّذوا الأوامر التالية:

kubectl exec -it -n ideanote svc/ideanote-redis-master -- redis-cli
# or
kubectl port-forward -n ideanote svc/ideanote-redis-master 6379:6379
redis-cli -h localhost -p 6379

تهيئة المخطط الفرعي المضمّن ingress-nginx

يثبّت Ideanote Helm Chart مخطط ingress-nginx chart بوصفه مخططًا فرعيًا افتراضيًا.
وهذا يهيئ موازن تحميل لخدمة Ideanote، ويُستخدم بوصفه متحكم الدخول لكائن الدخول Ideanote.

يمكنكم تهيئة المخطط الفرعي ingress-nginx بتغيير القيم في الملف values.yaml ضمن المفتاح ingress-nginx.
يرجى الاطلاع على قائمة القيم المسموح بها للمخطط الفرعي المضمّن ingress-nginx هنا.

مثال على التهيئة:

ingress-nginx:
  enabled: true
  controller:
    service:
      annotations:
        cloud.google.com/load-balancer-type: "Internal"
    resources:
      requests:
        memory: 1Gi
        cpu: 250m
      limits:
        memory: 2Gi
        cpu: 500m

تهيئة المخطط الفرعي المضمّن cert-manager

يقوم Ideanote Helm Chart بتثبيت مخطط cert-manager كمخطط فرعي افتراضيًا.
وهذا يضبط cert-manager لإنشاء شهادات TLS وإدارتها تلقائيًا لخدمة Ideanote.

يمكنك ضبط المخطط الفرعي cert-manager بتغيير القيم في الملف values.yaml ضمن المفتاح cert-manager.
يرجى الاطلاع على قائمة القيم المسموح بها للمخطط الفرعي cert-manager المضمّن هنا.

مثال على الإعداد:

cert-manager:
  install: true
  installCRDs: false
  replicaCount: 2

التفاعل مع خدمة cert-manager

نوصي بتثبيت cmctl للتفاعل مع خدمة cert-manager.
يمكن لأداة سطر الأوامر هذه مساعدتك في إدارة موارد cert-manager داخل مجموعتك.

على سبيل المثال، يمكنك باستخدام هذه الأداة تجديد الشهادة بتشغيل الأمر التالي:

cmctl renew ideanote-tls -n ideanote

kubectl get certificaterequest -n ideanote

ضبط الخدمات الخارجية/المُدارة

يأتي Ideanote مزودًا بمخططات فرعية مضمنة لـ PostgreSQL، Redis وLoad-balancer من الخدمات.
تُدار هذه الخدمات بواسطة Ideanote Helm Chart وتُثبّت افتراضيًا عند نشر Ideanote.
ومع ذلك، نوصي باستخدام خدمات خارجية/مدارة لأكبر عدد ممكن من هذه الخدمات عند تشغيل Ideanote في بيئة إنتاج.
سيضمن ذلك توفر بنية تحتية موثوقة وقابلة للتوسع.

يتضمن هذا القسم دليلاً حول كيفية تكوين الخدمات الخارجية/المُدارة لكل من PostgreSQL وRedis وLoad-balancer (مزيج من ingress-nginx وcert-manager).

تكوين مثيل خارجي من PostgreSQL

لاستخدام مثيل خارجي من PostgreSQL مع Ideanote، يجب توفير تفاصيل الاتصال عند تثبيت Ideanote Helm Chart.
إليك مثالاً على إعداد الاتصال بمثيل خارجي من PostgreSQL:

global:
  ideanote:
    psql:
      database: <database>
      username: <username>
      host: <host>
      passwordSecret:
        password: <password>

      # You can also instead create a secret object yourself with "kubectl" and provide it here
      # passwordSecret:
      #   name: <secret-name>
      #   key: postgres-password      # The key in the secret object where the password is stored

postgresql:
  install: false

تكوين مثيل خارجي من Redis

لاستخدام مثيل خارجي من Redis مع Ideanote، يجب توفير تفاصيل الاتصال عند تثبيت Ideanote Helm Chart.
إليك مثالاً على إعداد الاتصال بمثيل خارجي من Redis:

global:
  ideanote:
    redis:
      username: <username>
      host: <host>
      passwordSecret:
        password: <password>

      # You can also instead create a secret object yourself with "kubectl" and provide it here
      # passwordSecret:
      #   name: <secret-name>
      #   key: redis-password      # The key in the secret object where the password is stored

redis:
  install: false

إعداد مخصص لـ load-balancer

نوصي باستخدام موازن تحميل أصلي من موفر الخدمات السحابية لوحدة التحكم في الدخول.
غالباً ما يوفر موفرو الخدمات السحابية موازنات تحميل مُدارة يمكن استخدامها مع Kubernetes من خلال تعيين ingress class أو إضافة التعليقات التوضيحية إلى كائن الدخول.
يمكنك إضافة هذه القيم باستخدام الإعداد التالي:

global:
  ideanote:
    ingress:
      annotations: <annotations>
      className: <ingress-class>

cert-manager:
  install: false

ingress-nginx:
  install: false

تكوين عمليات التكامل

ستجد هنا أدلة حول كيفية تكوين عمليات التكامل المختلفة التي يدعمها Ideanote.
لا يلزم أي من عمليات التكامل هذه لتشغيل Ideanote محلياً، لكنها قد تعزز وظائف مساحة عملك.

تكوين تكامل Sendgrid

لكي يتمكن Ideanote من إرسال رسائل البريد الإلكتروني، يجب توفير مفتاح Sendgrid API عند تثبيت Ideanote Helm Chart.
يُرجى اتباع هذا الدليل لإعداد تكامل Sendgrid:

1․ أنشئ حساب Sendgrid إن لم يكن لديك حساب بالفعل.

2․ أنشئ مفتاح API في لوحة معلومات Sendgrid. يجب أن يتضمن على الأقل إمكانات Mail Send.

3․ زوّد ملف values.yaml بمفتاح API:

ideanote:
  api:
    sendgrid:
      key: "SG........."

تكوين تكامل OpenAI

لكي تتمكن منصة Ideanote من توفير وظائف الذكاء الاصطناعي، يجب توفير مفتاح OpenAI API عند تثبيت Ideanote Helm Chart.
يُرجى اتباع هذا الدليل لإعداد تكامل OpenAI:

1․ أنشئ حساب OpenAI إن لم يكن لديك حساب بالفعل.

2․ أنشئ مفتاح API في لوحة معلومات OpenAI. يجب أن يتضمن الأذونات All.

3․ زوّد ملف values.yaml بمفتاح API:

ideanote:
  api:
    openai:
      key: "sk-........."

تكوين تكامل SAML

يدعم Ideanote Helm Chart إعداد عملية النشر لديك بصفتها موفر خدمة SAML، بحيث يمكنك استخدام موفر الهوية الخاص بك للمصادقة.
يتطلب ذلك تقديم شهادة عند إعداد تكامل SAML.

يُرجى اتباع هذا الدليل لإعداد تكامل SAML:

1․ أنشئ شهادة موقّعة ذاتيًا باستخدام الأمر التالي:

openssl req -x509 -nodes -days 730 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=my-service.example.com"

2․ أضف الشهادة والمفتاح إلى ملف values.yaml وثبّت Ideanote Helm Chart:

global:
  ideanote:
    saml:
      cert: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
      key: ....

3․ انتقل إلى https://<your-domain>/api/sso/saml/metadata.xml فهذا هو الآن عنوان نقطة بيانات التعريف لموفر خدمة SAML في Ideanote.

4․ هيّئ موفّر الهوية لديك. يُرجى اتباع هذا الدليل لمزيد من المعلومات، وتذكّر استبدال عنوان URL الخاص بـ metadata.xml بعنوانك الخاص.

هيّئ تكامل LDAP

Ideanote يدعم LDAP بروتوكول التكامل مع دليل المستخدمين والمجموعات الحالي لديك، مثل Microsoft Active Directory وEntra ID. يمكنك استخدام LDAP لمصادقة المستخدمين ومزامنتهم، سواءً للتزويد عند تسجيل دخولهم إلى مساحة العمل في الوقت الفعلي، أو مسبقًا عبر خطوة التزويد المضمنة مباشرةً في معالج إعداد LDAP. لا يمكن تهيئة LDAP باستخدام إعداد values.yaml، بل يجب تهيئته بعد عملية إعداد مساحة عمل Ideanote أو أثناءها.

إذا كنت ترغب في استخدام LDAP، ولكنك لم تنفذ LDAP بعد في البنية التحتية لتقنية المعلومات لديك، فيُرجى الرجوع إلى الوثائق المناسبة لتنفيذ LDAP بما يتوافق مع بنيتك التحتية لتقنية المعلومات. نوصي بالموارد التالية:

• مصادقة LDAP باستخدام Microsoft Entra ID
• دليل خطوة بخطوة لإعداد LDAPS على Windows Server

في هذا الدليل، سنرشدك خلال عملية الإعداد على منصة Ideanote.

إعداد LDAP في مساحة العمل الخاصة بك

1. انتقل إلى الإعدادات.
   
2. انتقل إلى المصادقة.
   
3. انقر على إضافة لإنشاء خيار تسجيل دخول جديد.
   
4. اختر LDAP من قائمة الخيارات.
   

تهيئة LDAP

1. انقر على إضافة تهيئة.
   
2. أدخل عنوان URL لخادم LDAP، مع استبعاد بروتوكول ldap:// والمنفذ الخاص به.
   
3. أدخل Bind DN/UPN، وهو الاسم المميّز (DN) أو اسم المستخدم الأساسي (UPN) في بعض البيئات، مثل Microsoft Active Directory أو Microsoft Entra ID، ويُستخدم للربط (المصادقة) بدليل LDAP. وهو يحدد الإدخال داخل الدليل الذي سيستخدمه Ideanote لأغراض المصادقة والبحث. يجب أن يكون لهذا الحساب إذن قراءة الدليل. على سبيل المثال، قد يبدو اسم المستخدم الأساسي (UPN) بهذا الشكل you@your-domain.com، ما يسهل تذكره واستخدامه. وبدلًا من ذلك، قد يبدو اسم الربط المميّز (Bind DN) التقليدي بهذا الشكل CN=Admin,OU=Users,DC=your-domain,DC=com، وهو ما يحدد مستخدمًا إداريًا ضمن الوحدة التنظيمية Users في المجال your-domain.com.
   
4. أدخل كلمة مرور الربط. وهي كلمة المرور المرتبطة بالاسم المميّز للربط (Bind DN/UPN). تستخدم Ideanote كلمة المرور هذه لمصادقة اسم الربط المميّز المحدد عند الاتصال بدليل LDAP. يجب أن تتوافق كلمة المرور هذه مع الحساب المحدد في حقل Bind DN/UPN، سواء أكان اسم مستخدم أساسيًا (UPN) مثل you@your-domain.com أم اسمًا مميّزًا تقليديًا في LDAP مثل CN=Admin,OU=Users,DC=your-domain,DC=com. وتُعد كلمة المرور هذه ضرورية لإنشاء اتصال آمن لإجراء عمليات البحث وجلب معلومات المستخدم لعمليات المصادقة. وستكون القيمة المخزنة AES-256 مشفّرة.
   
5. انقر على Test Connection للتحقق من إمكانية الاتصال بعنوان URL لخادم LDAP، ومن إمكانية الربط به ("المصادقة") باستخدام Bind DN/UPN وكلمة مرور الربط المقدَّمين. إذا نجح الاتصال، فسيظهر النص تم إنشاء اتصال LDAP بنجاح بجوار الزر Test Connection.
   

في حال واجهت مشكلة، يُرجى الرجوع إلى قسم استكشاف أخطاء الاتصال وإصلاحها.

حقول التكوين الإضافية

1. يمثّل الاسم المميّز الأساسي (Base DN) المستوى الأعلى من شجرة الدليل التي ينبغي البحث فيها عند توفير المستخدمين والمجموعات. يمكنك استخدامه لتحديد الفرع الذي تريد التركيز عليه من الدليل. يجب أن يتمتع الاسم المميّز للربط (Bind DN) بصلاحية قراءة الاسم المميّز الأساسي وكائناته.
   
2. سيتم تطبيق مرشح LDAP، إن تم تحديده، عند البحث في الدليل الذي أعددته في Base DN. يفيد ذلك إذا أردت فرض قيود على نطاق المستخدمين الذين يمكن إنشاء حساباتهم والمصادقة على مساحة العمل الخاصة بك. يجب استخدام صياغة استعلام LDAP القياسية كما هو موضح في RFC 4515. على سبيل المثال: (&(givenName=you)(sn=yourlastname)).
   
3. عند التبديل إلى وضع التشغيل Use SSL/TLS، سيتم تفعيل LDAP عبر SSL (ldaps). ستظهر عدة حقول إضافية، ويمكنك الاطلاع على المزيد هنا.
   
4. عند تفعيل Use StartTLS، سيُستخدم StartTLS لبدء اتصال غير مشفّر عبر منفذ LDAP القياسي (389) أولًا، ثم ترقية الاتصال لاحقًا لاستخدام TLS من خلال عملية StartTLS. ستظهر عدة حقول إضافية، ويمكنك الاطّلاع عليها هنا.
   

تهيئة LDAPS أو StartTLS

عند تفعيل Use SSL/TLS أو Use StartTLS، ستظهر أسفله حقول تهيئة اختيارية إضافية:

1. شهادة/شهادات سلطة التصديق لخادم LDAP: قدّم شهادة/شهادات سلطة التصديق (CA) التي وقّعت شهادة SSL الخاصة بخادم LDAP. يُطلب ذلك إذا كان خادم LDAP يستخدم شهادات موقّعة ذاتيًا أو شهادات صادرة عن سلطة تصديق خاصة. يجب أن تكون الشهادة/الشهادات بتنسيق PEM.
   
2. شهادة العميل: قدّم شهادة العميل التي ستُعرض على خادم LDAP للمصادقة. يُطلب ذلك إذا كان خادم LDAP يتطلب المصادقة باستخدام شهادة العميل. يجب أن تكون الشهادة بتنسيق PEM.
   
3. المفتاح الخاص للعميل: قدّم المفتاح الخاص المطابق لشهادة العميل. يُطلب ذلك إذا قدّمت شهادة عميل. يجب أن يكون المفتاح الخاص بتنسيق PEM وألا يكون محميًا بكلمة مرور.
   
4. السماح بالشهادات الموقّعة ذاتيًا: فعّل هذا الخيار للسماح بالاتصالات بخوادم LDAP التي تستخدم شهادات موقّعة ذاتيًا دون التحقق من سلطة التصديق. تحذير: قد يؤدي تفعيل هذا الخيار إلى جعل اتصالك عرضة لهجمات الوسيط.
   

تعيين السمات

تدعم العديد من الخوادم الحديثة المتوافقة مع LDAPv3 الاستعلام عن المخطط المدعوم للسمات المتاحة. وعند توفره، سيكتشف Ideanote المخطط ويقترح إعدادات افتراضية مناسبة لكيفية ربط البيانات في دليلك بخصائص المستخدم/الفريق المقابلة في Ideanote. يمكنك الاطّلاع على عمليات الربط هذه وتخصيصها من صفحة ربط السمات.

1. 
   يمثل LDAP-attribute السمات التي تم اكتشافها في مخطط خادم LDAP لديك. وتأتي هذه السمات من موفّر الدليل لديك، مثل Microsoft Active Directory أو Microsoft Entra ID. إذا لم يكن خادم LDAP لديك متوافقًا مع LDAPv3 لأي سبب من الأسباب، فسنلجأ إلى تخمين أسماء السمات المحتملة استنادًا إلى الأعراف التاريخية وأنواع السمات الموضّحة في RFC4519. على سبيل المثال، يمثّل givenName عادةً الاسم الأول للشخص، بينما يمثّل sn عادةً اسم العائلة/اللقب للشخص.
   
2. 
   
   يمثّل النوع نسخة مبسّطة من تعريف الصياغة لسمة LDAP. توجد تعريفات صياغة كثيرة من هذا النوع، وقد وُصفت جميعها هنا في RFC4517، ولكن للتبسيط، تجمع Ideanote هذه التعريفات في التعريفات التالية:
   
   
   
   
   
   
   
   • 
     string: يمثّل تسلسلاً من المحارف. تستخدم تعريفات صياغة LDAP مثل DirectoryString، وPrintableString، وTelephoneNumber، وNumericString، وغيرها هذا النوع.
     
   • 
     date: يمثّل تاريخًا مرفقًا بطابع زمني، إما بالتنسيق Generalized Time (YYYYMMDDHHMMSSZ) أو بالتنسيق UTCTime (YYMMDDHHMMSSZ). سيفهم Ideanote ذلك ويحلّله، ما يتيح لك تعيينه إلى خصائص المستخدم/الفريق Ideanote الخاصة بالتاريخ.
     
   • 
     integer: رغم أن LDAP لا يتضمن تعريفات صياغة لقيم الفاصلة العائمة (إذ ستستخدم هذه بدلاً من ذلك تعريفات صياغة مثل NumericString، التي ستُعيّن إلى string في Ideanote)، فإن النوع `integer` يمثّل الأعداد الصحيحة، ويمكن تعيينها إلى خصائص المستخدم/الفريق Ideanote الرقمية.
     
   • 
     boolean: القيم المنطقية true وfalse.
     
   • 
     binary: تمثّل بعض سمات LDAP بيانات ثنائية، مثل السمة الشائعة thumbnailPhoto لصور الملفات الشخصية الرمزية للمستخدمين. ولا يمكن عادةً تعيينها إلا إلى avatar لدى مستخدمي Ideanote، وإلى logo لدى فرق Ideanote.
     
   • 
     reference: يشير تعريف صياغة LDAP DN (Distinguished Name) إلى كيان آخر يحمل اسم DN هذا، ويُستخدم عادةً في تعيين السمات على منصة Ideanote لتعيين السمة memberOf لارتباطات المجموعات لدى المستخدم إلى فرق Ideanote المكافئة.
     
3. 
   سمة المطابقة Ideanote تمثل خاصية البيانات لدى المستخدمين/الفرق التي ينبغي ربط سمة LDAP بها. يمكنك تخصيصها بالنقر على قائمة الخيارات المنسدلة لكل صف في القائمة. تعتمد الخيارات المتاحة للاختيار على نوع سمة LDAP. على سبيل المثال، لا يمكن ربط سمة LDAP من النوع date بـ First name.
   

مزامنة مجموعات/فرق المستخدمين

إذا كنت تريد مزامنة عضويات الفرق الخاصة بمستخدم (أو إيقاف مزامنتها) عند تسجيل دخوله إلى Ideanote (أو عند توفيره مسبقًا عبر خطوة التوفير)، فحدّد سمة LDAP التي تمثّل المجموعة (أو المجموعات) التي ينتمي إليها المستخدم.

في Microsoft Active Directory و Microsoft Entra ID، يُسمى هذا السمة عادةً memberOf، ويكون من النوع reference في Ideanote.

بشكل افتراضي، ستكون هذه السمة معيّنة بالفعل إلى خاصية المستخدم الخاصة Teams في Ideanote، كما هو موضح في الرسم التوضيحي أعلاه.

إذا كنت تريد إيقاف مزامنة الفرق:

1. حدّد سمة LDAP memberOf (أو الخاصية المكافئة في مخطط خادم LDAP لديك)
2. انقر على القائمة المنسدلة في ذلك الصف، ضمن عمود سمة Ideanote المطابقة.
3. حدّد عدم الاستيراد.

إنشاء تعيين مخصص للسمات

تعتمد التعيينات التي يعرضها Ideanote افتراضيًا على محاولاتنا لاختيار إعدادات افتراضية مناسبة. إذا كنت تريد تعيين سمات أخرى إلى Ideanote، فيمكنك أيضًا النقر على زر إضافة سمة الموجود أسفل جدولَي المستخدمين والمجموعات/الفرق.

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

يمكن حذف تعيينات السمات التي أنشأتها عبر مربع الحوار إضافة سمة بالنقر على رمز «×» بجوار الصف كما هو موضح أدناه، أو بتغيير التعيين إلى Do Not Import.

التوفير

عند تسجيل المستخدمين الدخول إلى مساحة العمل، ستُجرى لهم عملية التوفير. وهذا يعني مزامنة تمثيل بياناتهم في الدليل مع المستخدم المكافئ لهم في Ideanote، وفقًا لقواعد تعيين السمات التي حدّدتها.

ومع ذلك، توجد حالات كثيرة يكون فيها توفير المستخدمين مسبقًا أمرًا مناسبًا. ومن حالات الاستخدام الشائعة توفير جميع المستخدمين والفرق مسبقًا، بحيث تتمكن من إعداد صلاحيات الوصول إلى مجموعات أفكارك قبل دعوتهم رسميًا للمساهمة في مساحة العمل.

تتيح لك خطوة التوفير في إعدادات LDAP إجراء ذلك.

1. حقل البحث يتيح لك إجراء بحث مباشرةً في دليل LDAP الخاص بك. سيبحث الإدخال الذي تقدمه ضمن سمات LDAP الشائعة distinguishedName، userPrincipalName، sAMAccountName، mail، displayName، وcn.
   
2. يعرض الجدول جميع الإدخالات التي تم جلبها من دليلك، بالإضافة إلى التفاصيل ذات الصلة بكل منها، مثل ما إذا كانت تمثل مستخدمًا أو مجموعة، وموعد آخر مزامنة لها مع مساحة عملك، وغير ذلك.
   
3. يتيح لك عامل التصفية تضييق نطاق نتائج البحث أكثر. يمكنك اختيار عرض المجموعات أو المستخدمين فقط، وكذلك عرض الكيانات التي لم يسبق توفيرها في مساحة عملك فقط.
   
4. يبدأ زر بدء التوفير عملية التوفير. وستتمكن من متابعة التقدم في شريط تقدم بجوار الزر. وعند تفعيل التوفير، ستتمكن أيضًا من النقر على إلغاء لمنع توفير كيانات إضافية.
   

استكشاف مشكلات الاتصال وإصلاحها

عند إعداد LDAP على نحو صحيح، سيظهر النص تم إنشاء اتصال LDAP بنجاح بجوار الزر Test Connection.

ومع ذلك، قد تواجه بعض المشكلات الشائعة. فيما يلي نصائح لاستكشاف كل رسالة خطأ محتملة وإصلاحها:

خطأ: تعذّر تحديد موقع خادم LDAP. تأكد من إدخال عنوان URL الصحيح للخادم ومن أن شبكتك الحالية قادرة على الاتصال به.

الأسباب المحتملة:

• قد يكون عنوان URL لخادم LDAP مكتوبًا بشكل خاطئ أو غير صحيح.
• يتعذر على التطبيق الوصول إلى خادم LDAP بسبب قيود الشبكة.

خطوات استكشاف المشكلة وإصلاحها:

• تحقق مرة أخرى من اسم المضيف أو عنوان IP بحثًا عن أخطاء مطبعية.
• تأكد من وجود خادم LDAP على الشبكة الظاهرية نفسها التي يوجد عليها نشر Ideanote. وإذا لم يكن الأمر كذلك، فأعد إعداد ربط الشبكات أو شبكة VPN حتى تتمكن الشبكتان من الاتصال.
• تأكد من السماح بالاتصالات الصادرة من مجموعة Kubernetes التي تشغّل النشر المحلي لـ Ideanote على المنافذ التالية:
  
  
  • 389 لـ LDAP (افتراضيًا)
  • 636 لـ LDAPS (افتراضيًا)
• حدّث قواعد جدار الحماية للسماح بحركة المرور إلى خادم LDAP على هذه المنافذ.
• إذا كنت تستخدم اسم مضيف، فتحقق من إعداد تحليل DNS على نحو صحيح داخل مجموعة Kubernetes.
• إذا كنت تستخدم Microsoft Entra ID وأعددت للتو Microsoft Entra Domain Services لتمكين تكامل LDAP، فيجب إعادة تشغيل مجموعة Kubernetes بالكامل قبل أن تتمكن من تحليل اسم المضيف.

خطأ: فشلت مصادقة LDAP باستخدام DN الربط وكلمة مرور الربط المقدّمين.

الأسباب المحتملة:

• بيانات الاعتماد غير صحيحة.
• مزامنة تجزئة كلمة المرور غير مفعّلة (وهي مشكلة شائعة في Microsoft Entra Domain Services)
• حساب المستخدم المستخدَم للربط معطّل أو مقفل أو منتهي الصلاحية.
• يتطلب خادم LDAP استخدام LDAPS، وقد لا تكون قد فعّلت مفتاح التبديل Use SSL/TLS، أو قدّمت شهادات/مفاتيح غير صحيحة.

خطوات استكشاف الأخطاء وإصلاحها:

• تحقّق مرة أخرى من صحة صيغة Bind DN وخلوّها من الأخطاء المطبعية.
  
  
  • يجب أن يكون Bind DN هو الاسم المميّز الكامل للمستخدم (مثل cn=admin,dc=example,dc=com)، أو اسم UPN الخاص به مثل you@your-domain.com عند استخدام Microsoft Entra ID أو Microsoft Active Directory.
• تأكّد من صحة كلمة مرور الربط.
• أجرِ المصادقة باستخدام عميل LDAP مع Bind DN وكلمة مرور الربط للتأكد من عملهما خارج Ideanote.
• عند استخدام Microsoft Entra Domain Services، تأكّد من تمكين مزامنة تجزئات كلمات المرور. إذا كنت قد أعددت Microsoft Entra DOmain Services مؤخراً، فقد تحتاج إلى إعادة تعيين كلمة مرور حساب Bind DN الذي تحاول المصادقة باستخدامه. فيما يلي تعليمات حسابات المستخدمين السحابية فقط، وفيما يلي تعليمات حسابات المستخدمين المتزامنة.
• تحقّق من أن حساب المستخدم المستخدَم للربط نشط ولا يخضع لأي قيود.
• حدّد ما إذا كان خادم LDAP يتطلب SSL/TLS.
  
  
  • إذا كان الأمر كذلك، فعّل Use SSL/TLS لاستخدام ldaps:// في عنوان URL للخادم. وتأكد أيضاً من أن LDAP Server PORT يشير إلى المنفذ الصحيح، وهو 636 افتراضياً لـ LDAPS.
  • تحقّق من تقديم شهادة CA الصحيحة لخادم LDAP، وشهادة العميل، والمفتاح الخاص للعميل (إذا لزم الأمر).
  • اختبر ما إذا كان تمكين «السماح بالشهادات الموقّعة ذاتياً» يحل المشكلة.
  • تأكّد من أن شهادة SSL لخادم LDAP موثوق بها لدى مجموعة Kubernetes.
  • استورد شهادة خادم LDAP إلى مخزن الثقة الخاص بالمجموعة عند الضرورة.

خطأ: نجحت المصادقة عبر LDAP، ولكن تعذّر البحث ضمن Base DN المقدّم.

الأسباب المحتملة:

• إن Base DN غير صحيح أو يشير إلى موقع غير صحيح في الدليل.
• ليس لدى مستخدم الربط إذن البحث ضمن Base DN المقدّم.

خطوات استكشاف الأخطاء وإصلاحها:

• تأكّد من تنسيق Base DN بشكل صحيح (مثل DC=your-domain,DC=com).
• تحقّق من وجود أخطاء مطبعية أو فواصل أو علامات مساواة في غير مواضعها.
• تأكّد من أن مستخدم الربط المحدد بواسطة Bind DN لديه أذونات القراءة/البحث ضمن Base DN.
• استخدم عميل LDAP (مثل ldapsearch) لاختبار البحث ضمن Base DN باستخدام بيانات اعتماد مستخدم الربط.
• تأكّد من أن بنية الدليل ضمن Base DN تحتوي على مدخلات المستخدمين التي تنوي الوصول إليها.

إذا لم تساعد أي من نصائح استكشاف الأخطاء وإصلاحها هذه، فيُرجى الرجوع إلى الوثائق المقدمة من مزود البنية التحتية لديك، أو التواصل مع Ideanote للحصول على مزيد من المساعدة في استكشاف الأخطاء وإصلاحها.

التهيئة لبيئة الإنتاج

يتضمن هذا القسم توصيات لتهيئة Ideanote Helm Chart لبيئات الإنتاج.

الخدمات الخارجية

نوصي بإسناد أكبر عدد ممكن من الخدمات إلى خدمات خارجية/مدارة عند تشغيل Ideanote في بيئة إنتاج.
وذلك لضمان توفر بنية تحتية موثوقة وقابلة للتوسع.

وينبغي على وجه الخصوص إدارة خدمة PostgreSQL خارجيًا، لأن المخطط الفرعي PostgreSQL المضمّن لا يدعم التوافر العالي أو النسخ الاحتياطية أو التوسع تلقائيًا.

يُرجى الرجوع إلى قسم تهيئة الخدمات الخارجية/المدارة لمزيد من المعلومات حول كيفية تهيئة الخدمات الخارجية.

التوسع التلقائي

افتراضيًا، لا يفعّل Ideanote Helm Chart التوسع التلقائي للخدمات.
وتأتي جميع الخدمات بعدد نسخ متماثلة افتراضي قدره 1، ويمكن توسيعها يدويًا بتغيير القيمة replicaCount في الملف values.yaml.

يمكنك تفعيل التوسع التلقائي للخدمات بإضافة ما يلي إلى الملف values.yaml:

global:
  ideanote:
    autoscaling:
      enabled: true

ingress-nginx:
  controller:
    autoscaling:
      enabled: true
      minReplicas: 2
      maxReplicas: 6

سيؤدي ذلك إلى إنشاء مُوسِّع أفقي تلقائي للـPod (HPA) لكل خدمة Ideanote، وتوسيع عدد النسخ المتماثلة استنادًا إلى استخدام الخدمة لوحدة المعالجة المركزية والذاكرة.
إنّ api و webapp ستتراوح خدمات 2 و 4 بين 1 و 4 نسخة متماثلة افتراضيًا، بينما ستتراوح بقية الخدمات بين minReplicas و maxReplicas. ويمكنك تغيير الحد الأدنى والأقصى لعدد النسخ المتماثلة بتغيير القيمتين values.yaml في ملف كل خدمة.
مثال على الإعداد:

ideanote:
  api:
    autoscaling:
      minReplicas: 3
      maxReplicas: 5

  html-renderer:
    autoscaling:
      enabled: false

  convert:
    autoscaling:
      minReplicas: 2
      maxReplicas: 3

طلبات الموارد

افتراضيًا، لا تحدد Ideanote Helm Chart طلبات الموارد لخدمات Ideanote.
ويتيح ذلك تشغيل الخدمات على مجموعات ذات موارد محدودة.

في بيئات الإنتاج، نوصي بتفعيل طلبات الموارد على مستوى النظام بإضافة ما يلي إلى ملف values.yaml:

global:
  ideanote:
    resources:
      enabled: true

تأتي كل خدمة بطلبات وحدود افتراضية لوحدة المعالجة المركزية/الذاكرة، وينبغي أن تكون مناسبة لمعظم حالات الاستخدام، لذا يُفترض أن يكون تفعيل الموارد على مستوى النظام كافيًا.
ومع ذلك، إذا احتجت إلى تغيير طلبات الموارد لخدمة معينة، فيمكنك فعل ذلك بتغيير القيم في ملف values.yaml ضمن مفتاح الخدمة المعني.
على سبيل المثال:

global:
  ideanote:
    resources:
      enabled: true

ideanote:
  api:
    resources:
      requests:
        memory: 1Gi
        cpu: 250m
      # Disable limits
      limits:
        memory: null
        cpu: null

postgresql:
  primary:
    resources:
      requests:
        memory: 1024Mi
        cpu: 500m
      limits:
        memory: 1536Mi
        cpu: 750m

redis:
  master:
    resources:
    requests:
        memory 512Mi
        cpu: 500m
    limits:
        memory: 768Mi
        cpu: 750m

ingress-nginx:
  controller:
    resources:
      requests:
        memory: 256Mi
        cpu: 250m
      limits:
        memory: 512Mi
        cpu: 500m

cert-manager:
  cainjector:
    resources:
      requests:
        cpu: 50m
        memory: 128Mi
  webhook:
    resources:
      requests:
        cpu: 50m
        memory: 128Mi
  startupapicheck:
    resources:
      requests:
        cpu: 50m
        memory: 128Mi
  resources:
    requests:
      cpu: 50m
      memory: 128M

وحدات التخزين الدائمة والنسخ الاحتياطية

إذا ثبّتَّ Ideanote Helm Chart مع جميع المخططات الفرعية المضمّنة، فسيُنشئ 3 PVCs (مطالبات وحدات التخزين الدائمة) في عنقودك:

• data-<release>-postgresql-0 لقاعدة بيانات PostgreSQL
• redis-data-<release>-redis-master-0 لقاعدة بيانات Redis
• <release>-storage-data لتحميلات الوسائط في Ideanote

سيخصص Kubernetes وحدات PVs (وحدات التخزين الدائمة) المقابلة لهذه PVCs، وستُخزَّن البيانات في هذه الوحدات.

بالنسبة إلى عمليات النشر في بيئة الإنتاج، نوصي بتنفيذ المهام الـ3 التالية:

1․ تم ضبط مساحة التخزين الافتراضية المخصصة للخدمات على الحد الأدنى. نوصي بزيادة حجم مساحة التخزين وفقًا لاحتياجاتك، وذلك بتعديل الملف values.yaml:

postgresql:
  primary:
    persistence:
      # Used as primary database. Critical to increase if you expect a large amount usage.
      size: 10Gi

redis:
  master:
    persistence:
      # Used as a memory cache. Not necessarily critical to increase.
      size: 5Gi

ideanote:
  storage:
    persistence:
      # User uploaded files will be stored here. Increase if you expect large file uploads.
      size: 20Gi

2․ PVs تُنشأ افتراضيًا وفق سياسة الاستعادة Delete، ما يعني أنه عند حذف PVC، سيُحذف أيضًا PV والبيانات الموجودة عليه. لذلك نوصي بتغيير سياسة الاستعادة إلى Retain بالنسبة إلى PVs الذي أنشأه Ideanote Helm Chart. ويمكنك فعل ذلك بتعديل PVs المخصّص باستخدام الأمر التالي:

# Set all PVs in the ideanote namespace to "Retain"
kubectl get pv -n ideanote -o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{end}' | xargs -I {} kubectl patch pv {} -n ideanote -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'

# Check that the PVs have been patched
kubectl get pv -n ideanote

# Patch individual PVs with the reclaim policy Retain
kubectl patch pv <pv-name> -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}' -n ideanote

3․ نوصي أيضًا بإعداد استراتيجية نسخ احتياطي تلقائي لجميع وحدات التخزين.

التسجيل والمراقبة

في الوقت الحالي، لا يوفر Ideanote حلًا مدمجًا للتسجيل مع مخطط Helm، لكننا نوصي بإعداد حل للمراقبة في بيئات الإنتاج.

في بيئات الإنتاج، نوصي أيضًا بتعديل global.ideanote.logLevel إلى info أو warn في ملف values.yaml للحد من كمية السجلات التي تنشئها الخدمات.

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

فحوصات الصحة الخارجية

فحوصات الصحة الداخلية

موازنة الأحمال وشبكة توصيل المحتوى (CDN)

إذا كان ذلك ممكنًا في بيئتك، نوصي بإعداد شبكة توصيل محتوى (CDN) أمام موازن الأحمال Ideanote لتخزين الأصول الثابتة مؤقتًا وتقليل الحمل على الخدمة.
ويُفضّل إعداد شبكة توصيل المحتوى (CDN) لتخزين جميع المسارات التي تبدأ بـ /files و /chunk- مؤقتًا.

الترقية

عند تشغيل Ideanote محليًا، ستحتاج إلى الترقية إلى إصدار جديد عند توفر إصدار جديد.
سيُعلمك Ideanote بتوفر إصدار جديد، وسيوفر ملاحظات الإصدار لكل إصدار جديد، والتي ستتضمن معلومات حول التغييرات غير المتوافقة والميزات الجديدة.

في بيئات الإنتاج، ستحتاج إلى إيلاء اهتمام خاص لـ دليل الترقية الذي يوفره Ideanote لتجنب أي توقف أو فقدان للبيانات.

استكشاف الأخطاء وإصلاحها

يُرجى التواصل مع developer@ideanote.io إذا واجهت مشكلات أثناء تشغيل Ideanote محليًا.
سيساعدك Ideanote في استكشاف المشكلة وإصلاحها، وسيقدم إرشادات حول كيفية حلها وفقًا للاتفاقية المعمول بها.
قبل التواصل معنا، يُرجى مراجعة دليل استكشاف الأخطاء وإصلاحها التالي لفهم المشكلة ومحاولة حلها بنفسك.

تعذّر تثبيت مخطط Helm

إذا كان Ideanote Helm Chart لا يُثبَّت، يُرجى تشغيل أمر التثبيت مع الخيار --debug للحصول على مزيد من المعلومات حول الخطأ.
سيعرض ذلك معلومات أكثر تفصيلًا عن الخطأ، ويساعدك على فهم سبب المشكلة.

إذا لم تتمكن من حل المشكلة، يُرجى التواصل مع developer@ideanote.io للحصول على مزيد من المساعدة.
يُرجى تضمين أكبر قدر ممكن من المعلومات حول المشكلة، بما في ذلك مخرجات التثبيت باستخدام --debug وملف values.yaml.

يمكنك أيضًا الاطلاع على نظرة عامة على المكونات المتعطلة بتشغيل الأمر التالي:

kubectl get all,certificaterequests,issuer -n ideanote

مخطط Helm عالق في حالة انتظار أو في حالة فشل

اطّلع على حالة مخطط Helm بتشغيل الأمر التالي:

helm status ideanote -n ideanote
# or
helm history ideanote -n ideanote

إذا كان مخطط Helm عالقًا في حالة انتظار أو في حالة فشل، فقد تحتاج إلى التراجع باستخدام الأمر التالي:

helm rollback ideanote -n ideanote

عنوان URL/IP-address أو شهادة SSL لا تعمل

يمكنك اختبار ما إذا كان IP-address المرتبط بموازن التحميل يستجيب على نحو صحيح، وذلك بتشغيل الأوامر التالية:

1․ اجمع عنوان IP الذي تم تخصيصه ديناميكيًا لموازن التحميل. تأكد من إقران مورد الدخول بعنوان IP وأسماء المضيفين.

kubectl get ingress -n ideanote

2․ تحقق من استجابة مجموعة Kubernetes للطلبات على النحو الصحيح باستخدام أمر curl هذا مع القيم (عنوان IP المرتبط واسم مضيف واحد) الواردة في الأمر أعلاه. تأكد من أنه يستجيب برمز الحالة 200 OK وبملف index-html الخاص بخدمة Ideanote.

# With only host
curl -kivL <host>

# With host and IP-address
curl -kivL -H 'Host: <host>' <ip-address>

3․ مع المخطط الفرعي ingress-controller المضمّن nginx، ينبغي أن تصبح الخدمة متاحة بشهادة TLS بعد بضع دقائق. وستستخدم شهادة موقّعة ذاتيًا يوفّرها ingress-nginx-controller افتراضيًا إلى أن يتم إنشاء الشهادة. ستعرض المتصفحات تحذيرًا يفيد بأن هذه الشهادة غير صالحة. بعد بضع دقائق، ينبغي إنشاء الشهادة وإتاحة الخدمة بشهادة صالحة.

4․ يمكنك التحقق من حالة CertificateRequest بتشغيل الأمر التالي:

kubectl get certificaterequest -n ideanote
kubectl describe CertificateRequest ideanote-tls-1 -n ideanote
kubectl get Issuer -n ideanote

تتعطل خدمة API باستمرار لأنها لا تستطيع الاتصال بقاعدة البيانات/Redis

إذا كانت خدمة api تتعطل لأنها لا تستطيع الاتصال بقاعدة البيانات أو Redis، فيُرجى التحقق مما يلي.

2․ تحقّق من سجلات خدمة api:

kubectl logs -n ideanote svc/ideanote-api

2․ تحقّق مما إذا كان postgres وredis قيد التشغيل (اتبع الخطوات )

kubectl get pods -n ideanote

قد تحتاج أحيانًا فقط إلى فرض إعادة تشغيل خدمة api لكي تتمكن من الاتصال بقاعدة البيانات وRedis مجددًا.

kubectl get pods -n ideanote
kubectl delete pod <pod-name> -n ideanote --force

kubectl run --rm -it --image=busybox test-pod -- /bin/sh
ping <redis-service-ip>
nc -zv <redis-service-ip> 6379

ping <postgres-service-ip>
nc -zv <postgres-service-ip> 5432

kubectl exec -it -n ideanote svc/ideanote-api -- /bin/sh

أرى الكثير من أخطاء TypeError: fetch failed في السجلات

أولًا، تحقّق من أن جميع الوحدات (pods) قيد التشغيل:

kubectl get pods -n ideanote

يمكنك أيضًا التحقق من إمكانية حل اسم DNS للخدمة مباشرةً من الوحدة (pod). على سبيل المثال:

kubectl exec svc/ideanote-api -n ideanote -- nslookup ideanote-convert.ideanote.svc.cluster.local

يمكنك التحقق من إمكانية اختبار اتصالك بالخدمات الأخرى مباشرةً من الوحدة (pod). على سبيل المثال:

kubectl exec svc/ideanote-webapp -n ideanote -- wget -qO- http://ideanote-api.ideanote.svc.cluster.local

قد تكون المشكلة أيضًا متعلقةً بسياسات الشبكة، التي يمكنها أحيانًا حظر الاتصال بين الخدمات.
قد تضطر إلى تعطيل سياسات الشبكة مؤقتًا لـ Ideanote لمعرفة ما إذا كانت هي سبب المشكلة.
يمكنك تعطيل سياسات الشبكة بتعيين global.ideanote.networkPolicies.enabled إلى false في الملف values.yaml.

مراقبة حركة مرور الشبكة في مجموعتك

يمكنك استخدام https://www.kubeshark.co/ لمراقبة حركة مرور الشبكة في مجموعتك.

1․ ثبّت kubeshark

sh <(curl -Ls https://kubeshark.co/install)

# OR

brew install kubeshark

2․ ابدأ kubeshark

kubeshark tap -n ideanote

3․ افتح لوحة معلومات kubeshark في متصفحك وراقب حركة مرور الشبكة

اختبار توفر كل خدمة

فيما يلي نظرة عامة على كيفية اختبار توفر كل خدمة.
يُرجى استخدام هذا الدليل مرجعًا لكيفية اختبار كل خدمة في حال حدوث مشكلات.

بث السجلات

لعرض سجلات خدمة معينة، يمكنك استخدام الأمر التالي.

kubectl logs -n ideanote svc/ideanote-api

يفيد هذا في تصحيح أخطاء الخدمة. يمكنك أيضًا طباعة سجلات جميع الوحدات (pods) في مساحة الاسم ideanote بتشغيل الأمر التالي:

kubectl get pods -n ideanote -o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{end}' | xargs -I {} kubectl logs -n ideanote {} --all-containers=true

إذا كنت ترغب في بث سجلات جميع الخدمات دفعةً واحدة، فنوصي بتثبيت kubetail وتشغيل الأمر التالي:

kubetail -n ideanote

أثناء استكشاف الأخطاء وإصلاحها، نوصي أيضًا بتعديل global.ideanote.logLevel إلى debug في الملف values.yaml لزيادة مقدار السجلات التي تنشئها الخدمات.

تحقّق من حالة الخدمات

للتحقق من جاهزية عمليات النشر، يمكنك تشغيل الأمر التالي. ينبغي أن يعرض 1/1 READY لكل خدمة.

kubectl get deployments -n ideanote

إذا لم تكن إحدى الخدمات جاهزة، يمكنك التحقق من الخدمة بتشغيل الأمر التالي:

kubectl describe deployment <service-name> -n ideanote

للحصول على عرض أكثر تفصيلاً للخدمات، نوصي بتثبيت k9s وتشغيل الأمر التالي:

k9s -n ideanote

تطبيق الويب

ينبغي أن تكون خدمة webapp متاحة على المسار /. ينبغي أن يعيد الأمر التالي رمز الحالة 200 OK مع ملف index html:

curl -kL your-domain.com

بدلاً من ذلك، يمكنك إعادة توجيه منفذ الخدمة إلى جهازك المحلي واختبارها باستخدام curl:

kubectl port-forward --namespace ideanote svc/ideanote-webapp 3000:80
curl -kL localhost:3000

واجهة برمجة التطبيقات

ينبغي أن تكون خدمة api متاحة على المسار /api. ينبغي أن يعيد الأمر التالي رمز الحالة 200 OK مع النص "Ideanote API":

curl -kL your-domain.com/api

بدلاً من ذلك، يمكنك إعادة توجيه منفذ الخدمة إلى جهازك المحلي واختبارها باستخدام curl:

kubectl port-forward --namespace ideanote svc/ideanote-webapp 3000:80
curl -kL localhost:3000

إذا أردت فحص قائمة انتظار الرسائل الداخلية في Ideanote API، فيمكنك زيارة المسار /api/bullmq.
للحصول على بيانات اعتماد قائمة انتظار الرسائل API، يُرجى تشغيل الأمر التالي:

kubectl get secret --namespace ideanote ideanote-api -o jsonpath="{.data.API_BULLMQ_CREDENTIALS}" | base64 -d

أداة الفكرة

ينبغي أن تكون خدمة idea-widget متاحة على المسار /widget. ينبغي أن يعيد الأمر التالي رمز الحالة 200 OK مع ملف index html:

curl -kL your-domain.com/widget

بدلاً من ذلك، يمكنك إعادة توجيه منفذ الخدمة إلى جهازك المحلي واختبارها باستخدام curl:

kubectl port-forward --namespace ideanote svc/ideanote-idea-widget 3000:80
curl -kL localhost:3000

التخزين

ينبغي أن تكون خدمة storage متاحة على المسار /files. ينبغي أن يعيد الأمر التالي رمز الحالة 200 OK مع النص "Ideanote Storage":

curl -kL your-domain.com/files

بدلاً من ذلك، يمكنك إعادة توجيه المنفذ الخاص بالخدمة إلى جهازك المحلي واختبارها باستخدام curl. ينبغي أن تعيد رمز الحالة 200 OK مع النص "Ideanote Convert":

kubectl port-forward --namespace ideanote svc/ideanote-storage 3000:80
curl -kL localhost:3000

تحويل

خدمة convert غير مكشوفة على الإنترنت، ولكن يمكنك اختبارها بإعادة توجيه منفذ الخدمة إلى جهازك المحلي واختبارها باستخدام curl.
ينبغي أن تعيد رمز الحالة 200 OK مع النص "Ideanote Convert":

kubectl port-forward --namespace ideanote svc/ideanote-convert 3000:80
curl -kL localhost:3000

يمكنك أيضًا التحقق من حالة مهام تحويل تحميل الوسائط بزيارة المسار /bullmq.

# 1: Port-forward the service to your local machine
kubectl port-forward --namespace ideanote svc/ideanote-convert 3000:80
# 2: Visit the /bullmq path in a browser:
http://localhost:3000/bullmq

عارض HTML

خدمة html-renderer غير مكشوفة على الإنترنت، ولكن يمكنك اختبارها بإعادة توجيه منفذ الخدمة إلى جهازك المحلي واختبارها باستخدام curl.
ينبغي أن تعيد رمز الحالة 200 OK مع النص "Ideanote HTML Renderer":

kubectl port-forward --namespace ideanote svc/ideanote-html-renderer 3000:80
curl -kL localhost:3000

postgresql

للتحقق من توفر الخدمة PostgreSQL، يمكنك إعادة توجيه منفذ الخدمة إلى جهازك المحلي واختبارها باستخدام psql.

# 1. Get the password for the database
kubectl get secret --namespace ideanote ideanote-postgres-password -o jsonpath="{.data.postgres-password-user}" | base64 -d

# 2. Open a connection to the database
kubectl exec -it -n ideanote svc/ideanote-postgresql -- psql -U ideanote -d ideanote

# 3. Check that the API has correctly run migrations in the database.
#    It should show a list of tables.
#    If this command shows "Did not find any relations." it means that the API hasn't been able to connect to the database.
ideanote=> \d

# 4. Exit psql
ideanote=> \q

redis

للتحقق من توفر الخدمة Redis، يمكنك إعادة توجيه منفذ الخدمة إلى جهازك المحلي واختبارها باستخدام redis-cli.

# 1. Port-forward the service to your local machine
kubectl port-forward --namespace ideanote svc/ideanote-redis-master 6379:6379

# 2. Initiate a connection to the database
redis-cli -h localhost -p 6379

# 3. Check that the api and convert services have been able to connect to the database.
127.0.0.1:6379> CLIENT LIST

# 4. Check that the api and convert services have been able to create keys in the database.
127.0.0.1:6379> KEYS *

مدير الشهادات

يُرجى الرجوع إلى الدليل الرسمي لمعرفة كيفية التحقق من تثبيت cert-manager بشكل صحيح.

إذا لم يتم إنشاء شهادتك، فيمكنك التحقق من حالة CertificateRequest عن طريق تشغيل الأمر التالي:

kubectl get certificaterequest -n ideanote
kubectl describe CertificateRequest ideanote-tls-1 -n ideanote

يمكنك أيضًا التحقق من حالة Issuer عن طريق تشغيل الأمر التالي:

kubectl get Issuer -n ideanote

من المفيد أيضًا التحقق من سجلات خدمة cert-manager لمعرفة ما إذا كانت هناك أي مشكلات.

ingress-nginx

للتحقق من حالة خدمة ingress-nginx، تحقّق أولًا من أنها قيد التشغيل:

kubectl get deployments -l app.kubernetes.io/name=ingress-nginx -n ideanote

جرّب إعادة توجيه منفذ الخدمة إلى جهازك المحلي واختبارها باستخدام curl (والذي ينبغي أن يعيد رمز الحالة "404 Not Found"):

kubectl port-forward --namespace ideanote svc/ideanote-ingress-nginx-controller 8080:80
curl -kL localhost:8080

ينبغي أيضًا التحقق من أنه قد تم تخصيص عنوان IP لها:

kubectl get svc -l app.kubernetes.io/name=ingress-nginx -n ideanote

تحقق أيضًا من أن Ideanote ingress قد تم تعيينه بشكل صحيح إلى ingress-nginx موازن التحميل.
ينبغي أن يعرض عنوان IP نفسه مثل خدمة ingress-nginx واسم المضيف المتوقع الذي عيّنته في ملف values.yaml عند تثبيت Ideanote Helm Chart.

kubectl get ingresses -n ideanote

جرّب إرسال طلب curl إلى عنوان IP. ينبغي أن يعيد رمز الحالة "404 Not Found":

curl -kL <ip-address>

جرّب الآن تضمين ترويسة "Host" في الطلب.
ينبغي أن يعرض ملف HTML للفهرس الخاص بخدمة تطبيق الويب Ideanote:

curl -kL -H 'Host: <host>' <ip-address>

أخيرًا، جرّب زيارة النطاق في متصفح. ينبغي أن يعرض تطبيق الويب Ideanote.

ترقية Ideanote إلى إصدار جديد

سيُصدر Ideanote إصدارات جديدة من Ideanote Helm Chart دوريًا، تتضمن ميزات جديدة وإصلاحات للأخطاء.
عند الترقية إلى إصدار جديد، ستحتاج إلى اتباع دليل الترقية الذي يقدمه Ideanote لتجنب أي توقف أو فقدان للبيانات.

صُممت جميع الخدمات لتكون عديمة الحالة (باستثناء redis وpostgres وstorage)، ويمكن ترقيتها دون أي توقف باستخدام استراتيجية التحديث المتتابع.

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

نحرص على اختبار الإصدارات في بيئات الإنتاج الخاصة بنا قبل طرحها للجمهور، لكننا نوصي باختبار الإصدار الجديد في بيئة تجريبية قبل ترقية بيئة الإنتاج.

قبل الترقية إلى إصدار جديد، يُرجى اتباع الخطوات التالية

1․ راجع ملاحظات الإصدار لمعرفة ما إذا كانت هناك تغييرات غير متوافقة أو ميزات جديدة.

2․ انسخ بياناتك احتياطيًا. نوصي بإنشاء نسخة احتياطية من قاعدتي بيانات PostgreSQL وRedis قبل الترقية إلى إصدار جديد. بالإضافة إلى ذلك، ضع خطة واضحة ومختبرة للتراجع عن تغييرات قاعدة البيانات في حال فشل الترقية.

3․ نوصي بتثبيت المكوّن الإضافي helm-diff وتشغيل الأمر التالي للاطلاع على التغييرات الدقيقة التي ستُجرى على مجموعة Kubernetes الخاصة بك:

HELM_DIFF_USE_INSECURE_SERVER_SIDE_DRY_RUN=true helm diff upgrade oci://europe-west3-docker.pkg.dev/ideanote/charts/ideanote --version 1.0.0 --namespace ideanote --values values.yaml --dry-run=server

عند الترقية إلى إصدار جديد، يُرجى اتباع الخطوات التالية:

1․ رقِّ Ideanote Helm Chart إلى الإصدار الجديد:

helm upgrade ideanote oci://europe-west3-docker.pkg.dev/ideanote/charts/ideanote --version 1.0.0 --namespace ideanote --wait --timeout 10m -f values.yaml

2․ تحقّق من حالة الترقية:

helm status ideanote --namespace ideanote

helm history ideanote --namespace ideanote

kubectl get pods -n ideanote --watch

3․ تُعدّ خدمة api أهم خدمة يجب التحقق منها بعد الترقية، إذ قد تستغرق عمليات الترحيل بضع دقائق لإكمالها، وقد تفشل وتتسبب في انقطاع الخدمة. اعرض سجلات API لمتابعة عمليات الترحيل:

kubectl logs svc/ideanote-api -n ideanote -f

عند التراجع إلى إصدار سابق، يُرجى اتباع الخطوات التالية:

1․ تحقّق مما إذا كانت قد نُفذت أي عمليات ترحيل في خدمة api:

kubectl logs svc/ideanote-api -n ideanote

يمكنك أيضًا التحقق من حالة عمليات ترحيل api باستخدام psql:

# 1. Get the password for the database
kubectl get secret --namespace ideanote ideanote-postgres-password -o jsonpath="{.data.postgres-password-user}" | base64 -d

# 2. Open a connection to the database
kubectl exec -it -n ideanote svc/ideanote-postgresql -- psql -U ideanote -d ideanote

# 3. Check if the API has ran migrations in the database. You can compare "migration_time" with the current date.
ideanote=> select * from knex_migrations order by migration_time desc limit 10;

2․ تراجع عن إصدار helm إلى الإصدار السابق:

helm rollback ideanote --namespace ideanote

3․ تحقّق من حالة التراجع عن التغييرات:

helm status ideanote --namespace ideanote

4․ إذا اكتملت بالفعل أي عمليات ترحيل في خدمة api وكنت بحاجة إلى التراجع، فمن الضروري للغاية أن تتراجع أيضًا عن قاعدة البيانات إلى حالتها السابقة، لأن مخطط قاعدة البيانات الجديد قد لا يكون متوافقًا مع الإصدار القديم من خدمة api، ولن تتمكن وحدة pod الخاصة بـ api من بدء التشغيل بسبب عدم تطابق مخطط قاعدة البيانات.

إصدارات مخطط Helm

فيما يلي قائمة بإصدارات Ideanote Helm Chart والتغييرات التي أُجريت في كل إصدار.

1.0.0

الإصدار الأول من Ideanote Helm Chart العام.

تغيير values.yaml بعد التثبيت

إذا غيّرت ملف values.yaml بعد تثبيت Ideanote Helm Chart، فيمكنك ترقية الإصدار باستخدام الأمر التالي:

helm upgrade ideanote oci://europe-west3-docker.pkg.dev/ideanote/charts/ideanote --version 1.0.0 --namespace ideanote --wait --timeout 10m -f values.yaml

إلغاء تثبيت Ideanote

لإلغاء تثبيت Ideanote Helm Chart، نفّذ الأمر التالي:

helm uninstall ideanote --namespace ideanote

سيؤدي ذلك إلى إزالة جميع الموارد والخدمات المرتبطة بـ Ideanote Helm Chart من مجموعة Kubernetes لديك.

تذكّر أنه لن تُلغى عملية تثبيت جميع الموارد، وسيتعين عليك إزالة الموارد التالية يدويًا:

# Delete all PVCs associated with the Ideanote Helm Chart
kubectl delete pvc -l app.kubernetes.io/name=postgresql -n ideanote
kubectl delete pvc -l app.kubernetes.io/name=redis -n ideanote
kubectl delete pvc -l app.kubernetes.io/name=storage -n ideanote

# Delete all PV's associated with the Ideanote Helm Chart
kubectl get pv -n ideanote
kubectl delete pv <pv-name>

# Delete global CustomResourceDefinitions (don't do this if you have multiple Ideanote installations in the same cluster)
kubectl delete crd \
  issuers.cert-manager.io \
  clusterissuers.cert-manager.io \
  certificates.cert-manager.io \
  certificaterequests.cert-manager.io \
  orders.acme.cert-manager.io \
  challenges.acme.cert-manager.io

# Delete the namespace
kubectl delete namespace ideanote