قم بإقران رفيق iOS

تحقق من طرفي الاتصال

الرفيق هو عميل لسطح المكتب السايدكار قيد التشغيل. ولا يستضيف قاعدة بيانات المشروع أو نواة الهندسة أو موفر النموذج أو مشغل سير العمل. قبل الاقتران، تأكد من أن سطح المكتب يفتح مشاريعه وأن الهاتف يمكنه التوجيه إلى سطح المكتب من خلال Wi-Fi أو نقطة اتصال شخصية أو شبكة تراكب/VPN تم تكوينها بالفعل.

استخدم نسخة iOS أصلية تحتوي على modules/companion-net. يفتقر Expo Go إلى هذه الوحدة ولا يمكنه إجراء الاتصال المثبت. تحتوي الحزمة أيضًا على احتياطي لتطوير المتصفح، لكن جلب المتصفح لا ينفذ سياسة التثبيت الأصلية. لا يوفر تكوين Android في البيان مكافئ Android لوحدة Swift.

bun install
bun run --cwd apps/mobile typecheck
bun run --cwd apps/mobile test
bun run --cwd apps/mobile ios

يتطلب أمر تشغيل iOS أنظمة التشغيل macOS وXcode وCocoaPods. يتطلب إنشاء الجهاز الفعلي جهازًا موثوقًا به وفريق توقيع. bun run --cwd apps/mobile build تصدير جافا سكريبت؛ لا يقوم بإنشاء IPA قابل للتثبيت. انظر مرجع المحمول للتخطيط وتنفيذ النقل.

تمكين بوابة سطح المكتب

افتح إعدادات سطح المكتب → الأجهزة ولوحة الهاتف المحمول المصاحبة لها، أو استخدمها /settings/companion. قم بتشغيل البوابة، ثم أنشئ اقترانًا مسمىًا وأظهر رمز الاستجابة السريعة الخاص بها. يعد هذا مستمعًا منفصلاً عن واجهة برمجة تطبيقات الاسترجاع العادية: HTTPS on IPv4 0.0.0.0، المنفذ 8443 افتراضيًا.

تقبل الخدمة منافذ الأعداد الصحيحة 1024–65535. إذا احتل تطبيق آخر المنفذ المحدد، فسيفشل التمكين؛ اختر منفذًا مجانيًا وقم بإنشاء رابط بالعنوان الناتج. اسمح بالاتصال عبر جدار حماية سطح المكتب للشبكة التي تنوي استخدامها. لا يقوم التطبيق بإنشاء مرحل عام أو إعادة توجيه المنفذ أو VPN.

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

الفحص والتمكين من خلال واجهة برمجة تطبيقات سطح المكتب

لإعداد تطوير قابل للتكرار، استخدم رمز الإطلاق الخاص بسايدكار معزولة تتحكم فيها. استبدل المنفذ 43111 بمنفذ الحدث الجاهز الخاص به. هذه هي مكالمات إدارة سطح المكتب؛ لا يُسمح لرمز الهاتف بإدارة البوابة الخاصة به.

CADCAM_URL=http://127.0.0.1:43111
CADCAM_TOKEN=local-development-token
CADCAM_PAIR_DIR=$(mktemp -d /tmp/cadcamfun-pair-guide.XXXXXX)

curl --fail-with-body "$CADCAM_URL/api/companion"   -H "Authorization: Bearer $CADCAM_TOKEN"

curl --fail-with-body -X POST "$CADCAM_URL/api/companion/enable"   -H "Authorization: Bearer $CADCAM_TOKEN"   -H 'Content-Type: application/json'   -d '{"port":18443}'

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

قم بإنشاء اقتران واحد مسمى

curl --fail-with-body -X POST "$CADCAM_URL/api/companion/pair"   -H "Authorization: Bearer $CADCAM_TOKEN"   -H 'Content-Type: application/json'   -d '{"name":"Workshop iPhone","host":"192.168.1.20"}'   -o "$CADCAM_PAIR_DIR/pairing.json"

CADCAM_DEVICE_ID=$(bun --no-env-file -e   'console.write((await Bun.file(process.argv[1]).json()).id)'   "$CADCAM_PAIR_DIR/pairing.json")

استبدل المضيف المثال بعنوان يمكن للهاتف الوصول إليه، أو احذف المضيف الاختياري لاستخدام الاكتشاف. تم اقتطاع الاسم ويجب أن يحتوي على 1–60 أحرف. النجاح هو HTTP 201 مع id و link. إنشاء رمز مميز لا يمكّن المستمع؛ تمكينه بشكل منفصل.

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

قم بتحميل الاقتران على iOS

