سايدكار

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

السايدكار هي واجهة Bun الخلفية المشتركة بين سطح المكتب وتكامل التطوير المحلي. فهو يفتح SQLite، ويوفر المستودعات وخدمات المجال، ويخدم واجهة برمجة تطبيقات HTTP المحددة بالمخطط، ويستضيف المساعد وتكامل سير العمل. يبدأ غلاف Tauri الملف الثنائي المعبأ ويكتشف المنفذ المخصص له من حدث بدء تشغيل يمكن قراءته آليًا.

apps/sidecar/src/layers.ts يتكون من واجهة برمجة التطبيقات المقدمة والمعالجات والترخيص والمستودعات والخدمات. يتم تكوين مقدمي الخدمات الاختياريين مثل الدفع المدفوع ونماذج الذكاء الاصطناعي من خلال خدماتهم؛ غيابهم لا يحول سجل قاعدة البيانات إلى تكامل خارجي فعال.

بروتوكول العملية والإغلاق

خادم HTTP الرئيسي يربط فقط 127.0.0.1، مع المنفذ 0 لذلك يختار نظام التشغيل منفذًا متاحًا. تم تعطيل مهلة HTTP الخاملة للسماح باستدعاء مساعد طويل بالبقاء صامتًا بين الأحداث المتدفقة. تم تكوين إيقاف تشغيل HTTP بطريقة رشيقة لمدة 500 مللي ثانية قبل متابعة إنهاء النطاق.

بعد نجاح التحقيق في الصحة العامة لواجهة برمجة التطبيقات (API)، تقوم العملية بطباعة حدث جاهز على stdout. يؤدي فشل بدء التشغيل إلى طباعة حدث خطأ وتعيين رمز خروج فاشل. تنتقل السجلات التشغيلية إلى stderr كـ JSON؛ stdout محجوز لبروتوكول العملية الأصلية.

{"event":"ready","port":53211}
{"event":"error","message":"Startup failure details"}

رسالة stdin منتهية بالسطر الجديد مع event: "shutdown"أو إغلاق stdin أو SIGINT أو SIGTERM يطلق نطاق الخادم. يتم تجاهل الرسائل الأصلية المشوهة، كما يتم تجاهل السطر غير المكتمل ذو الحجم الكبير. تقوم أدوات الإنهاء بإيقاف الخدمات المملوكة ونقطة التفتيش/إغلاق SQLite. يتم الإبلاغ عن إنهاء المقاطعة فقط كخروج نظيف.

التكوين المطلوب

AppConfigService يقرأ تكوين العملية مرة واحدة apps/sidecar/src/config.ts. CADCAMFUN_TOKEN هو الرمز المميز لحامل التطبيق المطلوب و CADCAMFUN_DATA_DIR هو دليل بيانات التطبيق المطلوب. مسار قاعدة البيانات هو <dataDir>/cadcamfun.db. CADCAMFUN_MIGRATIONS_DIR اختياري ويوفر مجلد ترحيل SQL؛ وبدونها لا تطبق طبقة قاعدة البيانات عمليات ترحيل التطبيق.

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

bun run --filter @cadcamfun/sidecar start

تحدد الحزمة السايدكار start و typecheck مخطوطات. التجميع الثنائي المعبأ مملوك للنصوص البرمجية لإصدار المستودع، وليس حزمة سايدكار build يأمر.

التكوين الاختياري

• CADCAMFUN_APP_URL يحدد الأساس لروابط المصادقة؛ CADCAMFUN_DEBUG_LINKS يتيح إعادة ضبط تصحيح الأخطاء/الروابط السحرية والإعدادات الافتراضية إلى خطأ.
• CADCAMFUN_AI_HOST هو nikcli (افتراضي؛ يتم تشغيل الدردشة من خلال مضيف المحادثة المضمن) أو direct (AI SDK فقط). CADCAMFUN_AI_OFFLINE (منطقي، خطأ افتراضي) يؤدي إلى تعطيل مسار شبكة كتالوج النماذج الاختياري. CADCAMFUN_AI_MINIMAX_BASE_URL يتجاوز نقطة نهاية MiniMax.
• STRIPE_SECRET_KEY تمكن مزود الشريط؛ STRIPE_PRICE_BASIC, STRIPE_PRICE_PRO، و STRIPE_PRICE_ENTERPRISE توفير أسعار الخطة المدفوعة. STRIPE_WEBHOOK_SECRET مطلوب للتحقق من webhook الموقع.
• CRON_SECRET يزود سر طريق كرون. وبدون ذلك، يمكن للتطبيق المحلي الاتصال بهذا المسار بدون سر كرون إضافي. ADMIN_EMAIL هو التحقق من هوية المسؤول القديم؛ بشكل افتراضي، يكون ملف التعريف المحلي هو المسؤول عن التثبيت الخاص به.
• OTEL_EXPORTER_OTLP_ENDPOINT لتمكين تصدير القياس عن بعد OTLP الذي تم تكوينه. بدون نقطة نهاية، يتم إيقاف تصدير القياس عن بعد الخارجي.

