為什麼常駐程序需要一個管理者

FastCGI 要求應用程式程序常駐，於是出現幾個 CGI 下不存在的問題，因為 CGI 的程序活一個請求就結束、沒有機會累積：

• 開幾個程序：太少，並發的請求要排隊；太多，記憶體吃光。
• 一個程序掛了誰補：常駐的程序可能因為程式錯誤或記憶體不足而死掉，要有人把它補回來。
• 記憶體隨時間漲：worker 活得久，C 擴充的記憶體洩漏會一點一點累積。
• 某個請求卡住：一個跑不完的請求會一直佔著一個 worker，佔住的 worker 越多，能處理新請求的就越少。

PHP-FPM 就是處理這幾件事的常駐服務（見 PHP-FPM）。它的 PHP 版本記在官方 ChangeLog 裡：PHP 5.3.3（2010 年 7 月）的 ChangeLog 記著「Added FastCGI Process Manager (FPM) SAPI」，FPM 從這個版本起隨 PHP 本體發行。PHP-FPM 的架構是一個主程序（master）加一群 worker：master 不處理請求，只負責讀設定、開 worker、補死掉的 worker、轉送管理訊號；worker 才是實際執行 PHP 的程序。

PHP 官方文件對它有一句明確的安全要求：php-fpm must not be reachable from an untrusted network——FastCGI 的埠（預設 9000）不能對不受信任的網路開放。FastCGI 協定本身沒有驗證，誰連得上這個埠，誰就能指定 SCRIPT_FILENAME 要 PHP 執行哪個檔案（見 FastCGI 的安全邊界）。所以它只聽 127.0.0.1 或 Unix socket，或用 listen.allowed_clients 限制來源。

pool：一組 worker 與它的執行身分

PHP-FPM 把 worker 分成一個或多個 pool，每個 pool 是一組設定相同的 worker，可以指定自己的執行帳號（user / group）、監聽位址（listen）、以及 PHP 設定。這一個機制解掉了 mod_php 最大的限制：

mod_php 的所有站台都以 Apache 的帳號執行，彼此的檔案互相看得到。PHP-FPM 讓每個站台一個 pool、各自指定執行帳號：

1[site_a]
2user = site_a
3group = site_a
4listen = /run/php/site_a.sock
5
6[site_b]
7user = site_b
8group = site_b
9listen = /run/php/site_b.sock

listen 可以是 Unix socket 的路徑（如上）或 IP:埠。web 伺服器與 PHP-FPM 在同一台機器、同一個檔案系統時可以用 Unix socket，少走一層 TCP；分在不同容器或不同機器時要用 TCP，這也是容器環境預設 listen = 9000 的原因。

site_a 的 PHP 以 site_a 的帳號執行，讀不到 site_b 的檔案，產生的檔案也屬於 site_a。這把 CGI 加 suEXEC 才有的隔離，做在了常駐程序上——既有隔離，又沒有每個請求啟動程序的成本。這是共享主機從 CGI 換到 PHP-FPM 的主因。

pm：開 worker 的三種策略

pm 決定 PHP-FPM 怎麼決定開幾個 worker，有三個值：

三者的上限都是 pm.max_children，差別只在平常保持幾個 worker 活著。dynamic 是預設，它的「動態」是 PHP-FPM 在常駐的 worker 群裡依閒置數量增減，不是每個請求開關程序，所以跟 CGI 的每請求一程序是兩回事。

容器裡的取捨跟整台伺服器不同。一個容器通常只跑一個 pool，而且 max_children 已經依容器的記憶體上限配好；這時 dynamic 省下的閒置記憶體別的程式也用不到，static 反而省掉流量上升時臨時開 worker 的延遲。

max_children：並發上限與排隊

pm.max_children 是這個 pool 最多能同時存在的 worker 數量，也就是這個 pool 最多能同時處理幾個請求。一個 worker 一次只處理一個請求，所以超過這個數量的請求要排隊等。每個 worker 各自連資料庫，所以實例數 × pm.max_children 也是資料庫連線數的上限，要算進資料庫的 max_connections（各語言的連線模型對照見 1.17 應用程式存取資料庫的工具分層）。

這一點可以直接量。設 pm = static、pm.max_children = 2，然後同時送 6 個各需要 1 秒的請求：

1各請求完成的秒數：[1.06, 1.06, 2.07, 2.07, 3.08, 3.09]  總時間 3.1 秒

兩個 worker 同時處理兩個請求（約 1 秒完成），剩下的排隊：第三、四個等前兩個做完（約 2 秒），第五、六個再等一輪（約 3 秒）。這就是 max_children 太小時的樣子：請求都成功了，延遲隨排隊長度線性增加。

max_children 要設多大，由兩件事夾出來：

• 上界是記憶體：每個 worker 都佔記憶體（框架越大佔越多）。max_children 乘上單一 worker 的記憶體，不能超過機器分給 PHP 的量，否則系統開始用 swap 或直接把程序殺掉。單一 worker 的記憶體要用最重的那一類請求的峰值估，不能用平均值：下面〈max_requests〉一節量到，worker 處理完一個重請求之後，記憶體會保留一段時間才降回來，而尖峰時可能每個 worker 剛好都處理過重請求。
• 下界是並發需求：太小就像上面那樣排隊。需要多少並發，看請求把時間花在哪裡：大部分時間在等資料庫或外部 API 的請求，worker 等待時不佔 CPU，數量可以遠多於 CPU 核心數；大部分時間在計算的請求，worker 數超過核心數之後只增加切換成本，處理量不會再上升。

這是 PHP-FPM 最常調、也最該記進壓測結果的一個值。壓測時換了機器、換了框架、改了這個值，數字就不能跟之前比。

max_requests：定期換掉 worker 以控制記憶體

pm.max_requests 讓一個 worker 處理滿指定數量的請求之後，自己結束，由 master 開一個新的 worker 補上。設 pm.max_requests = 3，對計數腳本連續請求，可以看到 PID 換掉：

1pid=7 static=1 ...
2pid=7 static=1 ...
3pid=7 static=1 ...
4pid=8 static=1 ...     # PID 7 處理滿 3 個請求後，換成 PID 8

它防的是哪一種記憶體成長，要先把 worker 的記憶體分成兩類，因為兩類跨請求的行為不同。

PHP 程式碼用的記憶體不會隨處理過的請求數增長，但會暫時停在高點。 PHP 程式碼建立的變數、陣列與物件，由 PHP 自己的記憶體管理器（Zend Memory Manager）配置，請求結束時全部釋放——這是 shared-nothing 的一部分。不過「釋放」是釋放給記憶體管理器，不等於立刻還給作業系統，所以從作業系統看到的 RSS 不會馬上降。用一個只開一個 worker 的 pool，讓每個請求都落在同一個程序上，量它的 RSS（作業系統看到的實體記憶體佔用）：

1初始                                  rss=10MB
2一個建立 50 萬筆小陣列的請求（PHP 峰值 210MB）
3之後的小請求，依序：                  rss=112MB → 62MB → 36MB → 24MB → 18MB → 14MB → 14MB

請求早就結束了，RSS 卻停在 112MB，再隨後面的請求逐步降回約 14MB。原因在記憶體管理器的實作：它以 2MB 的 chunk 為單位向作業系統要記憶體，請求結束時不把 chunk 全部還回去，而是留下一部分給下一個請求用，省掉反覆向作業系統申請與歸還的成本。留下多少由一個移動平均決定，每個請求結束時更新成「上一次的平均與這次請求的峰值兩者的平均」，保留的 chunk 數跟著這個平均走。代入上面的量測：重請求之前平均接近 0，重請求的峰值約 210MB，這個請求結束時平均變成兩者的一半、約 105MB，所以保留了約 102MB；之後每個輕請求的峰值只有約 2MB，平均每次再減半。PHP 回報的記憶體依序是 102、52、26、14、8、4、2 MB，就是這個減半。這個調整只在請求結束時發生：worker 閒著沒有請求時，RSS 停在原來的值，不會隨時間自己降下來。單一一次配置超過約 2MB 的大區塊不走 chunk，請求結束時直接還給作業系統：一個配置 200MB 字串的請求結束後，RSS 立刻回到 12MB。

所以 worker 的 RSS 反映的是最近處理過的請求的峰值，不是它累計處理過幾個請求。重複「每 5 個輕請求夾 1 個重請求」六輪，每輪結束時的 RSS 都停在 14MB，沒有一輪比一輪高。

真正會跨請求累積的，是 PHP 記憶體管理器以外的記憶體。 C 寫的擴充與它們依賴的函式庫，有一部分記憶體直接向作業系統的配置器要，不經過 Zend Memory Manager，也不在請求結束時被清掉。這一類有洩漏時，worker 的 RSS 會隨處理過的請求數一路往上，不會降回來。max_requests 防的是這一類：與其逐一追查是哪個擴充在漏，讓 worker 處理一定數量的請求後整個換掉，舊程序累積的記憶體隨它結束一起還給作業系統。代價是新 worker 的 OPcache 命中要重新累積（見 OPcache 與程序壽命），所以這個值不設太小。

