本番運用

概要

このページは、NextPDF を本番環境へ投入し、そこで運用し続けるためのチェックリストです。マニュアル全体を束ねる役割を持ち、各項目は詳細を扱うページへリンクしています。つまり、ここで確認し、リンク先で読む構成です。 最初のリリースの前に デプロイ前チェックリストを最後まで進めてください。 アップグレードの頻度と インシデントトリアージの入口は、 運用開始後（day-two）オペレーションの一部として折に触れて見直してください。

デプロイ前チェックリスト

• ランタイムを確認します： NextPDF は PHP >=8.4 <9.0 を必要とします。 Composer はこの範囲外のものをすべて拒否します。 インストールを参照してください。
• php -m で 6 つの必須拡張を確認します： ext-mbstring、 ext-zlib、ext-intl、ext-gd、ext-curl、そして ext-openssl。 インストールページでは、 それぞれが何をするかを説明しています。
• 環境を一括で確認するには vendor/bin/nextpdf doctor を実行します （PHP のバージョン、拡張、フォントの利用可否を 1 つのレポートにまとめます）。
• ハードウェアをサイジングする前に、レンダリング経路を決めます。 インプロセスパイプライン（writeHtml()）は追加のサービスを必要としません。 Artisan、Gotenberg、Cloudflare はそれぞれ、運用すべきブラウザまたはネットワークサービスを追加します。決定には パスを選ぶを使ってください。
• レンダラーブリッジを選んだ場合は、本番稼働前にそのセキュリティと運用に関するページを読んでください。 レンダラー面の堅牢化を参照してください。
• レンダリングに使うフォントだけを、ビルド時にバンドルします。 本番環境でのフォントのプロビジョニングを参照してください。

リソースのサイジング

平均ではなく、生成する最大のドキュメントに合わせてサイジングします。 getPdfData() は Portable Document Format (PDF) ドキュメント全体をメモリ上に構築し、1 つの文字列として返します。

• ワーカーまたは関数のメモリを、 サーバーレスのサイジングガイダンス に従って設定します。数ページのドキュメントは 512～1024 MB で余裕がありますが、 画像の多いドキュメントやページ数の多いドキュメントはさらに必要です。
• タイムアウトは、最悪ケースのビルド時間を上回るように、余裕を持たせて設定します。 サイズ過大なジョブは、オブジェクトストレージへ書き込む非同期キューへ移します。 同じ サイジングセクション にそのパターンが示されています。
• 長寿命のワーカーには、タイムスタンプ検証を無効にした opcache を設定します。 Docker レシピの opcache セクション に本番向けの ini 値が載っています。
• 起動後にメモリまたはスループットがずれてきたら、 症状からレバーへの決定表 から始めてください。

ワーカー安全性のルール

Document は使い捨てです。構築し、1 回だけ書き出し、スコープから外れるに任せます。 リクエストごと、またはキュージョブごとに新しいインスタンスを作成してください。 共有してよいのは、プロセス寿命のレジストリ — FontRegistry と ImageRegistry — だけであり、これらはワーカー起動時に 1 回だけ作成します。これは PHP-FPM、 キューワーカー、そして長時間稼働するアプリケーションサーバーの、リクエスト単位・ジョブ単位のモデルに合致します。

• 起動シーケンスとサイクルごとのリセットを含むレシピ： ワーカーセーフなバッチレンダリング。
• 契約を一問一答で： ワーカーセーフかつスレッドセーフか？

レンダラー面の堅牢化

HTML は信頼できないものとして扱ってください。特にユーザーの影響を受けるものはなおさらです。パスを選ぶは、その境界を示しています。既定では、組み込みパイプラインはスクリプトを一切実行せず、 リモートリソースを取得しません。一方、各ブリッジはブラウザまたはネットワークサービスを介してレンダリングします。ブリッジを本番トラフィックに公開する前に、 そのセキュリティと運用に関するページを最後まで進めてください：

• Artisan のセキュリティと運用 — Chrome レンダラー面。
• Gotenberg のセキュリティと運用 — Gotenberg サービス面。
• Cloudflare のセキュリティと運用 — エッジデプロイ面。
• エンジンをサービスとして実行しますか？ Connect のセキュリティと運用を追加してください。

可観測性

NextPDF はサービスレベル目標 (SLO) の目標値を公表していません。以下で計測するレンダリング所要時間とメモリのメトリクスから、自分たちの目標値を導き出してください。

最初のインシデントの後ではなく、その前にレンダリング経路を計装してください。

• インプロセスエンジン： OpenTelemetry で観測する。
• NextPDF Connect のデプロイ： Connect の OpenTelemetry レシピ。
• レンダリングごとに、次を記録します：実時間、ピークメモリ、ページ数、出力サイズ、 そして エラーリファレンスの例外カテゴリを伴う結果。
• 失敗だけでなく、傾向にアラートを設定します：ビルド時間の上昇、ピークメモリの上昇、そしてタイムアウトやメモリ枯渇の件数は、 メモリとパフォーマンスのエントリ における先行的なシグナルです。

アップグレードの頻度

• バージョンサポートポリシーを一度読み、 以後はリリースをそれに準拠させます。このポリシーは、セマンティックバージョニングの契約、安定性ラベル、非推奨のライフサイクル、そしてこのマニュアルが用いるライフサイクル用語（active、lts、maintenance、frozen、eol）を定義しています。
• composer.lock をコミットして、デプロイされるすべてのワーカーが同じエンジンバージョンを解決するようにします。 インストールページがこの規律を明記しています。
• バージョンを上げるたびに変更履歴を確認してください。

インシデントトリアージの入口

レンダラーブリッジのインシデント（Chrome のクラッシュ、Gotenberg の停止、 エッジレンダリングの失敗）については、そのブリッジの失敗モードのセクションから始めてください。そのセクションは レンダラー面の堅牢化にあります。

• クラス名ではなく症状から、 トラブルシューティングナレッジベースで始めてください。
• 捕捉した例外を、そのカテゴリとコンテキスト契約に対応付けます。 エラーリファレンスを参照してください。

関連情報

• 本番環境での NextPDF の運用 — エンジンが負荷下でこのように振る舞う理由を解説する Insider_ エッセイです。
• NextPDF アプリケーションのコンテナ化 — 本番向け Docker イメージを端から端まで。
• サーバーレスへのデプロイ — Lambda、Cloud Run、App Runner の具体的な事項。
• Connect でのワーカーセーフなレンダリング — 同じ寿命ルールをサーバーに適用したもの。