Skip to content

الوكيل العكسي (بادئة مسار URL)

قدّم Potato تحت مسار فرعي خلف وكيل عكسي، مثل https://host/app1/. اضبط بادئة URL للنشر حتى تُحَلّ الأصول الثابتة وإجراءات التوسيم والبثوث الحية بشكل صحيح تحت مسار التركيب.

يمكن لـ Potato أن يعمل خلف وكيل عكسي تحت مسار فرعي لعنوان URL مثل https://host/app1/، وهو أمر شائع عندما تتشارك عدة خوادم داخلية نقطة نهاية HTTPS عامة واحدة:

text
https://host/app1/  ->  http://127.0.0.1:8000/
https://host/app2/  ->  http://127.0.0.1:8001/

تُحمّل واجهة التوسيم الأصول الثابتة وتنفّذ الإجراءات عبر عناوين URL النسبية للجذر (/static/...، /updateinstance، /annotate، /media/...). عندما يُركَّب Potato تحت /app1، فإن تلك العناوين كانت ستُحَلّ بدلاً من ذلك بالنسبة إلى الجذر العام، وهو ما يظهر كأخطاء 404 في ملفات CSS و JS، أو واجهة مخفية، أو فشل الحفظ التلقائي مع رسالة «annotations not saved». تعالج بادئة النشر هذا دون حيل nginx خاصة بكل موقع.

كيف يعمل

يضبط كلا الخيارين أدناه قيمة WSGI الموسومة SCRIPT_NAME، التي يقرأها Potato بوصفها المصدر الموثوق الوحيد لمُخرَج url_for(...) المُصيَّر من الخادم، ولبادئة جانب العميل المكشوفة للمتصفح عبر window.config.url_prefix. تلتف تلك البادئة حول fetch() وsendBeacon() وEventSource وسمات href/action/src النسبية للجذر. عند عدم ضبط أي بادئة، تكون SCRIPT_NAME فارغة ولا يتغير شيء، لذا فهذا لا يفعل شيئاً في عمليات potato start العادية.

الخيار أ — POTATO_PROXY_FIX (الوكيل يرسل ترويسة مُمَرَّرة)

استخدم هذا عندما تتحكم في الوكيل ويمكنه إرسال ترويسات مُمَرَّرة. يُمكِّن Potato آلية ProxyFix الخاصة بـ Werkzeug، التي تقرأ X-Forwarded-Prefix (و-Proto/-Host/-For) لكل طلب.

bash
export POTATO_PROXY_FIX=1
potato start config.yaml -p 8000

nginx، يزيل البادئة ويمررها بوصفها ترويسة:

nginx
location /app1/ {
    proxy_pass         http://127.0.0.1:8000/;   # trailing slash strips /app1/
    proxy_set_header   Host              $host;
    proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header   X-Forwarded-Proto $scheme;
    proxy_set_header   X-Forwarded-Prefix /app1;
}

تثق آلية ProxyFix في الترويسات المُمَرَّرة. لا تُمكِّن POTATO_PROXY_FIX إلا عندما يكون التطبيق قابلاً للوصول حصرياً عبر الوكيل الموثوق. إذا كان المنفذ الداخلي قابلاً للوصول مباشرة أيضاً، فقد ينتحل العميل X-Forwarded-Prefix أو -Host ويُسمِّم عناوين URL المُنشَأة.

الخيار ب — POTATO_URL_PREFIX (تعذّر تغيير إعداد الوكيل)

استخدم هذا عندما لا يمكنك إضافة ترويسات مُمَرَّرة لكنك تعرف مسار التركيب العام. يحقن Potato البادئة في SCRIPT_NAME بنفسه.

bash
export POTATO_URL_PREFIX=/app1
potato start config.yaml -p 8000

ما زال على الوكيل أن يزيل البادئة قبل التمرير، حتى يتلقى Flask مسارات بلا بادئة مثل /static/styles.css:

nginx
location /app1/ {
    proxy_pass       http://127.0.0.1:8000/;     # trailing slash strips /app1/
    proxy_set_header Host $host;
}

إذا ضُبط المتغيران معاً، تفوز البادئة المُمَرَّرة لكل طلب وتكون POTATO_URL_PREFIX هي البديل الاحتياطي.

البث الحي (الأحداث المُرسَلة من الخادم)

يستخدم عارضا الوكيل الحي والترميز الحي تقنية SSE. تُطبَّق بادئة URL تلقائياً، لكن SSE يحتاج أيضاً إلى أن يعطّل الوكيل التخزين المؤقت في موضع البث، وإلا فستُحتجَز الأحداث:

nginx
location /app1/api/ {
    proxy_pass            http://127.0.0.1:8000/api/;
    proxy_set_header      Host $host;
    proxy_buffering       off;
    proxy_read_timeout    3600s;
}

التحقق

  1. حمّل https://host/app1/ وتأكد من تحميل CSS و JS دون أخطاء 404.
  2. أجرِ توسيماً وتأكد من حفظه تلقائياً.
  3. تنقّل بين «التالي/السابق» وتأكد من تصيير الوسائط والبيانات.
  4. إذا كنت تستخدم تقييم الوكيل الحي، فتأكد من اتصال البث وتحديثه.

ملاحظات وقيود

  • تُضاف البادئة أيضاً إلى الروابط النسبية للجذر داخل محتوى التوسيم المعروض. على مؤلفي المحتوى الذين يقصدون الإشارة إلى الجذر العام استخدام عناوين URL مطلقة.
  • تعتمد عمليات النشر المثبَّتة عبر pip على الأصول الثابتة المُحزَّمة؛ تأكد من أن بناءك يتضمن أدلة static/ المتداخلة.

ذات صلة

للاطلاع على تفاصيل التنفيذ، راجع وثائق المصدر.