Uruchamianie i wykrywanie w NextPDF Connect

W skrócie

Każdy transport ma osobny punkt wejścia i osobną sekwencję uruchamiania. Wspólne są dla nich pojęcia rejestru, konfiguracji i bramki. Działają jako niezależne procesy, więc uruchomienie jednego nie uruchamia pozostałych.

Instalacja

composer require nextpdf/server

Przegląd koncepcyjny

Sekwencja uruchamiania MCP

Metoda McpServer::create() składa serwer Model Context Protocol (MCP) w stałej kolejności. Najpierw wczytuje konfigurację, buduje na jej podstawie politykę bezpieczeństwa, tworzy rejestr narzędzi i uruchamia wykrywanie poziomów. Następnie buduje magazyn dokumentów w pamięci na podstawie skonfigurowanego czasu życia (TTL) i pojemności, tworzy transport stdio oraz składa procedurę obsługi protokołu JSON-RPC z bramką potwierdzeń i rejestratorem audytu. Potem serwer wchodzi w pętlę odczyt–obsługa–zapis i działa, dopóki na standardowym wejściu nie pojawi się koniec pliku.

Sekwencja uruchamiania REST

Metoda HttpServer::create() odczytuje HttpConfig ze środowiska i uwzględnia nadpisania z interfejsu wiersza poleceń (CLI). Następnie rozwiązuje magazyn kluczy API w następującej kolejności preferencji: najpierw plikowy magazyn z przeładowywaniem na gorąco, potem plik statyczny, a na końcu środowisko. Dalej rozwiązuje magazyny ograniczania liczby żądań i idempotentności. Korzystają z Redis, gdy Redis jest skonfigurowany i osiągalny; w przeciwnym razie przechodzą na magazyn w pamięci. Potem serwer otwiera współdzielony magazyn zadań SQLite, buduje usługi aplikacji i tworzy tablicę tras. Ponieważ tablica tras jest budowana na podstawie wykrytych poziomów, uwzględnia zainstalowane pakiety. Następnie RoadRunner steruje pętlą żądań procesu roboczego.

Sekwencja uruchamiania gRPC

Metoda GrpcServer::create() rozwiązuje ten sam magazyn kluczy, buduje te same usługi aplikacji i rejestruje usługę nextpdf.connect.v1 w procesie roboczym Spiral gRPC. Gdy zależność od silnika jest niedostępna, serwer gRPC nadal się uruchamia i obsługuje zapytania o kondycję oraz możliwości. W tym stanie proces nie odmawia uruchomienia; zamiast tego zdalne wywołania procedur (RPC) przenoszące dane kończą się kontrolowanym niepowodzeniem.

Wykrywanie narzędzi

Wykrywanie jest domyślnym etapem rejestracji narzędzi w rejestrze. Najpierw rejestrowany jest poziom core. Następnie rejestrowani są dostawcy Pro i Enterprise, jeśli ich klasy rozwiążą się przez class_exists(). Dołączeni dostawcy abstrakcyjnego drzewa składniowego (AST) oraz mutacji są potem rejestrowani na poziomie Pro, o ile pozwalają na to ich bramki środowiskowe. Każda rejestracja jest filtrowana przez listę dozwolonych enabled_tools, a odpowiedź MCP initialize raportuje wynikowe liczby dla poszczególnych poziomów. Zobacz /connect/tool-catalog/.

Wykrywanie transportów

Żadne pojedyncze ustawienie konfiguracji nie „włącza transportów”. Każdy transport to osobny punkt wejścia. REST i gRPC mają osobne profile RoadRunner. Wdrożenie wybiera transporty na podstawie uruchamianego profilu: .rr.yaml dla REST, .rr.grpc.yaml dla gRPC lub .rr.full.yaml dla obu. Transporty działają jako niezależne procesy. Brak klienta MCP nigdy nie blokuje serwera REST, a brak klienta REST nigdy nie blokuje MCP. Zobacz /connect/deployment/.

Kolejność rozwiązywania konfiguracji

Serwer MCP rozwiązuje konfigurację w następującej kolejności pierwszeństwa: środowisko (NEXTPDF_MCP_*) ma pierwszeństwo przed sekcją nextpdf_mcp w pliku YAML, która z kolei ma pierwszeństwo przed wbudowanymi wartościami domyślnymi. Serwery REST i gRPC odczytują HttpConfig ze zmiennych środowiskowych NEXTPDF_* z bezpiecznymi wartościami domyślnymi. Nie odczytują pliku YAML MCP. Zobacz /connect/configuration/.

Powiązania kontenera

Nie ma żadnego kontenera wstrzykiwania zależności ani dostawcy usług do zarejestrowania. Każda fabryka create() buduje własny graf obiektów jawnie i deterministycznie. Istnieją dwa punkty rozszerzenia możliwe do wstrzyknięcia – transport oraz fabryka procesów roboczych – i oba służą do testowania, a nie do łączenia zależności aplikacji.

Przykład kodu – szybki start

Sprawdź wynik wykrywania bez obsługi ruchu:

./vendor/bin/generate-skills --dry-run --list-tools

Przykład kodu – środowisko produkcyjne

Uruchom połączone transporty pod jednym supervisorem:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

Przypadki brzegowe i pułapki

• Brak poziomu nie powoduje niepowodzenia uruchamiania. Wykrywanie poziomów po cichu pomija nieobecny pakiet Pro lub Enterprise. Serwer uruchamia się z katalogiem core.

• Nadpisanie obniżające poziom powoduje niepowodzenie uruchamiania. Wpis risk_level_overrides, który osłabia narzędzie z approval_required, powoduje zgłoszenie wyjątku podczas wczytywania konfiguracji; serwer odmawia uruchomienia. Jest to zachowanie zamierzone.

• Awaria Redis obniża wydajność, ale nie powoduje awarii. Jeśli Redis jest skonfigurowany, ale nieosiągalny podczas uruchamiania, serwer REST przechodzi na magazyny w pamięci. Sprawdzaj kondycję Redis, zamiast zakładać, że jest używany.

Wydajność

Koszt uruchamiania wynika z parsowania konfiguracji, skanowania rejestru i wykrywania poziomów. Pole performance_budget strony wyznacza limit tego kosztu. Koszt jest ponoszony raz na uruchomienie procesu, a nie przy każdym żądaniu.

Uwagi dotyczące bezpieczeństwa

Polityka bezpieczeństwa jest budowana przed rejestrem, więc lista dozwolonych enabled_tools ogranicza wykrywanie już od pierwszej rejestracji. Klucze API nigdy nie są odczytywane z pliku YAML MCP; transporty sieciowe rozwiązują klucze z pliku sekretów lub ze środowiska. Zobacz /connect/security-and-operations/.

Zgodność

Ta strona opisuje mechanikę uruchamiania. Odwołania dotyczące protokołu i bezpieczeństwa znajdują się na stronach /transports/mcp/, /transports/rest/, /transports/grpc/ oraz /connect/security-and-operations/.

Kontekst komercyjny

Wykrywanie poziomów podczas uruchamiania to jedyny punkt, w którym nextpdf/premium dodaje do katalogu swoje narzędzia Pro i Enterprise, gdy nextpdf/premium jest zainstalowany obok serwera.

Zobacz także

• /connect/tool-catalog/ – co rejestruje wykrywanie i dlaczego zmienia się liczba
• /connect/configuration/ – szczegółowa kolejność rozwiązywania
• /connect/deployment/ – wybór transportów za pomocą profili RoadRunner
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ – szczegóły dla poszczególnych transportów