Эксплуатация в production

Кратко

Эта страница — чек-лист для вывода NextPDF в production и его дальнейшей эксплуатации. Она систематизирует руководство: каждый пункт ссылается на страницу с подробностями, поэтому здесь вы отмечаете пункты, а подробности читаете на связанных страницах. Пройдите Чек-лист перед развёртыванием перед первым выпуском. Возвращайтесь к разделам Ритм обновлений и Точки входа для разбора инцидентов в рамках повседневной эксплуатации.

Чек-лист перед развёртыванием

• Подтвердите среду выполнения: NextPDF требует PHP >=8.4 <9.0. Composer отклоняет всё за пределами этого диапазона. См. Установка.
• Проверьте шесть обязательных расширений с помощью php -m: ext-mbstring, ext-zlib, ext-intl, ext-gd, ext-curl и ext-openssl. Страница установки объясняет, за что отвечает каждое из них.
• Запустите vendor/bin/nextpdf doctor для разовой проверки среды (версия PHP, расширения и доступность шрифтов в одном отчёте).
• Определите путь рендеринга, прежде чем рассчитывать оборудование. Внутрипроцессный конвейер (writeHtml()) не требует дополнительной службы. Artisan, Gotenberg и Cloudflare — каждый добавляет браузер или сетевую службу для работы. Для выбора используйте Выбор пути.
• Если вы выбрали мост рендеринга, прочитайте его страницу о безопасности и эксплуатации перед запуском. См. Усиление поверхности рендерера.
• Включайте в сборку только те шрифты, которые вы рендерите, — и только их. См. Обеспечение шрифтов в production.

Расчёт ресурсов

Рассчитывайте под самый большой документ, который вы генерируете, а не под средний. getPdfData() строит весь документ Portable Document Format (PDF) в памяти и возвращает его одной строкой.

• Задавайте память воркера или функции по рекомендациям по расчёту для serverless: документ в несколько страниц комфортно укладывается в 512–1024 МБ; документам с большим числом изображений или страниц нужно больше.
• Устанавливайте тайм-ауты выше времени сборки в худшем случае, с запасом. Переносите слишком крупные задачи в асинхронную очередь, которая пишет в объектное хранилище, — тот же раздел о расчёте показывает этот шаблон.
• Предоставляйте долгоживущим воркерам opcache с отключённой проверкой временных меток. Раздел про opcache в рецепте для Docker содержит production-значения ini.
• Когда после запуска память или пропускная способность начинают дрейфовать, начните с таблицы решений «симптом → рычаг».

Правила безопасности воркеров

Document предназначен для однократного использования. Постройте его, запишите один раз и дайте ему выйти из области видимости; создавайте новый экземпляр на каждый запрос или каждую задачу очереди. Совместно используйте между вызовами только реестры уровня процесса — FontRegistry и ImageRegistry, — создавая их один раз при старте воркера. Это соответствует модели «на запрос, на задачу» у PHP-FPM, очередей-воркеров и долгоживущих серверов приложений.

• Рецепт с последовательностью запуска и сбросом на каждом цикле: Безопасный для воркеров пакетный рендеринг.
• Контракт в одном ответе: Безопасен ли он для воркеров и потоков?

Усиление поверхности рендерера

Относитесь к HTML как к недоверенному, особенно к тому, на что влияет пользователь. Выбор пути обозначает границу: по умолчанию встроенный конвейер не выполняет скриптов и не загружает удалённых ресурсов, тогда как каждый мост рендерит через браузер или сетевую службу. Прежде чем открывать мост для production-трафика, проработайте его страницу о безопасности и эксплуатации:

• Безопасность и эксплуатация Artisan — поверхность рендерера Chrome.
• Безопасность и эксплуатация Gotenberg — поверхность службы Gotenberg.
• Безопасность и эксплуатация Cloudflare — поверхность развёртывания на edge.
• Запускаете движок как службу? Добавьте Безопасность и эксплуатация Connect.

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

NextPDF не публикует целевых показателей уровня обслуживания (SLO); выведите свои из метрик длительности рендеринга и памяти, которые вы измеряете ниже.

Инструментируйте путь рендеринга до первого инцидента, а не после.

• Внутрипроцессный движок: Наблюдение с OpenTelemetry.
• Развёртывания NextPDF Connect: Рецепт OpenTelemetry для Connect.
• На каждый рендеринг фиксируйте: реальное время, пиковую память, число страниц, размер вывода и результат с категорией исключения из справочника ошибок.
• Настраивайте оповещения на тренды, а не только на сбои: рост времени сборки, рост пиковой памяти и счётчики тайм-аутов или исчерпания памяти — ведущие сигналы в материалах по памяти и производительности.

Ритм обновлений

• Прочитайте политику поддержки версий один раз, затем придерживайтесь её в выпусках. Она определяет контракт семантического версионирования, метки стабильности, жизненный цикл устаревания и словарь жизненного цикла (active, lts, maintenance, frozen, eol), который использует это руководство.
• Фиксируйте composer.lock в системе контроля версий, чтобы каждый развёрнутый воркер разрешал одну и ту же версию движка, — страница установки формулирует эту дисциплину.
• Просматривайте список изменений перед каждым повышением версии.

Точки входа для разбора инцидентов

При инциденте с мостом рендеринга (сбой Chrome, недоступность Gotenberg, отказ рендеринга на edge) начните с раздела о режимах отказа этого моста в Усиление поверхности рендерера.

• Начинайте с симптома, а не с имени класса, в базе знаний по устранению неполадок.
• Сопоставьте перехваченное исключение с его категорией и контрактом контекста в справочнике ошибок.

См. также

• Эксплуатация NextPDF в production — эссе Insider_ о том, почему движок ведёт себя так под нагрузкой.
• Контейнеризация приложения NextPDF — production-образ Docker от начала до конца.
• Развёртывание на serverless — особенности Lambda, Cloud Run и App Runner.
• Безопасный для воркеров рендеринг на Connect — те же правила времени жизни, применённые к серверу.