PHP-FPM: Cara Kerja, Setting pm.max_children, dan Mengatasi Error 502 dan 504

Sebagian besar situs PHP di belakang Nginx berjalan dengan PHP-FPM, tapi banyak server masih memakai pool bawaan dengan lima worker. Artikel ini menjelaskan cara kerja PHP-FPM, cara menghitung pm.max_children dari pemakaian memori nyata, cara memberi setiap situs pool dan versi PHP sendiri, serta arti error 502 dan 504 yang sering muncul.

Dipublikasikan 11 menit baca
Rak server dengan lampu status di ruang server

Ketika situs PHP di Nginx tiba-tiba menampilkan 502 Bad Gateway, atau melambat setiap kali ada promo, penyebabnya sering kali bukan kode PHP. Penyebabnya adalah PHP-FPM, process manager yang berada di antara web server dan aplikasi, yang masih berjalan dengan setting bawaan saat diinstall. Di Debian dan Ubuntu, artinya hanya ada satu pool dengan maksimal lima proses worker. Untuk server uji coba itu cukup, tapi untuk toko online yang ramai jauh dari cukup. Artikel ini menjelaskan cara kerja PHP-FPM dan cara mengaturnya untuk beban nyata, berdasarkan hal-hal yang sering kami temukan saat mengambil alih server PHP dari tim lain.

Apa Itu PHP-FPM dan Kenapa Nginx Membutuhkannya

Nginx tidak bisa menjalankan PHP. Ketika ada request untuk file .php, Nginx meneruskannya lewat FastCGI ke service terpisah lalu menunggu jawabannya. PHP-FPM, singkatan dari FastCGI Process Manager, adalah service tersebut. PHP-FPM menjalankan satu master process yang menyiapkan sekelompok proses worker PHP. Setiap worker menangani satu request dalam satu waktu, menjalankan script, mengirim response ke Nginx, lalu menunggu request berikutnya.

Apache bisa bekerja dengan cara lain. Dengan mod_php, PHP dimuat di dalam setiap proses Apache. Cara ini hanya jalan dengan model prefork yang lebih lama, dan membuat request untuk gambar pun ikut membawa memori interpreter PHP. Setup Apache modern memakai model event dengan PHP-FPM lewat proxy_fcgi, pembagian yang sama seperti di Nginx. Apa pun web server-nya, jumlah request PHP yang bisa ditangani server dalam satu waktu sama dengan jumlah worker PHP-FPM, dan angka inilah yang paling penting untuk diatur dengan benar.

Pool, Worker, dan Lokasi File

PHP-FPM disusun dalam pool. Pool adalah kelompok worker yang punya user Linux sendiri, socket sendiri, batasan sendiri, dan setting PHP sendiri. Instalasi baru punya satu pool bernama www. Di Debian dan Ubuntu, filenya berada di folder per versi PHP:

  • /etc/php/8.4/fpm/php-fpm.conf berisi setting global seperti error log dan aturan emergency restart.
  • /etc/php/8.4/fpm/pool.d/ berisi satu file untuk setiap pool. Bawaannya www.conf.
  • /etc/php/8.4/fpm/php.ini adalah php.ini untuk request web. Command line memakai /etc/php/8.4/cli/php.ini yang merupakan file berbeda, itulah sebabnya sebuah setting bisa berlaku di php artisan tapi tidak di website.
  • /run/php/php8.4-fpm.sock adalah socket bawaan yang dihubungi Nginx.
  • Nama service-nya php8.4-fpm, jadi perintahnya systemctl reload php8.4-fpm dan journalctl -u php8.4-fpm.

Di sistem berbasis Red Hat, lokasinya /etc/php-fpm.conf dan /etc/php-fpm.d/, sedangkan di image Docker php resmi file pool ada di /usr/local/etc/php-fpm.d/. Isi setting-nya sama di mana pun.

Static, Dynamic, atau Ondemand

Setting pm menentukan cara pool menyalakan dan mematikan worker. Ketiga mode punya batas atas yang sama, yaitu pm.max_children. Bedanya hanya pada berapa banyak worker yang tetap hidup saat server sedang sepi.