1. افتح شاشة الاتصال الخاصة بتطبيق CADCAMFUN المثبت.
2. اختر مسح رمز QR الخاص بالاقتران وامنح حق الوصول إلى الكاميرا، أو استخدم لصق رابط الاقتران.
3. للإدخال اليدوي، قم بتوفير عنوان سطح المكتب والرمز المميز وبصمة الشهادة الكاملة من خلال نموذج الاتصال.
4. السماح بالوصول إلى الشبكة المحلية عندما يطالبك نظام iOS بذلك. يعد الوصول إلى الكاميرا والوصول إلى الشبكة أذونات منفصلة.
5. انتظر حتى ينجح مسبار الصحة/bootstrap ويفتح التطبيق المشاريع.

يتطلب المحلل اللغوي أصل HTTPS بدون معلومات المستخدم أو محتوى المسار أو الاستعلام أو الجزء. يجب أن تكون الرموز المميزة 16–4096 أحرف بدون مسافة بيضاء/أحرف تحكم؛ بصمات الأصابع هي بالضبط 64 أحرف سداسية عشرية. يتم رفض الروابط غير الصالحة قبل بدء الطلبات.

يتم إلغاء تكرار الأصول البديلة المكتشفة. يقوم العميل بسباق المرشحين، ويستخدم أول اتصال ناجح، ويجهض الاتصالات الأخرى، ويحفظ الأصل الناجح. يعلن Discovery عن ما يصل إلى ستة عناوين IPv خاصة مناسبة4، بما في ذلك نطاقات Wi-Fi ونقطة الاتصال ونطاقات IPv4 ذات نمط Tailscale؛ لا يعلن مستمع IPv4 الحالي عن مضيفي IPv6 المكتشفين.

ما شهادة تثبيت الشيكات

يستخدم النقل السريع سريع الزوال URLSession الحالات ومندوب الثقة المخصص. فهو يحصل على بايتات DER الخاصة بالشهادة الطرفية، ويحسب SHA-256، ويقبل الاتصال فقط عندما يساوي هذا التجزئة بصمة الإصبع المقترنة. HTTPS مطلوب ويتم رفض عمليات إعادة التوجيه. لا يتراجع المتصلون الأصليون بصمت إلى الجلب غير المثبت إذا كانت الوحدة مفقودة.

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

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

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

فهم نطاق الرمز المميز للجهاز

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

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

استخدام الجلسات واستعادة الاتصال

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

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

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

إلغاء أو إلغاء الاقتران عمدا

curl --fail-with-body -X DELETE   "$CADCAM_URL/api/companion/devices/$CADCAM_DEVICE_ID"   -H "Authorization: Bearer $CADCAM_TOKEN"

curl --fail-with-body "$CADCAM_URL/api/companion"   -H "Authorization: Bearer $CADCAM_TOKEN"

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

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

تشخيص الفشل حسب الطبقة

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

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

خريطة التنفيذ

عقد الإدارة هو packages/api/src/groups/companion.ts. دورة حياة Sidecar وسياسة المسار موجودة services/companion.ts و companion-gateway.ts. تحليل الهاتف، واستعادة الاتصال، والتخزين، وواجهة المستخدم موجودة lib/pairing.ts, server.tsx, storage.ts، و app/connect.tsx. مندوب الثقة الأصلي هو modules/companion-net/ios/CompanionNetModule.swift.

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

ما يمكن للهاتف المقترن الاتصال به

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

تشريح الارتباط الاقتران

cadcamfun://pair?host=https%3A%2F%2F192.168.1.20%3A8443&token=<43-char base64url>&fp=<sha256 hex>&name=Ada%27s+iPhone&hosts=https%3A%2F%2F100.64.0.7%3A8443

الشهادة عبارة عن شهادة P-256 موقعة ذاتيًا والتي تشتمل على أسماء بديلة للموضوع localhost, 127.0.0.1والعناوين الخاصة التي يمكن الوصول إليها بالجهاز. يتم الاحتفاظ بها في <dataDir>/companion، لذلك تستمر عمليات الاقتران في إعادة التشغيل. يؤدي استبدالها إلى تغيير بصمة الإصبع ويتطلب الاقتران مرة أخرى.

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

يتم التحكم في المحاولات الحاملة الفاشلة لكل عنوان IP: بعد فشل 10 خلال 60 ثانية، تجيب البوابة على HTTP 429 ("عدد كبير جدًا من المحاولات الفاشلة") حتى تمر النافذة. وإلا فإن الرمز المميز الخاطئ أو الذي تم إبطاله يحصل على HTTP 401.

تم التقاط حالة البوابة

{ "enabled": false, "port": null, "fingerprint": null, "host": "172.30.0.2", "devices": [] }

لو host ليس هو العنوان الذي يمكن لهاتفك الوصول إليه (على سبيل المثال حاوية أو واجهة VPN)، فسيفشل الاقتران في طبقة الشبكة على الرغم من أن كل شيء آخر صحيح.

في 3د