คู่มือนักพัฒนา Cloudflare

ภาพรวมโดยย่อ

แพ็กเกจ Cloudflare ย้ายการเรนเดอร์ Portable Document Format (PDF) ไปยังขอบเขตของ Worker ให้ถือว่าการเรนเดอร์ด้วย Worker การสำรองในเครื่อง การป้องกัน application programming interface (API) และคลังเก็บ R2 เป็นความสามารถที่แยกจากกัน โดยแต่ละส่วนจัดการความล้มเหลวของตนเอง

ใช้คู่มือนี้เมื่อสร้างบริการเรนเดอร์ที่ขอบเครือข่าย เอนด์พอยต์เรนเดอร์ที่มีการป้องกัน เวิร์กโฟลว์การจัดเก็บถาวร หรือเส้นทางการสำรองในเครื่องด้วย nextpdf/cloudflare

ขอบเขตของสถาปัตยกรรม

เลเยอร์	เป็นเจ้าของโดย	ความรับผิดชอบ	สิ่งที่ไม่ควรใส่ไว้ที่นี่
เอนด์พอยต์ของแอปพลิเคชัน	แอปพลิเคชัน	อนุญาตผู้เรียกใช้งาน ทำให้คำขอเรนเดอร์เป็นรูปแบบมาตรฐาน และบังคับใช้นโยบายทางธุรกิจ	โทเค็นของ Worker ที่ฝังไว้ในโค้ด
การป้องกัน API	nextpdf/cloudflare และแอปพลิเคชัน	การตรวจสอบคีย์ API การตรวจสอบขนาดเพย์โหลด และการตัดสินใจจำกัดอัตราภายในกระบวนการ	การเรียกเก็บเงิน สิทธิ์ของผู้เช่า หรือการบังคับใช้โควตาแบบคงทน
ตัวเรนเดอร์ Cloudflare	nextpdf/cloudflare	ตรวจสอบ Hypertext Markup Language (HTML) และ Worker Uniform Resource Locator (URL) ส่งเพย์โหลดการเรนเดอร์ และแยกวิเคราะห์การตอบกลับ	การเรนเดอร์เทมเพลตหรือการสืบค้นโดเมน
Worker	การปรับใช้แอปพลิเคชัน	เรียกใช้ Browser Rendering และส่งคืนไบต์ PDF หรือผลลัพธ์ที่มีโครงสร้าง	นโยบายการจัดเก็บฝั่ง PHP
การสำรองในเครื่อง	การปรับใช้แอปพลิเคชัน	เรนเดอร์เมื่อ Worker ไม่พร้อมใช้งาน	การสำรองแบบเงียบที่ปิดบังปัญหาขัดข้องด้านปฏิบัติการ
คลังเก็บ R2	nextpdf/cloudflare	อัปโหลดไฟล์ PDF สร้างคีย์อ็อบเจกต์ และสร้าง signed URL	เมทาดาทาทางธุรกิจที่อ่อนไหวซึ่งยังไม่ผ่านการตรวจทาน

วงจรชีวิตขณะรันไทม์

