الوثائق

تكوين وقت التشغيل

اختر العملية ودليل البيانات ونوع بيانات الاعتماد وإعدادات التكامل التي تتحكم فعليًا في كل وقت تشغيل.

مترجم تلقائيًا من الإنجليزية. عرض الأصل بالإنجليزية

أصحاب التكوين

يقرأ السايدكار تكوين البيئة من خلاله AppConfigService في apps/sidecar/src/config.ts. تقرأ الطبقة تلك القيم عند إنشائها وتمرر قيمة AppConfig إلى الخدمات التي تحتاج إليها. لا يؤدي تغيير متغير shell الأصلي إلى تغيير الخدمة قيد التشغيل بالفعل.

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

قم بتكوين مالك السلوك الذي تنوي تغييره. على سبيل المثال، لا يؤدي تعيين عنوان URL لترحيل واجهة سطر الأوامر (CLI) إلى إعادة توجيه قاعدة بيانات سطح المكتب الأصلية، كما أن تكوين مساعد التوثيق لا يوفر بيانات اعتماد موفر الذكاء الاصطناعي لسطح المكتب.

ابدأ سايدكار معزولة

محطة تفاعلية في جذر المستودع

CADCAMFUN_TOKEN=local-development-token \
CADCAMFUN_DATA_DIR=/tmp/cadcamfun-config-example \
CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle" \
CADCAMFUN_AI_HOST=direct \
CADCAMFUN_AI_OFFLINE=1 \
bun --no-env-file apps/sidecar/src/main.ts

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

بالنسبة للحلقة الأصلية العادية، استخدم bun run desktop:dev. يقوم بإعداد ثنائي السايدكار والترحيلات قبل تشغيل Tauri، الذي يمتلك اتصال العملية الناتج. لا تبدأ تشغيل سايدكار يدوية ثانية وتفترض أن عرض الويب الأصلي سيتم إرفاقه بها.

إعدادات الاتصال والتخزين المطلوبة

جلسة	تقصير	سلوك
`CADCAMFUN_TOKEN`	مطلوب	بيانات اعتماد حامل التطبيق المنقحة لمسارات واجهة برمجة التطبيقات المحلية المحمية.
`CADCAMFUN_DATA_DIR`	مطلوب	جذر الولاية المحلية المُدارة بواسطة السايدكار. قاعدة البيانات هي `cadcamfun.db` تحته.
`CADCAMFUN_MIGRATIONS_DIR`	غائب	تم تمرير دليل الترحيل إلى طبقة قاعدة البيانات. بدونها، لا يؤدي فتح قاعدة البيانات إلى إنشاء جداول التطبيقات أو ترقيتها.
`CADCAMFUN_APP_URL`	غائبة في التكوين	تم توفير عنوان URL الأساسي لعمليات تكامل رابط الحساب. تقرر الخدمة ذات الصلة الإجراء الاحتياطي الخاص بها.
`CADCAMFUN_DEBUG_LINKS`	خطأ شنيع	تمكين حقول استجابة التطوير لارتباطات الحساب في المعالجات التي تدعمها.

دليل البيانات هو جذر تخزين، وليس عنوان ربط HTTP. تم إصلاح مستمع الخادم الرئيسي 127.0.0.1 مع منفذ سريع الزوال. تستخدم الشبكة المصاحبة بوابة HTTPS الخاصة بها والتي تم تمكينها بشكل صريح؛ لا يؤدي تغيير إعداد URL إلى جعل مستمع الاسترجاع عامًا.

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

تتم قراءة الرمز المميز للتطبيق كقيمة منقحة ولا يظهر أبدًا في سجلات التكوين. تتم قراءة كل إعداد في هذه الصفحة مرة واحدة apps/sidecar/src/config.ts; تصبح القيمة التي تم تغييرها سارية المفعول فقط بعد إعادة تشغيل السايدكار.

مضيف الذكاء الاصطناعي والاتصال

جلسة	تقصير	سلوك
`CADCAMFUN_AI_HOST`	`nikcli`	يختار `nikcli` أو `direct`. لا يضيف المضيف المباشر حلقة الأداة المستمرة المضمنة والمجدول المتخصص.
`CADCAMFUN_AI_OFFLINE`	خطأ شنيع	تعطيل تحميل كتالوج موفر الشبكة ومعالج البحث المباشر على الويب. إنه ليس تنفيذ نموذج محلي.
`CADCAMFUN_AI_MINIMAX_BASE_URL`	غائب	تجاوز نقطة النهاية المقطوعة الاختيارية لتكوين MiniMax المضمن.