ModeCara kerjaCocok untukKekurangan
staticSelalu menjalankan worker sebanyak pm.max_childrenServer atau container khusus untuk satu aplikasi yang ramaiMemori tetap terpakai meskipun malam hari tidak ada traffic
dynamicMenjaga jumlah worker idle di antara pm.min_spare_servers dan pm.max_spare_servers, lalu menambah worker sampai batasSebagian besar VPS dengan satu aplikasi, dan merupakan bawaan DebianAda empat angka yang harus diatur, dan kombinasi yang salah membuat worker terus dinyalakan dan dimatikan
ondemandMenyalakan worker hanya saat ada request dan mematikannya setelah pm.process_idle_timeoutServer yang meng-host banyak situs kecil, di mana sebagian besar pool lebih sering diamRequest pertama setelah sepi harus menunggu worker baru menyala

Untuk server yang menjalankan satu aplikasi utama, kami biasanya memilih dynamic dengan spare server yang cukup longgar, atau static kalau server memang khusus untuk aplikasi itu dan memorinya tidak berbagi dengan database. Untuk server berisi dua puluh website company profile, ondemand mencegah situs yang sepi menahan memori yang sebenarnya bisa dipakai situs yang ramai.

Cara Menghitung pm.max_children

pm.max_children adalah angka terpenting di PHP-FPM. Kalau terlalu kecil, request mengantre di belakang worker yang sibuk padahal CPU masih menganggur. Kalau terlalu besar, lonjakan traffic menyalakan lebih banyak worker daripada yang muat di memori, server mulai swap, dan semuanya melambat bersamaan, termasuk database. Nilai yang tepat dihitung dari memori, bukan dari angka yang ditemukan di internet.

  1. 1Biarkan aplikasi berjalan dengan traffic normal selama beberapa waktu, supaya worker sudah menangani halaman yang sebenarnya, bukan hanya halaman depan.
  2. 2Ukur rata-rata memori per worker. Di Ubuntu, ps --no-headers -o rss -C php-fpm8.4 menampilkan memori resident setiap proses dalam kilobyte. Abaikan master process, hitung rata-rata sisanya, dan catat juga nilai terbesarnya. Worker Laravel atau WordPress biasanya memakai sekitar 40 sampai 100 MB, tapi yang menentukan adalah angka dari aplikasi Anda sendiri.
  3. 3Hitung memori yang tersedia untuk PHP. Mulai dari total RAM, kurangi kebutuhan sistem operasi, database kalau berjalan di server yang sama, Redis, dan layanan lain, lalu sisakan margin aman 10 sampai 20 persen.
  4. 4Bagi memori tersebut dengan rata-rata ukuran worker lalu bulatkan ke bawah. Contohnya VPS 8 GB dengan MySQL memakai 2,5 GB, sistem dan Redis sekitar 1 GB, dan margin 1 GB, sehingga tersisa 3,5 GB. Dengan 70 MB per worker hasilnya 50, jadi pm.max_children = 50.
  5. 5Untuk mode dynamic, mulai dengan pm.start_servers dan pm.min_spare_servers sekitar seperempat dari batas, dan pm.max_spare_servers sekitar setengahnya, lalu sesuaikan berdasarkan status page yang dijelaskan di bawah.

Jangan menghitung dengan memory_limit dari php.ini. memory_limit adalah batas maksimal yang boleh dipakai satu request sebelum PHP menghentikannya, misalnya 256 MB, bukan pemakaian normal sebuah worker. Membagi RAM dengan memory_limit menghasilkan angka yang terlalu kecil. memory_limit adalah plafon untuk melindungi server dari satu request yang lepas kendali, sedangkan rata-rata pemakaianlah yang menentukan berapa worker yang muat.

Jumlah core CPU tidak sepenting yang sering dikira. Sebagian besar request web menghabiskan banyak waktu menunggu database atau API eksternal, dan worker yang sedang menunggu tidak memakai CPU. Karena itu 50 worker di server 4 core adalah hal yang wajar untuk aplikasi web biasa. Pengecualiannya adalah pekerjaan berat di CPU seperti membuat PDF atau resize gambar di dalam request. Di kasus itu, worker yang lebih banyak dari jumlah core hanya menambah antrean, dan pekerjaan semacam itu memang sebaiknya dipindah ke queue.

Setting Lain yang Perlu Diubah

SettingBawaan Debian dan UbuntuYang biasa kami pakai
pm.max_children5Dihitung dari memori seperti di atas
pm.max_requests0, worker tidak pernah diganti500 sampai 1000, untuk membatasi memory leak pelan dari extension atau kode
request_terminate_timeout0, tanpa batasSedikit di atas request terlama yang masih wajar, misalnya 60s
request_slowlog_timeout dan slowlogMati5s dengan file log per pool, untuk mendapat stack trace request yang lambat
pm.status_path dan ping.pathTidak aktif/fpm-status dan /fpm-ping, hanya bisa diakses dari localhost atau monitoring
catch_workers_outputnoyes, supaya error yang ditulis ke stderr masuk ke log FPM

