Konfiguracja NextPDF Connect

W skrócie

NextPDF Connect ma dwa obszary konfiguracji. Serwer Model Context Protocol (MCP) odczytuje plik YAML oraz zmienne NEXTPDF_MCP_*. Serwery REST i gRPC odczytują zmienne środowiskowe NEXTPDF_*. Konfiguracja staje się niezmienna w chwili uruchomienia serwera.

Instalacja

composer require nextpdf/server

Przegląd koncepcyjny

Serwer MCP ustala konfigurację według określonej kolejności priorytetów. Wygrywa źródło o najwyższym priorytecie:

Zmienne środowiskowe (NEXTPDF_MCP_*).
Sekcja nextpdf_mcp pliku konfiguracyjnego YAML.
Wbudowane wartości domyślne.

Podaj plik YAML za pomocą --config=PATH. Jeśli go pominiesz, serwer korzysta wyłącznie z wartości domyślnych i zmiennych środowiskowych. Wynikowy obiekt McpConfig jest obiektem wartości typu readonly. Po uruchomieniu żadne ustawienie nie może się zmienić.

Serwery REST i gRPC odczytują HttpConfig ze środowiska podczas uruchamiania. Obsługują przesłonięcia z poziomu środowiska: NEXTPDF_BIND, NEXTPDF_WORKER_COUNT, NEXTPDF_SESSIONS_ENABLED oraz NEXTPDF_CORS_ENABLED. Dla pozostałych limitów obowiązują bezpieczne wartości domyślne.

Powierzchnia API

Konfiguracja MCP (`nextpdf-mcp`)

Plik YAML, sekcja nextpdf_mcp:

nextpdf_mcp:
  enabled_tools: []          # empty/absent = all available tools allowed
  temp_directory: /tmp/nextpdf-mcp
  max_documents: 50
  document_ttl: 1800
  max_file_size_bytes: 104857600
  allow_file_output: true
  compress: true
  risk_level_overrides:
    fill_form: 3             # raise fill_form to ApprovalRequired (see below)

Przesłonięcia z poziomu środowiska dla serwera MCP:

Zmienna	Klucz konfiguracji	Wartość domyślna
`NEXTPDF_MCP_ENABLED_TOOLS`	`enabled_tools`	wszystkie narzędzia są dozwolone
`NEXTPDF_MCP_TEMP_DIR`	`temp_directory`	systemowy katalog tymczasowy + `/nextpdf-mcp`
`NEXTPDF_MCP_MAX_FILE_SIZE`	`max_file_size_bytes`	`104857600` (100 MB)
`NEXTPDF_MCP_MAX_DOCUMENTS`	`max_documents`	`50`
`NEXTPDF_MCP_DOCUMENT_TTL`	`document_ttl`	`1800` sekund
`NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED`	(steruje dostępem do `parse_pdf`)	nieustawione (wyłączone)
`NEXTPDF_AST_TOOLS_ENABLED`	(steruje dostępem do narzędzi AST)	włączone
`NEXTPDF_MUTATION_TOOLS_ENABLED`	(steruje dostępem do narzędzi mutacji AST)	nieustawione (wyłączone)

Konfiguracja REST i gRPC

Zmienna	Wartość domyślna	Działanie
`NEXTPDF_BIND`	`0.0.0.0:8080`	Adres nasłuchu REST
`NEXTPDF_WORKER_COUNT`	`4`	Liczba procesów roboczych PHP RoadRunner
`NEXTPDF_SESSIONS_ENABLED`	`false`	Włącza stanowe punkty końcowe sesji
`NEXTPDF_CORS_ENABLED`	`false`	Włącza nagłówki odpowiedzi CORS
`NEXTPDF_API_KEYS`	nieustawione	Definicje kluczy API w treści
`NEXTPDF_API_KEYS_FILE`	nieustawione	Ścieżka do pliku z kluczami API
`NEXTPDF_JOB_STORE_PATH`	katalog tymczasowy systemu	Ścieżka magazynu zadań SQLite
`NEXTPDF_REDIS_HOST`	nieustawione	Po ustawieniu włącza magazyny oparte na Redis

Serwer REST korzysta z Redis, gdy ustawiono NEXTPDF_REDIS_HOST i załadowano ext-redis:

Zmienna	Wartość domyślna
`NEXTPDF_REDIS_PORT`	`6379`
`NEXTPDF_REDIS_PASSWORD`	puste
`NEXTPDF_REDIS_DATABASE`	`0`
`NEXTPDF_REDIS_PREFIX`	`nextpdf:`
`NEXTPDF_REDIS_CONNECT_TIMEOUT`	`2.0` sekundy
`NEXTPDF_REDIS_READ_TIMEOUT`	`2.0` sekundy

Przykład kodu — szybki start

Uruchom serwer MCP z jawnie wskazanym plikiem konfiguracyjnym:

