docs(guide): add a low-resource deployment guide in 21 languages (#548)

New guide/low-resource page: what runs well on 2 GB machines, a Raspberry Pi / old laptop Compose walkthrough with tuned caps, the env-var knobs that matter on small hardware, and what to skip. Linked from getting-started, the deployment hardware section, and the sidebar. Translated into all 20 non-English locales via the i18n batch pipeline; parity check and VitePress build pass. Admin merge: docs-only PR, the path-filtered required integration contexts never report (#420 precedent). Closes #497
2026-08-03 07:46:42 +02:00 · 2026-07-17 00:40:48 +08:00
parent 1f4878ac4d
commit fe85dd2b98
104 changed files with 2323 additions and 80 deletions
@@ -0,0 +1,103 @@
+---
+i18n_source_hash: f5de74aee1b9
+i18n_provenance: machine
+i18n_output_hash: e66e6e2d05d0
+---
+# Установка на маломощном оборудовании {#low-resource-setups}
+
+SnapOtter хорошо работает на маломощном оборудовании: Raspberry Pi 4 или 5, старом ноутбуке или VPS с 2 ГБ памяти. Эта страница служит практическим руководством для таких машин: чего ожидать, готовая для копирования конфигурация с разумными лимитами и какие функции лучше пропустить. Полные данные бенчмарков, на которых основаны эти цифры, находятся в разделе [Требования к оборудованию](/ru/guide/deployment#hardware-requirements).
+
+Два жёстких ограничения с самого начала:
+
+- **Только 64 бита.** Образ собирается для `linux/amd64` и `linux/arm64`. 32-битный ARM (`armv7`/`armhf`) не поддерживается, поэтому Pi первого поколения и семейство Pi Zero отпадают.
+- **Минимум 2 ГБ памяти.** С 512 МБ стек не запускается, а 1 ГБ не хватает на многофайловых пакетах. Наименьшая комфортно работающая конфигурация: 2 ГБ и 2 ядра.
+
+## Что хорошо работает на маломощном оборудовании {#what-runs-well}
+
+Каждый инструмент без ИИ работает на машине с 2 ГБ и 2 ядрами: разделы «Изображения» и «Файлы» целиком, PDF-инструменты, а также видео- и аудиооперации с копированием потока (обрезка, отключение звука, смена контейнера). Большинство завершается менее чем за секунду.
+
+Исключение составляют два типа нагрузки:
+
+- **Перекодирование видео** (конвертация между кодеками) упирается в CPU. Клип 1080p, который занимает ~40 с на быстром десктопном CPU, может обрабатываться несколько минут на CPU класса Pi. Операции с копированием потока остаются мгновенными.
+- **ИИ-инструментам** нужны RAM (рекомендуется 4 ГБ) и диск (крупные наборы моделей занимают по 4-5 ГБ каждый), а тяжёлые из них (апскейл, восстановление фото, удаление фона) непрактичны на CPU класса Pi. Лёгкий ИИ, такой как распознавание лиц и OCR, вполне пригоден, если на него хватает памяти.
+
+Ничто из этого не устанавливается и не работает, пока вы этим не пользуетесь: без установленных ИИ-наборов приложение в простое занимает около 360 МБ, а ИИ-наборы скачиваются только тогда, когда администратор их включает.
+
+## Пошаговая установка на Raspberry Pi / старом ноутбуке {#walkthrough}
+
+Это стандартная установка через Compose из раздела [Начало работы](/ru/guide/getting-started) плюс лимиты ресурсов и консервативные ограничения. Предполагается 64-битная ОС (на Pi: Raspberry Pi OS 64-bit или Ubuntu Server arm64).
+
+```yaml
+services:
+  snapotter:
+    image: snapotter/snapotter:latest
+    ports:
+      - "1349:1349"
+    volumes:
+      - ./snapotter-data:/data
+    environment:
+      - DATABASE_URL=postgres://snapotter:snapotter@db:5432/snapotter
+      - REDIS_URL=redis://redis:6379
+      # Small-box profile: see the table below for what each cap does.
+      - CONCURRENT_JOBS=1
+      - MAX_WORKER_THREADS=2
+      - MAX_BATCH_SIZE=5
+      - MAX_UPLOAD_SIZE_MB=100
+      - MAX_MEGAPIXELS=50
+      - MAX_VIDEO_DURATION_S=300
+    deploy:
+      resources:
+        limits:
+          cpus: "2"
+          memory: 2G
+    depends_on:
+      - db
+      - redis
+    restart: unless-stopped
+
+  db:
+    image: postgres:17-alpine
+    environment:
+      - POSTGRES_USER=snapotter
+      - POSTGRES_PASSWORD=snapotter
+      - POSTGRES_DB=snapotter
+    volumes:
+      - ./postgres-data:/var/lib/postgresql/data
+    restart: unless-stopped
+
+  redis:
+    image: redis:8-alpine
+    command: redis-server --maxmemory 256mb --maxmemory-policy noeviction
+    restart: unless-stopped
+```
+
+Замечания для машин класса Pi:
+
+- **Предпочитайте USB SSD, а не SD-карту** для тома данных и Postgres. Рабочие каталоги заданий создают реальную дисковую нагрузку, а SD-карты и медленные, и быстро изнашиваются.
+- **Единый контейнер «всё в одном» здесь тоже работает** (встроенные Postgres и Redis, когда `DATABASE_URL`/`REDIS_URL` не заданы), и на хосте с ограниченной памятью стоит снизить лимит его встроенного Redis через `REDIS_MAXMEMORY` (см. [Конфигурация](/ru/guide/configuration)). Compose даёт более тонкий контроль по каждому сервису, поэтому в этом руководстве используется именно он.
+- **Добавьте swap на устройствах с 2 ГБ.** Он не даёт случайному всплеску (большой PDF, пакет, который вы забыли ограничить) закончиться завершением процесса из-за нехватки памяти. Вариант, щадящий SD-карту: zram.
+- Образ arm64 работает только на CPU; CUDA на платах ARM нет.
+
+## Параметры настройки {#tuning-knobs}
+
+Все лимиты задаются переменными окружения и полностью документированы в разделе [Конфигурация](/ru/guide/configuration). `0` означает «без ограничений» или «авто». Вот те, что важны на маломощном оборудовании:
+
+| Переменная | Рекомендация для маломощной машины | Что она защищает |
+|---|---|---|
+| `CONCURRENT_JOBS` | `1` | Сколько заданий выполняется параллельно. Автоопределение берёт число ядер CPU минус одно: это нормально на больших машинах и слишком агрессивно на 2-ядерной машине при нехватке памяти. |
+| `MAX_WORKER_THREADS` | `2` | Пул потоков обработки изображений. |
+| `MAX_BATCH_SIZE` | `5` | Пакетная обработка: именно на ней машинам с 1-2 ГБ первым делом не хватает памяти. |
+| `MAX_UPLOAD_SIZE_MB` | `100` | Не даёт одному огромному файлу занять всё рабочее пространство. |
+| `MAX_MEGAPIXELS` | `50` | Декодирование изображения на 100+ Мп расходует RAM независимо от размера файла. |
+| `MAX_VIDEO_DURATION_S` | `300` | Долгие перекодирования занимают слабый CPU на минуты и даже часы. |
+| `PROCESSING_TIMEOUT_S` | `600` | Жёсткий потолок, чтобы вышедшее из-под контроля задание рано или поздно освободило машину. |
+
+Эти лимиты определяют, что сервер принимает, поэтому настраивайте их под то, чем вы реально пользуетесь, а не как можно меньше. Если вы не работаете с видео, ограничение `MAX_VIDEO_DURATION_S` ничего не стоит; если вы ежедневно сканируете документы, не ограничивайте `MAX_PDF_PAGES`.
+
+## Что пропустить {#what-to-skip}
+
+- **Тяжёлые ИИ-наборы.** Апскейлу, восстановлению фото и удалению фона нужен GPU или быстрый многоядерный CPU, а каждый набор занимает 4-5 ГБ на диске. На маломощной машине просто не устанавливайте их; инструменты, чей набор не установлен, показывают предложение установки вместо запуска.
+- **Перекодирование видео как регулярная нагрузка.** Разовые перекодирования допустимы (они просто медленные); постоянной очереди перекодирования нужны ядра CPU, а не Pi.
+- **Неиспользуемые инструменты в целом.** Администратор может отключать отдельные инструменты в Settings: они исчезают из интерфейса, а их API-маршруты перестают регистрироваться. Само по себе это не экономит память, но не даёт использовать общий небольшой экземпляр под ту единственную нагрузку, которую оборудование не потянет.
+
+Если позже вы перенесёте экземпляр на более мощное оборудование, уберите лимиты (верните их в `0`), и тот же том данных продолжит работать.