تتم إدارة مفاتيح الموفر بواسطة واجهة برمجة التطبيقات الخاصة ببيانات الاعتماد وتستمر بواسطة خدمة الذكاء الاصطناعي في <dataDir>/ai/credentials.json. ولا يتم توفيرها عن طريق اختراع متغير بيئة غير موثق لكل مزود. استخدم نقاط نهاية حالة الموفر/النموذج لتحديد ما تم تكوينه و دليل الذكاء الاصطناعي لتوجيه النموذج المباشر المدعوم.

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

يتم تحميل سياسة المشغل من <dataDir>/ai/policy.json. يقوم المضيف المضمن بعزل أدلة العمل/التكوين الخاصة به أسفل مساحة تخزين الذكاء الاصطناعي الخاصة بالتطبيق. السياسة وبيانات الاعتماد وسياق الجلسة وذاكرة التخزين المؤقت لكتالوج الموفر لها أغراض مختلفة؛ لا يؤدي نسخ ملف واحد إلى إعادة بناء وقت تشغيل المحادثة بالكامل.

تكامل الحساب والفواتير

جلسة	يستخدم	عند الغياب
`STRIPE_SECRET_KEY`	مصادقة API الشريطية الصادرة.	الخروج المدفوع وتكامل بوابة الفوترة غير متاحين.
`STRIPE_WEBHOOK_SECRET`	تحقق من حمولات خطاف الويب Stripe الموقعة.	يرفض معالج webhook العرض بدون تكوين التحقق.
`STRIPE_PRICE_BASIC`, `STRIPE_PRICE_PRO`, `STRIPE_PRICE_ENTERPRISE`	معرفات الأسعار للخطط المدفوعة. يتم تجاهل القيم الفارغة.	لا يمكن للتعيين المفقود تحديد سعر الدفع الذي تم تكوينه لهذه الخطة.
`CRON_SECRET`	بيانات اعتماد مشتركة إضافية لصيانة كرون.	لا يحتاج هذا الحارس إلى سر كرون إضافي؛ لا يزال قبول حامل التطبيق ساريًا.
`ADMIN_EMAIL`	هوية المسؤول المستخدمة من قبل سياسة الحساب/الخدمة.	يحتفظ ملف تعريف التثبيت المحلي بالسلوك الإداري المحلي الذي تنفذه خدماته.

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

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

يبدأ المسار التجريبي للفوترة خلال 14-يوم PRO محاكمة (TRIAL_DAYS في apps/sidecar/src/repos/billing-repo.ts، يستخدم من قبل http/billing.ts). الخطط المتاحة هي FREE, BASIC, PRO، و ENTERPRISE; فقط الخطط الثلاث المدفوعة تأخذ أ STRIPE_PRICE_* جلسة.

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

OTEL_EXPORTER_OTLP_ENDPOINT يمكّن مصدري التتبع والقياس والسجل OTLP/HTTP للعربة السايدكار. بدون نقطة نهاية غير فارغة، يتم تعطيل طبقة القياس عن بعد الاختيارية هذه. يبني كود المصدر نقاط النهاية الخاصة بالإشارة؛ تكوين جامع يدعم تلك الإشارات.

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

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

تكوين العميل

تستخدم معاينة سطح المكتب للمتصفح فقط واجهة برمجة التطبيقات المزيفة في الذاكرة عندما VITE_SIDECAR_URL غائب. لتوصيله بسايدكار تم تشغيلها يدويًا، قم بتعيين عنوان URL هذا و VITE_SIDECAR_TOKEN قبل البدء فيت. يحصل مسار Tauri المعبأ على اتصاله من الصدفة بدلاً من ذلك.

المتصفح يستخدم السايدكار التي يتم تشغيلها يدويًا

VITE_SIDECAR_URL=http://127.0.0.1:READY_PORT \
VITE_SIDECAR_TOKEN=local-development-token \
bun run --filter @cadcamfun/desktop dev