這兩類的分別給出一個判讀方法：在穩定的負載下，觀察 worker 的 RSS 在輕請求之後回落到的底部。底部固定，代表成長來自重請求的暫時保留，max_requests 不必設；底部隨時間一路往上，代表有 PHP 記憶體管理器以外的洩漏，這才是 max_requests 要處理的情形。

request_terminate_timeout 與 slowlog：跑太久的請求

一個卡住的請求會一直佔著一個 worker。佔住的 worker 越多，max_children 裡能處理新請求的名額就越少，到最後整個 pool 都卡在慢請求上，新請求全部排隊。PHP-FPM 有兩個設定處理這件事。

request_terminate_timeout 是強制上限：一個請求跑超過這個時間，PHP-FPM 直接終止處理它的 worker。設 request_terminate_timeout = 3s，對一個會跑 5 秒的請求：

1$ curl -o /dev/null -w "%{http_code} after %{time_total}s" localhost/sleep.php?s=5
2502 after 3.24s

PHP-FPM 的 log 記下整個過程：

1WARNING: child 11, script 'sleep.php' execution timed out (3.2 sec), terminating
2WARNING: child 11 exited on signal 15 (SIGTERM) ...

而 Nginx 這一側，因為 worker 被終止、連線斷掉，記下：

1[error] recv() failed (104: Connection reset by peer) while reading
2  response header from upstream

這解釋了一個常見的現象：前端收到 502 Bad Gateway，但 Nginx 的 log 寫的是「連線被 upstream 重設」——因為 PHP-FPM 為了保護 worker 名額，主動把那個卡住的 worker 殺掉了。5xx 還有另一個常見成因跟逾時無關：worker 全忙時新請求在佇列裡排隊，延遲一路上升，排得夠久會撞到 Nginx 自己的逾時。兩者在 status 頁分得開，後者的 max listen queue 會大於 0（見下面的〈status 頁〉一節）。request_terminate_timeout 跟 PHP 自己的 max_execution_time 量的不是同一種時間。PHP 官方文件寫明，max_execution_time 只計算腳本本身執行的時間，花在腳本以外的活動——系統呼叫、串流操作、資料庫查詢——不算進去（Windows 例外，那裡量的是實際經過的時間）。所以一個卡在等資料庫回應的請求，max_execution_time 可能永遠不會觸發。request_terminate_timeout 由 PHP-FPM 從外部計算實際經過的時間，卡在哪裡都會終止。

request_slowlog_timeout 不終止請求，只在請求超過指定時間時把它當下的 PHP 呼叫堆疊記進 slowlog。設 request_slowlog_timeout = 1s，一個在 loadReport() 裡 sleep 的請求會留下：

1[pool www] pid 6
2script_filename = /var/www/html/slow.php
3[0x...] usleep() /var/www/html/slow.php:2
4[0x...] loadReport() /var/www/html/slow.php:3
5[0x...] handle() /var/www/html/slow.php:4

堆疊直接指出慢在哪一行、哪一層呼叫。這是找出慢請求根源最直接的工具，不必改程式加計時。

一個部署上的細節：PHP-FPM 取 worker 的堆疊是靠 ptrace 這個系統呼叫，在 Docker 預設的權限下會失敗（failed to ptrace(ATTACH) ... Operation not permitted），slowlog 因此是空的。容器裡要用 slowlog 得在啟動時加 --cap-add SYS_PTRACE。

status 頁：看這個 pool 現在的狀態

pm.status_path 開一個狀態頁，列出 pool 當下的 worker 數量、排隊與累計計數。前面那個 max_children = 2 的排隊測試跑完後，狀態頁是：

 1pool:                 www
 2process manager:      static
 3accepted conn:        15
 4listen queue:         0
 5max listen queue:     4
 6idle processes:       1
 7active processes:     1
 8total processes:      2
 9max active processes: 2
10max children reached: 0
11slow requests:        0

幾個欄位直接對應前面的設定：

• max listen queue：等待空閒 worker 的請求，最多排到過幾個。上面是 4，正好是那次 6 個並發裡、扣掉 2 個正在處理的其餘 4 個。這個數字長期大於 0，代表 max_children 在尖峰時不夠用，請求要排隊等空閒的 worker。
• max children reached：PHP-FPM 想多開 worker、卻撞到 max_children 上限的次數。這個計數只在 dynamic 與 ondemand 下會動，因為只有這兩種模式會「想多開」：上面那次是 static，請求排了 4 個而它仍然是 0；同樣 6 個並發換成 pm = dynamic（max_children = 2）時，它變成 1、max listen queue 是 5。所以 static 模式要看 max listen queue，不能看這一欄。
• slow requests：超過 request_slowlog_timeout 的請求累計數。

所以判斷 max_children 夠不夠，要先看 pool 用的是哪一種 pm：static 只能看 max listen queue（max children reached 在 static 下永遠是 0），dynamic 與 ondemand 兩欄都能看。max listen queue 長期大於 0 就該往上調，前提是記憶體容得下；長期是 0 代表還有餘裕。

停機與重載的訊號

PHP-FPM 的 master 依收到的訊號決定怎麼停或怎麼換掉 worker，PHP 原始碼附的 man page 列出四個：

「graceful」要等正在處理的請求多久，由另一個設定 process_control_timeout 決定：master 送出停止訊號之後，最多等 worker 這麼久。它的預設值是 0，也就是不等。一個請求要跑 3 秒，在它跑到第 1 秒時對 master 送 SIGUSR2：

1process_control_timeout = 0（預設）  →  502，在 1.07 秒時中斷
2process_control_timeout = 10         →  200，跑滿 3.0 秒才回應

SIGQUIT 一樣：預設值下 docker stop 一送出 PHP-FPM 就結束，進行中的請求拿到 502；設成 10 之後，docker stop 花了 2 秒，等那個請求做完。所以要讓 reload 與停機不中斷請求，process_control_timeout 要設成比最長的正常請求還長的秒數（它寫在設定檔的 [global] 段），而容器平台的停機逾時（docker stop -t、Kubernetes 的 terminationGracePeriodSeconds）要比它更長，否則平台會先強制終止。

設好之後，reload 只換 PHP 不動 Nginx。這跟 mod_php 的「改 PHP 設定要重載 Apache」是不同的隔離層級：PHP-FPM 是獨立的服務，重載 PHP 時 Nginx 的程序與它和客戶端之間的連線都不受影響。這也是 PHP 官方建議「用 PHP-FPM 取代 mod_php」的理由之一——PHP 能獨立於 web 伺服器重啟。

PHP-FPM 管的事情總覽

回到開頭那幾個「常駐程序帶出的問題」，PHP-FPM 的每一個旋鈕各對應一個：

這些旋鈕都是因為 worker 常駐才需要。worker 常駐同時讓一件事變得有意義：OPcache。程序活得夠久，編譯好的 opcode 才有機會被下一個請求重用，重用的程度在 OPcache 與程序壽命 實測。

如果連應用程式的狀態也想跨請求保留（框架只啟動一次），就要再往前走一步到常駐 worker 模型，那是另一組取捨，見 常駐 worker 模型。而把 Nginx 跟 PHP-FPM 放進容器時，兩個程序怎麼擺、要不要拆成兩個容器，見 容器裡的 Nginx 與 PHP-FPM。

概念位置

PHP-FPM 把直譯器放在 web 伺服器外面的常駐程序裡：程序活過很多請求，應用程式狀態仍然只活一個請求（shared-nothing）。它只講 FastCGI，所以前面一定要有一個講 HTTP 的 web 伺服器（nginx 或 Apache 的 mod_proxy_fcgi）。PHP 5.3.3 起隨 PHP 本體發行。

可觀察訊號與例子

• pm.max_children 決定並發上限：一個 worker 一次處理一個請求，超過上限的請求排隊，status 頁的 max listen queue 會大於 0。
• 502 加上「Connection reset by peer」：worker 被 request_terminate_timeout 終止、或 reload／停機時沒有等進行中的請求（process_control_timeout 預設 0）。
• 預設監聽 9000：FastCGI 沒有驗證，PHP 官方文件要求 php-fpm 不能讓不受信任的網路連到。
• pool：每個 pool 可以指定執行帳號，讓不同站台的 PHP 互相讀不到檔案。

設計責任

部署 PHP-FPM 要決定 max_children（以最重請求的記憶體峰值估）、max_requests、request_terminate_timeout 與 process_control_timeout，並把 FastCGI 埠限制在信任的網路內。各設定的實測見 PHP-FPM。

OPcache 快取的是編譯結果

PHP 每次執行一個 .php 檔，都要先把原始碼編譯成 opcode——Zend 引擎實際執行的指令——再執行它（見 OPcache）。沒有快取時，每個請求的每個檔案都要重新讀檔、解析、編譯。

OPcache 把編譯好的 opcode 存進一塊共享記憶體，下一次要執行同一個檔案時，直接從共享記憶體拿編譯結果，跳過讀檔與編譯。它快取的是程式碼，不是資料：變數的值、查詢結果、請求之間的狀態都不在裡面，shared-nothing 不受影響。PHP 5.5 起 OPcache 隨 PHP 一起發行；PHP 8.5 依〈Make OPcache required〉這份 RFC 把它靜態編進 PHP 本體，不必也不能再另外安裝，開關仍然由 opcache.enable 控制。

