NextPDF Artisan için Chrome işleyicisi kurulumu

Bir bakışta

Köprü, yerel bir Chrome/Chromium işlemini chrome-php/chrome aracılığıyla başlatır ve yönetir. Taşınabilir Belge Biçimi (PDF) işlemelerinin başarılı olması ve doğru kapsayıcı ile korumalı alan kararlarını verebilmeniz için bu sayfadaki adımlarla bu çalışma zamanını kurun.

Köprü Chrome ile nasıl iletişim kurar

BrowserPool, (isteğe bağlı olarak açık bir ikili dosya yolu kullanarak) bir chrome-php/chromeBrowserFactory oluşturur ve Chrome’u sabit bir bayrak kümesiyle başlatır: headless: true, keepAlive: true, windowSize: [1200, 800], sendSyncDefaultTimeout: renderTimeout * 1000 ve /integrations/artisan/configuration/ sayfasında listelenen özel bayraklar. Ardından köprü, başlatılan işlemi Chrome DevTools Protocol (CDP) üzerinden yönetir. Uzaktan hata ayıklama bağlantı noktası üzerinden ayrı bir Chrome işlemine bağlanmaz; bu nedenle açığa çıkarılacak veya kimliği doğrulanacak bir ağ uç noktası yoktur. Chrome, PHP iş parçacığının alt işlemi olarak çalışır. tests/Unit/Artisan/BrowserPoolTest.php::getBrowserCreatesAndReusesInstanceWithExpectedOptions testi, bu başlatma seçeneklerini tam olarak doğrular.

İkili dosyayı sağlama

İş parçacığı kullanıcısının çalıştırabileceği bir Chrome veya Chromium derlemesi kurun:

# Debian / Ubuntu
apt-get install -y chromium

# RHEL / Fedora
dnf install -y chromium

# Alpine (containers)
apk add --no-cache chromium nss freetype harfbuzz ttf-freefont

İş parçacığı kullanıcısı olarak başsız modda çalıştığını doğrulayın:

chromium --headless --dump-dom about:blank

Boş bir Belge Nesne Modeli (DOM) ile birlikte çıkış kodu 0, ikili dosyanın ve paylaşılan kitaplıklarının mevcut olduğunu gösterir. Sıfır olmayan bir çıkış, köprünün ChromeRenderException olarak ortaya çıkardığı hatanın aynısıdır. Önce bunu burada düzeltin.

Köprüyü ikili dosyaya yönlendirme

Standart bir yolda ikili dosya bulunduğunda otomatik algılama (chrome-php/chrome varsayılanı) çalışır. Belirlenimci üretim davranışı için yolu açıkça sabitleyin:

$config = new ChromeRendererConfig(
    chromeBinaryPath: '/usr/bin/chromium',
);

veya dizi yapılandırmasıyla:

$config = ChromeRendererConfig::fromArray([
    'chrome_binary' => '/usr/bin/chromium',
]);

Kapsayıcı sağlama ve korumalı alan kararı

Bir kapsayıcıda Chrome’un işletim sistemi korumalı alanı, ek çekirdek yetenekleri olmadan kök / işlem tanımlayıcı (PID) 1 olarak çoğu zaman başlatılamaz. İki yolunuz var:

1. Korumalı alanı koruyun (tercih edilen). İş parçacığını kök olmayan bir kullanıcı olarak çalıştırın ve kapsayıcıya Chrome’un korumalı alanının ihtiyaç duyduğu yetenekleri verin (genellikle SYS_ADMIN veya kullanıcı ad alanı oluşturulmasına izin veren bir seccomp profili). Bu, Chrome işlem yalıtımını bozulmadan korur.
2. Korumalı alanı devre dışı bırakın. no_sandbox: true ayarlayın. Chrome, --no-sandbox ile başlatılır. Bu, Chrome’un işlem yalıtımı korumalı alanını kaldırır: yüzeysel bir bayrak değildir, kapsama düzeyinde gerçek bir azalmadır. Bunu yalnızca korumalı alanın etkinleştirilemediği yerlerde kullanın, Chrome’u kısıtlı bir kapsayıcı içinde kök olmayan bir kullanıcı olarak çalıştırın ve dağıtımı, girdiye daha yüksek güven gerektiren bir dağıtım olarak ele alın. Köprünün ağ engelleri (İçerik Güvenlik İlkesi (CSP) ve CDP engellemesi) her iki durumda da yürürlükte kalır, ancak bunlar işlem yalıtımının yerini tutmaz. Bu, güvenilmeyen içeriğin işlenmesine yönelik OWASP ASVS en az ayrıcalık ve yalıtım rehberliğiyle uyumludur.

