SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

VPS 上執行 AI 代理程式的無頭 Chromium

整理 VPS 執行無頭 Chromium 的常見故障,包括 /dev/shm 太小、sandbox 參數、缺少字型與程序洩漏,並說明如何事先設定限制。

執行環境

VPS 上的無頭瀏覽器是沒有視窗的 Chromium,由程式碼而非使用者操作。在伺服器上,它是長時間執行的程序樹,代理程式會透過本機 socket 與其通訊。安裝只需一個命令,後續的運作管理才是主要工作。您必須限制瀏覽器可使用的系統資源,並避免讓其控制端點暴露在公開網際網路上。

本指南假設您已決定使用的工具,現在需要進行實際運作管理。如果您仍在比較 crawler 與 extractor,請先從 自行託管的 Firecrawl 替代方案 開始,再回到本節。以下內容都使用 Playwright 的 Chromium,因為 Playwright 會提供自有的瀏覽器版本與相依套件安裝程式。因此,相同的命令可在裸機 Ubuntu VPS 與容器內執行。命令會固定使用 Playwright 1.62。

在不猜測相依套件的情況下安裝 Chromium

npm i -D playwright@1.62.0
npx playwright install --with-deps chromium

--with-deps 會執行 apt,安裝 Chromium 所需的共用函式庫與字型,執行到需要權限時會要求 root。瀏覽器本身則會下載到執行該命令之使用者的 ~/.cache/ms-playwright。這一點對伺服器很重要,因為服務使用者通常不是您登入時使用的帳號。請先以管理員身分使用 sudo npx playwright install-deps chromium 一次安裝系統套件,再在安裝命令與服務單元中設定 PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers,讓兩者共用同一份瀏覽器。服務若無法存取瀏覽器,啟動時會失敗,並在訊息中指出搜尋過的路徑。

請固定 Playwright 版本。每個版本都對應特定的瀏覽器版本,因此未固定的 npm update 可能會在服務執行期間替換瀏覽器。截至 November 16, 2026,最新版本為 1.65.1,因此變更固定版本前,請先閱讀發行說明。對於 ARM64 伺服器,請注意 1.63 重新命名了瀏覽器目錄,這會影響下文的 AppArmor 設定檔。

Chromium 有兩種組建,兩者不是相同的程式。在 headless 模式中,Playwright 預設使用 headless shell。這是較小的二進位檔,只能在 headless 模式下執行。一般安裝會將它下載到完整瀏覽器旁,而 npx playwright install --with-deps --only-shell 只會安裝 shell。使用 chromium channel 取得完整瀏覽器;Playwright 的瀏覽器文件稱其為「真正的 Chrome 瀏覽器,因此更接近實際環境、更可靠,且提供更多功能」。大量抓取資料時請使用 shell。網站行為不同且需要查明原因時,請使用完整瀏覽器。

無頭瀏覽器為何會在容器中當機

Docker 會為每個容器提供 64 MB 的 /dev/shm。Docker 文件明確說明:「如果完全省略大小,系統會使用 64m。」Chromium 會透過這個共享記憶體區域,在各程序之間傳遞轉譯內容,因此單一繁重頁面就可能將其填滿。接著 renderer 會結束,您的用戶端會回報目標已當機,即使該頁面在您的筆電上運作正常。變更任何設定前,先從容器內確認其大小。

df -h /dev/shm

有兩種真正的修正方式,兩者是替代方案,不應同時使用。--ipc=host 會讓容器使用主機的 IPC namespace,因此使用主機的 /dev/shm,通常是 RAM 的一半。Playwright 的 Docker 指南 建議採用此方式,因為未採用時「Chromium 可能耗盡記憶體並當機」。代價是容器與主機之間不再具備 IPC 隔離。--shm-size=1g 則保留私有 namespace,只將掛載區域加大。

docker run --rm -it --init --ipc=host --user pwuser mcr.microsoft.com/playwright:v1.62.0-noble /bin/bash

