Blacksky AppView

هذا هو فرع بلاك سكاي من التطبيق المرجعي لبروتوكول AT من قبل Bluesky Social PBC. يعمل على تشغيل AppView على api.blacksky.community.

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

ما هو المختلف

جميع التغييرات موجودة في packages/bsky (منطق AppView)، services/bsky (إعدادات التشغيل)، وهجرة مخصصة واحدة. كل شيء آخر هو من المنبع.

لماذا لا نستخدم مستهلك الخدمة المدمج؟

تتضمن طبقة البيانات من المنبع مستهلك خدمة بلغة TypeScript (subscription.ts) يقوم بفهرسة الأحداث مباشرة. استبدلناه بـ rsky-wintermute، وهو مفهرس بلغة Rust، لعدة أسباب:

• الأداء على نطاق واسع: يقوم مستهلك TypeScript بمعالجة الأحداث بشكل تسلسلي. على نطاق الشبكة (~1000 حدث/ثانية، 18.5 مليار سجل إجمالي)، فإن إعادة التعبئة الكاملة بمعدل ~90 سجل/ثانية ستستغرق 6.5 سنوات. يستهدف Wintermute أكثر من 10,000 سجل/ثانية مع معالجة طوابير متوازية.
• هندسة إعادة التعبئة: يفصل Wintermute الفهرسة الحية عن إعادة التعبئة في طوابير مستقلة (firehose_live، firehose_backfill، repo_backfill، labels). لا يتم حظر الأحداث الحية أبدًا بواسطة عمل إعادة التعبئة.
• أدوات التشغيل: يتضمن Wintermute أدوات للفهرسة المباشرة لحسابات محددة، واستيراد دليل PLC بكميات كبيرة، وإعادة تشغيل دفق الوسوم، وإصلاح مراجع البلوب، وإدارة الطوابير — كل ما هو مطلوب عند بدء تشغيل AppView من الصفر.

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

إصلاحات الأداء والتشغيل

هذه مفيدة على نطاق واسع لأي شخص يستضيف AppView بنفسه على نطاق واسع.

تحسين استعلام LATERAL JOIN (packages/bsky/src/data-plane/server/routes/feeds.ts)

• تمت إعادة كتابة getTimeline و getListFeed باستخدام LATERAL JOINs في PostgreSQL لفرض استخدام الفهرس لكل مستخدم بدلاً من مسح الجدول بالكامل. تحسن كبير للمستخدمين الذين يتابعون آلاف الحسابات.

طبقة تخزين مؤقت Redis (packages/bsky/src/data-plane/server/cache/)

• ملفات الممثلين (TTL 60 ثانية)، السجلات (5 دقائق)، أعداد التفاعلات (30 ثانية)، بيانات التعريف للمنشورات (5 دقائق)
• تقليل حمل قاعدة البيانات تحت حركة المرور الإنتاجية
• مشكلة معروفة: يوجد خطأ في تسلسل الطوابع الزمنية لـ protobuf في ذاكرة التخزين المؤقت للممثلين حيث تفقد كائنات Timestamp طريقة .toDate() بعد إعادة التوزيع عبر Redis، مما يسبب تعبئة غير كاملة للملف الشخصي عند الوصول إلى ذاكرة التخزين المؤقت. نعمل حاليًا مع تعطيل التخزين المؤقت لـ Redis. الإصلاح هو تحويل الطوابع الزمنية إلى سلاسل ISO عند الكتابة إلى ذاكرة التخزين المؤقت وإعادة بنائها عند القراءة.

فرض تفضيلات الإشعارات من جانب الخادم (packages/bsky/src/api/app/bsky/notification/listNotifications.ts)

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

إصلاح مفتاح التوقيع القديم في مدقق المصادقة (packages/bsky/src/auth-verifier.ts)

• عند إعادة محاولة التحقق من JWT (forceRefresh)، يتم تجاوز ذاكرة التخزين المؤقت للهوية في طبقة البيانات ويتم حل مستند DID مباشرة من دليل PLC. يصلح فشل المصادقة بعد ترحيل الحساب حيث يتم تدوير مفتاح التوقيع ولكن ذاكرة التخزين المؤقت تحتوي على المفتاح القديم.