استبدل العنصر النائب للمنفذ. تنتمي إعدادات Vite إلى عملية تطوير الواجهة الأمامية؛ ولا يؤدي تغييرها إلى إعادة تشغيل السايدكار أو إعادة تكوينها. يخضع الوصول إلى المتصفح إلى سياسة الاسترجاع/Tauri CORS الخاصة بالسايدكار والقبول العادي للحامل.

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

اختيار مسار قاعدة البيانات

عملية	قاعدة الاختيار
السايدكار الأصلية لسطح المكتب	دليل بيانات التطبيق المقدم من Tauri، إذن `cadcamfun.db`.
سايدكار يدوية	`CADCAMFUN_DATA_DIR/cadcamfun.db`.
ترحيل قاعدة البيانات CLI	`DATABASE_URL`، إزالة الأولي `file:`; خلاف ذلك العملية النسبية `./data/cadcamfun.db`.
جذر `db:migrate` إزار	يقوم بتشغيل البرنامج النصي لحزمة قاعدة البيانات، بحيث يتم حل الإعداد الافتراضي داخل `packages/db`.
استوديو التوثيق	`CADCAMFUN_DB`، ثم `DATABASE_URL`، ثم جذر المستودع `data/cadcamfun.db`. يجب أن يكون الملف موجودا.

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

تطبيق والتحقق من التغيير

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

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

تشخيص التكوين

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

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

الأدلة المصدرية: apps/sidecar/src/config.ts, layers.ts, main.ts, observability.ts, services/ai.ts, packages/db/src/migrate.ts، و packages/web/script/studio-server.ts.

كل إعداد سايدكار في طاولة واحدة

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

عامل	يكتب	تقصير	يستخدم من قبل
`CADCAMFUN_TOKEN`	سلسلة منقحة	مطلوب	برمجيات وسيطة حاملة لكل طريق محمي
`CADCAMFUN_DATA_DIR`	خيط	مطلوب	قاعدة البيانات، وتخزين الذكاء الاصطناعي، والمكونات الإضافية، والرفيق، والتحميلات
`CADCAMFUN_MIGRATIONS_DIR`	خيط	غائب	طبقة قاعدة البيانات؛ غائب يعني عدم إنشاء مخطط
`CADCAMFUN_APP_URL`	خيط	غائب	الروابط الموجودة في رسائل البريد الإلكتروني الخاصة بالحساب (الإرث `NEXTAUTH_URL`)
`CADCAMFUN_DEBUG_LINKS`	منطقية	false	إعادة ضبط الصدى والروابط السحرية في الردود (التطوير فقط)
`CADCAMFUN_AI_OFFLINE`	منطقية	false	لا يوجد تنزيل لكتالوج الموفر ولا يوجد بحث مباشر على الويب
`CADCAMFUN_AI_HOST`	`nikcli` \| `direct`	`nikcli`	مساعد المضيف؛ فشل أي قيمة أخرى في بدء التشغيل
`CADCAMFUN_AI_MINIMAX_BASE_URL`	سلسلة، قلصت	غائب	نقطة نهاية MiniMax للمضيف المضمن
`STRIPE_WEBHOOK_SECRET`	خيط	غائب	وبدون ذلك، سيتم رفض خطافات الويب الشريطية
`STRIPE_SECRET_KEY`	سلسلة منقحة	غائب	بدونها، لن يكون الخروج المدفوع وبوابة الفوترة متاحين
`STRIPE_PRICE_BASIC`, `_PRO`, `_ENTERPRISE`	سلسلة، قلصت	غائب	معرف السعر لكل خطة مدفوعة؛ يتم تجاهل القيم الفارغة
`CRON_SECRET`	خيط	غائب	سر مشترك ل `/api/cron/*`; بدونه يكون الطريق مفتوحًا للتطبيق المحلي
`ADMIN_EMAIL`	خيط	غائب	البريد الإلكتروني للمسؤول؛ بشكل افتراضي، يدير ملف التعريف المحلي التثبيت الخاص به
`OTEL_EXPORTER_OTLP_ENDPOINT`	سلسلة، قلصت	غائب	عنوان URL الأساسي لجامع OTLP/HTTP؛ القياس عن بعد معطل بدونه

التطبيق المبلغ عنه version تم إصلاحه في الكود (6.0.0) ، لا تقرأ من البيئة.

القيم غير الصالحة توقف بدء التشغيل

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

تتم قراءة المتغيرات خارج تكوين السايدكار

عامل	قارئ	غاية
`DATABASE_URL`	`packages/db` ترحيل البرنامج النصي ومجموعة الرذاذ	الهدف ل `db:migrate` / `db:generate`; رائدة `file:` تم تجريده. تقصير `./data/cadcamfun.db` نسبة إلى `packages/db`.
`CADCAMFUN_DB`، ثم `DATABASE_URL`	خادم ويب ستوديو (`packages/web/script/studio-server.ts`)	قاعدة البيانات التي يفتحها الاستوديو المحلي؛ تقصير `data/cadcamfun.db` في جذر المستودع.
`NIKCLI_LOCALE`, `NIKCLI_LANGUAGE`, `NIKCLI_REGION`	مضيف مساعد مضمن	تجاوز لغة المساعد والمنطقة.
`LC_ALL`, `LC_MESSAGES`, `LANG`, `LANGUAGE`, `TZ`	مضيف مساعد مضمن	اكتشاف لغة النظام والمنطقة الزمنية عند عدم تعيين أي تجاوز.

يقوم غلاف سطح المكتب بتمرير ثلاثة متغيرات بالضبط إلى السايدكار التي يطلقها: CADCAMFUN_TOKEN (رمز عشوائي جديد لكل عملية إطلاق)، CADCAMFUN_DATA_DIR (دليل بيانات التطبيق) و CADCAMFUN_MIGRATIONS_DIR (الهجرات المجمعة). يجب أن يكون أي شيء آخر موجودًا في البيئة التي بدأ بها تطبيق سطح المكتب نفسه.

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

<CADCAMFUN_DATA_DIR>/

cadcamfun.db            SQLite database (+ -wal / -shm while running)
backups/                pre-migration snapshots, newest five kept
auth-secret             signing secret for account session tokens (0600)
auth-revoked.json       revoked session tokens
ai/
  credentials.json      provider API keys (owner-readable only)
  policy.json           operator policy for the assistant
  skills/               user skills
  session-owners/       which account owns which assistant session
  nikcli/               isolated working and config dirs of the embedded host
plugins/                assistant plugins loaded at startup
plugins-registry/       installed marketplace plugin files
companion/              gateway TLS cert.pem and key.pem (0600)
storage/                file storage for library import/export, entity I/O and plugins
uploads/profiles/       profile pictures
downloads/              files served by /api/download
waitlist.json           local waitlist entries

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

تعامل مع الدليل على أنه سري

ai/credentials.json, auth-secret والمفتاح الخاص المصاحب عبارة عن بيانات اعتماد. لا تلتزم بدليل بيانات التطوير أو ترفقه بتقارير الأخطاء.

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

التطوير دون الاتصال بالإنترنت باستخدام قاعدة بيانات سريعة الاستخدام

export CADCAMFUN_TOKEN=dev-$(openssl rand -hex 16)
export CADCAMFUN_DATA_DIR="$(mktemp -d)"
export CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle"
export CADCAMFUN_AI_HOST=direct
export CADCAMFUN_AI_OFFLINE=true
bun --no-env-file apps/sidecar/src/main.ts

اختبار البريد الإلكتروني للحساب

export CADCAMFUN_APP_URL=http://localhost:4321
export CADCAMFUN_DEBUG_LINKS=true      # reset/magic links appear in responses

القياس عن بعد إلى جامع محلي

export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318

الفواتير في وضع الاختبار

export STRIPE_SECRET_KEY=sk_test_...
export STRIPE_WEBHOOK_SECRET=whsec_...
export STRIPE_PRICE_PRO=price_...

لم يتم ضبطه أبدًا CADCAMFUN_DEBUG_LINKS التطوير الخارجي: يضع روابط الحساب في استجابات HTTP.

في 3د

حيث تتم قراءة التكوين اسحب إلى المدار · قم بالتمرير للتكبير · اسحب بزر الماوس الأيمن للتحريك

Processes at run time. The Tauri shell spawns the sidecar and waits for its {”event”:”ready”,”port”:N} line on stdout (sidecar.rs); the webview then talks HTTP to 127.0.0.1 on that port with the bearer token. The sidecar owns the SQLite database, the embedded nikcli AI host (CADCAMFUN_AI_HOST=nikcli, the default) and plugins; the mobile app reaches it through companion pairing.