NextPDF Gotenberg в production-среде

Краткий обзор

Мост выполняет один синхронный HTTP-запрос и проверяет результат. Он не выполняет повторных попыток, не ставит задания в очередь, не кэширует и не ограничивает частоту запросов. Реализуйте эти механизмы в приложении вокруг моста. На этой странице показано, какие функции где должны находиться и какие гарантии даёт мост, чтобы вы могли правильно построить остальную часть системы.

Рассматривайте каждое преобразование как удалённый вызов службы, которой вы управляете, но не контролируете внутри своего процесса. Учитывайте её задержки и сбои.

Получение конфигурации и секретов

GotenbergConfig хранит URL для API и, когда включена аутентификация, токен носителя (bearer token). Поле токена помечено атрибутом #[\SensitiveParameter], поэтому в трассировках стека оно скрывается. Вы по-прежнему отвечаете за его безопасное получение.

• Загружайте токен из менеджера секретов или из переменной окружения, переданной при запуске процесса. Не храните его в системе контроля версий и не помещайте в файл конфигурации, который попадает в образ.
• Создавайте конфигурацию один раз для области видимости запроса или один раз для рабочего процесса, а не для каждого преобразования. Конфигурация неизменяема, и хранить её дёшево.
• GotenbergConfig::fromArray() намеренно принимает некорректные входные данные и молча подставляет значения по умолчанию. В production-среде проверяйте исходный массив перед вызовом fromArray(). Тогда отсутствующий URL проявится как ошибка конфигурации при запуске, а не позднее как исключение Invalid Gotenberg configuration: apiUrl is empty при каждом преобразовании.

Таймауты

timeout (в секундах, по умолчанию 30) — это жёсткий таймаут передачи, применяемый транспортом, привязанным к cURL. Преобразование офисных документов через LibreOffice не мгновенно; крупные или сложные документы обрабатываются дольше. Устанавливайте таймаут с запасом, исходя из измеренной задержки преобразования ваших реальных документов. Держите его ниже любого таймаута вышестоящего шлюза или значения max_execution_time среды выполнения PHP. Тогда мост первым завершится по таймауту и вернёт типизированное исключение, а процесс не будет принудительно остановлен.

Если вы используете путь с внедрённым клиентом PHP Standard Recommendation 18 (PSR-18) (без внедрённого responseFactory или с “голым” URL на IP-адрес без привязок), мост не применяет значение timeout к этому клиенту. Настройте таймаут и на PSR-18-клиенте, чтобы оба транспорта оставались ограниченными.

Повторные попытки

Мост отправляет ровно один запрос на вызов и никогда не повторяет попытку. Добавьте повторные попытки на стороне вызывающего кода и сделайте их безопасными:

• Повторяйте только сбои транспортного уровня (GotenbergConvertException, причиной которого является исключение PSR-18-клиента) и идемпотентные ошибки сервера (HTTP 502, 503, 504). Не повторяйте без разбора каждое GotenbergConvertException. Ответ класса 400 обычно означает, что входные данные неверны, поэтому такая же повторная попытка завершится тем же сбоем.
• Используйте ограниченную экспоненциальную задержку (backoff) с джиттером. Когда служба преобразования под нагрузкой возвращает 503, шквал запросов только усугубляет проблему.
• Ограничьте общее число попыток и суммарное фактическое время. Преобразование и без того медленное, поэтому неограниченные повторные попытки многократно увеличивают хвостовую задержку.
• Повторная проверка выполняется автоматически: каждый повторный вызов заново выполняет проверку URL и повторную проверку адреса, поэтому повторная попытка не может случайно обойти защиту от подделки запросов на стороне сервера (SSRF).

Параллелизм и пропускная способность

Каждое преобразование удерживает одно соединение и один рабочий процесс LibreOffice на стороне Gotenberg до завершения запроса. Сам мост не хранит состояния, и его безопасно использовать одновременно из многих рабочих процессов. При этом пропускная способность преобразования у службы Gotenberg всё равно ограничена.

