Konfigurasi NextPDF Connect

Ikhtisar

NextPDF Connect memiliki dua jalur konfigurasi. Server Model Context Protocol (MCP) membaca berkas YAML dan variabel NEXTPDF_MCP_*. Server REST dan gRPC membaca variabel lingkungan NEXTPDF_*. Konfigurasi menjadi tidak dapat diubah setelah server boot.

Pemasangan

composer require nextpdf/server

Gambaran konseptual

Server MCP menentukan konfigurasi dengan urutan prioritas tetap. Sumber dengan prioritas tertinggi akan menang:

Variabel lingkungan (NEXTPDF_MCP_*).
Bagian nextpdf_mcp pada berkas konfigurasi YAML.
Nilai bawaan internal.

Berikan berkas YAML dengan --config=PATH. Jika Anda tidak menyertakannya, server hanya menggunakan nilai bawaan dan variabel lingkungan. McpConfig yang dihasilkan merupakan objek nilai readonly. Tidak ada pengaturan yang dapat berubah setelah boot.

Server REST dan gRPC membaca HttpConfig dari lingkungan saat boot. Keduanya mendukung NEXTPDF_BIND, NEXTPDF_WORKER_COUNT, NEXTPDF_SESSIONS_ENABLED, dan NEXTPDF_CORS_ENABLED sebagai override melalui lingkungan. Batas lainnya menggunakan nilai bawaan yang aman.

Permukaan API

Konfigurasi MCP (`nextpdf-mcp`)

Berkas YAML, bagian 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)

Override melalui lingkungan untuk server MCP:

Variabel	Kunci konfigurasi	Bawaan
`NEXTPDF_MCP_ENABLED_TOOLS`	`enabled_tools`	semua alat diizinkan
`NEXTPDF_MCP_TEMP_DIR`	`temp_directory`	temp sistem + `/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` detik
`NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED`	(mengontrol gate `parse_pdf`)	tidak diatur (dinonaktifkan)
`NEXTPDF_AST_TOOLS_ENABLED`	(mengontrol gate alat AST)	diaktifkan
`NEXTPDF_MUTATION_TOOLS_ENABLED`	(mengontrol gate alat mutasi AST)	tidak diatur (dinonaktifkan)

Konfigurasi REST dan gRPC

Variabel	Bawaan	Efek
`NEXTPDF_BIND`	`0.0.0.0:8080`	Alamat listen REST
`NEXTPDF_WORKER_COUNT`	`4`	Jumlah worker PHP RoadRunner
`NEXTPDF_SESSIONS_ENABLED`	`false`	Aktifkan endpoint sesi stateful
`NEXTPDF_CORS_ENABLED`	`false`	Aktifkan header respons CORS
`NEXTPDF_API_KEYS`	tidak diatur	Definisi kunci API inline
`NEXTPDF_API_KEYS_FILE`	tidak diatur	Jalur ke berkas kunci API
`NEXTPDF_JOB_STORE_PATH`	temp sistem	Jalur penyimpanan pekerjaan SQLite
`NEXTPDF_REDIS_HOST`	tidak diatur	Mengaktifkan penyimpanan berbasis Redis saat disetel

Redis digunakan oleh server REST ketika NEXTPDF_REDIS_HOST disetel dan ext-redis dimuat:

Variabel	Bawaan
`NEXTPDF_REDIS_PORT`	`6379`
`NEXTPDF_REDIS_PASSWORD`	kosong
`NEXTPDF_REDIS_DATABASE`	`0`
`NEXTPDF_REDIS_PREFIX`	`nextpdf:`
`NEXTPDF_REDIS_CONNECT_TIMEOUT`	`2.0` detik
`NEXTPDF_REDIS_READ_TIMEOUT`	`2.0` detik

Contoh kode — Mulai cepat

Jalankan server MCP dengan berkas konfigurasi eksplisit:

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

Contoh kode — Produksi

Batasi katalog MCP ke allowlist eksplisit dan naikkan risiko sebuah alat:

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

Dengan enabled_tools yang tidak kosong, kebijakan keamanan hanya mengizinkan nama alat yang tercantum. Registri akan secara diam-diam mengabaikan setiap alat lainnya. Daftar kosong atau tidak ada akan mengizinkan semua alat yang tersedia.

Kasus khusus dan jebakan

Dua alat kritis tidak dapat diturunkan. output_pdf dan sign_pdf secara bawaan mewajibkan persetujuan: entri risk_level_overrides yang menurunkan salah satu alat di bawah ApprovalRequired akan melemparkan InvalidArgumentException saat pemuatan, dan server menolak untuk boot. Anda dapat menaikkan atau menurunkan tingkat risiko setiap alat lainnya, jadi tinjau setiap penurunan dengan mengacu pada model ancaman Anda sendiri. Lihat /connect/hitl-risk-tiers/.
enabled_tools menyaring, bukan menambahkan. Mencantumkan nama alat Pro saat nextpdf/premium tidak ada tidak akan membuatnya muncul. Allowlist diambil irisannya dengan alat-alat yang benar-benar ditemukan oleh registri.
Variabel lingkungan mengalahkan YAML untuk server MCP. Variabel NEXTPDF_MCP_* menggantikan kunci yang sama dalam berkas YAML. Server REST dan gRPC sama sekali tidak membaca berkas YAML MCP.
parse_pdf bersifat opt-in. Server mendaftarkan alat parse_pdf hanya ketika NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED bernilai true atau 1. Alat ini tidak tersedia secara bawaan, bahkan dalam katalog inti.

Performa

Konfigurasi diurai satu kali saat boot. Pengaturan max_documents dan document_ttl membatasi penyimpanan dokumen dalam memori. Menurunkannya mengurangi penggunaan memori puncak, tetapi memperpendek masa hidup dokumen. Jumlah worker dan batas muatan per tingkat adalah kontrol penyetelan deployment, yang dibahas di /connect/deployment/.

Catatan keamanan

Perlakukan enabled_tools sebagai kontrol tolak secara bawaan untuk deployment dengan hak akses minimal: cantumkan hanya alat yang dibutuhkan oleh integrasi tertentu.
Jangan pernah menyimpan kunci API dalam berkas YAML. Gunakan NEXTPDF_API_KEYS_FILE dengan berkas yang di-mount sebagai secret Docker atau Kubernetes. Server lebih memilih penyimpanan berkas dengan pemuatan ulang langsung, sehingga kunci dapat dirotasi tanpa perlu memulai ulang. Lihat /connect/security-and-operations/.
temp_directory adalah direktori dasar yang diberlakukan untuk keluaran berkas. Server melakukan kanonisasi jalur keluaran dan menolak apa pun yang hasil resolusinya berada di luar direktori tersebut.

Kepatuhan

Halaman ini menjelaskan mekanisme konfigurasi. Sitasi kepatuhan untuk autentikasi dan keamanan transport tercantum di /connect/security-and-operations/.

Konteks komersial

Batas muatan dan tenggang waktu per tingkat (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit, dan tenggang waktu yang sesuai) berlaku untuk transport REST sesuai dengan tingkat kunci API yang terautentikasi. Batas ini hanya berlaku ketika alat Pro atau Enterprise terpasang dan kunci memiliki hak atasnya.

Lihat juga

/connect/install/ — pemasangan dan paket opsional
/connect/boot-and-discovery/ — cara konfigurasi mengalir ke urutan boot
/connect/hitl-risk-tiers/ — model risiko dan override khusus peningkatan
/connect/security-and-operations/ — konfigurasi kunci API dan keamanan transport
/connect/deployment/ — jumlah worker, Redis, dan batas tingkat di produksi