Blacksky AppView

Dies ist der Fork des AT Protocol Reference Implementation von Blacksky, der von Bluesky Social PBC erstellt wurde. Er betreibt die AppView unter api.blacksky.community.

Wir veröffentlichen dies aus Transparenzgründen und damit andere Gemeinschaften von der Arbeit profitieren können. Dieses Repository akzeptiert keine Beiträge, Issues oder PRs. Wenn Sie die kanonische atproto-Implementierung wünschen, verwenden Sie bluesky-social/atproto.

Was ist anders?

Alle Änderungen befinden sich in packages/bsky (AppView-Logik), services/bsky (Laufzeitkonfiguration) und einer benutzerdefinierten Migration. Alles andere ist Upstream.

Warum nicht der integrierte Firehose-Consumer?

Die Upstream-Datenebene enthält einen TypeScript-Firehose-Consumer (subscription.ts), der Ereignisse direkt indiziert. Wir haben ihn aus mehreren Gründen durch rsky-wintermute, einen Rust-Indexer, ersetzt:

• Skalierbarkeit: Der TypeScript-Consumer verarbeitet Ereignisse sequenziell. Bei Netzwerk-Skala (~1.000 Ereignisse/s, 18,5 Mrd. Datensätze insgesamt) würde ein vollständiger Backfill mit ~90 Datensätzen/s 6,5 Jahre dauern. Wintermute zielt auf 10.000+ Datensätze/s mit paralleler Warteschlangenverarbeitung ab.
• Backfill-Architektur: Wintermute trennt Live-Indizierung und Backfill in unabhängige Warteschlangen (firehose_live, firehose_backfill, repo_backfill, labels). Live-Ereignisse werden nie durch Backfill-Arbeiten blockiert.
• Betriebswerkzeuge: Wintermute enthält Hilfsprogramme für die direkte Indizierung bestimmter Konten, den PLC-Verzeichnis-Bulk-Import, die Label-Stream-Wiedergabe, die Reparatur von Blob-Referenzen und die Warteschlangenverwaltung – alles erforderlich, wenn eine AppView von Grund auf neu aufgesetzt wird.

Die Datenebene und die AppView aus diesem Repository laufen weiterhin unverändert. Sie lesen aus der PostgreSQL-Datenbank, die Wintermute beschreibt. Wir starten nur das eingebaute Firehose-Abonnement nicht.

Leistungs- und Betriebsfixes

Diese sind allgemein für jeden nützlich, der eine AppView in großem Maßstab selbst hostet.

LATERAL-JOIN-Abfrageoptimierung (packages/bsky/src/data-plane/server/routes/feeds.ts)

• getTimeline und getListFeed wurden mit PostgreSQL LATERAL JOINs umgeschrieben, um die Indexnutzung pro Benutzer zu erzwingen, anstatt vollständige Tabellenscans durchzuführen. Große Verbesserung für Benutzer, die Tausenden von Konten folgen.

Redis-Caching-Layer (packages/bsky/src/data-plane/server/cache/)

• Actor-Profile (60s TTL), Datensätze (5m), Interaktionszahlen (30s), Post-Metadaten (5m)
• Reduziert Datenbanklast unter Produktionstraffic
• Bekanntes Problem: Der Actor-Cache hat einen Protobuf-Zeitstempel-Serialisierungsfehler, bei dem Timestamp-Objekte nach JSON-Roundtrip durch Redis ihre .toDate()-Methode verlieren, was bei Cache-Treffern zu unvollständiger Profilhydrierung führt. Wir betreiben Redis-Caching derzeit deaktiviert. Die Lösung besteht darin, Zeitstempel beim Cache-Schreiben als ISO-Strings zu serialisieren und beim Lesen zu rekonstruieren.

Serverseitige Durchsetzung von Benachrichtigungseinstellungen (packages/bsky/src/api/app/bsky/notification/listNotifications.ts)

• Wenn der Client keine reasons angibt, wendet der Server die gespeicherten Benachrichtigungseinstellungen des Benutzers an. Ohne dies werden die Einstellungen nur clientseitig durchgesetzt und haben keine Wirkung.

Auth-Verifier-Problem mit abgelaufenem Signaturschlüssel (packages/bsky/src/auth-verifier.ts)

• Bei JWT-Überprüfungswiederholung (forceRefresh) wird der In-Memory-Identity-Cache der Datenebene umgangen und das DID-Dokument direkt aus dem PLC-Verzeichnis aufgelöst. Behebt Authentifizierungsfehler nach Kontomigration, bei der der Signaturschlüssel rotiert, der Cache aber den alten Schlüssel enthält.

JSON-Bereinigung (packages/bsky/src/data-plane/server/routes/records.ts)

• Entfernt Nullbytes (\u0000) und Steuerzeichen aus gespeicherten Datensätzen vor der JSON-Analyse. Diese sind gemäß RFC 8259 gültig, werden aber von Node.js JSON.parse() abgelehnt, was zu stillen rowToRecord-Analysefehlern in der Datenebene führt, die sich als fehlende Posts äußern.

Community-Beiträge (Blacksky-spezifisch)

Infrastruktur für private Community-Beiträge, die auf der AppView und nicht auf einzelnen PDSes leben. Spezifisch für die Funktionsweise von Blacksky, könnte aber als Referenz für andere Gemeinschaften dienen.

• Benutzerdefinierter Lexikon-Namespace community.blacksky.feed.* mit Endpunkten zum Einreichen, Abrufen, Löschen, für Timeline und Thread-Ansichten
• Separate community_post-Tabelle (Migration: 20260202T120000000Z-add-community-post.ts)
• Mitgliedschafts-Gating auf Datenebene und API-Ebene
• Integration mit getPostThreadV2 für gemischte Standard-/Community-Post-Threads
• Erfordert eine separate Mitgliederdatenbank (BLACKSKY_MEMBERSHIP_DB_URL)

Architektur

Bluesky Relay (bsky.network)
     |
     v
rsky-wintermute -----> PostgreSQL 17 <----- Palomar
  (Rust-Indexer)            |                (Go-Suche)
  - Firehose-Consumer       |                     |
  - Backfiller              |                     v
  - Label-Indexer           |               OpenSearch
  - Direkt-Indexer          |
                            v
                    bsky-dataplane (gRPC :2585) <--- Redis (optional)
                            |
                            v
                    bsky-appview (HTTP :2584)
                            |
                            v
                    Reverse-Proxy (Caddy/nginx)

Komponentenübersicht

rsky-wintermute im Detail

Wintermute ist ein monolithischer Rust-Dienst mit vier parallelen Verarbeitungspfaden:

• Ingester: Stellt eine Verbindung zum bsky.network-Firehose per WebSocket her, schreibt Ereignisse in Fjall (eingebetteter Key-Value-Store) Warteschlangen
• Indexer: Liest aus den Warteschlangen, parst Datensätze, schreibt mit ON CONFLICT für Idempotenz in PostgreSQL
• Backfiller: Ruft vollständige Repo-CAR-Dateien von PDSes ab, entpackt Datensätze in die Backfill-Warteschlange
• Label-Indexer: Abonniert Labeler-WebSocket-Streams, verarbeitet Label-Create/Negate-Ereignisse

Zusätzliche CLI-Werkzeuge im rsky-Repo:

• queue_backfill – DIDs für Backfill aus CSV, PDS-Entdeckung oder direkten DID-Listen in die Warteschlange stellen
• direct_index – bestimmte Repos abrufen und indizieren, unter Umgehung der Warteschlangen (nützlich zur Reparatur einzelner Konten)
• label_sync – Label-Streams ab Cursor 0 wiedergeben, um verpasste Negationen nachzuholen
• plc_import – Bulk-Import von Handle/DID-Zuordnungen aus dem PLC-Verzeichnis
• palomar-sync – Follower-Anzahlen und PageRank mit OpenSearch synchronisieren

rsky-video

Video-Upload-Dienst für Benutzer, deren PDS Blueskys video.bsky.app nicht unterstützt. Verwendet eine eigene DID (did:web:video.blacksky.community), um sich über Dienst-Auth-JWTs bei Benutzer-PDSes zu authentifizieren. Ablauf:

1. Client erhält Dienst-Auth-Token vom PDS (Zielgruppe: DID des Videodienstes)
2. Client lädt Videobytes zu rsky-video hoch
3. rsky-video generiert eine CID, lädt den Blob auf das PDS des Benutzers hoch
4. Video wird an Bunny Stream CDN zur Transkodierung weitergeleitet
5. Bei Abschluss erstellt der Client den Post, der auf den Blob verweist – das PDS validiert die Existenz des Blobs

Label-Behandlung

Moderationslabels stammen von Labeler-Diensten (z.B. Blueskys Ozone) per WebSocket-Abonnement. Der Ingester von Wintermute verarbeitet Labels in einer dedizierten label_live-Warteschlange (geringes Volumen, getrennt vom Haupt-Firehose). Das Werkzeug label_sync kann den vollständigen Stream eines Labelers wiedergeben, um verpasste Negationen (Entfernungen von Labels) nachzuholen, ohne Labels erneut einzufügen.

Einrichtung

Voraussetzungen

• Node.js 18+ und pnpm (zum Bauen der Datenebene und AppView)
• PostgreSQL 17 mit dem Schema bsky
• Redis (optional, für Caching – siehe bekanntes Problem oben)
• rsky-wintermute, das den Firehose konsumiert und die Datenbank füllt
• OpenSearch (falls Palomar-Suche ausgeführt wird)

Datenbank

Das Schema bsky wird durch die Migrationen der Datenebene erstellt. Beim ersten Start wendet die Datenebene alle Migrationen automatisch an. Die einzige Blacksky-spezifische Migration ist 20260202T120000000Z-add-community-post.ts (Tabelle für Community-Beiträge). Wenn Sie keine Community-Beiträge benötigen, können Sie sie entfernen.

rsky-wintermute schreibt in dasselbe Schema. Alle INSERT-Anweisungen verwenden ON CONFLICT, daher ist es sicher, Wintermute und die Datenebenen-Migrationen in beliebiger Reihenfolge auszuführen.

Bauen

pnpm install
pnpm build

Datenebene ausführen

node services/bsky/dataplane.js

AppView ausführen

node services/bsky/api.js

Betrieb im großen Maßstab

Backfill-Zeitplan

Ein vollständiger Netzwerk-Backfill (alle ~42 Mio. Benutzer, ~18,5 Mrd. Datensätze) dauert selbst mit Wintermutes paralleler Verarbeitung Wochen. Erwarten Sie:

• Live-Indizierung: Hält von Tag eins an in Echtzeit Schritt (~1.000 Ereignisse/s)
• Vollständiger Backfill: 2-4 Wochen bei 10.000 Datensätzen/s, abhängig von der Reaktionsfähigkeit der PDSes und den Netzwerkbedingungen
• Teilweiser Backfill: Stunden bis Tage für eine Teilmenge von Benutzern (z.B. nur Community-Mitglieder)

Während des Backfills ist die AppView funktionsfähig, zeigt aber unvollständige Daten für Benutzer, die noch nicht backgefillt wurden. Live-Ereignisse werden unabhängig vom Backfill-Fortschritt sofort indiziert.

Probleme, die wir auf dem Weg dorthin gelöst haben

Dies sind Probleme, auf die wir beim Aufsetzen einer AppView für das gesamte Netzwerk gestoßen sind. Wenn Sie dasselbe tun, werden Sie wahrscheinlich auf einige davon stoßen:

COPY-Textformat-JSON-Korruption: Das COPY-Textprotokoll von PostgreSQL behandelt Backslash als Escape-Zeichen. Wenn Ihr Bulk-Loader Backslashes in JSON-Strings nicht escaped, wird \" zu " und Sie erhalten stillschweigend korrupte Datensätze. Die Spalte record.json ist vom Typ text (nicht jsonb), daher wird PostgreSQL dies nicht abfangen. Wir haben etwa 66.000 korrupte Datensätze gefunden und mussten sie durch erneutes Abrufen über die öffentliche API reparieren.

Nullbytes in JSON: Einige AT Protocol-Datensätze enthalten \u0000 (Nullbyte), was gemäß RFC 8259 gültiges JSON ist, aber von Node.js JSON.parse() abgelehnt wird. Die Datenebene gibt für diese Datensätze stillschweigend null zurück. Entfernen Sie Nullbytes, bevor Sie in die Datenbank schreiben.

Zeitstempel-Format-Empfindlichkeit: Die Datenebene erwartet Zeitstempel mit Millisekundengenauigkeit und Z-Suffix (2026-01-12T19:45:23.307Z). Nanosekundengenauigkeit oder Zeitzonenoffset-Format (+00:00) verursachen subtile Sortierungs- und Vergleichsprobleme.

Aufblähung der Benachrichtigungstabelle: Ohne eine eindeutige Einschränkung für (did, recordUri, reason) wächst die Benachrichtigungstabelle unbegrenzt mit Duplikaten. Unsere erreichte 1,3 Milliarden Zeilen (663 GB), bevor wir es bemerkten. Das Hinzufügen von ON CONFLICT DO NOTHING zu INSERTs hilft nur, wenn der eindeutige Index zuerst existiert, und das Erstellen des Index erfordert die Deduplizierung der vorhandenen Daten.

Post-Einbettungstabellen: Die Tabellen post_embed_image und post_embed_video werden standardmäßig nicht gefüllt, wenn Ihr Indexer sie nicht verarbeitet. Ohne diese liefert der Medienfilter auf getAuthorFeed nichts zurück. Diese müssen separat backgefillt werden.

Label-Negations-Reihenfolge: Label-Negations-Ereignisse (Entfernung) verweisen auf das ursprüngliche Label nach Quelle, URI und Wert. Wenn Negationen vor dem ursprünglichen Label eintreffen (häufig während Backfills), werden sie stillschweigend verworfen. Das Werkzeug label_sync spielt den gesamten Stream ab, um diese zu erfassen.

Fjall-Warteschlangen-Vergiftung: Die eingebettete Fjall-Datenbank (für Wintermutes Warteschlangen) kann nach Abstürzen in einen "vergifteten" Zustand geraten, der alle Warteschlangenoperationen blockiert. Die Lösung besteht darin, das Warteschlangen-Datenbankverzeichnis zu löschen und neu zu starten – Wintermute holt den Stand vom Relay-Cursor auf (Relays behalten etwa 72 Stunden Verlauf).

TLS-Provider-Initialisierung: Rusts rustls erfordert die explizite Installation eines Crypto-Providers vor jeder TLS-Verbindung. Ohne rustls::crypto::aws_lc_rs::default_provider().install_default() beim Start führt die erste WebSocket-Verbindung zum Firehose zu einer Panik.

Signaturschlüssel-Rotation nach Kontomigration: Wenn Benutzer zwischen PDSes migrieren, ändert sich ihr Signaturschlüssel. Die Datenebene speichert Identitätsdaten mit einem staleTTL von 1 Stunde zwischen. Während dieses Fensters schlägt die JWT-Überprüfung für migrierte Benutzer fehl. Die Lösung besteht darin, den Cache bei der Überprüfungswiederholung zu umgehen und direkt aus dem PLC-Verzeichnis aufzulösen.

Ressourcenanforderungen

Basierend auf dem Betrieb einer AppView für das gesamte Netzwerk (alle ~42 Mio. Benutzer, ~18,5 Mrd. Datensätze).

Speicheraufteilung (ungefähr, gesamtes Netzwerk):

Für eine kleinere Community, die eine teilweise AppView betreibt (nur Community-Mitglieder indiziert), skalieren die Anforderungen grob linear mit den indizierten Konten.

Synchronisation mit Upstream

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

Konflikte treten typischerweise in packages/bsky/src/data-plane/server/routes/ und packages/bsky/src/api/ auf. Lösen Sie diese, indem Sie unsere Ergänzungen neben den Upstream-Änderungen behalten.

Lizenz

Gleich wie Upstream: dual-lizenziert unter MIT und Apache 2.0. Siehe LICENSE-MIT.txt und LICENSE-APACHE.txt.