框架讓這件事的份量變得很大。Laravel 13 處理一個最簡單的健康檢查請求，get_included_files() 回報這個請求載入了 484 個檔案——設定、服務提供者、路由、中介層、框架本身的類別。這 484 個檔案每個請求都要用到，所以有沒有快取它們的編譯結果，差距是每個請求都要重付一次的成本。

在同一個 Laravel 容器（Nginx 加 PHP-FPM）上循序請求 /healthz，只切換 OPcache 的開關：

相差十幾倍，而請求做的事情完全一樣。差出來的時間幾乎都花在編譯那 484 個檔案上。

快取效果與程序壽命的關係

OPcache 的共享記憶體在 PHP 啟動時建立，屬於那個程序（以及它 fork 出來的子程序）。程序結束，那塊記憶體就跟著釋放，快取也就消失。所以同一個 OPcache，在不同的執行模型下效果完全不同。

CGI：命中次數永遠是零。 CGI 每個請求啟動一個新程序。每個程序都建立自己的 OPcache、把這次用到的檔案編譯進去，然後隨請求結束一起消失。在 CGI 下印出 OPcache 的統計，cached_scripts 每次都是 1（這次編譯進去了），hits 每次都是 0（從來沒有被重用過）。OPcache 是開著的，只是沒有作用。

PHP-FPM：worker 共用同一份快取。 PHP-FPM 的 master 在啟動時建立 OPcache 的共享記憶體，再 fork 出 worker，worker 繼承了這塊記憶體。所以一個 pool 裡所有 worker 讀寫的是同一份快取。對兩個 worker 輪流處理的請求印出統計：

1pid=6 opcache_enabled=true cached_scripts=1 hits=0
2pid=7 opcache_enabled=true cached_scripts=1 hits=1
3pid=6 opcache_enabled=true cached_scripts=1 hits=2
4pid=7 opcache_enabled=true cached_scripts=1 hits=3

PID 6 第一次執行時把腳本編譯進快取，PID 7 接下來直接命中——它自己沒有編譯過這個檔案，用的是 PID 6 編譯好的結果。命中次數跨 worker 累加。這帶出兩個推論：

• worker 被換掉不會清空快取。 pm.max_requests 換掉的是 worker，快取住在 master 建立的共享記憶體裡，新 worker 一啟動就能用。要清空快取得重啟或 reload 整個 PHP-FPM。
• 同一台機器上的不同 pool 共用同一個 master 時，也共用這塊記憶體。 所以 memory_consumption 要容得下所有 pool 的程式碼。

mod_php 的情況相同：Apache 的父程序載入 PHP 時建立共享記憶體，子程序繼承它。在 php:8.5-apache 上連續請求五次，五個不同的子程序（PID 16 到 20）回報的命中次數依序是 0、1、2、3、4。

快取的大小

OPcache 的共享記憶體大小固定，由兩個設定決定，php:8.5-fpm-alpine 的預設值是：

Laravel 13 骨架處理過請求之後，OPcache 回報快取了 467 個腳本，用掉 22.0 MB，剩下 106.0 MB；另外 interned strings（PHP 把重複出現的字串只存一份的區塊）用掉 4.3 MB。一個空骨架用不到預設值的五分之一，但正式專案加上大量套件之後，vendor/ 裡的檔案數可以到上萬個。

快取滿了時，OPcache 不會報錯讓請求失敗：放不進去的檔案就不被快取，每次重新編譯。檔案改過而留下的舊版本佔用的空間算是「浪費的記憶體」，剩餘空間不夠、而浪費的比例又超過 opcache.max_wasted_percentage（預設 5%）時，OPcache 會排定一次重啟，清空整份快取重新累積。兩種情形從外面看都只是請求變慢，所以要從 opcache_get_status() 讀：free_memory 接近零、或 num_cached_scripts 接近 max_accelerated_files，就是該調大的時候。手上的專案實際要多大，在部署環境跑過一輪主要的請求之後，讀這兩個值就知道。

部署新程式碼時舊版還會執行多久

OPcache 快取了編譯結果，所以檔案改了之後，PHP 什麼時候才去讀新版，由 opcache.validate_timestamps 與 opcache.revalidate_freq 決定。這是部署時最常撞到的問題。

