استقرار با Kubernetes

Kubernetes ممکن است برای یک سایت ایستا زیاده از حد باشد، اما اگر از قبل روی Helm و GitOps استانداردسازی کرده‌اید، گزینهٔ بسیار مناسبی است.

IMPORTANT

هدرهای لازم برای تبدیل فایل‌های Office

ابزارهای مبتنی بر LibreOffice (تبدیل Word، Excel، PowerPoint) برای پشتیبانی از SharedArrayBuffer به این هدرهای HTTP نیاز دارند:

• Cross-Origin-Opener-Policy: same-origin
• Cross-Origin-Embedder-Policy: require-corp

ایمیج‌های رسمی nginx در BentoPDF این هدرها را دارند. در Kubernetes، کنترلرهای Ingress/Gateway نیز پراکسی معکوس هستند، پس مطمئن شوید این هدرها حفظ می‌شوند (یا آن‌ها را در لبه اضافه کنید).

پیش‌نیازها

• یک کلاستر Kubernetes
• Helm v3
• یک ایمیج nginx از BentoPDF (مثلاً ghcr.io/alam00000/bentopdf:<tag>) که روی پورت 8080 سرویس می‌دهد

استقرار با Helm

نصب از این مخزن (چارت محلی)

kubectl create namespace bentopdf

helm upgrade --install bentopdf /path/to/bentopdf/chart \
  --namespace bentopdf \
  --set image.repository=ghcr.io/alam00000/bentopdf \
  --set image.tag=latest

نصب از GHCR (چارت OCI)

اگر چارت به‌صورت یک آرتیفکت OCI در GHCR منتشر شده باشد:

export GHCR_USERNAME="<github-org-or-user>"

helm upgrade --install bentopdf oci://ghcr.io/$GHCR_USERNAME/charts/bentopdf \
  --namespace bentopdf \
  --create-namespace \
  --version 0.1.0 \
  --set image.repository=ghcr.io/alam00000/bentopdf \
  --set image.tag=latest

در دسترس قرار دادن

Port-forward (آزمایش سریع)

kubectl -n bentopdf port-forward deploy/bentopdf 8080:8080

Ingress (اختیاری)

Ingress را فعال کنید (نمونه برای nginx-ingress):

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: pdf.example.com
      paths:
        - path: /
          pathType: Prefix

Gateway API (اختیاری)

این چارت از Gateway و HTTPRoute در Gateway API پشتیبانی می‌کند.

نمونه (اپراتور Cloudflare Gateway API):

gateway:
  enabled: true
  name: bento-tunnel
  namespace: bentopdf
  gatewayClassName: cloudflare

httpRoute:
  enabled: true
  parentRefs:
    - name: bento-tunnel
      namespace: bentopdf
      sectionName: http
  hostnames:
    - pdfs.example.com

اطمینان از کارکرد هدرهای SharedArrayBuffer (Ingress/Gateway)

چه چیزی «باید» اتفاق بیفتد

پیکربندی nginx در BentoPDF هدرهای پاسخ لازم را تنظیم می‌کند. بیشتر کنترلرهای Ingress/Gateway هدرهای پاسخ بالادستی را بدون تغییر عبور می‌دهند.

چه چیزی می‌تواند آن را خراب کند

• سیاست کنترلر/لبه‌ای که هدرهای پاسخ را بازنویسی یا حذف می‌کند
• یک میان‌افزار «هدرهای امنیتی» که مقادیر متفاوتی برای COOP/COEP تنظیم می‌کند

نحوهٔ بررسی

این را روی نقطهٔ پایانی عمومی خود اجرا کنید:

curl -I https://pdf.example.com/ | egrep -i 'cross-origin-opener-policy|cross-origin-embedder-policy'

باید این‌ها را ببینید:

• Cross-Origin-Opener-Policy: same-origin
• Cross-Origin-Embedder-Policy: require-corp

اگر کنترلر Ingress شما آن‌ها را حفظ نمی‌کند

هدرها را در لبه اضافه کنید (وابسته به کنترلر). نمونه برای nginx-ingress:

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/configuration-snippet: |
      add_header Cross-Origin-Opener-Policy "same-origin" always;
      add_header Cross-Origin-Embedder-Policy "require-corp" always;

خطاهای نوع MIME برای .mjs (خالی بودن iframe امضای PDF / پرکنندهٔ فرم)

اگر کنسول مرورگر برای یک درخواست .mjs خطای Failed to load module script: ... non-JavaScript MIME type "application/octet-stream" را نشان می‌دهد، یک کنترلر Ingress/Gateway جلوی nginx در BentoPDF هدر Content-Type بالادستی را با application/octet-stream جایگزین می‌کند.

nginx در ایمیج BentoPDF از قبل .mjs را با application/javascript ارائه می‌دهد. راه‌حل این است که جلوی حذف یا جایگزینی آن توسط کنترلر را بگیرید. برای nginx-ingress:

ingress:
  annotations:
    nginx.ingress.kubernetes.io/configuration-snippet: |
      location ~* \.mjs$ {
        types {} default_type application/javascript;
      }

یا از فیلتر ResponseHeaderModifier در Gateway API برای تنظیم Content-Type: application/javascript روی مسیرهای .mjs استفاده کنید. با DevTools ← زبانهٔ Network بررسی کنید: درخواست ناموفق .mjs اکنون باید content-type: application/javascript را نشان دهد.

اگر از Gateway API استفاده می‌کنید و می‌خواهید هدرها را اجباری اضافه کنید

Gateway API از فیلتر ResponseHeaderModifier پشتیبانی می‌کند. می‌توانید آن را در httpRoute.rules[*].filters قرار دهید:

httpRoute:
  enabled: true
  hostnames: [pdf.example.com]
  parentRefs:
    - name: bento-tunnel
      namespace: misc
      sectionName: http
  rules:
    - matches:
        - path: { type: PathPrefix, value: / }
      filters:
        - type: ResponseHeaderModifier
          responseHeaderModifier:
            set:
              - name: Cross-Origin-Opener-Policy
                value: same-origin
              - name: Cross-Origin-Embedder-Policy
                value: require-corp

پشتیبانی از فیلترهای خاص به کنترلر Gateway شما بستگی دارد؛ اگر فیلتری نادیده گرفته شد، هدرها را به‌جای آن در لایهٔ لبه/کنترلر اضافه کنید.

غیرفعال کردن ابزارهای خاص

از یک ConfigMap برای غیرفعال کردن ابزارها در زمان اجرا، بدون ساخت دوبارهٔ ایمیج، استفاده کنید:

apiVersion: v1
kind: ConfigMap
metadata:
  name: bentopdf-config
  namespace: bentopdf
data:
  config.json: |
    {
      "disabledTools": ["edit-pdf", "sign-pdf", "encrypt-pdf"]
    }

آن را در پوشهٔ ارائه‌شده mount کنید:

spec:
  containers:
    - name: bentopdf
      volumeMounts:
        - name: config
          mountPath: /usr/share/nginx/html/config.json
          subPath: config.json
          readOnly: true
  volumes:
    - name: config
      configMap:
        name: bentopdf-config

شناسهٔ ابزارها همان URL صفحه بدون .html است؛ هر ابزاری را باز کنید و به URL نگاه کنید (مثلاً edit-pdf، merge-pdf، compress-pdf). ابزارهای غیرفعال از صفحهٔ اصلی، جستجو، میان‌برها، سازندهٔ گردش کار و دسترسی مستقیم با URL پنهان می‌شوند. برای فهرست کامل گزینه‌ها راهنمای Docker را ببینید.