تنقية JSON (packages/bsky/src/data-plane/server/routes/records.ts)

• يزيل البايتات الفارغة (\u0000) والأحرف التحكم من السجلات المخزنة قبل تحليل JSON. هذه صالحة وفقًا لـ RFC 8259 ولكن يتم رفضها بواسطة JSON.parse() في Node.js، مما يسبب فشل تحليل rowToRecord صامت في طبقة البيانات يظهر كمنشورات مفقودة.

المنشورات المجتمعية (خاصة ببلاك سكاي)

البنية التحتية للمنشورات المجتمعية الخاصة التي تعيش على AppView بدلاً من PDSes الفردية. خاصة بكيفية عمل بلاك سكاي، ولكن يمكن أن تكون مرجعًا للمجتمعات الأخرى.

• مساحة اسم مخصصة community.blacksky.feed.* مع نقاط نهاية للإرسال، والحصول، والحذف، والجدول الزمني، وعرض الخيوط
• جدول منفصل community_post (الهجرة: 20260202T120000000Z-add-community-post.ts)
• التحقق من العضوية في طبقة البيانات وطبقة API
• التكامل مع getPostThreadV2 لمزيج من الخيوط القياسية والمجتمعية
• يتطلب قاعدة بيانات عضوية منفصلة (BLACKSKY_MEMBERSHIP_DB_URL)

الهندسة المعمارية

Bluesky Relay (bsky.network)
     |
     v
rsky-wintermute -----> PostgreSQL 17 <----- Palomar
  (مفهرس Rust)            |                (بحث Go)
  - مستهلك الخدمة          |                     |
  - معيد التعبئة          |                     v
  - مفهرس الوسوم          |               OpenSearch
  - مفهرس مباشر           |
                            v
                    bsky-dataplane (gRPC :2585) <--- Redis (اختياري)
                            |
                            v
                    bsky-appview (HTTP :2584)
                            |
                            v
                    خادم وكيل عكسي (Caddy/nginx)

نظرة عامة على المكونات

rsky-wintermute بالتفصيل

Wintermute هي خدمة Rust متجانسة مع أربعة مسارات معالجة متوازية:

• المبتلع (Ingester): يتصل بخدمة bsky.network عبر WebSocket، يكتب الأحداث إلى طوابير Fjall (مخزن قيم-مفاتيح مضمن)
• المفهرس (Indexer): يقرأ من الطوابير، يحلل السجلات، يكتب إلى PostgreSQL مع ON CONFLICT لضمان عدم التكرار
• معيد التعبئة (Backfiller): يجلب ملفات CAR كاملة للمستودعات من PDSes، يفك السجلات في طابور إعادة التعبئة
• مفهرس الوسوم (Label indexer): يشترك في تدفقات WebSocket للوسوم، يعالج أحداث إنشاء/نفي الوسوم

أدوات CLI إضافية مضمنة في مستودع rsky:

• queue_backfill — إدراج DIDs في قائمة انتظار إعادة التعبئة من CSV، أو اكتشاف PDS، أو قوائم DID مباشرة
• direct_index — جلب وفهرسة مستودعات محددة متجاوزًا الطوابير (مفيد لإصلاح حسابات فردية)
• label_sync — إعادة تشغيل تدفق الوسوم من المؤشر 0 للحاق بالنفي المفقود
• plc_import — استيراد تعيينات handle/DID بكميات كبيرة من دليل PLC
• palomar-sync — مزامنة أعداد المتابعين وPageRank إلى OpenSearch

rsky-video

خدمة رفع الفيديو للمستخدمين الذين لا يدعم PDS الخاص بهم تطبيق Bluesky video.bsky.app. تستخدم DID الخاصة بها (did:web:video.blacksky.community) للمصادقة على PDSes الخاص بالمستخدم عبر JWTs مصادقة الخدمة. التدفق:

