لماذا استضافة واجهة API لتوليد PDF ذاتيًا؟
خدمات PDF كـ SaaS تُحاسب لكل مستند أو صفحة أو استدعاء API. بمجرد أن يُولّد تطبيقك فواتير أو تقارير أو عقودًا بكميات كبيرة، تنمو التكلفة خطيًا مع استخدامك. Gotenberg تستبدلها بتكلفة VPS شهرية ثابتة بصرف النظر عن عدد PDF التي تُولّدها. كما تبقي مستنداتك خاصة: لا شيء يغادر بنيتك التحتية أثناء التحويل.
ما يمكن لـ Gotenberg تحويله
- HTML إلى PDF عبر نسخة Chromium كاملة — CSS وخطوط الويب وJavaScript واستفسارات وسائط الطباعة مُكرَّمة جميعها.
- أي رابط إلى PDF — أرشف مشاهدات لوحة التحكم وأنشئ تقارير أسبوعية أو التقط إيصالات الدفع.
- مستندات LibreOffice (DOCX وXLSX وPPTX وODT وODS وODP وأكثر من 20 صيغة) إلى PDF بدون تثبيت Microsoft Office.
- Markdown إلى PDF عبر مسار Chromium مع CSS قابل للتهيئة.
- دمج عدة ملفات PDF في ملف واحد باستدعاء API واحد.
- الصور (PNG وJPEG وWebP وTIFF) محوَّلة إلى PDF.
المتطلبات
خادم VPS بـ1 vCPU على الأقل و1 غيغابايت RAM (يُنصح بـ2 غيغابايت لتصيير Chromium المتزامن). Ubuntu 22.04 أو 24.04 مع Docker مثبَّت. لا يلزم نطاق — يمكنك استدعاء الواجهة API على http://127.0.0.1:3000 من تطبيقك الخلفي على نفس الخادم.
نشر Gotenberg خطوة بخطوة
إنشاء ملف compose
اتصل بـVPS عبر SSH وأنشئ مجلدًا:
mkdir gotenberg && cd gotenbergأنشئ docker-compose.yml مع خدمة gotenberg مرتبطة بـ 127.0.0.1:3000.
تشغيل الحاوية
شغّل docker compose up -d. يسحب Gotenberg الصورة (~1.5 غيغابايت، تشمل Chromium وLibreOffice) ويشغّل خادم HTTP. تحقق من نقطة نهاية الصحة:
curl http://127.0.0.1:3000/healthاستجابة {"status":"up"} تؤكد أن الخدمة جاهزة.
توليد أول PDF من HTML
أنشئ ملف HTML بسيطًا (invoice.html) وحوّله:
curl -s --request POST http://127.0.0.1:3000/forms/chromium/convert/html \
--form '[email protected]' \
-o invoice.pdfالاستجابة هي PDF كتدفق ثنائي.
تحويل مستند Word إلى PDF
ارفع ملف DOCX إلى مسار LibreOffice:
curl -s --request POST http://127.0.0.1:3000/forms/libreoffice/convert \
--form '[email protected]' \
-o contract.pdfإضافة المصادقة (مستحسن)
ليس لدى Gotenberg مصادقة مدمجة. النهج المستحسن: ثبّت nginx، أنشئ وكيلًا عكسيًا من https://gotenberg.your-domain.com إلى http://127.0.0.1:3000، وأضف مصادقة HTTP basic.
التكامل مع تطبيقك
Gotenberg محايد للغة — أي عميل HTTP يعمل. توجد مكتبات لـ PHP وNode.js وPython وGo وغيرها. لـ Laravel توجد حزمة رسمية تُغلّف الواجهة API. في Node.js يمكنك استدعاؤها بـ axios أو fetch الأصلية بإرسال كائن FormData مع محتوى HTML أو الملف.
