التثبيت والتشغيل

يتضمن هذا المستند المعلومات اللازمة لتثبيت برنامج Parsewise وتشغيله في البنية التحتية للعميل: مكونات التوريد، ومتطلبات البيئة، والإعداد، وإجراءات التثبيت والتشغيل.

1. مكونات التوريد

بيانات التوريد هي بيانات التثبيت السحابي لصاحب الحقوق، ومدوَّنة فيها عناوينه وخدماته. قبل تطبيقها يكيّفها العميل مع تثبيته:

• عناوين الصور — إلى الإصدارات من سجل التوريد؛
• القيم المكتوبة مباشرة في بيانات الخادم ومعالج الطوابير: FRONTEND_URL، SHOPS_DOMAIN، R2_ENDPOINT، R2_PUBLIC_URL، SMTP_HOST، SMTP_PORT، SMTP_USE_TLS، SMTP_START_TLS — إلى قيمه الخاصة (القيمة في البيان مقدَّمة على القيمة في السر)؛ LLM_MODEL_QUERY — إلى اسم نموذجه أو حذفها؛
• الإشارات إلى مفاتيح السر yandex-gpt-api-key وyandex-gpt-folder-id وyandex-maps-api-key وإلى السر metrika-credentials — تُحذف: فهي لازمة للتثبيت السحابي فقط، ومن دونها لا تعمل الحاويات في العنقود؛
• في بيان لوحة التحكم — تُحذف NEXT_PUBLIC_API_URL وNEXT_PUBLIC_YM_COUNTER_ID وتُعيَّن معاملات PARSEWISE_* من القسم 3؛
• قالب الأسرار — يُملأ بقيم العميل ويُطبَّق؛ ويضم كل الأسرار التي تقرؤها بيانات التوريد، ومنها app-config-full بالمعاملات SECRET_KEY وDOCS_USERNAME وDOCS_PASSWORD وEMAIL_FROM وINGRESS_LB_IP وLLM_BASE_URL؛
• معاملات الخدمات التي لا يستخدمها العميل — تُحذف: استقبال المدفوعات عبر Robokassa، وYandex Metrica؛
• نموذج سياسة الوصول إلى الحاوية — يُستبدل فيه اسم الحاوية وحساب الخادم؛ وهو مكتوب لـ Yandex Object Storage، وفي تخزين آخر تُضبط قواعد الوصول نفسها (القسم 2) بأدواته؛
• لعناوين المشاريع بصيغة مشروع.نطاق — تُصدر شهادة لـ *.نطاق عبر cert-manager مع تحقق DNS01 لدى مزوّد DNS الخاص بالعميل، وتُذكر في 06a-ingress-shops.yaml.

بيانات موقع التسويق والتوثيق والمراقبة ليست ضمن التوريد.

تُسلَّم الصور كأرشيف OCI لتحميلها في سجل العميل أو عبر سجل صور صاحب الحقوق.

تُبنى الصور من مرايا صاحب الحقوق: لا تُنزَّل الصور الأساسية وحزم Python وحزم npm من مستودعات عامة أثناء البناء. لمعالجة الصوت والفيديو تتضمن صورة الخادم ffmpeg من توزيعة Debian. لا يُنزَّل نموذج التضمين أثناء التثبيت والتشغيل. تعمل العمليات في حاويات الخادم ولوحة التحكم بمستخدم غير ذي امتيازات.

2. متطلبات البيئة

تفتح كل حاوية للخادم ولمعالج الطوابير حتى 40 اتصالًا بـ PostgreSQL. عند وجود عدد كبير من النسخ يُنصح باستخدام مجمّع اتصالات، مثل PgBouncer أو Odyssey.

موارد الحوسبة

مجموع طلبات الموارد دون مكونات نظام Kubernetes: نحو 5.8 vCPU و14.9 غيبيبايت من الذاكرة عند الحد الأدنى للنسخ، ونحو 21.1 vCPU و47.6 غيبيبايت عند الحد الأقصى. يجب أن تتسع العقدة لحاوية تضمين بطلب ذاكرة قدره 2.5 غيبيبايت.

الإعداد الذي يشغّل عليه صاحب الحقوق البرنامج: 4–10 عقد، كل منها 4 vCPU و8 غيبيبايت مع إضافة تلقائية للعقد؛ القاعدتان الرئيسية والمتجهية عنقودان منفصلان من PostgreSQL 15، كل منهما 2 vCPU و8 غيبيبايت مع قرص 20 غيبيبايت يتوسع تلقائيًا حتى 64 غيبيبايت؛ Valkey 7.2 — 2 vCPU و4 غيبيبايت.

3. الإعداد

تُعيَّن معاملات الخادم ومعالج الطوابير والمجدول بمتغيرات البيئة — من أسرار Kubernetes أو كقيم في البيانات (القسم 1). تتلقى النشرات الثلاث معاملات الاتصال نفسها بقواعد البيانات وRedis وتخزين الكائنات.