ขั้นตอน	พฤติกรรม	การดำเนินการของนักพัฒนา
การสร้างคอนฟิก	โหลด Worker URL โทเค็น API ค่าหมดเวลา ขีดจำกัดขนาด การสำรอง และพิน	จัดเก็บความลับไว้ในคอนฟิกการปรับใช้
การป้องกันคำขอ	(ทางเลือก) ApiProtection ตรวจสอบคีย์ ขนาด และขีดจำกัดอัตรา	เรียกใช้ก่อนงานเรนเดอร์ที่มีต้นทุนสูง
การเรียกตัวเรนเดอร์	CloudflareHtmlRenderer ตรวจสอบ HTML และ Worker URL จากนั้นส่ง JavaScript Object Notation (JSON)	จัดการกรณี Worker ไม่พร้อมใช้งานและความล้มเหลวในการเรนเดอร์แยกจากกัน
การแยกวิเคราะห์การตอบกลับ	CloudflareResponseParser::parse() รับเอาต์พุต PDF แบบไบนารีหรือเอาต์พุต JSON ที่มีโครงสร้าง	ปฏิเสธเอาต์พุตที่ไม่ถูกต้องหรือไม่ใช่ PDF
การสำรองในเครื่อง	ตัวเรนเดอร์ในเครื่อง (ทางเลือก) จัดการความล้มเหลวของ Worker	ฉีดแฟกทอรีของตัวเรนเดอร์ในเครื่องเฉพาะเมื่อโฮสต์รองรับเท่านั้น
คลังเก็บ R2	R2ArchiveManager จัดเก็บไบต์ PDF และสร้าง signed URL	จัดเก็บเฉพาะเมทาดาทาที่ไม่อ่อนไหว เว้นแต่จงใจจัดเก็บข้อมูลอ่อนไหว

โครงสร้างแอปพลิเคชันที่แนะนำ

