NextPDF Connect のデプロイ

概要

REST と gRPC のトランスポートは、RoadRunner のワーカープール内で実行されます。このパッケージには、HTTP のみ、gRPC のみ、両方を組み合わせたプロファイルという 3 つの RoadRunner プロファイルが付属しています。MCP トランスポートは通常のサブプロセスとして実行され、スーパーバイザーは不要です。

インストール

composer require nextpdf/server
./vendor/bin/rr get-binary

概念の概要

RoadRunner はプロセススーパーバイザーです。ワーカープールを管理し、メモリ負荷が高まるとワーカーを再起動し、各リクエストを空いているワーカーへルーティングします。PHP パッケージは、ワーカーのエントリポイントとして HTTP 用の bin/nextpdf-server と gRPC 用の bin/nextpdf-grpc を提供します。RoadRunner は、これらのエントリポイントを実行するプールを提供します。各ワーカーは一度に 1 つのリクエストを処理します。

MCP トランスポートの動作は異なります。bin/nextpdf-mcp は、単一の PHP プロセスです。stdio 経由の JSON-RPC で通信し、クライアントが直接起動します。

API サーフェス

RoadRunner プロファイル

プロファイル	トランスポート	コマンド
`.rr.yaml`	REST のみ	`rr serve -c .rr.yaml`
`.rr.grpc.yaml`	gRPC のみ	`rr serve -c .rr.grpc.yaml`
`.rr.full.yaml`	REST + gRPC	`rr serve -c .rr.full.yaml`

HTTP プロファイルは、REST リスナーを 0.0.0.0:8080 にバインドします。ステータスエンドポイントを :2114 で、メトリクスを :2112 で公開します。ワーカープールのサイズは NEXTPDF_WORKER_COUNT から決まり、デフォルトは 4 です。付属のプロファイルでは、スーパーバイザーがワーカーごとのメモリを 256 MB に制限します。

組み合わせプロファイルは、tcp://0.0.0.0:9090 で gRPC ワーカープールを追加します。このプールのサイズは NEXTPDF_GRPC_WORKER_COUNT から決まり、デフォルトは 2 です。gRPC 相互 TLS も構成します。

コードサンプル — クイックスタート

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

コードサンプル — 本番環境

組み合わせプロファイル、ファイルベースの鍵、Redis ベースの共有ストアを使用して、本番環境のコンテナーを実行します。

services:
  nextpdf-connect:
    image: ghcr.io/nextpdf-labs/server:latest
    command: ["rr", "serve", "-c", "/app/.rr.full.yaml"]
    ports:
      - "8080:8080"   # REST
      - "9090:9090"   # gRPC
    environment:
      - NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
      - NEXTPDF_WORKER_COUNT=8
      - NEXTPDF_GRPC_WORKER_COUNT=4
      - NEXTPDF_REDIS_HOST=redis
    secrets:
      - api-keys
    depends_on:
      redis:
        condition: service_healthy
    restart: unless-stopped
  redis:
    image: redis:8

エッジケースと注意点

インメモリストアはワーカーをまたぎません。 Redis がない場合、各ワーカーはレート制限、冪等性、ドキュメントの各ストアを個別に保持します。インメモリストアを使用するマルチワーカープールでは、レート制限に一貫性がなくなり、ワーカー間でドキュメントが失われます。ワーカー数が 1 を超えるプールでは、NEXTPDF_REDIS_HOST を設定し、ext-redis をインストールしてください。Redis 接続が失敗した場合、サーバーは自動的にインメモリにフォールバックします。Redis の正常性を確認し、正常であると決めつけないでください。
ジョブストアは WAL モードの SQLite です。 非同期ジョブは、すべての HTTP ワーカーと gRPC ワーカーが共有する単一の SQLite ファイルに永続化されます。そのファイルは、すべてのワーカーが書き込めるボリュームに配置してください。ワーカーのシャットダウン時には、実行中のジョブをベストエフォートで失敗としてマークするため、それらのジョブが孤立したままになることはありません。
bin/nextpdf-prune はメンテナンス用のエントリポイントです。 これは vendor/bin/ ではなく、リポジトリに付属しています。ストアのプルーニングタスクでは、これを直接呼び出してください。これはサーバートランスポートではありません。
イメージの PHP バージョンに ext-redis が含まれていない場合があります。 付属の Dockerfile は、ext-redis をベストエフォートでビルドします。ベースの PHP に対応する互換性のあるリリースが存在しない場合は、その拡張機能なしで続行します。Redis ベースのストアに依存する前に、実行中のイメージにその拡張機能が存在することを確認してください。

パフォーマンス

ワーカープールのサイズは、利用可能な CPU とメモリに合わせて NEXTPDF_WORKER_COUNT で設定します。各ワーカーは、スーパーバイザーのメモリ上限で制限される PHP プロセスです。レンダリング負荷の高いワークロードでは、コアごとに 1 つのワーカーから始め、その後メトリクスエンドポイントを見ながら調整します。gRPC プールのサイズは独立して設定します。gRPC クライアントは通常、数が少なく、より長時間存続するため、このサイズは一般的に HTTP プールより小さくなります。

セキュリティに関する注意事項

gRPC の相互 TLS

組み合わせプロファイルは、gRPC トランスポートを相互 TLS 用に構成します。サーバーは証明書を提示し、クライアント証明書を要求して検証します。サーバー鍵、サーバー証明書、クライアント CA は、イメージに組み込むのではなく、デプロイメントのシークレットとして提供します。これらは帯域外で生成し、ローテーションしてください。信頼されていないネットワーク上で、平文リスナーを使用して gRPC トランスポートを実行しないでください。

REST の TLS 終端

REST プロファイルは、平文の HTTP リスナーをバインドします。その前段で TLS を終端し（リバースプロキシ、ロードバランサー、またはサービスメッシュ）、リスナーは内部ネットワークのみにバインドしてください。クライアント ID は Authorization ヘッダーで変更せずに転送してください。サーバーは独自に鍵を検証します。リスナー自体はセキュアなトランスポートを提供しません。それを提供するのは、このデプロイメント構成です。

シークレット

API キーは NEXTPDF_API_KEYS_FILE でマウントし、インラインの NEXTPDF_API_KEYS 変数ではなくシークレットファイルを指すようにしてください。ファイルベースのストアは変更時にホットリロードされるため、ローテーションに再起動は不要です。鍵や TLS の秘密情報を、イメージに組み込まないでください。詳しくは /connect/security-and-operations/. を参照してください。

適合性

デプロイメントの仕組みには、規範的なプロトコルに関する主張は含まれません。認証およびトランスポートセキュリティの出典は、/connect/security-and-operations/. に固定されています。

商用コンテキスト

追加の Pro および Enterprise のツールを同じワーカー内に登録するには、nextpdf/premium をイメージにインストールします。別個のプロセスやポートは関与しません。パッケージングの境界は、イメージのビルド時に設定されます。