request_terminate_timeout perlu penjelasan khusus. Banyak orang mengira max_execution_time di php.ini akan menghentikan request yang lambat, padahal di Linux setting itu hanya menghitung waktu saat kode PHP berjalan. Waktu menunggu query database, panggilan HTTP, atau baca file tidak dihitung, sehingga request yang tertahan di API lambat bisa menahan satu worker selama beberapa menit. request_terminate_timeout dihitung berdasarkan waktu nyata, dan setting inilah yang benar-benar membebaskan worker.

Slow log adalah salah satu fitur PHP-FPM yang paling berguna sekaligus paling jarang dipakai. Dengan request_slowlog_timeout = 5s, setiap request yang berjalan lebih dari lima detik akan menulis backtrace ke slow log, lengkap dengan fungsi yang sedang dijalankan saat itu. Ketika situs lambat dan tidak ada yang tahu sebabnya, slow log selama beberapa jam biasanya langsung menunjuk query atau panggilan API yang bermasalah.

Satu Pool untuk Setiap Situs

Banyak server menjalankan semua situs di pool www bawaan dengan user www-data. Cara ini berjalan sampai salah satu situs kebanjiran traffic dan memakai semua worker, sehingga situs lain di server yang sama ikut menampilkan 502. Ini juga masalah keamanan: kalau satu situs WordPress dibobol, penyerang menjalankan kode sebagai www-data dan bisa membaca file konfigurasi situs lain, termasuk password database-nya.

Memberi setiap situs pool sendiri menyelesaikan kedua masalah itu. Buat user Linux untuk setiap situs, salin www.conf ke file baru seperti shop.conf, lalu ubah baris-baris berikut:

  • [shop] di baris paling atas, yaitu nama pool yang muncul di log dan status page.
  • user = shop dan group = shop, supaya PHP berjalan sebagai user milik situs itu dan hanya bisa membaca file situs tersebut.
  • listen = /run/php/php8.4-fpm-shop.sock, socket terpisah untuk setiap pool.
  • listen.owner = www-data dan listen.group = www-data, supaya Nginx tetap bisa terhubung ke socket.
  • pm.max_children dan nilai pm lainnya yang dihitung khusus untuk situs ini.
  • php_admin_value[open_basedir] = /var/www/shop:/tmp dan php_admin_value[memory_limit] = 256M untuk batasan yang tidak bisa diubah aplikasi saat berjalan.

Setelah itu arahkan server block Nginx untuk situs tersebut ke socket baru dengan fastcgi_pass unix:/run/php/php8.4-fpm-shop.sock, uji konfigurasi dengan php-fpm8.4 -t dan nginx -t, lalu reload kedua service. Ingat bahwa total pm.max_children dari semua pool di satu server tetap harus muat di memori. Kalau pool-nya banyak, mode ondemand sangat membantu.

Beberapa Versi PHP di Satu Server

PHP tidak punya satu tool seperti nvm untuk Node.js, dan di server memang tidak membutuhkannya. PHP-FPM sudah memisahkan versi dengan rapi. Di Ubuntu, PPA milik Ondřej Surý, dan repository packages.sury.org untuk Debian, menyediakan semua versi PHP yang masih didukung secara berdampingan. Install php8.2-fpm, php8.4-fpm, dan php8.5-fpm, maka masing-masing berjalan sebagai service sendiri dengan folder sendiri di /etc/php dan socket sendiri. Situs lama tetap di 8.2 dengan mengarahkan server block Nginx-nya ke socket 8.2, sedangkan situs baru memakai 8.5.

  • Extension terpisah per versi. Install php8.4-mysql tidak berpengaruh ke 8.2, jadi pasang php8.2-mysql, php8.2-mbstring, php8.2-xml, dan lainnya untuk setiap versi yang dipakai situs.
  • Perintah php di command line adalah pilihan tersendiri. update-alternatives --set php /usr/bin/php8.4 mengubah php default, yang berpengaruh ke cron job, perintah artisan, dan Composer. Untuk situs dengan versi berbeda, panggil binary-nya langsung, misalnya php8.2 artisan schedule:run.
  • Rencanakan akhir masa dukungan setiap versi. PHP 8.2 menerima update keamanan terakhir pada 31 Desember 2026, dan PHP 8.3 setahun setelahnya. Server yang masih punya pool 8.2 setelah tanggal itu menjalankan PHP tanpa patch untuk situs tersebut.
  • Cek versi yang benar-benar dipakai website, bukan hanya php -v. Cara sederhananya buat file sementara di folder situs yang menampilkan PHP_VERSION lalu langsung hapus, atau cek socket yang dipakai server block Nginx. Setelah update keamanan seperti perbaikan PHP2Shell bulan Oktober, semua service php-fpm harus di-restart, bukan hanya versi default.

