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/uk/guide/deployment.md

@@ -1,8 +1,8 @@
 ---
 description: "Розгорніть SnapOtter у продакшені за допомогою Docker. Вимоги до апаратного забезпечення, налаштування GPU та конфігурації зворотного проксі для Nginx, Traefik і Cloudflare."
-i18n_source_hash: 6b6957060fa6
-i18n_provenance: machine
-i18n_output_hash: 823840401d54
+i18n_output_hash: 4d221e5eaf97
+i18n_source_hash: e0d8d5f6fc87
+i18n_provenance: human
 ---
 
 # Розгортання {#deployment}
@@ -11,6 +11,12 @@ SnapOtter розгортається як стек Docker Compose із 3 кон
 
 Див. [Docker Image](./docker-tags) щодо налаштування GPU, прикладів Docker Compose і фіксації версій.
 
+
+<!-- korean-ocr-contract:start -->
+::: info Сумісність OCR для корейської мови
+Швидкий OCR підтримує `auto`, `en`, `de`, `es`, `fr`, `zh` і `ja`, але не корейську мову (`ko`). Для корейської потрібен пакет точного OCR і рівень `balanced` або `best`. Пакет працює в офіційних контейнерах Linux amd64 і arm64, зокрема на вузлах NVIDIA, де OCR і далі виконується на CPU. Непідтримувані системи отримують явну помилку сумісності без прихованого переходу на `fast`. Корейська з `fast` або застарілим псевдонімом `tesseract` відхиляється до постановки в чергу з `FEATURE_INCOMPATIBLE` і `fast-korean-unsupported`.
+:::
+<!-- korean-ocr-contract:end -->
 ## Швидкий старт (CPU) {#quick-start-cpu}
 
 ```yaml
@@ -113,7 +119,7 @@ docker compose up -d
 
 ## Швидкий старт (NVIDIA CUDA) {#quick-start-nvidia-cuda}
 
-Для прискорення через NVIDIA CUDA на AI-інструментах (видалення фону, збільшення роздільності, покращення облич, OCR):
+Для прискорення NVIDIA CUDA у підтримуваних інструментах ШІ (видалення фону, масштабування, покращення обличчя):
 
 ```yaml
 # docker-compose-gpu.yml - Requires: NVIDIA GPU + nvidia-container-toolkit
@@ -251,10 +257,10 @@ deploy:
 |---|---|
 | CPU | 4 ядра |
 | RAM | 4 GB |
-| Диск | 3 GB (образ) + 24 GB (моделі AI) + робочий простір |
+| Disk | 3 ГБ (зображення) + близько 20 ГБ (усі додаткові пакети AI) + робочий простір |
 | GPU | Не потрібен (резервний варіант на CPU) |
 
-**Саме встановлення AI-бандлів піднімає RAM до 4 GB.** Без встановленого AI застосунок у стані спокою займає близько 360 MB; з усіма сімома встановленими бандлами він тримає ~2.6 GB резидентно, оскільки Python AI-сайдкар попередньо завантажує свої моделі (видалення фону, збільшення роздільності, OCR, транскрипція, виявлення облич, реставрація) під час запуску. Не-AI встановлення залишаються легкими; AI-встановлення потребують ≥4 GB.
+**Встановлення та запуск більших пакетів штучного інтелекту – це те, що підштовхує рекомендацію до 4 ГБ RAM.** Без встановлення додаткових пакетів програма простоює близько 360 МБ. Застарілі інструменти Python використовують sidecar, тоді як точний OCR використовує виділений довготривалий dispatcher, закріплений на активному незмінному поколінні. Перед активацією інсталятор запускає smoke test на кандидаті. Потім він автоматично перемикається на новий dispatcher і зливає попередній dispatcher перед garbage collection. Кожен офіційний артефакт точного OCR повинен передати свій найгірший release suite всередині 4 GiB cgroup, тоді як рекомендація хосту 4 ГБ залишає запас для програми Node.js, Postgres, Redis, черг і одночасної роботи.
 
 Більшість AI-інструментів цілком придатні до використання на CPU; парі з них справді потрібен GPU. Виміряно на сучасному 4-ядерному CPU:
 
@@ -271,7 +277,7 @@ SnapOtter навмисно не запікає ці завантаження м
 
 Деякі інструменти залежать від більш ніж одного спільного бандла. Наприклад, Passport Photo потребує і `background-removal`, і `face-detection`; якщо `background-removal` вже встановлено, увімкнення Passport Photo завантажує лише відсутній бандл `face-detection`. Те саме повторне використання застосовується до всіх AI-інструментів.
 
-Розміри завантажень моделей AI:
+Приблизний обсяг пам’яті додаткового набору AI:
 
 | Бандл | Розмір на диску |
 |---|---|
@@ -279,9 +285,16 @@ SnapOtter навмисно не запікає ці завантаження м
 | Upscale + Покращення облич + Видалення шуму | 5-6 GB |
 | Виявлення облич | 200-300 MB |
 | Стирання об'єктів + Colorize | 1-2 GB |
-| OCR | 5-6 GB |
+| Точний OCR (`balanced`/`best`) | ~208-234 MiB завантажити / ~409-488 MiB встановити |
 | Реставрація фото | 4-5 GB |
-| **Усі бандли** | **~24 GB** |
+| Транскрипція | ~600 МБ |
+| **Усі набори** | **~20 ГБ встановлено** |
+
+Швидкий 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`, мають працювати на однаковій архітектурі ЦП; закріплюйте розгортання з кількома репліками за сумісними вузлами за допомогою спорідненості вузлів (node affinity). Для змішаних реплік amd64/arm64 потрібні окремі томи даних і незалежні розгортання SnapOtter.
+
+Точний час виконання зберігає одне активне покоління та очищає його кеш завантажень після активації. Для цього випуску перша інсталяція тимчасово потребує приблизно 620-720 MiB для архіву та постановки, а оновлення може досягти піку близько 1,2 GiB, поки старе покоління залишається активним. Програма інсталяції обчислює точні вимоги з підписаного індексу та поточних поколінь перед завантаженням або витягуванням і зазнає помилки раніше, якщо обсяг даних замалий.
 
 ```yaml
 deploy:
@@ -353,7 +366,6 @@ SnapOtter підтримує **55+ вхідних форматів** і **14 в
 
 - **Зміна розміру з урахуванням вмісту** аварійно завершується на великих зображеннях (>5 MP) через обмеження в бінарному файлі caire. Добре працює з меншими зображеннями.
 - **Декодування HEIF** займає 13-23 секунди. HEIC (варіант Apple) значно швидший — 0.3-0.9 секунди.
-- **OCR для японської** дає збій на CPU через баг MKLDNN у PaddlePaddle. Працює на GPU.
 - **Upscale** дає таймаут на CPU для всього, крім малих зображень. Для практичного використання потрібен 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}
+
+Офіційний контейнер забезпечує підтримку проксі середовища Node. Якщо SnapOtter має отримати доступ до сховища часу виконання OCR або інших служб HTTPS через корпоративний проксі, установіть `HTTPS_PROXY` (і `HTTP_PROXY`, якщо потрібно). Встановіть для `NO_PROXY` розділений комами список хостів, до яких потрібно отримати прямий доступ, наприклад Postgres, Redis і внутрішнє сховище об’єктів.
+
+Якщо проксі-сервер або внутрішня служба підписана приватним центром сертифікації, підключіть сертифікат ЦС лише для читання та вкажіть на нього `NODE_EXTRA_CA_CERTS`. Файл повинен існувати на момент запуску процесу Node:
+
+```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}
 
 Контейнер містить вбудовану перевірку стану: