fix: make OCR portable and reliable across AMD64 and ARM64 (#519)

* fix: make OCR portable and reliable

* fix: harden OCR installation portability

* fix: pin OCR partials across downloads

* fix: make OCR execution reliably asynchronous

* fix: harden OCR portability and docs routes

* fix: preserve decoder and docs safeguards

apps/docs/ar/guide/deployment.md

@@ -1,8 +1,8 @@
 ---
 description: "انشر SnapOtter في بيئة الإنتاج باستخدام Docker. متطلبات العتاد وإعداد GPU وإعدادات الوكيل العكسي لـ Nginx و Traefik و Cloudflare."
-i18n_source_hash: 6b6957060fa6
-i18n_provenance: machine
-i18n_output_hash: d93b79a4df81
+i18n_output_hash: 44503f8d944c
+i18n_source_hash: e0d8d5f6fc87
+i18n_provenance: human
 ---
 
 # النشر {#deployment}
@@ -11,6 +11,12 @@ i18n_output_hash: d93b79a4df81
 
 راجع [صورة Docker](./docker-tags) لإعداد GPU وأمثلة Docker Compose وتثبيت الإصدار.
 
+
+<!-- korean-ocr-contract:start -->
+::: info توافق OCR الكوري
+يدعم Fast OCR اللغات `auto` و`en` و`de` و`es` و`fr` و`zh` و`ja`، لكنه لا يدعم الكورية (`ko`). تتطلب الكورية حزمة OCR الدقيقة ومستوى `balanced` أو `best`. تعمل الحزمة على حاويات Linux amd64 وarm64 الرسمية، بما في ذلك مضيفات NVIDIA حيث يبقى OCR على CPU. تُرجع الأنظمة غير المدعومة خطأ توافق صريحاً ولا تعود بصمت إلى `fast`. كما يُرفض طلب Korean مع `fast` أو الاسم القديم `tesseract` قبل وضعه في قائمة الانتظار، مع `FEATURE_INCOMPATIBLE` والسبب `fast-korean-unsupported`.
+:::
+<!-- korean-ocr-contract:end -->
 ## بداية سريعة (المعالج المركزي) {#quick-start-cpu}
 
 ```yaml
@@ -113,7 +119,7 @@ docker compose up -d
 
 ## بداية سريعة (NVIDIA CUDA) {#quick-start-nvidia-cuda}
 
-لتسريع NVIDIA CUDA على أدوات الذكاء الاصطناعي (إزالة الخلفية، وتكبير الدقة، وتحسين الوجوه، و OCR):
+لتسريع NVIDIA CUDA على أدوات الذكاء الاصطناعي المدعومة (إزالة الخلفية، ورفع المستوى، وتحسين الوجه):
 
 ```yaml
 # docker-compose-gpu.yml - Requires: NVIDIA GPU + nvidia-container-toolkit
@@ -251,10 +257,10 @@ deploy:
 |---|---|
 | المعالج المركزي | 4 أنوية |
 | الذاكرة | 4 جيجابايت |
-| القرص | 3 جيجابايت (الصورة) + 24 جيجابايت (نماذج الذكاء الاصطناعي) + مساحة العمل |
+| Disk | 3 جيجابايت (صورة) + حوالي 20 جيجابايت (جميع حزم الذكاء الاصطناعي الاختيارية) + مساحة عمل |
 | GPU | غير مطلوب (رجوع إلى المعالج المركزي) |
 
-**تثبيت حزم الذكاء الاصطناعي هو ما يرفع الذاكرة إلى 4 جيجابايت.** بدون تثبيت أي ذكاء اصطناعي يعمل التطبيق في وضع الخمول حول 360 ميجابايت؛ ومع تثبيت جميع الحزم السبع يحتفظ بـ ~2.6 جيجابايت مقيمة، لأن الوحدة الجانبية للذكاء الاصطناعي بلغة Python تحمّل نماذجها مسبقًا (إزالة الخلفية، وتكبير الدقة، و OCR، والنسخ النصي، واكتشاف الوجوه، والاستعادة) عند بدء التشغيل. تبقى التثبيتات غير المعتمدة على الذكاء الاصطناعي خفيفة؛ أما تثبيتات الذكاء الاصطناعي فتحتاج ≥4 جيجابايت.
+**تثبيت وتشغيل حزم الذكاء الاصطناعي الأكبر حجمًا هو ما يدفع التوصية إلى 4 جيجابايت من RAM.** مع عدم وجود حزم اختيارية مثبتة، يظل التطبيق في وضع الخمول بحوالي 360 ميجابايت. تشترك أدوات Python القديمة في sidecar، في حين تستخدم OCR الدقيقة dispatcher مخصصة طويلة الأمد مثبتة على الجيل النشط غير القابل للتغيير. قبل التنشيط، يقوم المثبت بتشغيل smoke test على المرشح. ثم يتحول ذريًا إلى dispatcher الجديد ويستنزف dispatcher السابق قبل garbage collection. يجب على كل قطعة أثرية رسمية للتعرف الضوئي على الحروف (OCR) أن تجتاز أسوأ حالة release suite داخل 4 GiB cgroup، بينما تترك توصية المضيف بسعة 4 جيجابايت مجالًا لتطبيق Node.js و Postgres و Redis وقوائم الانتظار والعمل المتزامن.
 
 معظم أدوات الذكاء الاصطناعي قابلة للاستخدام تمامًا على المعالج المركزي؛ واثنتان منها تحتاجان GPU فعلًا. قِيست على معالج مركزي رباعي الأنوية حديث:
 
@@ -271,7 +277,7 @@ deploy:
 
 تعتمد بعض الأدوات على أكثر من حزمة مشتركة. على سبيل المثال، تحتاج صورة جواز السفر إلى كل من `background-removal` و `face-detection`؛ إذا كانت `background-removal` مثبّتة بالفعل، فإن تفعيل صورة جواز السفر لا ينزّل سوى الحزمة المفقودة `face-detection`. تنطبق نفس إعادة الاستخدام عبر جميع أدوات الذكاء الاصطناعي.
 
-أحجام تنزيل نماذج الذكاء الاصطناعي:
+تقديرات تخزين حزمة AI الاختيارية:
 
 | الحزمة | حجم القرص |
 |---|---|
@@ -279,9 +285,16 @@ deploy:
 | تكبير الدقة + تحسين الوجوه + إزالة الضوضاء | 5-6 جيجابايت |
 | اكتشاف الوجوه | 200-300 ميجابايت |
 | ممحاة الكائنات + التلوين | 1-2 جيجابايت |
-| OCR | 5-6 جيجابايت |
+| دقيق OCR (`balanced`/`best`) | ~208-234 MiB تنزيل / ~409-488 MiB مثبتة |
 | استعادة الصور | 4-5 جيجابايت |
-| **جميع الحزم** | **~24 جيجابايت** |
+| النسخ | ~600 ميجابايت |
+| **جميع الباقات** | **~20 جيجابايت مثبتة** |
+
+تم دمج Fast OCR في الصورة من خلال Tesseract، ويضيف حوالي 25 MiB، ولا يتطلب حزمة OCR الاختيارية أو متطلبات الذاكرة 4 GiB الخاصة بها. تتوفر الحزمة الدقيقة في حاويات Linux amd64 و arm64 الرسمية وتقوم بتشغيل ONNX Runtime على CPU. يستخدم مضيفو NVIDIA نفس وقت تشغيل CPU OCR، لذلك لا يعتمد OCR على إصدار CUDA أو بنية GPU. يتطلب وقت التشغيل الدقيق ما لا يقل عن 4 GiB من الذاكرة الفعالة: الحد الأقصى للحاوية التي تم تكوينها cgroup، خلاف ذلك الذاكرة المضيفة. يرفض SnapOtter الأنظمة التي تقل عن الحد الأدنى من التوافق الموقع قبل تنزيل الحزمة. يتم أيضًا رفض التثبيت الدقيق للحزمة على أرشيفات bare-metal/المنشأة مسبقًا والتي لا يمكن ضمان libc و Python ABI لها.
+
+يجب أن تستخدم النسخ المتماثلة التي تشترك في `DATA_DIR` نفسه بنية CPU نفسها؛ ثبّت عمليات النشر متعددة النسخ على عُقد متوافقة باستخدام تقارب العُقد (node affinity). تحتاج النسخ المختلطة من amd64 وarm64 إلى وحدات تخزين بيانات منفصلة وعمليات نشر مستقلة لـ SnapOtter.
+
+يحافظ وقت التشغيل الدقيق على جيل واحد نشط ويقوم بمسح ذاكرة التخزين المؤقت للتنزيل بعد التنشيط. لهذا الإصدار، يحتاج التثبيت الأول مؤقتًا إلى ما يقرب من 620-720 MiB للأرشيف بالإضافة إلى التدريج، ويمكن أن تصل الترقية إلى ذروتها بالقرب من 1.2 GiB بينما يظل الجيل القديم نشطًا. يحسب المثبت المتطلبات الدقيقة من الفهرس الموقع والأجيال الحالية قبل التنزيل أو الاستخراج، ويفشل مبكرًا إذا كان حجم البيانات صغيرًا جدًا.
 
 ```yaml
 deploy:
@@ -353,7 +366,6 @@ deploy:
 
 - **تغيير الحجم المدرك للمحتوى** يتعطل على الصور الكبيرة (>5 ميجابكسل) بسبب قيد في ثنائي caire. يعمل بشكل جيد مع الصور الأصغر.
 - **فك ترميز HEIF** يستغرق 13-23 ثانية. HEIC (نسخة Apple) أسرع بكثير عند 0.3-0.9 ثانية.
-- **OCR اليابانية** يفشل على المعالج المركزي بسبب علة MKLDNN في PaddlePaddle. يعمل على GPU.
 - **تكبير الدقة** ينتهي وقته على المعالج المركزي لأي شيء يتجاوز الصور الصغيرة. GPU مطلوب للاستخدام العملي.
 - **تحسين الوجوه بـ CodeFormer** أبطأ بشكل ملحوظ من GFPGAN (53 ثانية مقابل 2 ثانية على GPU). يُوصى بـ GFPGAN لمعظم حالات الاستخدام.
 
@@ -434,6 +446,26 @@ securityContext:
 | `SESSION_DURATION_HOURS` | `168` | عمر جلسة تسجيل الدخول (7 أيام) |
 | `CORS_ORIGIN` | (فارغ) | المصادر المسموح بها مفصولة بفواصل، أو فارغ للمصدر نفسه |
 
+### الوكيل الصادر وCA الخاص {#outbound-proxy-and-private-ca}
+
+تتيح الحاوية الرسمية دعم وكيل البيئة الخاص بالعقدة. لو SnapOtter يجب أن تصل إلى OCR مستودع وقت التشغيل أو خدمات HTTPS الأخرى من خلال وكيل الشركة، اضبط `HTTPS_PROXY` (و `HTTP_PROXY` عند الحاجة). قم بتعيين `NO_PROXY` على قائمة مفصولة بفواصل للمضيفين الذين يجب الوصول إليهم مباشرة، مثل Postgres, Redis, وتخزين الكائنات الداخلية.
+
+إذا تم توقيع الوكيل أو الخدمة الداخلية بواسطة مرجع مصدق خاص، فقم بتحميل شهادة CA للقراءة فقط وأشر `NODE_EXTRA_CA_CERTS` إليها. يجب أن يكون الملف موجودًا عند بدء عملية العقدة:
+
+```yaml
+services:
+  app:
+    environment:
+      HTTPS_PROXY: http://proxy.example.internal:3128
+      HTTP_PROXY: http://proxy.example.internal:3128
+      NO_PROXY: postgres,redis,minio,localhost,127.0.0.1
+      NODE_EXTRA_CA_CERTS: /etc/snapotter/custom-ca.pem
+    volumes:
+      - ./company-ca.pem:/etc/snapotter/custom-ca.pem:ro
+```
+
+احتفظ ببيانات اعتماد الوكيل خارج ملف Compose (على سبيل المثال، في ملف `.env` محمي أو سر). لا تقم بتعطيل التحقق من TLS: يقوم فهرس OCR الموقع بالمصادقة على بيانات تعريف الإصدار، بينما لا يزال التحقق من صحة TLS العادي يحمي النقل وكل طلب صادر آخر.
+
 ## فحص الصحة {#health-check}
 
 تتضمن الحاوية فحص صحة مدمجًا: