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

@@ -1,8 +1,8 @@
 ---
 description: "Разверните SnapOtter в продакшене с помощью Docker. Требования к оборудованию, настройка GPU и конфигурации обратного прокси для Nginx, Traefik и Cloudflare."
-i18n_source_hash: 6b6957060fa6
-i18n_provenance: machine
-i18n_output_hash: 8992ab5d785b
+i18n_output_hash: b5d2efef5f93
+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 на ИИ-инструментах (удаление фона, апскейлинг, улучшение лиц, OCR):
+Для ускорения NVIDIA CUDA с помощью поддерживаемых инструментов искусственного интеллекта (удаление фона, масштабирование, улучшение лица):
 
 ```yaml
 # docker-compose-gpu.yml - Requires: NVIDIA GPU + nvidia-container-toolkit
@@ -251,10 +257,10 @@ deploy:
 |---|---|
 | CPU | 4 ядра |
 | RAM | 4 ГБ |
-| Диск | 3 ГБ (образ) + 24 ГБ (модели ИИ) + рабочее пространство |
+| Disk | 3 ГБ (образ) + около 20 ГБ (все дополнительные пакеты AI) + рабочее пространство |
 | GPU | Не требуется (запасной вариант на CPU) |
 
-**Именно установка ИИ-пакетов повышает требования к RAM до 4 ГБ.** Без установленного ИИ приложение простаивает примерно на 360 МБ; со всеми семью установленными пакетами оно удерживает ~2,6 ГБ в резиденции, потому что Python-сайдкар ИИ предзагружает свои модели (удаление фона, апскейлинг, OCR, транскрипция, обнаружение лиц, реставрация) при запуске. Установки без ИИ остаются лёгкими; установки с ИИ требуют ≥4 ГБ.
+**Установка и запуск более крупных пакетов AI заставляет рекомендовать RAM 4 ГБ.** Без установленных дополнительных пакетов приложение занимает около 360 МБ. Устаревшие инструменты Python используют sidecar, тогда как точный OCR использует выделенный долгоживущий dispatcher, прикрепленный к активному неизменяемому поколению. Перед активацией установщик запускает smoke test на кандидате. Затем он атомарно переключается на новый dispatcher и сливает предыдущий dispatcher перед garbage collection. Каждый официальный артефакт точного оптического распознавания символов должен передавать свой наихудший вариант release suite внутри 4 GiB cgroup, в то время как рекомендация по хосту размером 4 ГБ оставляет место для приложения Node.js, Postgres, Redis, очередей и параллельной работы.
 
 Большинство ИИ-инструментов вполне пригодны на CPU; пара действительно требует GPU. Измерено на современном 4-ядерном CPU:
 
@@ -271,7 +277,7 @@ SnapOtter намеренно не встраивает загрузки этих
 
 Некоторые инструменты зависят от более чем одного общего пакета. Например, для инструмента Passport Photo требуются оба пакета `background-removal` и `face-detection`; если `background-removal` уже установлен, включение Passport Photo загружает только недостающий пакет `face-detection`. То же повторное использование применяется ко всем ИИ-инструментам.
 
-Размеры загрузок моделей ИИ:
+Дополнительные оценки объема хранилища AI-пакетов:
 
 | Пакет | Размер на диске |
 |---|---|
@@ -279,9 +285,16 @@ SnapOtter намеренно не встраивает загрузки этих
 | Апскейл + Улучшение лиц + Удаление шума | 5-6 ГБ |
 | Обнаружение лиц | 200-300 МБ |
 | Ластик объектов + Раскрашивание | 1-2 ГБ |
-| OCR | 5-6 ГБ |
+| Точный OCR (`balanced`/`best`) | ~208-234 Загрузка MiB / ~409-488 Установка MiB |
 | Реставрация фото | 4-5 ГБ |
-| **Все пакеты** | **~24 ГБ** |
+| Транскрипция | ~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+ входных форматов** и **
 
 - **Изменение размера с учётом содержимого** аварийно завершается на больших изображениях (>5 Мп) из-за ограничения в бинарнике caire. Нормально работает с изображениями меньшего размера.
 - **Декодирование HEIF** занимает 13-23 секунды. HEIC (вариант Apple) намного быстрее: 0,3-0,9 секунды.
-- **OCR для японского** не работает на CPU из-за ошибки MKLDNN в PaddlePaddle. Работает на GPU.
 - **Апскейл** превышает тайм-аут на CPU для всего, кроме малых изображений. Для практического использования требуется GPU.
 - Улучшение лиц **CodeFormer** значительно медленнее, чем GFPGAN (53 с против 2 с на GPU). Для большинства случаев рекомендуется GFPGAN.
 
@@ -434,6 +446,26 @@ securityContext:
 | `SESSION_DURATION_HOURS` | `168` | Время жизни сессии входа (7 дней) |
 | `CORS_ORIGIN` | (пусто) | Разрешённые источники через запятую, или пусто для same-origin |
 
+### Исходящий прокси и частный центр сертификации {#outbound-proxy-and-private-ca}
+
+Официальный контейнер обеспечивает поддержку прокси-сервера среды Node. Если SnapOtter должен получить доступ к репозиторию среды выполнения OCR или другим службам HTTPS через корпоративный прокси-сервер, установите `HTTPS_PROXY` (и `HTTP_PROXY`, если необходимо). Задайте для `NO_PROXY` список хостов, разделенных запятыми, к которым необходимо получить прямой доступ, например Postgres, Redis и внутреннее объектное хранилище.
+
+Если прокси-сервер или внутренняя служба подписаны частным центром сертификации, смонтируйте сертификат CA только для чтения и укажите на него `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}
 
 Контейнер включает встроенную проверку работоспособности: