Przewodnik dewelopera NextPDF Connect

W skrócie

NextPDF Connect (nextpdf/server) udostępnia niezależny od frameworka silnik PDF 2.0 NextPDF jako usługę. Nie implementuje generowania plików PDF od nowa. Każdą funkcję silnika udostępnia jako nazwane narzędzie ze schematem, a następnie serwuje ten katalog przez trzy transporty: Model Context Protocol (MCP) przez standardowe wejście i wyjście, interfejs Application Programming Interface (API) w stylu Representational State Transfer (REST) oraz gRPC. Skorzystaj z tego przewodnika podczas tworzenia rozwiązań opartych na serwerze, rozszerzania jego zestawu narzędzi lub uruchamiania go w środowisku produkcyjnym.

Projekt opiera się na trzech koncepcjach: rejestrze narzędzi, trzech niezależnych transportach oraz bramce potwierdzeń z udziałem człowieka (human-in-the-loop, HITL). Ta strona wyjaśnia, jak współdziałają i jak z nimi pracować bez osłabiania modelu bezpieczeństwa. Dokładne symbole narzędzi, zdalnych wywołań procedur (remote procedure call, RPC) i komunikatów znajdziesz w dokumencie Dokumentacja API.

Wymagania wstępne: PHP 8.4, Composer 2 oraz — w przypadku transportów sieciowych — plik wykonywalny RoadRunner i co najmniej jeden klucz API. Zainstaluj pakiet poleceniem composer require nextpdf/server.

Granica architektury

Utrzymuj każdą odpowiedzialność po właściwej stronie granicy. Narzędzie jest cienką nakładką na wywołanie silnika; nie może zawierać interpretacji układu, semantyki dokumentu ani logiki transformacji.

Warstwa	Właściciel	Odpowiedzialność	Nie umieszczaj tutaj
Klient lub agent	Twoja integracja	Wybór narzędzia do wywołania; przekazywanie człowiekowi wyzwań do potwierdzenia.	Logiki silnika ani wykrywania poziomu.
Transport	nextpdf/server	Ramkowanie żądań jako JSON-RPC, HTTP lub Protocol Buffers; uwierzytelnianie; kierowanie do modułu wykonawczego narzędzi.	Semantyki dokumentu.
Rejestr narzędzi	nextpdf/server	Wykrywanie poziomów, rejestrowanie narzędzi zgodnie z listą dozwolonych zabezpieczeń, wyszukiwanie narzędzia po nazwie.	Generowania plików PDF.
Narzędzie	nextpdf/server	Walidacja argumentów według schematu wejściowego i wywołanie silnika.	Interpretacji układu ani wieloetapowej orkiestracji.
Bramka potwierdzeń	nextpdf/server	Wstrzymanie operacji ApprovalRequired do czasu zatwierdzenia jej przez człowieka.	Uwierzytelniania wywołującego.
Silnik	nextpdf/core (oraz nextpdf/premium)	Generowanie, sprawdzanie i transformowanie zawartości PDF.	Kwestii transportu ani uwierzytelniania.

Cykl życia w czasie wykonywania

Każdy transport ma własny punkt wejścia i fabrykę rozruchu. Każdy z nich jawnie konstruuje swój graf obiektów. Nie ma tu kontenera wstrzykiwania zależności do zarejestrowania.

1. Wczytanie konfiguracji. Serwer MCP rozwiązuje konfigurację ze zmiennych środowiskowych (NEXTPDF_MCP_*), następnie z sekcji nextpdf_mcp w pliku YAML, a na końcu z wbudowanych wartości domyślnych, i tworzy readonlyMcpConfig. Serwery REST i gRPC odczytują HttpConfig ze zmiennych środowiskowych NEXTPDF_*. Zobacz Konfiguracja.
2. Zbudowanie polityki bezpieczeństwa. Lista dozwolonych enabled_tools jest budowana przed rejestrem, dzięki czemu ogranicza wykrywanie już od pierwszej rejestracji.
3. Skonstruowanie rejestru i wykrycie narzędzi. ToolRegistry::registerDefaults() rejestruje poziom core, następnie dostawców Pro i Enterprise, gdy ich klasy zostaną rozpoznane, a na końcu dołączonych dostawców AST i mutacji zgodnie z ich bramkami środowiskowymi.
4. Zbudowanie współdzielonych magazynów i bramki. Magazyn dokumentów w pamięci jest budowany na podstawie skonfigurowanego TTL i pojemności; ConfirmationGate jest tworzona razem ze swoim magazynem tokenów jednorazowego użytku.
5. Powiązanie transportu. MCP wchodzi w pętlę odczytu, obsługi i zapisu przez stdio aż do końca pliku. REST i gRPC budują swoją tabelę tras lub usług na podstawie wykrytych poziomów, a następnie przekazują pętlę żądań do RoadRunnera.

Żądanie podąża następnie tą ścieżką: uwierzytelnienie (REST i gRPC), rozwiązanie narzędzia lub operacji, uruchomienie bramki potwierdzeń dla operacji ApprovalRequired, wykonanie względem silnika oraz zwrócenie wyniku. Zobacz Rozruch i wykrywanie.

Model transportu

Trzy transporty współdzielą koncepcje rejestru, konfiguracji i bramki, jednak działają jako niezależne procesy. Uruchomienie jednego nie uruchamia pozostałych.

Transport	Punkt wejścia	Kiedy go wybrać
MCP	bin/nextpdf-mcp	Lokalny klient sztucznej inteligencji (artificial intelligence, AI), który uruchamia serwer jako zaufany podproces.
REST	bin/nextpdf-server	Sieciowi klienci HTTP; kontrakt opisany dokumentem OpenAPI 3.1.
gRPC	bin/nextpdf-grpc	Typowani klienci strumieniowi; usługa nextpdf.connect.v1.NextPDFConnect.

Wybierz transporty zgodnie z uruchamianym profilem RoadRunner: .rr.yaml (tylko REST), .rr.grpc.yaml (tylko gRPC) lub .rr.full.yaml (oba). Transport MCP to zwykły podproces i nie wymaga nadzorcy. Szczegóły protokołu znajdziesz w sekcjach Transport MCP, Transport REST oraz Transport gRPC.

Zalecana struktura wdrożenia

Uruchamiaj transporty sieciowe pod RoadRunnerem ze współdzielonymi magazynami i kluczami montowanymi z magazynu sekretów. Połączony profil pozwala REST i gRPC współdzielić jednego nadzorcę.

Ścieżka lub ustawienie	Przeznaczenie
.rr.full.yaml	Połączony profil REST i gRPC pod jednym nadzorcą.
NEXTPDF_API_KEYS_FILE	Ścieżka do montowanego z magazynu sekretów pliku kluczy API, przeładowywanego na gorąco.
NEXTPDF_REDIS_HOST	Włącza oparte na Redis magazyny ograniczania liczby żądań, idempotentności i dokumentów dla pul wieloprocesowych.
NEXTPDF_WORKER_COUNT / NEXTPDF_GRPC_WORKER_COUNT	Dobór wielkości puli procesów roboczych dla pul HTTP i gRPC.
Katalog bazowy danych wyjściowych	Dedykowany wolumin z uprawnieniami systemu plików zgodnymi z zasadą najmniejszych uprawnień dla narzędzi zapisujących pliki.

Poniższy przykład powłoki uruchamia połączony profil z kluczami montowanymi z magazynu sekretów i współdzielonym magazynem Redis. Nie zawiera żadnych sekretów; klucze są montowane w /run/secrets/api-keys.

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
export NEXTPDF_WORKER_COUNT=8
export NEXTPDF_GRPC_WORKER_COUNT=4
export NEXTPDF_REDIS_HOST=redis
./vendor/bin/rr serve -c .rr.full.yaml

W przypadku puli wieloprocesowej skonfiguruj Redis i upewnij się, że ext-redis jest obecne w obrazie uruchomieniowym. Bez tego magazyny ograniczania liczby żądań, idempotentności i dokumentów działają osobno dla każdego procesu roboczego. Zobacz Wdrożenie.

Rejestr narzędzi i rozstrzyganie poziomów

NextPDF\Server\ToolRegistry (src/ToolRegistry.php) buduje katalog podczas rozruchu. Poziom jest deklarowanym niezmiennikiem: każde narzędzie zwraca własne tier() oraz riskLevel(). Rejestr nigdy nie wnioskuje poziomu na podstawie przestrzeni nazw ani sposobu pakowania.

1. Poziom core rejestruje się bezwarunkowo: narzędzia dokumentów i diagnostyczne, a także generate_barcode, gdy obecny jest rdzeniowy rejestr koderów kodów kreskowych, oraz parse_pdf tylko wtedy, gdy NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED ma wartość true lub 1.
2. Dostawcy Pro i Enterprise rejestrują się, gdy ich klasy dostawców zostaną rozpoznane, co jest sprawdzane za pomocą class_exists(). Brakujący poziom jest po cichu pomijany.
3. Dołączeni dostawcy AST i mutacji rejestrują się na poziomie Pro, sterowani bramkami NEXTPDF_AST_TOOLS_ENABLED i NEXTPDF_MUTATION_TOOLS_ENABLED (obie włączone domyślnie).
4. Filtr polityki bezpieczeństwa przefiltrowuje każdą rejestrację przez listę dozwolonych enabled_tools. Lista dozwolonych wyłącznie zawęża katalog; nigdy go nie rozszerza. Licznik dla każdego poziomu zlicza wyłącznie narzędzia dopuszczone przez politykę.

Odpowiedź MCP initialize oraz punkt końcowy REST GET /api/v1/capabilities raportują wynikowe liczniki dla każdego poziomu oraz sumę. Każdą stałą sumę podaną w tekście traktuj jako nieaktualną; odpytuj działający serwer. Zobacz Katalog narzędzi.

Poziomy ryzyka i bramka potwierdzeń

Każde narzędzie deklaruje jeden z czterech poziomów ryzyka z wyliczenia RiskLevel (src/Config/RiskLevel.php): Safe (0), Caution (1), Review (2) oraz ApprovalRequired (3). Rejestrowanie audytowe obowiązuje od poziomu Caution wzwyż. Przesłonięcie w konfiguracji może podnieść ryzyko narzędzia; nigdy nie może obniżyć narzędzia, które z założenia jest ApprovalRequired. Moduł wczytujący konfigurację zgłasza wyjątek podczas wczytywania, a serwer odmawia uruchomienia, zamiast działać z osłabioną bramką.

Gdy narzędzie ApprovalRequired zostanie wywołane bez prawidłowego tokena, ConfirmationGate (src/Mcp/ConfirmationGate.php) zwraca jednorazowy token wyzwania. Token wiąże nazwę narzędzia, losowy nonce oraz 300-sekundowy czas życia (time-to-live, TTL), ale nie argumenty, ponieważ klienci mogą przy ponawianiu ponownie serializować argumenty w innej kolejności kluczy. Agent przekazuje wyzwanie człowiekowi i ponownie wywołuje to samo narzędzie z tokenem w argumencie _confirmation_token. Token jest zużywany przy użyciu, dopuszczając dokładnie jedno wywołanie objęte bramką.

Poniższy przykład w PHP to pomocnik niezależny od transportu. Obsługuje wywołanie narzędzia MCP, a w przypadku wyzwania potwierdzającego pokazuje je osobie zatwierdzającej przed ponowieniem z wydanym tokenem. Deklaruje typy ścisłe, jest w pełni otypowany i przechwytuje najbardziej szczegółowy wyjątek, zamiast przechwytywać każdy błąd bez rozróżnienia.

examples/connect/confirm-and-call.php

<?php

declare(strict_types=1);

namespace App\Connect;

use JsonException;

/**
 * Drives one tool call and resolves an ApprovalRequired confirmation
 * challenge through a human approver before retrying.
 */
final readonly class ConfirmingToolCaller
{
    public function __construct(
        private McpClientInterface $client,
        private HumanApproverInterface $approver,
    ) {}

    /**
     * @param non-empty-string     $toolName
     * @param array<string, mixed> $arguments
     *
     * @return array<string, mixed> The tool result content
     *
     * @throws JsonException         When a response cannot be decoded
     * @throws ApprovalDeniedException When the human declines the challenge
     */
    public function call(string $toolName, array $arguments): array
    {
        $response = $this->client->callTool($toolName, $arguments);

        if (!isset($response['challenge'], $response['token'])) {
            return $response;
        }

        $challenge = (string) $response['challenge'];
        $token = (string) $response['token'];

        if (!$this->approver->approve($toolName, $challenge)) {
            throw new ApprovalDeniedException($toolName);
        }

        $arguments['_confirmation_token'] = $token;

        return $this->client->callTool($toolName, $arguments);
    }
}

Powiąż McpClientInterface, HumanApproverInterface oraz ApprovalDeniedException z własnym kanałem transportu i zatwierdzania. Ponowienie wykorzystuje pierwotne argumenty wraz z wydanym tokenem; nigdy nie zatwierdzaj wyzwania automatycznie bez decyzji człowieka. Zobacz Poziomy ryzyka HITL.

Punkty rozszerzeń

Rozszerzaj serwer, dodając narzędzia i dostarczając dostawców, a nie edytując rejestr.

Punkt rozszerzenia	Zastosowanie	Ograniczenie
Klasa implementująca ToolInterface	Nowa funkcja silnika udostępniona jako narzędzie.	Zadeklaruj tier(), riskLevel(), category() oraz inputSchema() w formacie JSON Schema; utrzymuj klasę jako cienką nakładkę na silnik.
Dostawca ToolProviderInterface	Rejestrowanie zestawu narzędzi dla poziomu.	Dostawcy Pro i Enterprise są wykrywani za pomocą class_exists(); nie wymagaj pakietu zastrzeżonego po stronie serwera.
Lista dozwolonych enabled_tools	Zawężenie udostępnianego katalogu do najmniejszych uprawnień.	Lista dozwolonych tylko zawęża katalog; nie może zarejestrować nieobecnego narzędzia.
risk_level_overrides	Wzmacnianie wdrożenia przez podniesienie ryzyka narzędzia.	Tylko podwyższanie; obniżenie narzędzia ApprovalRequired powoduje niepowodzenie rozruchu.
Wstrzykiwalne punkty styku transportu i procesów roboczych	Testowanie serwera w izolacji.	Te granice istnieją na potrzeby testów, a nie do łączenia komponentów aplikacji.

Procedura operacyjna

1. Wybierz profil. Uruchom .rr.yaml, .rr.grpc.yaml lub .rr.full.yaml dla udostępnianych transportów.
2. Zamontuj klucze z magazynu sekretów. Skieruj NEXTPDF_API_KEYS_FILE na plik sekretu; preferuj plikowy magazyn kluczy z przeładowywaniem na gorąco, żeby rotacja nie wymagała ponownego uruchomienia.
3. Skonfiguruj współdzielone magazyny. Ustaw NEXTPDF_REDIS_HOST i potwierdź obecność ext-redis dla każdej puli większej niż jeden proces roboczy; umieść magazyn zadań SQLite na woluminie zapisywalnym przez wszystkie procesy robocze.
4. Zakończ TLS. Uruchamiaj REST za terminatorem Transport Layer Security (TLS); uruchamiaj gRPC z wzajemnym TLS w każdej niezaufanej sieci, z kluczem serwera, certyfikatem serwera i urzędem certyfikacji klienta dostarczonymi jako sekrety wdrożeniowe.
5. Sprawdzaj kondycję. Używaj anonimowych punktów końcowych /healthz i /readyz (REST) lub wywołań RPC HealthCheck i ReadinessCheck (gRPC) do sond orkiestratora.
6. Ogranicz zakres katalogu. Ogranicz enabled_tools do minimalnego zestawu potrzebnego integracji.

Weryfikuj kondycję usługi Redis, zamiast ją zakładać. Serwer REST przełącza się awaryjnie na magazyny pamięciowe, gdy skonfigurowane połączenie z Redis zawiedzie. Zobacz Wdrożenie oraz Bezpieczeństwo i operacje.

Obsługa awarii

Awaria	Gdzie się ujawnia	Zalecana reakcja
Nieznany document_id	Wykonanie narzędzia	Zwróć wywołującemu zdefiniowany błąd; poinstruuj go, aby najpierw wywołał create_pdf.
Nieaktualny ETag przy mutacji	Narzędzie mutacji AST	Odczytaj dokument ponownie za pomocą get_document_ast i ponów z aktualnym ETag.
Brakujący lub nieprawidłowy klucz API (REST)	Oprogramowanie pośredniczące uwierzytelniania	Zwróć 401 z wyzwaniem WWW-Authenticate: Bearer; nie ujawniaj, która część była błędna.
Poziom bez uprawnień (REST)	Autoryzacja	Zwróć 403; poziom klucza jest niższy niż poziom operacji.
Brak trasy dla poziomu (REST)	Router	Zwróć 404; pakiet nie jest zainstalowany. To oczekiwane działanie, a nie usterka.
Nieprawidłowy token (gRPC)	Moduł uwierzytelniający gRPC	Zakończ wywołanie niepowodzeniem z kodem UNAUTHENTICATED.
Redis nieosiągalny	Rozruch lub czas wykonywania	Przełącz się awaryjnie na magazyny pamięciowe; powiadom operatorów i zweryfikuj kondycję usługi Redis.
Ścieżka wyjściowa poza katalogiem bazowym	Narzędzie zapisujące pliki	Zachowaj zasadę fail-closed; ścieżka jest kanonizowana, a próby przejścia są odrzucane.