كل هذه الأسماء قرأتها في مكان واحد AppConfigService; يتم الاحتفاظ بالمفتاح السري للرمز المميز والشريط كقيم منقحة حتى لا تظهر في السجلات. تتم إدارة مفاتيح موفر الذكاء الاصطناعي من خلال واجهة برمجة تطبيقات بيانات الاعتماد وملف بيانات الاعتماد المخصص. ولا تتم قراءتها كإعدادات بيئة مفتاح API للبائع بواسطة AppConfigService.

الوصول إلى HTTP واكتشاف واجهة برمجة التطبيقات (API).

ينشر السايدكار /api/openapi.json لعقده المقدم ويستخدم البرامج الوسيطة لحاملها في المجموعات المحمية. يختار رأس الجلسة الاختيارية الثانية الحساب التمثيلي. يتم إنشاء ملف التعريف المحلي أو إعادة استخدامه ضمن local@cadcamfun.local، مع إبقاء التثبيت قابلاً للاستخدام دون تسجيل الدخول إلى الحساب.

يعترف كورس tauri://localhost، HTTP/HTTPS tauri.localhostو HTTP localhost أو 127.0.0.1 ينشأ بمنفذ اختياري. لا تتلقى الأصول الأخرى أي رأس استجابة للأصل المسموح به. CORS هي سياسة المتصفح؛ تظل البرمجيات الوسيطة للحامل هي التحكم في الوصول إلى المسارات المحمية.

تغطي المجموعات المقدمة موارد التصميم، وإنشاء التصنيع والتحقق منه، وCAD الدقيق، والمكتبات، والتكاليف، والذكاء الاصطناعي، وVCS/سير العمل، والأحداث، وعناصر التحكم المصاحبة، والهوية، والمؤسسات، والإشعارات، والملفات، والمكونات الإضافية، والفوترة، والتحليلات، وقائمة الانتظار، وMCP، والحالة المحلية. راجع مستند OpenAPI قيد التشغيل للحصول على تفاصيل الطريقة والحمولة.

رأس الحساب التمثيلي هو x-session-token. بدونه، أو باستخدام رمز مميز لا يتم التحقق منه باعتباره رمزًا مميزًا للجلسة لمستخدم حالي، تعمل الطلبات كملف تعريف محلي (src/http/authorization.ts).

منظمة المصدر

main.ts يطلق الخادم المحدد والبروتوكول الأصلي. config.ts تكوين الإمدادات, layers.ts تبعيات الأسلاك, startup.ts جاهزية الأسهم ومنفذ الاسترجاع، shutdown.ts يقرأ رسائل إيقاف تشغيل الوالدين، و observability.ts تكوين القياس عن بعد الاختياري.

http/ خرائط التحقق من صحة الطلبات للخدمات. repos/ يقوم بتعيين الموارد لاستعلامات Drizzle وقواعد الوصول إلى الموارد. services/ ينسق السلوك عبر الموارد، و plugins/ يحتوي على تطبيقات العامل المضيف والمتصفح.

مجموعات المعالج

يتم تجميع المعالجات حسب الموارد: المشاريع والرسومات والمكونات ومسارات الأدوات والإضافات، ومولد مسار الأدوات، وCAD الدقيق، وتكوينات المواد/الأدوات/الجهاز وطرق تخزينها، والمكتبة، والتكاليف، والملفات، والمؤسسات، والإشعارات، والمستخدم/المصادقة، والفوترة، والتحليلات، وقائمة الانتظار، وMCP، وخدمات التطبيقات المتنوعة، وحالة القيمة الرئيسية، والذكاء الاصطناعي، وVCS، والأحداث، وإدارة المرافق.

entity-io.ts كيان أسهم مساعدي الاستيراد/التصدير. authorization.ts يطبق بيانات اعتماد التطبيق والجسر. لقد اجتازت الحمولة المعلنة للمعالج بالفعل فك تشفير المخطط؛ لا يزال التحقق من صحة مستوى الخدمة يتحقق من المراجع والملكية واتساق الأدلة وقيود المجال.