إلزامية

للمعاملات FRONTEND_URL وEMAIL_FROM وSHOPS_DOMAIN وINGRESS_LB_IP قيم افتراضية تشير إلى التثبيت السحابي لصاحب الحقوق، لذا يجب تعيينها في تثبيت العميل.

النموذج اللغوي

لا يستخدم البرنامج خدمات شركة OpenAI: «متوافق مع OpenAI» يعني فقط صيغة الواجهة البرمجية التي يدعمها vLLM وخوادم النماذج الأخرى. والاسمان openai وOPENAI_API_KEY محفوظان وفق هذه الصيغة.

التضمين

اختيارية

لوحة التحكم والأداة

تقرأ لوحة التحكم معاملات التثبيت من متغيرات بيئة الحاوية عند التشغيل. المتغير غير المعيَّن يُبقي القيمة التي بُنيت بها الصورة؛ والمتغير بقيمة فارغة يعطّل الوظيفة المقابلة. بُنيت الصورة بقيم التثبيت السحابي لصاحب الحقوق — عدّاد Yandex Metrica، وتطبيقات Yandex ID وVK ID، وعنوان الأداة على releases.parsewise.ru — لذا تُعيَّن في تثبيت العميل PARSEWISE_YM_COUNTER_ID وPARSEWISE_YANDEX_CLIENT_ID وPARSEWISE_VK_CLIENT_ID صراحة بقيمه الخاصة أو فارغة، وPARSEWISE_WIDGET_SCRIPT_URL بعنوان الأداة في البنية التحتية للعميل.

تحصل الأداة على عنوان خادم الواجهة البرمجية عبر المعامل apiUrl في window.ParsewiseConfig على الصفحة، مع معرّف المشروع shopId؛ وعلى رابط سياسة معالجة البيانات الشخصية عبر المعامل privacyPolicyUrl أو من إعدادات المشروع.

البناء نفسه للوحة التحكم والأداة يعمل في أي تثبيت: لا حاجة إلى إعادة بنائهما لعنوان العميل ومعاملاته.

4. التثبيت

1. جهّز PostgreSQL: القاعدتين الرئيسية والمتجهية. يجب أن يتوفر النوع vector في القاعدة المتجهية. إن لم يتوفر، ينفّذ البرنامج CREATE EXTENSION IF NOT EXISTS vector؛ وإن لم يكن لدور التطبيق هذا الحق، ينفّذ مسؤول القاعدة CREATE EXTENSION vector مسبقًا.
2. جهّز Redis وحاوية تخزين كائنات متوافق مع S3؛ واضبط قواعد CORS والوصول إلى كائنات الحاوية وفق القسم 2.
3. حمّل الصور إلى سجل متاح للعنقود واذكر عناوينها في البيانات.
4. أنشئ مساحة الأسماء والأسرار بمعاملات القسم 3.
5. اذكر في بيان التوجيه أسماء نطاقات الواجهة البرمجية ولوحة التحكم، واضبط TLS.
6. طبّق البيانات. عند التشغيل ينشئ الخادم الجداول الناقصة في القاعدة الرئيسية ويطبّق الترحيلات المضمّنة في الصورة؛ وينشئ التخزين المتجهي جداوله وفهارسه.
7. ضع ملفات الأداة على خادم ثابت أو في تخزين الكائنات لدى العميل.
8. تحقّق من التثبيت:
   • جميع الحاويات في حالة الجاهزية؛ تحمّل حاويات التضمين النموذج خلال مدة تصل إلى ثلاث دقائق؛
   • يعيد الطلب GET /v1/public/health إلى خادم الواجهة البرمجية {"status": "ok"}؛
   • في سجل الخادم يوجد السطر Alembic migrations applied (head reached) ولا توجد رسائل Alembic upgrade failed ولا أخطاء pgvector.

5. بدء العمل

1. ادخل إلى لوحة التحكم وأنشئ مشروعًا.
2. اضبط شخصية المساعد: الاسم والصورة الرمزية وقواعد الإجابة.
3. املأ قاعدة المعرفة: ارفع الملفات، أو استورد المنتجات أو الملفات الشخصية من ملف، أو اربط مصدرًا عبر رابط.
4. ادعُ أعضاء الفريق وعيّن الأدوار.
5. اربط الأداة بصفحات الموقع أو الحساب الشخصي:

<script>
  window.ParsewiseConfig = {
    shopId: "معرّف_المشروع",
    apiUrl: "https://عنوان_خادم_API",
  };
</script>
<script async src="https://عنوان_الملفات_الثابتة/widget.iife.js"></script>

الإجراءات التفصيلية للعمل في لوحة التحكم موجودة في دليل المستخدم والمسؤول.

6. التشغيل