Error yang Sering Muncul dan Artinya

Yang terlihatPenyebab umumYang perlu dicek atau diubah
502 Bad Gateway dengan connect() to unix:/run/php/... failed (2: No such file or directory) di log NginxPHP-FPM tidak berjalan, atau Nginx mengarah ke socket versi PHP yang tidak terpasangsystemctl status php8.4-fpm, lalu pastikan path socket di fastcgi_pass sama dengan pool
502 dengan (13: Permission denied)Nginx tidak diizinkan membuka socketAtur listen.owner dan listen.group di pool sesuai user yang menjalankan Nginx
server reached pm.max_children setting di log FPM, halaman menggantung atau 502Semua worker sibuk dan request mengantreNaikkan pm.max_children kalau memori cukup, kalau tidak cari request yang lambat lewat slow log
504 Gateway Timeout tepat setelah 60 detikRequest lebih lama dari batas tunggu Nginx yang diatur fastcgi_read_timeoutPerbaiki request yang lambat atau pindahkan ke queue. Menaikkan timeout hanya menyembunyikan masalah
Primary script unknown, atau halaman kosong bertuliskan File not foundSCRIPT_FILENAME mengarah ke path yang tidak bisa dilihat pool, atau diblokir open_basedirCek root dan fastcgi_param SCRIPT_FILENAME di Nginx serta user dan open_basedir di pool
Worker dimatikan kernel dan ada pesan Out of memory di dmesgpm.max_children lebih besar dari kemampuan serverHitung ulang dari memori worker yang sebenarnya lalu turunkan batasnya

Pantau Status Page

Dengan pm.status_path aktif dan hanya diizinkan dari localhost di Nginx, curl http://localhost/fpm-status menampilkan kondisi pool saat itu. Ada tiga angka yang paling penting. active processes menunjukkan berapa worker yang sedang sibuk. max children reached menghitung berapa kali pool menyentuh batasnya sejak dinyalakan, dan idealnya tetap nol atau sangat jarang naik. listen queue menunjukkan request yang menunggu worker kosong, dan angka di atas nol yang bertahan lebih dari sesaat berarti pengguna sedang menunggu. Uptime Kuma, Zabbix, Netdata, dan exporter php-fpm untuk Prometheus bisa membaca halaman ini dan mengirim alert.

Dasar Keamanan

  • Pakai Unix socket, atau 127.0.0.1 kalau memang harus TCP. Port PHP-FPM seperti 9000 yang terbuka ke internet membuat siapa pun bisa mengirim request FastCGI langsung, dan dengan parameter tertentu bisa menjalankan kode PHP di server.
  • Cegah Nginx meneruskan file yang tidak ada ke PHP. Di Debian dan Ubuntu, gunakan include snippets/fastcgi-php.conf yang sudah menangani hal ini, atau tambahkan try_files $uri =404 di location PHP. Tanpa itu, di beberapa setup, file upload seperti avatar.jpg/x.php bisa dijalankan sebagai PHP.
  • Biarkan security.limit_extensions berisi .php saja, supaya FPM menolak menjalankan jenis file lain.
  • Jangan pernah membuka status page ke publik. Halaman itu menampilkan URL request, alamat client, dan seberapa sibuk server.
  • Jalankan setiap situs di pool dan user sendiri seperti dijelaskan di atas, supaya satu situs yang dibobol tidak bisa membaca file situs lain.

PHP-FPM di Docker dan Alternatifnya

Image resmi php:8.4-fpm menjalankan PHP-FPM yang mendengarkan port 9000 di dalam container, biasanya dipasangkan dengan container Nginx terpisah yang terhubung lewat jaringan internal Docker. Semua yang dibahas di atas tetap berlaku. File pool ada di /usr/local/etc/php-fpm.d/www.conf, dan pm.max_children dihitung dari batas memori container, bukan memori seluruh host. Container dengan batas 1 GB dan lima worker bawaan jarang kehabisan memori, tapi juga jarang melayani lebih dari lima request sekaligus.