opcache.validate_timestamps 決定 OPcache 要不要檢查檔案有沒有改過。opcache.revalidate_freq 是檢查的間隔秒數。php:8.5-fpm-alpine 的預設值是 validate_timestamps=On、revalidate_freq=2。實測兩種設定下，改了檔案之後的行為：

 1# validate_timestamps=1, revalidate_freq=2（預設）
 2改檔之前  version=2
 3改檔之後 t+0s  version=2
 4         t+1s  version=2
 5         t+3s  version=3     # 間隔過了，OPcache 檢查到檔案改了，重新編譯
 6
 7# validate_timestamps=0
 8改檔之前  version=1
 9改檔之後  version=1          # 連續請求都還是舊版
10         version=1
11         version=1
12reload 之後 version=2        # kill -USR2 讓 PHP-FPM reload，快取清空才換成新版

兩種設定各有用途：

• validate_timestamps=1：改檔之後最多 revalidate_freq 秒就生效，代價是每隔這段時間 PHP 要對檔案做一次 stat。開發環境與「直接覆寫伺服器上的檔案」的部署方式適合這個。
• validate_timestamps=0：OPcache 完全不檢查檔案，省掉所有 stat；改了檔案永遠不會生效，部署流程必須在換完程式碼之後 reload 或重啟 PHP-FPM。程式碼包在容器映像檔裡的部署適合這個：映像檔裡的檔案不會在執行中被改，每次部署都是啟動新容器，新容器的快取在啟動時是空的。開發時用 bind mount 把主機上的原始碼掛進容器，雖然也是容器，檔案卻會被改，要算成上一種情形、留著 validate_timestamps=1；設成 0 的話，改了檔案頁面不會變，也沒有任何錯誤訊息。

validate_timestamps=1 下還有一個中間狀態要知道：部署是逐一覆寫檔案時，在 revalidate_freq 那幾秒內，有的檔案已經重新編譯成新版、有的還是舊版快取，同一個請求可能同時執行到新舊兩版的程式碼。把整個版本目錄準備好再一次切換（例如換一個符號連結），然後 reload，可以避開這個狀態。

OPcache 的 JIT 與 preload

OPcache 另外帶著 JIT 與 preload，兩者跟快取 opcode 相鄰，解決的是不同的問題：

• JIT：把 opcode 進一步編譯成 CPU 的機器碼。它對計算密集的程式（數學運算、影像處理）有幫助，對多數時間在等資料庫與網路的 web 請求效果有限。php:8.5-fpm-alpine 預設 opcache.jit=disable。
• preload（opcache.preload）：PHP-FPM 啟動時先執行一支指定的腳本，把它載入的類別常駐在共享記憶體裡，之後每個請求不必再載入它們。被 preload 的檔案改了要重啟 PHP-FPM 才生效。

OPcache 與執行模型的關係

OPcache 的效果整個建立在程序壽命上：CGI 下沒有作用，常駐的 PHP-FPM worker 讓它重用到極致。但它只省掉「編譯」這一段。框架在每個請求開頭還要做另一件事——執行那 484 個檔案：建立服務容器、註冊服務、讀設定、建立路由表——這一段 OPcache 省不掉，因為 shared-nothing 要求每個請求從空白的狀態開始。

想連這一段也省掉，就要讓應用程式的狀態也跨請求保留，框架只啟動一次。那是 常駐 worker 模型 的做法，也是它要付出的代價的來源。

兩種擺法

拆成兩個容器符合「一個容器一個職責」的慣例（見 Container per Service）：Nginx 與 PHP-FPM 可以各自更新映像檔、各自看 log、各自重啟。放進同一個容器則讓這個 PHP 服務對外就是一個講 HTTP 的單位，這在兩種情況下有用：平台只接受「一個容器、一個 HTTP 埠」的服務（多數 PaaS 與 serverless 容器平台），以及要把 PHP 服務跟其他講 HTTP 的後端一起放進同一個負載平衡的 upstream——一個 upstream 只能用一種協定轉送，Nginx 的 proxy_pass（HTTP）與 fastcgi_pass（FastCGI）不能混在同一個 upstream 裡。

「拆成兩個容器」指的是兩個容器仍然部署在一起：同一個 compose 專案，或 Kubernetes 的同一個 pod。同一個 pod 裡的容器共用網路（Nginx 用 127.0.0.1:9000 連 PHP-FPM），也能共用一個 volume 放程式碼，由 Kubernetes 分別監看兩個容器，不必手寫下面〈放進同一個容器〉那一節的腳本。拆成兩個獨立部署、跨 pod 連 FastCGI 也做得到，但 9000 就得在叢集網路上開放，要另外用 NetworkPolicy 之類的機制限制只有 Nginx 連得到。