Ujawniaj awarie silnika jako zdefiniowane obiekty błędów, nigdy jako ciche sukcesy. Dokument Dokumentacja API szczegółowo opisuje model błędów dla każdego transportu.

Bezpieczne wartości domyślne

Zagadnienie	Domyślnie	Kiedy przesłonić
parse_pdf	Wyłączone (włączane na życzenie przez NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED).	Włączaj tylko wtedy, gdy integracja wymaga inspekcji strukturalnej.
enabled_tools	Pusta (dozwolone wszystkie wykryte narzędzia).	Ustaw jawną listę dozwolonych dla wdrożeń zgodnych z zasadą najmniejszych uprawnień.
Przesłonięcia ryzyka	Brak.	Podnoś ryzyko na potrzeby wzmocnionego wdrożenia; nigdy nie próbuj obniżać.
document_ttl / max_documents	1800 sekund / 50 dokumentów.	Obniż dla wdrożeń wrażliwych na rezydencję danych lub ograniczonych pamięcią.
allow_file_output	Włączone.	Ustaw na false dla bezstanowych wdrożeń wrażliwych na rezydencję danych.
Liczba procesów roboczych	Cztery (HTTP), dwa (gRPC).	Dobierz wielkość na podstawie obserwowanego opóźnienia i dostępnych rdzeni.
Nasłuch REST	Nieszyfrowany HTTP za terminatorem TLS.	Zawsze terminuj TLS po stronie nadrzędnej; nigdy nie udostępniaj ruchu nieszyfrowanego w niezaufanej sieci.
gRPC w niezaufanych sieciach	Wzajemny TLS.	Wymagany; nigdy nie uruchamiaj nieszyfrowanego nasłuchu gRPC w niezaufanej sieci.

Lista kontrolna testów

• Testy rejestru potwierdzają, że brakujący poziom Pro lub Enterprise jest po cichu pomijany, a katalog core nadal się rejestruje.
• Testy listy dozwolonych potwierdzają, że enabled_tools zawęża katalog i nigdy nie dodaje narzędzia, którego rejestr nie wykrył.
• Testy bramki potwierdzeń potwierdzają, że narzędzie ApprovalRequired zwraca wyzwanie przy pierwszym wywołaniu, wykonuje się raz przy prawidłowym tokenie jednorazowym i unieważnia token po jego TTL.
• Testy obniżania ryzyka potwierdzają, że wpis risk_level_overrides osłabiający narzędzie ApprovalRequired powoduje niepowodzenie rozruchu.
• Testy uwierzytelniania obejmują brakujące, zniekształcone, wyłączone i wygasłe klucze w REST (401 z WWW-Authenticate) i gRPC (UNAUTHENTICATED) oraz odrzucenie z powodu uprawnień poziomu (403).
• Testy współbieżności potwierdzają, że nieaktualny ETag powoduje niepowodzenie mutacji, a powtórzony idempotency_key odtwarza wynik z pamięci podręcznej.
• Testy ograniczenia ścieżek potwierdzają, że ścieżka wyjściowa pliku rozwiązująca się poza katalogiem bazowym jest odrzucana.
• Utrzymuj dane testowe małe i niewrażliwe; nigdy nie zatwierdzaj prawdziwego klucza API ani zawartości dokumentu.

Zobacz też

• Dokumentacja API — dokładne symbole narzędzi, RPC i komunikatów
• Katalog narzędzi — zweryfikowany zestaw core i licznik w czasie wykonywania
• Poziomy ryzyka HITL — model ryzyka i koperta potwierdzenia
• Konfiguracja — kolejność rozwiązywania i przesłonięcie tylko podwyższające
• Wdrożenie — profile RoadRunner, Redis i wzajemny TLS
• Bezpieczeństwo i operacje — uwierzytelnianie, bezpieczeństwo transportu i model zagrożeń