1. يحصل العميل على رمز مصادقة الخدمة من PDS (الجمهور: DID خدمة الفيديو)
2. يرفع العميل بايتات الفيديو إلى rsky-video
3. يقوم rsky-video بإنشاء CID، ويرفع البلوب إلى PDS الخاص بالمستخدم
4. يتم توجيه الفيديو إلى CDN Bunny Stream للتحويل
5. عند الانتهاء، يقوم العميل بإنشاء المنشور مع الإشارة إلى البلوب — يتحقق PDS من وجود البلوب

معالجة الوسوم

تأتي وسوم التعديل من خدمات الوسم (مثل Ozone من Bluesky) عبر اشتراك WebSocket. يقوم مبتلع Wintermute بمعالجة الوسوم في طابور مخصص label_live (حجم منخفض، منفصل عن الخدمة الرئيسية). يمكن لأداة label_sync إعادة تشغيل التدفق الكامل للوسوم للحاق بالنفي المفقود (إزالة الوسوم) دون إعادة إدراج الوسوم.

الإعداد

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

• Node.js 18+ و pnpm (لبناء طبقة البيانات و AppView)
• PostgreSQL 17 مع مخطط bsky
• Redis (اختياري، للتخزين المؤقت — راجع المشكلة المعروفة أعلاه)
• rsky-wintermute يستهلك الخدمة ويملأ قاعدة البيانات
• OpenSearch (إذا كنت تشغل بحث Palomar)

قاعدة البيانات

يتم إنشاء مخطط bsky بواسطة هجرات طبقة البيانات. في التشغيل الأول، ستطبق طبقة البيانات جميع الهجرات تلقائيًا. الهجرة الوحيدة الخاصة ببلاك سكاي هي 20260202T120000000Z-add-community-post.ts (جدول المنشورات المجتمعية). إذا كنت لا تحتاج إلى منشورات مجتمعية، يمكنك إزالتها.

يكتب rsky-wintermute إلى نفس المخطط. جميع عبارات INSERT الخاصة به تستخدم ON CONFLICT لذلك من الآمن تشغيل wintermute وهجرات طبقة البيانات بأي ترتيب.

البناء

pnpm install
pnpm build

تشغيل طبقة البيانات

node services/bsky/dataplane.js

تشغيل AppView

node services/bsky/api.js

العمل على نطاق واسع

الجدول الزمني لإعادة التعبئة

تستغرق إعادة التعبئة الكاملة للشبكة (جميع ~42 مليون مستخدم، ~18.5 مليار سجل) أسابيع حتى مع المعالجة المتوازية لـ wintermute. توقع:

• الفهرسة الحية: تواكب الأحداث في الوقت الفعلي من اليوم الأول (~1000 حدث/ثانية)
• إعادة التعبئة الكاملة: 2-4 أسابيع بمعدل 10,000 سجل/ثانية اعتمادًا على استجابة PDS وظروف الشبكة
• إعادة التعبئة الجزئية: ساعات إلى أيام لمجموعة فرعية من المستخدمين (مثل أعضاء المجتمع فقط)

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

المشكلات التي حللناها للوصول إلى هنا

هذه هي المشكلات التي واجهناها أثناء بدء تشغيل AppView للشبكة الكاملة. إذا كنت تفعل الشيء نفسه، فمن المحتمل أن تصادف بعضًا منها:

تلف JSON في تنسيق COPY النصي: يعامل بروتوكول COPY النصي في PostgreSQL الشرطة المائلة للخلف كحرف هروب. إذا لم يقم أداة التحميل الجماعي الخاص بك بهروب الشرطة المائلة للخلف في سلاسل JSON، فإن \" تصبح " وتحصل على سجلات تالفة بصمت. عمود record.json هو من نوع text (وليس jsonb)، لذلك لن يلتقط PostgreSQL ذلك. وجدنا حوالي 66,000 سجل تالف واضطررنا إلى إصلاحها عن طريق إعادة الجلب من API العام.