兩種擺法共用同一個起點：官方的 php-fpm 映像檔。

官方 php-fpm 映像檔替容器改掉的預設值

PHP-FPM 原本是為「裝在一台伺服器上、由 systemd 管理」設計的，它的預設值有幾項在容器裡不適用。官方映像檔用一個 php-fpm.d/docker.conf 把它們改掉：

1[global]
2error_log = /proc/self/fd/2      ; 錯誤 log 寫到 stderr，docker logs 才看得到
3
4[www]
5access.log = /proc/self/fd/2     ; 存取 log 也寫到 stderr（PHP-FPM 啟動時會關掉 stdout）
6clear_env = no                   ; 把容器的環境變數交給 worker
7catch_workers_output = yes       ; worker 的輸出也收進主 log
8listen = 9000                    ; 聽所有網路介面的 9000

另外映像檔設了 STOPSIGNAL SIGQUIT，docker stop 送給它的是 SIGQUIT 而不是預設的 SIGTERM。SIGQUIT 是 PHP-FPM 的 graceful stop，SIGTERM 是立即終止。但 graceful stop 要等進行中的請求多久，由 process_control_timeout 決定，而它的預設值是 0：只靠 STOPSIGNAL，docker stop 時進行中的請求仍然拿到 502。實測與設定方式見 PHP-FPM 的停機與重載的訊號。映像檔沒有改這個值，所以要在自己的設定檔加上：

1[global]
2; 停機與 reload 時，最多等進行中的請求這麼久；要比最長的正常請求長，比平台的停機逾時短
3process_control_timeout = 10

其中 clear_env 最容易在自己寫設定時改壞。PHP-FPM 自己的預設是 clear_env = yes：worker 啟動時清掉所有環境變數，PHP 程式用 getenv() 讀不到。而容器的設定慣例正是用環境變數傳進去（資料庫密碼、APP_KEY）。同一個容器帶著 APP_KEY=secret-from-env 啟動，只改這一個設定：

1clear_env = no   →  getenv("APP_KEY") = 'secret-from-env'
2clear_env = yes  →  getenv("APP_KEY") = false

沒有任何錯誤訊息，程式讀到的是 false。自己寫 pool 設定或從非容器環境搬一份 www.conf 進來時，要確認這一行還是 no。

拆成兩個容器：Nginx 這一側也要有程式碼

拆成兩個容器時，最容易漏的是程式碼要兩邊都有。理由是兩個容器各自要用到檔案，用途不同：

• PHP-FPM 容器要有 PHP 檔：Nginx 送來的 SCRIPT_FILENAME 是一個路徑，PHP-FPM 在自己的檔案系統裡找這個路徑去執行。
• Nginx 容器要有靜態檔：CSS、JS、圖片由 Nginx 直接從自己的檔案系統回，不經過 PHP。try_files 判斷檔案存不存在，也是看 Nginx 自己的檔案系統。

只把程式碼掛進 PHP-FPM 容器，而 Nginx 容器沒有，一般的 Laravel 式設定（try_files $uri /index.php$is_args$args）不會報錯，而是給出錯的內容。請求 /app.css：

1# Nginx 容器沒有程式碼
2HTTP/1.1 200 OK
3Content-Type: text/html; charset=UTF-8
4（內容是 index.php 產生的頁面）
5
6# Nginx 容器也掛上同一份程式碼
7HTTP/1.1 200 OK
8Content-Type: text/css
9body{}

Nginx 在自己的檔案系統找不到 app.css，try_files 就照設定退回給 index.php，於是 PHP 回了一頁 HTML，狀態碼 200。監控看到的是全部成功，瀏覽器看到的是樣式全部消失。做法有兩種：用同一個 volume 把程式碼同時掛進兩個容器；或者正式部署時在建置映像檔的階段，把 public/ 底下的靜態檔複製一份進 Nginx 的映像檔。兩個容器裡的路徑也要一致（例如都是 /var/www/html），因為 Nginx 組出來的 SCRIPT_FILENAME 是拿自己的 root 拼的，PHP-FPM 要能在同一個路徑找到檔案。

另一件事是 FastCGI 埠的暴露範圍。映像檔的 listen = 9000 聽所有網路介面，在 compose 網路裡 Nginx 才連得到它。PHP 官方文件明寫 php-fpm 不能讓不受信任的網路連到——FastCGI 沒有驗證，連得到 9000 的人能指定 PHP 執行哪個檔案。所以 compose 裡 PHP-FPM 服務不寫 ports:，9000 只在容器網路內可達。

放進同一個容器：要自己做程序監看