تكوين خدمة المجال

توفر خدمات الذكاء الاصطناعي إجراءات الرسم وCAM، والفحص المعياري/الدقيق، وسياق المشروع، والذاكرة، ومجلات العمال، وأدوات المكونات الإضافية. cam-program.ts يعيد تشغيل طلبات التصنيع التي تم التقاطها والتحقق من صحة الأدلة الأصلية أثناء عمليات الحفظ. تطبق خدمات السجل اللقطات وقواعد الفرع المحمي ونقل GitHub وتنفيذ سير العمل.

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

حدود المستودع

تستخدم المستودعات المشتركة Database.query خدمة للاستمرارية وفشل التخزين المكتوب. يقومون بفك تشفير JSON المخزن وفرض الوصول الخاص بالموارد أو توفير مساعدي التفويض. تقوم معالجات HTTP بترجمة فشل المجال/التخزين إلى أخطاء الاستجابة المعلنة؛ الحسابات الهندسية تبقى في @cadcamfun/core.

تكامل البرنامج المساعد

مضيف العامل العام موجود plugins/host.ts. يتم تمكين تحميل خدمة البرنامج المساعد لمساعد الإنتاج بشكل صريح ai:tool ملحقات من دليل البرنامج المساعد للتطبيق. يستخدم مثبت ZIP للمتصفح وواجهة برمجة تطبيقات bootstrap مسارات البيان والتخزين الخاصة بهما. يرى الإضافات قبل تحديد تنسيق الامتداد أو افتراض أن القدرة سلكية.

بوابة HTTPS المصاحبة

البوابة المصاحبة عبارة عن مستمع HTTPS منفصل يمكنه استئناف الإعداد الذي تم تمكينه مسبقًا. فهو يربط IPv4 لعملاء الشبكة، ويقدم شهادة تم إنشاؤها ويتم الاحتفاظ بها بموجب <dataDir>/companion، ويستخدم الرموز المميزة للجهاز القابلة للإلغاء. يوفر الاقتران بصمة شهادة حتى يتمكن جهاز النقل المحمول من تثبيت سطح المكتب.

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

الاستعداد والتشخيص

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

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

ملكية البيانات

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

إطلاق مثيل محلي يمكن التخلص منه

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

export CADCAMFUN_DATA_DIR="$(mktemp -d /tmp/cadcamfun-docs.XXXXXX)"
export CADCAMFUN_TOKEN="$(openssl rand -hex 32)"
export CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle"
export CADCAMFUN_AI_HOST=direct
export CADCAMFUN_AI_OFFLINE=1
bun run --filter @cadcamfun/sidecar start

اقرأ منفذ الحدث الجاهز بدلاً من افتراض رقم ثابت. أبقِ stdin مفتوحًا أثناء تشغيل الخدمة؛ تطلب الأنابيب من مصدر إدخال منتهي بالفعل إيقاف تشغيله. استخدم SIGTERM أو بروتوكول إيقاف التشغيل لتحرير قاعدة البيانات. يظل الدليل القابل للتصرف متاحًا للتفتيش بعد الخروج.

مع توفر عنوان URL للاتصال ورمزه المميز بالفعل في غلاف العميل، قارن الحياة العامة بالوصول المحمي:

curl --fail-with-body "$CADCAMFUN_URL/api/health"
curl --fail-with-body -H "Authorization: Bearer $CADCAMFUN_TOKEN" "$CADCAMFUN_URL/version"
curl --fail-with-body -H "Authorization: Bearer $CADCAMFUN_TOKEN" "$CADCAMFUN_URL/api/projects"

مصدر: apps/sidecar/src/main.ts, config.ts, shutdown.ts، و test/process.test.ts.

السجلات والقياس عن بعد الاختياري

سجلات Stderr JSON وأحداث الاستعداد/الخطأ stdout لها مستهلكون مختلفون. يجب على المشغل تحليل خطوط stdout الكاملة وإعادة توجيه stderr أو الاحتفاظ به بشكل منفصل. يعد الطلب الذي يفشل بعد الاستعداد بمثابة خطأ في التطبيق، وليس حدث بدء تشغيل ثانٍ.

متى OTEL_EXPORTER_OTLP_ENDPOINT تم تكوينه، ObservabilityLive يقوم بإعداد الدُفعات للامتدادات/السجلات وتصدير المقاييس الدورية. فإنه يلحق /v1/traces, /v1/metrics، و /v1/logs إلى قاعدة المجمع المتوفرة بعد إزالة الخطوط المائلة الزائدة. توفير قاعدة جامع مثل http://collector:4318، بدلاً من عنوان URL للإشارة المُلحقة بالفعل.