البايتات الفارغة في JSON: تحتوي بعض سجلات بروتوكول AT على \u0000 (بايت فارغ)، وهو JSON صالح وفقًا لـ RFC 8259 ولكن يتم رفضه بواسطة JSON.parse() في Node.js. تقوم طبقة البيانات بإرجاع null بصمت لهذه السجلات. قم بإزالة البايتات الفارغة قبل الكتابة إلى قاعدة البيانات.

حساسية تنسيق الطوابع الزمنية: تتوقع طبقة البيانات طوابع زمنية بدقة ملي ثانية ولاحقة Z (2026-01-12T19:45:23.307Z). الدقة النانوية أو تنسيق إزاحة المنطقة الزمنية (+00:00) يسبب مشكلات دقيقة في الفرز والمقارنة.

تضخم جدول الإشعارات: بدون قيد فريد على (did, recordUri, reason)، ينمو جدول الإشعارات بلا حدود مع التكرارات. وصل حجم جدولنا إلى 1.3 مليار صف (663 جيجابايت) قبل أن نلتقطه. إضافة ON CONFLICT DO NOTHING إلى INSERTs يساعد فقط إذا كان الفهرس الفريد موجودًا أولاً، ويتطلب إنشاء الفهرس إزالة التكرارات من البيانات الموجودة.

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

ترتيب نفي الوسوم: تشير أحداث نفي الوسوم (الإزالة) إلى الوسم الأصلي بواسطة المصدر وURI والقيمة. إذا وصلت أحداث النفي قبل الوسم الأصلي (شائع أثناء إعادة التعبئة)، يتم إسقاطها بصمت. تقوم أداة label_sync بإعادة تشغيل التدفق الكامل لالتقاط هذه الحالات.

تسمم طابور Fjall: يمكن لقاعدة بيانات Fjall المضمنة (المستخدمة لطوابير wintermute) الدخول في حالة "مسمومة" بعد الأعطال، مما يمنع جميع عمليات الطابور. الإصلاح هو حذف دليل قاعدة بيانات الطابور وإعادة التشغيل — سيلحق wintermute بالركب من مؤشر المرحل (تحتفظ المرحلات بحوالي 72 ساعة من التاريخ).

تهيئة موفر TLS: يتطلب rustls في Rust تثبيت موفر تشفير صراحة قبل أي اتصال TLS. بدون rustls::crypto::aws_lc_rs::default_provider().install_default() عند بدء التشغيل، ينهار أول اتصال WebSocket بالخدمة.

تدوير مفتاح التوقيع بعد ترحيل الحساب: عندما يهاجر المستخدمون بين PDSes، يتغير مفتاح التوقيع الخاص بهم. تقوم طبقة البيانات بتخزين بيانات الهوية مؤقتًا مع staleTTL لمدة ساعة. خلال هذه النافذة، يفشل التحقق من JWT للمستخدمين المهاجرين. الإصلاح هو تجاوز ذاكرة التخزين المؤقت عند إعادة محاولة التحقق والحل مباشرة من دليل PLC.

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

استنادًا إلى تشغيل AppView للشبكة الكاملة (جميع ~42 مليون مستخدم، ~18.5 مليار سجل).

تفصيل التخزين (تقريبي، الشبكة الكاملة):

لمجتمع أصغر يشغل AppView جزئيًا (فهرسة أعضاء المجتمع فقط)، تتناسب المتطلبات تقريبًا خطيًا مع عدد الحسابات المفهرسة.

المزامنة مع المنبع

git remote add upstream https://github.com/bluesky-social/atproto.git
git fetch upstream
git merge upstream/main

ستكون التعارضات عادة في packages/bsky/src/data-plane/server/routes/ و packages/bsky/src/api/. قم بحلها عن طريق الاحتفاظ بإضافاتنا إلى جانب تغييرات المنبع.

الترخيص

نفس المنبع: مرخص بموجب ترخيص مزدوج MIT و Apache 2.0. انظر LICENSE-MIT.txt و LICENSE-APACHE.txt.