./vendor/bin/nextpdf-mcp --config=/etc/nextpdf/nextpdf-mcp.yaml

Przykład kodu — środowisko produkcyjne

Ogranicz katalog MCP do jawnej listy dozwolonych narzędzi i podnieś poziom ryzyka narzędzia:

nextpdf_mcp:
  enabled_tools:
    - create_pdf
    - add_text
    - output_pdf
    - diagnostic.doctor
  temp_directory: /var/lib/nextpdf/tmp
  max_file_size_bytes: 26214400
  risk_level_overrides:
    add_text: 2          # upgrade add_text from caution to review

Gdy lista enabled_tools nie jest pusta, zasady bezpieczeństwa dopuszczają wyłącznie wymienione nazwy narzędzi. Rejestr bez komunikatu pomija każde inne narzędzie. Pusta lub nieobecna lista dopuszcza wszystkie dostępne narzędzia.

Przypadki brzegowe i pułapki

Nie można obniżyć poziomu ryzyka dwóch krytycznych narzędzi. output_pdf oraz sign_pdf są z założenia objęte bramką zatwierdzenia: wpis risk_level_overrides, który obniża którekolwiek z tych narzędzi poniżej ApprovalRequired, powoduje podczas ładowania zgłoszenie InvalidArgumentException, a serwer odmawia uruchomienia. Poziom ryzyka każdego innego narzędzia można podnieść lub obniżyć, dlatego każde obniżenie przeanalizuj pod kątem własnego modelu zagrożeń. Zobacz /connect/hitl-risk-tiers/.
enabled_tools filtruje, nie dodaje. Samo wymienienie nazwy narzędzia Pro przy braku nextpdf/premium nie sprawia, że się ono pojawi. Lista dozwolonych elementów jest przecinana ze zbiorem narzędzi faktycznie wykrytych przez rejestr.
W przypadku serwera MCP środowisko ma pierwszeństwo przed plikiem YAML. Zmienna NEXTPDF_MCP_* przesłania ten sam klucz w pliku YAML. Serwery REST i gRPC w ogóle nie odczytują pliku YAML MCP.
parse_pdf wymaga jawnego włączenia. Serwer rejestruje narzędzie parse_pdf tylko wtedy, gdy NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED ma wartość true lub 1. Domyślnie nie jest obecne, nawet w katalogu podstawowym.

Wydajność

Konfiguracja jest analizowana jednokrotnie podczas uruchamiania. Ustawienia max_documents oraz document_ttl ograniczają magazyn dokumentów w pamięci. Ich obniżenie zmniejsza szczytowe zużycie pamięci, ale skraca czas życia dokumentów. Liczba procesów roboczych oraz limity ładunku dla poszczególnych poziomów to parametry strojenia wdrożenia opisane w /connect/deployment/.

Uwagi dotyczące bezpieczeństwa

Traktuj enabled_tools jako mechanizm odmowy domyślnej dla wdrożeń zgodnych z zasadą najmniejszych uprawnień: wymień tylko te narzędzia, których potrzebuje dana integracja.
Nigdy nie przechowuj kluczy API w pliku YAML. Użyj NEXTPDF_API_KEYS_FILE z plikiem zamontowanym jako sekret Docker lub Kubernetes. Serwer preferuje magazyn plikowy z przeładowaniem na gorąco, dzięki czemu klucze można rotować bez ponownego uruchamiania. Zobacz /connect/security-and-operations/.
Katalog temp_directory jest wymuszonym katalogiem bazowym dla plików wyjściowych. Serwer normalizuje ścieżki wyjściowe i odrzuca wszystko, co po rozwiązaniu ścieżki prowadzi poza niego.

Zgodność

Ta strona opisuje mechanizmy konfiguracji. Cytowania dotyczące zgodności w zakresie uwierzytelniania i bezpieczeństwa transportu są przypięte w /connect/security-and-operations/.

Kontekst komercyjny

Limity ładunku i czasu oczekiwania dla poszczególnych poziomów (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit oraz odpowiadające im limity czasu oczekiwania) obowiązują dla transportu REST zgodnie z poziomem uwierzytelnionego klucza API. Wchodzą one w życie tylko wtedy, gdy zainstalowano narzędzia Pro lub Enterprise, a klucz ma do nich uprawnienia.

Zobacz też

/connect/install/ — instalacja i pakiety opcjonalne
/connect/boot-and-discovery/ — jak konfiguracja trafia do sekwencji uruchamiania
/connect/hitl-risk-tiers/ — model ryzyka i przesłonięcie działające wyłącznie w górę
/connect/security-and-operations/ — konfiguracja kluczy API i bezpieczeństwo transportu
/connect/deployment/ — liczba procesów roboczych, Redis i limity dla poziomów w środowisku produkcyjnym