Korumalı alanın neyi koruyup neyi korumadığını da kapsayan tam sınır bildirimi, /integrations/artisan/security-and-operations/ sayfasındadır. Bu sayfa, korumalı alanı devre dışı bırakmanın güvenli olduğunu iddia etmez.

Referans kapsayıcı şekli

FROM php:8.4-cli
RUN apt-get update && apt-get install -y --no-install-recommends \
        chromium fonts-liberation \
    && rm -rf /var/lib/apt/lists/*
RUN useradd -m -u 10001 worker
USER worker
ENV CHROME_BINARY=/usr/bin/chromium
# Set CHROME_NO_SANDBOX=1 only if the sandbox cannot be enabled in your runtime.

İş parçacığını kök olarak değil, worker (kullanıcı kimliği 10001) olarak çalıştırın. Köprü, --disable-dev-shm-usage bayrağını zaten uygular; bu bayrak, ek ayar gerektirmeden kapsayıcılarda yaygın görülen küçük /dev/shm kaynaklı çökmeleri önler.

Yazı tipleri

Köprü, uzak yazı tiplerinin getirilmesini engeller (--disable-remote-fonts ve CSP). İhtiyaç duyduğunuz yazı tiplerini işletim sistemi katmanında kurun veya bunları data: Tekdüzen Kaynak Tanımlayıcısı (URI) kullanan @font-face kaynakları olarak defaultCss ya da Köprü Metni İşaretleme Dili (HTML) içine gömün. Çince, Japonca ve Korece (CJK) çıktısı için imajda kurulu bir CJK yazı tipi paketi (örneğin fonts-noto-cjk) gerekir.

Sağlık yoklaması

Ana uygulamadan bağımsız olarak tam köprü yolunu denemek için bu bağımsız yoklamayı kullanın:

chrome-health.php

<?php

declare(strict_types=1);

use NextPDF\Artisan\ChromeHtmlRenderer;
use NextPDF\Artisan\ChromeRendererConfig;

require __DIR__ . '/vendor/autoload.php';

$renderer = new ChromeHtmlRenderer(
    ChromeRendererConfig::fromArray([
        'chrome_binary' => getenv('CHROME_BINARY') ?: null,
        'no_sandbox'    => (bool) getenv('CHROME_NO_SANDBOX'),
    ]),
);

$result = $renderer->render('<p>ok</p>', 200.0, 0.0);
fwrite(STDOUT, strlen($result->getPdfData()) > 0 ? "CHROME_OK\n" : "CHROME_EMPTY\n");
$renderer->close();

CHROME_OK, başlatma, işleme ve içe aktarma adımlarını doğrular. Fırlatılan istisna, doğrudan hatanın kendisidir. Bunu /integrations/artisan/troubleshooting/ sayfasında eşleştirin. Orkestre edilen dağıtımlarda bu yoklamayı hazır olma denetimi olarak bağlayın.

Kaynak yalıtımı notları

• Chrome’u ayrılmış, kök olmayan bir kullanıcı olarak çalıştırın.
• Ana makinede bir bellek sınırı uygulayın; köprü, büyümeyi 100 işlemelik yeniden başlatmayla sınırlar, ancak ana makine düzeyinde üst sınır yine de gereklidir.
• Güvenilmeyen girdinin erişebildiği herhangi bir yolda, render_timeout değerini bir üst akış istek bütçesiyle eşleştirin.
• Chrome uzaktan hata ayıklama bağlantı noktasını açığa çıkarmayın. Köprü böyle bir bağlantı noktası kullanmaz ve açık bir CDP bağlantı noktası, kimliği doğrulanmamış bir denetim kanalıdır.

Hata modları ve sorun giderme

Belirti	Olası neden	Nereye bakmalı
ChromeNotAvailableException	chrome-php/chrome kurulu değil	/integrations/artisan/install/
ChromeRenderException ilk işlemede	İkili dosya eksik / korumalı alan başlatılamıyor	Bu sayfa; /integrations/artisan/troubleshooting/
Boş PDF	Görünür kutu yok / Chrome çökmesi	/integrations/artisan/troubleshooting/
Uzak görüntüler boş	Ağ erişimi tasarım gereği engellendi	/integrations/artisan/security-and-operations/
Düzenli aralıklarla gecikme artışı	100 işlemelik yeniden başlatma	/integrations/artisan/production-usage/

Ayrıca bakınız

• /integrations/artisan/install/
• /integrations/artisan/configuration/
• /integrations/artisan/security-and-operations/
• /integrations/artisan/troubleshooting/
• /integrations/artisan/production-usage/