PHP-FPM sekarang bukan satu-satunya cara menjalankan PHP. FrankenPHP, yang kini dikelola di bawah The PHP Foundation, serta Laravel Octane dengan Swoole atau RoadRunner menyimpan aplikasi di memori di antara request, sehingga aplikasi berbasis framework bisa terasa jauh lebih cepat. Tapi aturan mainnya juga berubah, karena state yang tertinggal di memori dari satu request bisa terbawa ke request berikutnya. Untuk sebagian besar aplikasi PHP, PHP-FPM yang diatur dengan benar masih pilihan paling sederhana, dan tempat yang tepat untuk memulai sebelum melirik yang lain.

Checklist Singkat

  1. 1Cek pool apa saja yang berjalan di server dan versi PHP yang dipakai setiap situs. Rencanakan pindah dari PHP 8.2 sebelum akhir 2026, dan perhatikan bahwa PHP 8.6 dijadwalkan rilis 19 November 2026.
  2. 2Ukur memori worker yang sebenarnya dan atur pm.max_children berdasarkan angka itu, dengan menyisakan ruang untuk database dan margin.
  3. 3Atur pm.max_requests, request_terminate_timeout, dan slow log di setiap pool.
  4. 4Beri setiap situs pool, user, dan socket sendiri.
  5. 5Aktifkan status page khusus untuk localhost dan hubungkan ke monitoring.
  6. 6Setiap ada rilis keamanan PHP, restart semua service php-fpm di server lalu pastikan versi yang dilaporkan setiap situs.

Sebagian besar perubahan ini bisa selesai dalam satu sore tanpa biaya tambahan, tapi sering kali menjadi pembeda antara server yang tumbang saat kampanye dan server yang menanganinya dengan tenang. Kalau server PHP atau Laravel Anda sering menampilkan 502 saat ramai, atau Anda ingin ada yang meninjau setup-nya, tim managed service kami bisa membantu, dan training Laravel kami membahas deployment dan PHP-FPM untuk tim yang ingin mengelolanya sendiri.

Poin penting

  • PHP-FPM menjalankan worker PHP di belakang Nginx, dan jumlah worker sama dengan jumlah request PHP yang bisa ditangani server dalam satu waktu.
  • Bawaan Debian dan Ubuntu sebanyak lima worker terlalu kecil untuk kebanyakan situs production.
  • Hitung pm.max_children dari rata-rata memori per worker dan sisa RAM setelah database, bukan dari memory_limit.
  • Atur pm.max_requests, request_terminate_timeout, dan slow log. Di Linux, max_execution_time tidak menghitung waktu menunggu I/O.
  • Beri setiap situs pool, user, dan socket sendiri, dan gunakan service php8.x-fpm terpisah untuk menjalankan beberapa versi PHP berdampingan.
  • Pakai Unix socket atau localhost untuk PHP-FPM, jangan buka status page ke publik, dan restart semua service FPM setelah update keamanan PHP.
Bagikan artikel ini

Artikel terkait

Artikel lain tentang software development, AI, cloud, dan infrastruktur.

Kode JavaScript berwarna di layar gelapPengembangan Backend

10 menit baca

Cara Pakai nvm untuk Node.js: Install, .nvmrc, dan Kenapa Kurang Cocok di Server

nvm memudahkan kita menyimpan Node.js 22, 24, dan 26 di satu laptop lalu berpindah versi sesuai proyek. Panduan ini membahas cara install, perintah sehari-hari, .nvmrc, perubahan di nvm 0.41.0, masalah yang sering muncul, dan alasan server production sebaiknya memakai cara lain.

Permukaan logam usang dengan bercak karat oranye dan goresan halusPengembangan Backend

10 menit baca

Rust untuk Software Bisnis: Kapan Sepadan dan Kapan Go atau Node.js Sudah Cukup

Rust kini ada di kernel Linux, Android, dan inti jaringan Cloudflare. Bukan berarti semua aplikasi bisnis harus ditulis dengan Rust. Apa yang sebenarnya ditawarkan Rust, benchmark melawan Go dan Node.js pada 2 juta baris data, kapan kurva belajarnya sepadan, dan cara mengadopsinya tanpa menulis ulang semuanya.

Mari berdiskusi

Sedang mencari partner untuk pengembangan software?

Ceritakan proyek yang sedang Anda bangun, kebutuhan yang ingin diselesaikan, dan tantangan yang dihadapi. Kami dapat membantu membahas pendekatan teknis, scope, timeline, dan estimasi biaya.

Mulai diskusi