اسم خدمة الموارد هو cadcamfun-sidecar ونسخته تأتي من تكوين التطبيق. تتم معالجة إعدادات بيئة موارد OpenTelemetry القياسية بواسطة SDK. يعد التصدير عبر الشبكة اختياريًا، بينما يظل stderr المحلي متاحًا عند عدم تكوين أي أداة تجميع.

مصدر: apps/sidecar/src/observability.ts و main.ts.

تحديد الحدود الفاشلة

تغطي اختبارات دورة حياة العملية الحقيقية EOF، وخط JSON لإيقاف التشغيل المقسم، وSIGTERM، ثم أعد تشغيل دليل البيانات نفسه وتحقق من المشاريع المستمرة. يقومون أيضًا بتفتيش WAL بعد الخروج. يؤدي هذا إلى تحديد سلوك دورة حياة العملية المصدر؛ لا تزال القشرة المعبأة والتسليم الخاص بالآلة تتطلب التحقق من صحتها.

مصدر: apps/sidecar/test/process.test.ts, src/http/authorization.ts, src/layers.ts، و src/services/companion.ts.

تسلسل بدء التشغيل بالتفصيل

1. تنشئ الصدفة رمز إطلاق مميزًا مكونًا من 32 بايت عشوائي، بترميز سداسي عشري كأحرف 64، وتبدأ السايدكار بـ CADCAMFUN_TOKEN, CADCAMFUN_DATA_DIR، و CADCAMFUN_MIGRATIONS_DIR.
2. AppConfigService يقرأ كافة الإعدادات مرة واحدة. فشل الإعداد المطلوب المفقود في بدء التشغيل باستخدام error حدث.
3. يتم فتح طبقة قاعدة البيانات <dataDir>/cadcamfun.db، ويمكّن وضع WAL والمفاتيح الخارجية، ويطبق عمليات الترحيل من دليل عمليات الترحيل.
4. تتكون الطبقات من: قاعدة البيانات، ثم المستودعات، ثم الخدمات، ثم معالجات HTTP. كل مورد مملوك لطبقة، لذلك يقوم إيقاف التشغيل بتحريره بترتيب تبعية عكسي.
5. يرتبط خادم HTTP 127.0.0.1 على المنفذ 0، ويقوم نظام التشغيل باختيار منفذ مجاني.
6. يتم التحقيق في طريق الصحة العامة. إلا بعد أن يجيب هو {"event":"ready","port":N} مكتوب على stdout.
7. ينتظر الصدفة ما يصل إلى 60 ثانية لهذا الخط ويعيد تشغيل السايدكار مرة واحدة على الأكثر. ينتظر عرض الويب ما يصل إلى 125 ثانية لمدة get_sidecar_endpoint، ثم يتصل.

نموذج المصادقة

تستخدم الرموز المميزة HS256 مع جهة الإصدار cadcamfun. التحقق من الرموز المميزة التي تم إبطالها باسم invalid، ويتم تجاهل الرموز المميزة غير المعروفة أو المزورة عن طريق الإلغاء. يتم إنشاء سر التوقيع مرة واحدة لكل تثبيت ويتم تخزينه في دليل البيانات، لذلك يتم التحقق من الروابط الصادرة قبل إعادة التشغيل بعد ذلك.

ما يعيش في دليل البيانات

قم بعمل نسخة احتياطية للدليل بأكمله أثناء إيقاف السايدكار، أو بعد إيقاف التشغيل الذي قام بفحص WAL. النسخ فقط cadcamfun.db بينما يمكن أن تفوت عمليات التشغيل السايدكار عمليات الكتابة الأخيرة التي لا تزال موجودة في ملف WAL.

تم التقاط الخط الجاهز

CADCAMFUN_TOKEN=t CADCAMFUN_DATA_DIR="$(mktemp -d)" \
CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle" \
CADCAMFUN_AI_HOST=direct CADCAMFUN_AI_OFFLINE=true \
bun --no-env-file apps/sidecar/src/main.ts
# stdout: {"event":"ready","port":43461}

يتم اختيار المنفذ بواسطة نظام التشغيل في كل بداية. السطر هو أول إخراج قياسي بعد أن تصبح عمليات الترحيل والطبقات جاهزة، لذلك يمكن للعميل الذي يراه أن يتصل بواجهة برمجة التطبيقات (API) على الفور. أبقِ stdin مفتوحًا: إغلاقه هو إشارة إيقاف التشغيل.

في 3د