同一個容器裡跑兩個程序，容器的主程序（PID 1）就不能直接是 php-fpm 或 nginx，要有一支腳本把兩個都啟動起來。這支腳本要負責三件事，而三件都是單一程序的容器不必想的。

任一個程序結束，整個容器也要結束。 只剩一半在跑的容器最難排查：Nginx 還活著，PHP-FPM 已經掛了，每個請求都回 502，而容器的狀態仍是 running，平台不會重啟它。腳本要等待任一個子程序結束，然後停掉另一個、讓自己結束。shell 的 wait -n 做的就是「等任一個子程序結束」，但 Alpine 預設的 busybox sh（1.37）在這裡有一個陷阱：子程序被訊號殺掉時（kill -9、記憶體不足被系統終止），它的 wait -n 不會返回，正好漏掉崩潰這個最需要偵測的情況。換成 bash 的 wait -n，子程序被 kill -9 時會立刻返回、帶著狀態碼 137。

把停機訊號轉給兩個程序。 docker stop 只把訊號送給 PID 1，也就是這支腳本，shell 不會自動轉給子程序。腳本要接住訊號、自己轉送。這裡有一個連帶的細節：映像檔設了 STOPSIGNAL SIGQUIT，所以腳本收到的是 QUIT。只寫 trap ... TERM 的腳本接不到它，而 PID 1 對沒有註冊處理器的訊號一律忽略，結果 docker stop 要等滿 10 秒的逾時才強制終止——實測只接 TERM 時 docker stop 花 10 秒，加上 QUIT 之後 1 秒完成。

把 FastCGI 只開給容器內部。 兩個程序在同一個容器裡，Nginx 用 127.0.0.1:9000 連 PHP-FPM 就夠了，FastCGI 不必聽在網路介面上。映像檔的 listen = 9000 設在 docker.conf，在 php-fpm.d/ 底下放一個檔名排在它後面的設定檔（例如 zzz-listen.conf）覆蓋它：

1[www]
2listen = 127.0.0.1:9000

php-fpm.d/ 底下的檔案依檔名順序讀取，後讀到的設定覆蓋前面的，所以檔名要排在 docker.conf 之後。

這三件事寫成 entrypoint 腳本：

 1#!/bin/bash
 2# 用 bash：busybox sh 的 wait -n 在子程序被訊號殺掉時不返回
 3
 4# docker stop 送來的是 SIGQUIT（映像檔的 STOPSIGNAL），一併接 TERM 與 INT
 5stop() {
 6    kill -QUIT "$fpm" "$web" 2>/dev/null   # 兩者的 graceful stop；PHP-FPM 要設 process_control_timeout 才會等
 7}
 8trap stop QUIT TERM INT
 9
10php-fpm -F &                               # -F：前景執行，讓這支腳本當它的父程序
11fpm=$!
12nginx -e stderr -g 'daemon off;' &         # -e stderr：讀設定之前的錯誤 log 也寫到 stderr
13web=$!
14
15wait -n                                    # 任一個結束就往下走
16status=$?
17stop                                       # 停掉另一個
18wait
19exit "$status"

映像檔要另外裝 bash 與 nginx（apk add bash nginx）。以非 root 使用者執行時，Nginx 的 pid 檔與暫存目錄要放在那個使用者寫得進去的位置（例如 /tmp），監聽的埠也要用 1024 以上。

這組驗證值得在建好映像檔時跑一次，因為三件事出錯時容器都照樣啟動、照樣回應：用 kill -9 分別殺掉 PHP-FPM 與 Nginx 的 master，確認容器在幾秒內結束；量 docker stop 的時間，確認不是 10 秒；從容器外面連 9000，確認連線被拒。

兩種擺法的選擇

兩種擺法的差別落在「誰負責程序監看」：拆成兩個容器時，平台（compose、Kubernetes）監看每個程序，每個容器只有一個主程序，失敗時平台看得到；放進同一個容器時，這份責任移進了 entrypoint 腳本，上面那三件事都要自己做對。

放進同一個容器時，手寫腳本之外也可以用 process supervisor（s6-overlay、supervisord）管理兩個程序，由它負責監看與回收結束的子程序，代價是映像檔多一個相依；手寫腳本的好處是沒有額外相依，三件事都看得到。

所以預設是拆成兩個容器；只有在平台只接受單一 HTTP 容器、或要讓 PHP 服務跟其他 HTTP 後端進同一個 upstream 時，才放進同一個容器，並把上面的驗證當成映像檔的驗收條件。兩種擺法都繼承 PHP-FPM 的 shared-nothing 模型；不再每個請求重新啟動框架的做法是另一個執行模型，見 常駐 worker 模型。