--disable-dev-shm-usage 是大多數搜尋結果會提供的解法,但它的作用不同:它會將這些檔案從 /dev/shm 移至暫存目錄。如果 /tmp 位於磁碟上,您只是將當機問題換成較慢的轉譯速度與磁碟寫入。如果 /tmp 是 tmpfs,資料仍會位於 RAM 中,容量上限只受 tmpfs 大小限制;核心文件 說明,其預設大小為實體 RAM 的一半,而且 tmpfs 頁面可能會被移出至 swap。這是瀏覽器耗盡小型 VPS 資源的一種方式。Playwright 1.62 預設會傳遞 --disable-dev-shm-usage;若要使用您設定大小的 /dev/shm,請在啟動選項中以 ignoreDefaultArgs: ['--disable-dev-shm-usage'] 移除該引數。

實際上停用 --no-sandbox 的代價

Chromium 會使用 Linux user namespaces 建立 sandbox,隔離每個 renderer。這個 sandbox 是惡意網頁與伺服器之間的邊界。Playwright 預設停用 Chromium sandbox,因此請在啟動選項中使用 chromiumSandbox: true 啟用。啟用的 sandbox 無法啟動時,Chromium 會拒絕執行,日誌中會出現類似以下內容的行:

Failed to move to new namespace: PID namespaces supported, Network namespace supported, but failed: errno = Operation not permitted

通常的建議是使用 --no-sandbox。Chromium 的安全性頁面直接說明了代價:「我們不建議這麼做,因為這會大幅降低安全性,也可能導致 Chromium 無法正常運作。」會依照連結瀏覽的代理程式,本質上就是在瀏覽公開網路,而降低後的安全性正是在這種環境中接受測試。請找出真正原因。

以 root 執行,以及 user namespaces 受到封鎖,是需要檢查的兩個原因。以 root 執行時,Chromium sandbox 無法使用,因此 Playwright 的映像檔會建立名為 pwuser 的一般使用者。在 Docker 中,Playwright 也建議使用允許 clone、setns 和 unshare 的 seccomp profile,讓 sandbox 瀏覽正常運作。在 Ubuntu 24.04 及更新版本中,AppArmor 會限制非特權 user namespaces;若 Chromium binary 位於任何內建 profile 都未涵蓋的路徑,也會遭到拒絕。Playwright 在 ~/.cache/ms-playwright 下的下載內容正是位於這類路徑。請檢查以下兩項:

id -u
sysctl kernel.apparmor_restrict_unprivileged_userns
sudo dmesg | grep -i userns_create

sysctl 的 1,以及包含 apparmor="DENIED" operation="userns_create" 的 kernel 行,會確認第二個原因。請在 /etc/apparmor.d/pw-chromium 中允許該 binary,讓其他內容仍維持這項限制:

abi <abi/4.0>,
include <tunables/global>