เส้นทาง	วัตถุประสงค์
app/Pdf/Cloudflare/*	ตัวห่อหุ้มของแอปพลิเคชันสำหรับ CloudflareHtmlRenderer
app/Pdf/Workers/*	data transfer objects (DTOs) ของคำขอ Worker และนโยบายเฉพาะเอนด์พอยต์
app/Pdf/Archive/*	การประสานงานคลังเก็บ R2 และการตัดสินใจด้านการเก็บรักษา
app/Pdf/Fallback/*	LocalRendererFactoryInterface และงานพัฒนาการสำรองที่ได้รับอนุญาต
tests/Pdf/Cloudflare/*	การทดสอบกรณี Worker ขัดข้อง โทเค็นไม่ถูกต้อง เพย์โหลด และคลังเก็บ

แยกโทเค็น API ฝั่ง PHP ออกจากโทเค็นของ Worker โดย PHP จะยืนยันตัวตนกับ Worker และ Worker ควรยืนยันตัวตนคำขอขาเข้าก่อนเริ่มงานเบราว์เซอร์

<?php

use NextPDF\Cloudflare\ApiProtection;
use NextPDF\Cloudflare\ApiProtectionConfig;
use NextPDF\Cloudflare\ApiKeyValidator;

$protection = new ApiProtection(
    new ApiProtectionConfig(maxRequestsPerMinute: 30),
    new ApiKeyValidator([$expectedApiKey]),
);

$result = $protection->checkRequest(
    clientId: $clientId,
    payloadSize: strlen($html),
    apiKey: $presentedApiKey,
);

if (!$result->allowed) {
    return new JsonResponse(['error' => $result->denialReason], 429, $result->toHeaders());
}

รูปแบบของตัวเรนเดอร์

สร้างตัวเรนเดอร์ด้วยดีเพนเดนซี PHP Standards Recommendation (PSR) จากเฟรมเวิร์กของคุณ รวมถึง PSR-18 และ PSR-17 ระบุการสำรองในเครื่องให้ชัดเจน เพื่อให้ผู้ปฏิบัติงานเห็นได้ว่าระบบหยุดใช้ Worker เมื่อใด

<?php

use NextPDF\Cloudflare\CloudflareHtmlRenderer;
use NextPDF\Cloudflare\CloudflareRendererConfig;

$renderer = new CloudflareHtmlRenderer(
    config: CloudflareRendererConfig::fromArray([
        'worker_url' => getenv('NEXTPDF_CLOUDFLARE_WORKER_URL'),
        'api_token' => getenv('NEXTPDF_CLOUDFLARE_API_TOKEN'),
        'render_timeout' => 30,
        'max_html_size' => 1_000_000,
        'fallback_to_local' => false,
    ]),
    httpClient: $httpClient,
    requestFactory: $requestFactory,
    streamFactory: $streamFactory,
);

$rendered = $renderer->render($html, widthPt: 595.28);

รูปแบบของคลังเก็บ R2

จัดเก็บถาวรหลังการเรนเดอร์สำเร็จและนโยบายอนุมัติผลลัพธ์แล้วเท่านั้น ให้ถือว่า public URL และ signed URL เป็นการตัดสินใจคนละส่วนกัน

<?php

use NextPDF\Cloudflare\R2ArchiveManager;

$upload = $archive->upload(
    pdfData: $rendered->pdfData,
    filename: 'invoice-1234.pdf',
    metadata: [
        'document_type' => 'invoice',
    ],
);

if ($upload->isValid()) {
    $temporaryUrl = $archive->generateSignedUrl($upload->key, 600);
}

อย่าใส่ชื่อลูกค้า ที่อยู่อีเมล ยอดรวมใบแจ้งหนี้ หรือตัวระบุที่อยู่ภายใต้ข้อกำหนดไว้ในเมทาดาทาของอ็อบเจกต์ เว้นแต่นโยบายการเก็บรักษาและการเข้าถึงจะอนุญาตอย่างชัดเจน

จุดขยายความสามารถ

จุดขยายความสามารถ	ใช้สำหรับ	ข้อจำกัด
LocalRendererFactoryInterface	การสำรองในเครื่องผ่าน Artisan หรือตัวเรนเดอร์อื่น	ต้องส่งคืนอ็อบเจกต์ที่นำ LocalRendererInterface ไปใช้
ApiProtectionConfig	นโยบายคีย์ API ขนาดเพย์โหลด และการจำกัดอัตรา	ขีดจำกัดในหน่วยความจำมีผลต่อแต่ละกระบวนการ
ApiKeyValidator	ตัวช่วยสำหรับการตรวจสอบคีย์แบบ timing-safe และการหมุนเวียนคีย์	จัดเก็บความลับไว้นอกซอร์สโค้ด
R2ArchiveConfig	บักเก็ต ข้อมูลรับรอง คำนำหน้าเส้นทาง เอนด์พอยต์ และขีดจำกัดขนาด	ห้ามบันทึกข้อมูลรับรองลงในล็อกโดยเด็ดขาด
PinnedCurlTransport	การบังคับใช้พิน Internet Protocol (IP) และ Subject Public Key Info (SPKI)	ต้องใช้รันไทม์ที่รองรับ cURL และแฟกทอรีการตอบกลับ
CloudflareResponseParser	การแยกวิเคราะห์การตอบกลับของ Worker	ปฏิเสธเอาต์พุต PDF ที่ไม่ถูกต้องและการตอบกลับที่เป็นข้อผิดพลาด

เวิร์กโฟลว์การพัฒนา

1. สร้างเส้นทางการเรนเดอร์ในเครื่องก่อน
2. เพิ่มการเรนเดอร์ด้วย Worker โดยใช้ฟิกซ์เจอร์ HTML ขนาดเล็กที่เป็นตัวแทน
3. เปิดใช้การป้องกันคำขอก่อนเปิดเผยเอนด์พอยต์สาธารณะ
4. เพิ่มการอัปโหลด R2 หลังจากโฟลว์การเรนเดอร์และการตอบกลับเสถียรแล้วเท่านั้น
5. ทดสอบเส้นทางกรณี Worker ล่ม โทเค็นไม่ถูกต้อง เพย์โหลดใหญ่เกินขนาด การจำกัดอัตรา และความล้มเหลวของ R2
6. เพิ่มล็อกที่แยกแยะการเรนเดอร์ด้วย Worker การเรนเดอร์แบบสำรอง การอัปโหลดคลังเก็บ และการสร้าง signed URL

การจัดการความล้มเหลว

ความล้มเหลว	ตำแหน่งที่ควรจัดการ	การตอบสนองที่แนะนำ
คีย์ API ที่ขาดหายหรือไม่ถูกต้อง	เลเยอร์การป้องกัน API	ปฏิเสธคำขอก่อนที่งานเรนเดอร์จะเริ่มต้น
เพย์โหลดใหญ่เกินขนาด	การป้องกัน API หรือการตรวจสอบของตัวเรนเดอร์	ส่งคืนผลการตรวจสอบที่ล้มเหลวโดยไม่เรียก Worker
Worker URL ที่ไม่ปลอดภัย	นโยบายความปลอดภัยของตัวเรนเดอร์	ทำให้คอนฟิกหรือคำขอล้มเหลวก่อนเกิด input/output (I/O) ผ่านเครือข่าย
Worker ไม่พร้อมใช้งาน	ขอบเขตของตัวเรนเดอร์	ใช้การสำรองอย่างชัดเจนเฉพาะเมื่อได้รับอนุญาตเท่านั้น มิฉะนั้นให้ล้มเหลวอย่างเห็นได้ชัด
ความล้มเหลวในการอัปโหลด R2	ขอบเขตของคลังเก็บ	ส่งคืนการตอบกลับ PDF หากการจัดเก็บถาวรเป็นทางเลือก และให้ล้มเหลวหากนโยบายกำหนดให้ต้องจัดเก็บถาวร
ความล้มเหลวในการหมุนเวียนพิน	การปรับใช้และการปฏิบัติงาน	หมุนเวียนด้วยพินสำรองและแผนการย้อนกลับ

ค่าเริ่มต้นที่ปลอดภัย

ประเด็นที่เกี่ยวข้อง	ค่าเริ่มต้น	เมื่อใดควรแทนที่
การสำรอง	เปิดใช้งานตามค่าเริ่มต้นของคอนฟิก	ปิดใช้งานเมื่อการเรนเดอร์ในเครื่องจะละเมิดการแบ่งแยกของการปรับใช้
ขนาด HTML สูงสุด	5,000,000 ไบต์	ลดลงสำหรับเอนด์พอยต์สาธารณะ
time to live (TTL) ของ signed URL	3600 วินาที	ลดให้สั้นลงสำหรับ PDF ที่อ่อนไหว
ชุดพิน	ว่างเปล่า	เพิ่มพินเฉพาะเมื่อมีแผนการหมุนเวียนและพินสำรองเท่านั้น
ข้อกำหนดคีย์ API	เปิดใช้งานตามค่าเริ่มต้นของคอนฟิกการป้องกัน	ปิดใช้งานเฉพาะสำหรับการเรียกภายในที่เป็นส่วนตัวและยืนยันตัวตนแล้วเท่านั้น

รายการตรวจสอบการทดสอบ

• การทดสอบตัวเรนเดอร์ครอบคลุม HTML ที่ถูกต้อง HTML ที่ใหญ่เกินขนาด Worker URL ที่ไม่ถูกต้อง และการตอบกลับที่เป็นข้อผิดพลาดของ Worker
• การทดสอบการป้องกัน API ครอบคลุมคีย์ที่ขาดหาย คีย์ที่ไม่ถูกต้อง เพย์โหลดที่ใหญ่เกินไป และการเกินขีดจำกัดอัตรา
• การทดสอบ R2 ครอบคลุมการอัปโหลดที่สำเร็จ การอัปโหลดที่ใหญ่เกินไป สถานะ Hypertext Transfer Protocol (HTTP) ที่ล้มเหลว บักเก็ตที่ไม่ถูกต้อง และการสร้าง signed URL
• การทดสอบการสำรองยืนยันว่าเส้นทางตัวเรนเดอร์ในเครื่องชัดเจนและสังเกตการณ์ได้
• การทดสอบการขนส่งครอบคลุม IP ที่ปักหมุด พินคีย์สาธารณะ การหมดเวลา และการปิดใช้การเปลี่ยนเส้นทางตามนโยบาย
• การทดสอบด้านการสังเกตการณ์ยืนยันว่ามีเหตุการณ์ล็อกที่แยกจากกันสำหรับการเรนเดอร์ การสำรอง การจัดเก็บถาวร และการสร้าง signed URL