• Ограничьте число одновременно выполняемых преобразований на своей стороне (очередью, семафором или пулом рабочих процессов) до уровня, который способен выдержать Gotenberg. Размер лимита зависит от вашего развёртывания Gotenberg, а не от этого пакета; см. /integrations/gotenberg/security-and-operations/.
• Ограничение размера входных данных (maxFileSize, по умолчанию 50 MiB) — единственное встроенное ограничение ресурсов в мосте. Мост применяет его внутри процесса до отправки запроса, поэтому файл сверх лимита никогда не расходует пропускную способность службы. Снизьте его до уровня, действительно необходимого вашим документам; меньший лимит дешевле защищает от отказа в обслуживании, чем больший.
• Кэширование внутри процесса отсутствует. Если вы преобразуете один и тот же документ многократно, кэшируйте полученный Portable Document Format (PDF) в своём приложении, используя в качестве ключа хеш содержимого входных данных.

Наблюдаемость

Внедрите логгер PHP Standard Recommendation 3 (PSR-3), чтобы получать по одной записи уровня debug на каждый запрос преобразования. Запись содержит URL запроса, имя файла, обнаруженный формат и длину содержимого запроса. Она не содержит ни содержимое файла, ни токен носителя.

• Превратите этот сигнал в метрику: подсчитывайте преобразования по формату и результату и записывайте реальное время вокруг каждого вызова convertFile() / convertString() в виде гистограммы задержек. Сам мост метрики не выдаёт.
• Объект результата предоставляет поле renderTimeMs. Оно равно 0.0, если ваша интеграция не измеряет и не задаёт его; мост не заполняет его из ответа Gotenberg. Если это значение вам нужно, измеряйте время вызова самостоятельно.
• Записывайте исключения в журнал вместе с их типом. Тип исключения — основной сигнал о том, что именно произошло; каталог см. в /integrations/gotenberg/troubleshooting/.
• Вызывайте isAvailable() из эндпоинта готовности или работоспособности, а не при каждом преобразовании. Он отправляет запрос HEAD на /health. Вызов перед каждым преобразованием вдвое увеличивает частоту запросов к службе и не даёт пользы.

Контракт обработки сбоев

Мост сообщает о сбоях через типизированные исключения и никогда не возвращает частичный или непроверенный результат. Он гарантирует следующее:

• Статус, отличный от 200, заголовок Content-Type без application/pdf или тело, которое не начинается с %PDF, вызывают GotenbergConvertException. Мост возвращает объект результата только тогда, когда проходят все три проверки.
• Сбой PSR-18-клиента (включая сетевой сбой или таймаут) оборачивается в GotenbergConvertException: исходное исключение становится его причиной, а код исключения клиента переносится в код исключения моста.
• Сбои проверки (URL не по HTTPS, private/reserved адрес, ввод сверх лимита, небезопасное имя файла) вызывают RuntimeException до любого сетевого трафика.
• Нераспознанное расширение файла вызывает ValueError до любого сетевого трафика.

Перехватывайте конкретные типы. Пример программы в examples/convert-office-to-pdf.php демонстрирует исчерпывающий порядок перехвата. /integrations/gotenberg/troubleshooting/ объясняет каждый триггер.

Граница постобработки

Мост создаёт PDF и на этом останавливается. Типичный production-конвейер выглядит так:

1. Преобразуйте офисный документ этим мостом.
2. Загрузите полученные байты в документ NextPDF.
3. Примените постобработку: сборку страниц, нанесение водяных знаков, преобразование в Portable Document Format/Archive (PDF/A) и цифровые подписи.

Шаг 3 относится к NextPDF, а не к мосту. nextpdf/premium предоставляет подписание, профили PDF/A и нанесение водяных знаков. Держите преобразование и постобработку на отдельных этапах, чтобы можно было диагностировать сбой преобразования независимо от сбоя подписания.

Поддержка PDF Advanced Electronic Signatures (PAdES) в редакции Pro ограничена только базовым уровнем B-B. Она не предоставляет B-T, B-LT или B-LTA, и эти профили не подразумеваются при преобразовании документа через этот мост. Возможность долгосрочной валидации — это отдельный вопрос редакции и выходит за рамки этого пакета.

См. также

• /integrations/gotenberg/configuration/ — правила выбора транспорта и модель привязок.
• /integrations/gotenberg/security-and-operations/ — развёртывание и усиление защиты зависимости Gotenberg.
• /integrations/gotenberg/troubleshooting/ — каталог исключений.
• /integrations/gotenberg/integration/ — подключение преобразованного PDF к конвейеру NextPDF.