profile pw-chromium /{home/*/.cache/ms-playwright,opt/pw-browsers}/*/chrome-*/{chrome,headless_shell,chrome-headless-shell} flags=(unconfined) {
  userns,
}

使用 sudo apparmor_parser -r /etc/apparmor.d/pw-chromium 載入設定。在 x86-64 上,Playwright 會將完整 browser 放在 chrome-linux64/chrome,並將 shell 放在 chrome-headless-shell-linux64/chrome-headless-shell。在 ARM64 上,Playwright 1.62 會將兩者安裝在不同目錄:chromium-<revision>/chrome-linux/chrome 和 chromium_headless_shell-<revision>/chrome-linux/headless_shell。從 1.63 起,ARM64 會遵循 x86-64 的配置,使用 chrome-linux-arm64/chrome 和 chrome-headless-shell-linux-arm64/chrome-headless-shell。chrome-* glob 可涵蓋所有這些配置,而 /opt/pw-browsers 分支則涵蓋使用 PLAYWRIGHT_BROWSERS_PATH 建立的共用安裝。路徑也包含 browser revision,因此每次 Playwright 升級時都會變更。上述 glob 可避免受此影響。若 profile 是針對某個精確路徑撰寫,該路徑不再符合規則時不會產生明顯錯誤;瀏覽器會在一次看似無關的更新後再次啟動失敗。

為什麼螢幕擷取結果是空白或充滿方框

空白的螢幕擷取結果,或充滿空白矩形的結果,通常是字型問題,而不是渲染錯誤。install-deps 會拉取可正常運作的基礎字型:fonts-liberation、fonts-freefont-ttf、fonts-noto-color-emoji、fonts-unifont、日文使用 fonts-ipafont-gothic、中文使用 fonts-wqy-zenhei、泰文使用 fonts-tlwg-loma-otf。這組字型不包含 Noto CJK,因此韓文及其他幾種文字系統會退回使用 fontconfig 找到的字型。請直接查詢 fontconfig,不要猜測:

fc-match "sans-serif:lang=ko"
fc-match "sans-serif:lang=ar"
fc-list | wc -l

如果所需語言解析到 unifont,或退回到不含實際字形的字型,請安裝 fonts-noto-core 和 fonts-noto-cjk,然後再次執行檢查。fontconfig 會快取結果,因此安裝字型後請重新啟動瀏覽器。完全不含任何字型的精簡映像檔會在啟動時記錄 Fontconfig error: Cannot load default config file,並將所有頁面渲染成空白。

地區設定與時區和字型無關,且會改變頁面顯示的內容,而不只是外觀。Playwright 的 context locale 與時區預設使用系統設定,因此請檢查映像檔的組態,不要假設 LANG 未設定或時區為 UTC。請針對每個 browser context 設定,而不是針對整台機器設定,這樣同一個瀏覽器就能處理不同地區的工作。

const context = await browser.newContext({
  locale: 'en-GB',
  timezoneId: 'Europe/Paris',
});

洩漏的瀏覽器程序如何讓主機開始使用 swap

兩個不同的問題共用「zombie」這個名稱。真正的 zombie 是已結束、但其父程序從未呼叫 wait() 的程序。它只保留 PID 項目,不保留其他資源,因此不會耗用記憶體。當瀏覽器在容器中以 PID 1 執行時,會累積這類程序,因為 PID 1 預設不會回收子程序。Docker 的 --init 旗標正好能解決這個問題,因為它會執行一個小型 init,負責「轉送訊號並回收程序」。在 Compose 中,對應的設定是 init: true。

真正讓主機開始使用 swap 的洩漏則不同:Chromium 程序仍在執行,但沒有人關閉它們。當工作在 newContext() 與 close() 之間拋出例外,或控制腳本遭到終止而留下孤立的瀏覽器程序樹時,就會發生這種情況。最嚴重的情況是每個請求都啟動新的瀏覽器。請計算數量:

pgrep -c -f 'headless_shell|chrome'
ps -eo pid,ppid,rss,etime,comm --sort=-rss | head -20

這個數量在工作之間應回到閒置時的值。如果數量在一天內持續上升,問題出在程式碼,而不是啟動旗標:在 finally 區塊中關閉 context,在 SIGTERM 時關閉瀏覽器,並在執行固定數量的工作後重新建立瀏覽器,不要讓同一個瀏覽器持續執行一個月。在 systemd 下,停止或重新啟動服務會終止該 unit 的 cgroup 中所有程序,因此 sudo systemctl restart browser.service 是可靠的重設方式。手動在 terminal multiplexer 中啟動的瀏覽器沒有這項保證,其孤立程序會在工作階段結束後繼續存在。

單一瀏覽器內容需要多少 RAM

請精確定義問題,因為「一個瀏覽器」不是單一程序。Chromium 會執行一個瀏覽器程序、一個 GPU 程序、多個公用程式程序,以及每個網站各自的一個 renderer 程序。網站隔離也會讓跨網站 iframe 使用個別的 renderer。BrowserContext 是同一個程序樹中的獨立 cookie jar 與儲存區,因此建立第二個 context 的成本很低。第二個頁面則不同,因為它會啟動 renderer 程序,而包含大量廣告的頁面還會啟動多個程序。

因此,應測量的數值是整個程序樹在自有工作負載下的記憶體峰值。其他人的部落格提供的數值在這裡沒有參考價值,因為代理程式開啟的頁面才會決定實際需求。請在實際使用的機器上,針對預計瀏覽的網站進行測量:

sudo systemd-run --unit=browser-probe -p MemoryMax=2G -p MemorySwapMax=0 -p WorkingDirectory=/srv/agent /usr/bin/node worker.js
systemctl status browser-probe

在 Ubuntu 24.04 上,輸出中的 Memory: 行會顯示該 unit 目前與峰值的使用量。讓 worker 一次只開啟一個頁面,記錄峰值,再以同時開啟兩個頁面的方式重複測量,以了解第二個頁面的實際成本。接著即可用算術方式計算並行數:以總 RAM 扣除系統其他部分所需的記憶體,保留幾百 MB 的餘裕,再除以每個 worker 測得的峰值。若要估算底層機器的規格,請參閱 代理程式 VPS 需要多少 RAM 與 CPU。

請在兩個層面限制這個數值。在程式碼中使用固定的 worker pool 或 semaphore,讓代理程式請求暴增時進入佇列,而不是啟動更多瀏覽器。在作業系統中使用 cgroup 限制,避免佇列程式的錯誤連帶拖垮整台機器:

[Service]
MemoryMax=2G
MemorySwapMax=0
TasksMax=512
Restart=always

MemorySwapMax=0 的重要性超出一般預期。沒有這項設定時,cgroup 接近限制後可以將頁面移至 swap,因此整台機器通常仍會維持運作,但每個請求都會變慢;這比明確失敗更難診斷。Swap 只能延後問題發生:systemd 的文件指出,如果使用量「無法控制在限制以下,便會在該 unit 內啟動 out-of-memory killer」。將 swap 上限設為 0 後,該 unit 就無法使用 swap;達到 MemoryMax 時,系統會先嘗試 reclaim,若 reclaim 無法控制使用量,才會觸發 OOM kill。Restart=always 會在主要程序結束時重新啟動服務,但單獨對 renderer 執行 OOM kill 並不保證服務會重新啟動。Compose 中對應的控制項是 mem_limit、shm_size 與 init,詳見 在 Docker Compose 中設定記憶體限制。

避免將瀏覽器端點暴露在公用網際網路

Playwright 可以將瀏覽器以伺服器模式執行,並提供 WebSocket URL 給代理程式:

const { chromium } = require('playwright');
const server = await chromium.launchServer({ port: 3000 });
console.log(server.wsEndpoint());

該端點沒有登入機制。Playwright API 文件直接說明:「任何知道 wsPath 的程序或網頁(包括在 Playwright 中執行的程序或網頁)都能控制該 OS 使用者。」預設主機是 localhost,「只接受來自迴路介面的連線」;文件也警告,傳入 0.0.0.0 這類明確位址,會「將瀏覽器 RPC 暴露給任何能連線至監聽埠的對象」。Chrome 自己的 --remote-debugging-port 情況更糟。DevTools 通訊協定完全沒有任何驗證機制,安全性完全取決於是否繫結至迴路介面。

確認實際公開了哪些內容,也要從第二台機器和 VPS 分別進行檢查:

ss -ltnp

任何繫結至 0.0.0.0 的瀏覽器埠都屬於安全性問題。請記住,多數供應商會在控制面板中另設網路防火牆,而你的 ufw 規則無法得知該防火牆的設定。請改用 SSH 通道或私有 VPN,從另一台機器連線至該端點:

ssh -N -L 3000:127.0.0.1:3000 you@your-vps

這裡的風險不只是瀏覽器工作階段遭竊。可由他人控制的瀏覽器,就是位於你網路內部的請求偽造工具。任何能連線至該 socket 的人,都能讓它擷取 http://127.0.0.1:8080、資料庫管理頁面,或雲端中繼資料位址 169.254.169.254,再從頁面中讀取回應。你的防火牆會將請求視為來自 VPS 本身,因此允許該請求。請將控制端點視同該主機上的 shell 存取權。

MCP 伺服器的情況相同。npx @playwright/mcp@latest --headless --port 8931 會在 localhost 上透過 HTTP 提供服務,而 --host 0.0.0.0 是將本機工具轉為公開服務的旗標。該專案的 README 明確表示,Playwright MCP「不是安全邊界」。請將該埠維持繫結至迴路介面,並讓代理程式透過相同的通道存取。

代理程式讀取的頁面是不受信任的輸入

會瀏覽公開網路的代理程式,會將陌生人撰寫的文字提供給同時持有您指示的模型。頁面可能包含直接寫給模型的文字,要求模型放棄目前工作、呼叫工具,或將資料張貼到某個 URL。模型接收到的兩者都是文字,因此沒有可靠的方法區分頁面內容與您的指示。請將環境設計成讓惡意頁面可利用的範圍降至最低。

  • 讓瀏覽器以獨立的 OS 使用者執行,且其環境中不得有 SSH 金鑰或雲端憑證。
  • 每項工作使用全新的 context,並在搭配 Playwright MCP 時使用 --isolated;工作之間關閉 MCP 瀏覽器,以捨棄該工作階段的儲存內容。
  • 工作允許時,維護 origin allowlist。Playwright MCP 使用 --allowed-origins 和 --blocked-origins,其值為以分號分隔的清單。這些篩選條件不會影響重新導向,也不是安全邊界。
  • 任何會變更狀態的動作都必須先取得人工確認,例如寄送郵件或付款。

更理想的做法,是將整個瀏覽器放在可直接丟棄並重新建置的機器上。這與 在可丟棄的 VM 中執行 coding agents 的理由相同。如果代理程式的實際工作是搜尋,而不是開放式瀏覽,使用範圍更窄的工具會比完整瀏覽器安全:使用自有 SearXNG 支援的搜尋 skill 可傳回結果,而完全不載入惡意頁面。

FAQ

為什麼 Chromium 在 Docker 中會當機,但直接在同一台 VPS 上執行卻正常?

因為容器預設只有 64 MB 的 /dev/shm,而主機的容量大得多。Chromium 會透過這個共享記憶體區域傳遞渲染內容,因此頁面內容繁重時會填滿該區域,導致 renderer 結束。先在容器內執行 df -h /dev/shm 進行確認,接著使用 --ipc=host 啟動,讓它使用主機的共享記憶體;或使用 --shm-size=1g,擴大容器自己的共享記憶體。--disable-dev-shm-usage 只會將問題移到 /tmp。Playwright 1.62 預設會傳入該 flag;使用 ignoreDefaultArgs: ['--disable-dev-shm-usage'],讓 Chromium 使用你配置大小的共享記憶體。

如果 VPS 沒有執行其他程式,使用 --no-sandbox 安全嗎?

不安全。sandbox 可防止惡意頁面存取機器的其他部分,而 Chromium 的安全性頁面對此 flag 的說明是:「我們不鼓勵使用此設定,因為它會大幅降低安全性,也可能導致 Chromium 無法正常運作。」遵循連結的 agent 會瀏覽公開網路。請改為修正根本原因:不要以 root 執行瀏覽器;在 Ubuntu 24.04 中,為瀏覽器二進位檔路徑加入包含 userns, 的 AppArmor profile,讓該單一程式可使用非特權 user namespace。使用 chromiumSandbox: true 明確啟用 sandbox;在 Docker 中,也使用 Playwright 建議的 seccomp profile。

在小型 VPS 上可以執行多少個瀏覽器?

請實測,不要直接套用某個數字。Chromium 會為每個網站啟動一個 renderer process,因此數量取決於你開啟的頁面。使用 MemoryMax 設定,在 systemd-run 下執行一個 worker,從 systemctl status 的 Memory: 行讀取尖峰值,再以可用 RAM 除以該尖峰值,並保留餘裕。透過兩層機制限制結果:在程式碼中加入佇列,並在 unit file 中設定 MemoryMax,讓突發請求等待,而不是讓機器開始使用 swap。

我的 agent 可以從另一台機器連線到瀏覽器嗎?

可以,但絕對不要將連接埠繫結到 0.0.0.0。Playwright server endpoint 和 Chrome DevTools port 都會接受任何能連到它們的 client,且沒有密碼保護。讓 listener 維持在 127.0.0.1,並透過 SSH tunnel 或 private VPN 傳送連線。使用 ss -ltnp 在伺服器上驗證,並從外部執行連接埠檢查;也要檢查供應商另外提供的 network firewall。

為什麼頁面明明已載入,我取得的螢幕擷取畫面卻是空白?

缺少字型。沒有涵蓋頁面所使用文字系統的字型時,文字會轉成空白方框,或根本不會顯示,因此以少量圖片為主的頁面回傳後看起來會是空白。針對每種要擷取的語言執行 fc-match "sans-serif:lang=ko";若結果是 generic fallback,請安裝 fonts-noto-core 和 fonts-noto-cjk,然後重新啟動瀏覽器,讓 fontconfig 重新載入快取。完全沒有字型的容器會在啟動時記錄 Fontconfig error: Cannot load default config file。

這篇文章對您有幫助嗎?