Operasi produksi

Sekilas pandang

Halaman ini adalah daftar periksa untuk membawa NextPDF ke produksi dan menjaganya tetap di sana. Halaman ini mengurasi manual: setiap item menautkan ke halaman yang membahasnya secara mendalam, sehingga Anda memverifikasi di sini dan membaca di sana. Kerjakan Daftar periksa pra-deploy sebelum rilis pertama. Tinjau kembali Irama peningkatan versi dan Titik masuk triase insiden sebagai bagian dari operasi hari-kedua.

Daftar periksa pra-deploy

• Konfirmasikan runtime: NextPDF memerlukan PHP >=8.4 <9.0. Composer menolak apa pun di luar rentang itu. Lihat Instalasi.
• Verifikasi keenam ekstensi wajib dengan php -m: ext-mbstring, ext-zlib, ext-intl, ext-gd, ext-curl, dan ext-openssl. Halaman instalasi menjelaskan fungsi masing-masing.
• Jalankan vendor/bin/nextpdf doctor untuk pemeriksaan lingkungan sekali jalan (versi PHP, ekstensi, dan ketersediaan font dalam satu laporan).
• Putuskan jalur rendering Anda sebelum menentukan ukuran hardware. Pipeline in-process (writeHtml()) tidak memerlukan layanan tambahan. Artisan, Gotenberg, dan Cloudflare masing-masing menambahkan browser atau layanan jaringan yang harus dioperasikan. Gunakan Pilih jalur Anda untuk memutuskan.
• Jika Anda memilih bridge renderer, baca halaman keamanan-dan-operasinya sebelum go-live. Lihat Perkuat permukaan renderer.
• Bundel font yang Anda render pada waktu build, dan hanya font itu. Lihat Sediakan font di produksi.

Penentuan ukuran sumber daya

Tentukan ukuran untuk dokumen terbesar yang Anda hasilkan, bukan rata-ratanya. getPdfData() membangun seluruh dokumen Portable Document Format (PDF) di memori dan mengembalikannya sebagai satu string.

• Atur memori worker atau function berdasarkan panduan penentuan ukuran serverless: dokumen beberapa halaman berjalan nyaman pada 512–1024 MB; dokumen dengan banyak gambar atau banyak halaman memerlukan lebih banyak.
• Atur timeout di atas waktu build kasus terburuk, dengan margin. Pindahkan job berukuran berlebih ke antrean asinkron yang menulis ke object storage — bagian penentuan ukuran yang sama menunjukkan polanya.
• Aktifkan opcache dengan validasi timestamp dimatikan untuk worker berumur panjang. Bagian opcache pada resep Docker memuat nilai ini produksi.
• Ketika memori atau throughput menyimpang setelah peluncuran, mulailah dari tabel keputusan gejala-ke-pengungkit.

Aturan keamanan worker

Sebuah Document bersifat sekali pakai. Bangun, tulis satu kali, dan biarkan keluar dari scope; buat instance baru per permintaan atau per job antrean. Bagikan hanya registri berumur-proses — FontRegistry dan ImageRegistry — dengan membuatnya satu kali saat worker boot. Ini sesuai dengan model per-permintaan, per-job dari PHP-FPM, worker antrean, dan server aplikasi berumur panjang.

• Resep dengan urutan boot dan reset per-siklus: Rendering batch yang aman untuk worker.
• Kontraknya dalam satu jawaban: Apakah aman untuk worker dan aman untuk thread?

Perkuat permukaan renderer

Perlakukan HTML sebagai tidak tepercaya, terutama apa pun yang dipengaruhi pengguna. Pilih jalur Anda menetapkan batasannya: secara default, pipeline bawaan tidak menjalankan skrip dan tidak mengambil sumber daya jarak jauh, sedangkan setiap bridge merender melalui browser atau layanan jaringan. Sebelum memaparkan bridge ke lalu lintas produksi, kerjakan halaman keamanan-dan-operasinya:

• Keamanan dan operasi Artisan — permukaan renderer Chrome.
• Keamanan dan operasi Gotenberg — permukaan layanan Gotenberg.
• Keamanan dan operasi Cloudflare — permukaan deployment edge.
• Menjalankan mesin sebagai layanan? Tambahkan Keamanan dan operasi Connect.

Observabilitas

NextPDF tidak menerbitkan target service-level objective (SLO); turunkan milik Anda dari metrik durasi-render dan memori yang Anda ukur di bawah ini.

Instrumentasikan jalur render sebelum insiden pertama, bukan sesudahnya.

• Mesin in-process: Amati dengan OpenTelemetry.
• Deployment NextPDF Connect: Resep OpenTelemetry untuk Connect.
• Per render, catat: wall time, memori puncak, jumlah halaman, ukuran output, dan hasilnya beserta kategori eksepsinya dari referensi kesalahan.
• Beri peringatan berdasarkan tren, bukan hanya kegagalan: waktu build yang meningkat, memori puncak yang meningkat, serta jumlah timeout atau kehabisan memori adalah sinyal utama dalam entri memori dan kinerja.

Irama peningkatan versi

• Baca kebijakan dukungan versi sekali, lalu buat setiap rilis mematuhinya. Kebijakan ini mendefinisikan kontrak semantic-versioning, label stabilitas, siklus hidup deprekasi, dan kosakata siklus hidup (active, lts, maintenance, frozen, eol) yang digunakan manual ini.
• Commit composer.lock agar setiap worker yang di-deploy meresolusi versi mesin yang sama — halaman instalasi menyatakan disiplin ini.
• Tinjau changelog sebelum setiap peningkatan versi.

Titik masuk triase insiden

Untuk insiden bridge renderer (Chrome crash, pemadaman Gotenberg, kegagalan rendering di edge), mulailah dari bagian mode-kegagalan bridge tersebut di Perkuat permukaan renderer.

• Mulailah dari gejala, bukan nama kelas, di basis pengetahuan pemecahan masalah.
• Petakan eksepsi yang tertangkap ke kategori dan kontrak konteksnya di referensi kesalahan.

Lihat juga

• Mengoperasikan NextPDF di produksi — esai Insider_ tentang mengapa mesin berperilaku demikian di bawah beban.
• Kontainerisasi aplikasi NextPDF — image Docker produksi, dari awal hingga akhir.
• Deploy di serverless — spesifik untuk Lambda, Cloud Run, dan App Runner.
• Rendering yang aman untuk worker di Connect — aturan masa-hidup yang sama diterapkan pada server.