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
@@ -1,7 +1,7 @@
 ---
 description: "Розгорніть SnapOtter у продакшені за допомогою Docker. Вимоги до апаратного забезпечення, налаштування GPU та конфігурації зворотного проксі для Nginx, Traefik і Cloudflare."
 i18n_output_hash: 4d221e5eaf97
-i18n_source_hash: e0d8d5f6fc87
+i18n_source_hash: 98172965118b
 i18n_provenance: human
 ---

@@ -218,6 +218,8 @@ docker logs SnapOtter 2>&1 | head -20

 Ці цифри отримані з бенчмарків на низці систем, від сучасної робочої станції amd64 з NVIDIA RTX 4070 до Raspberry Pi, на яких запускали весь каталог інструментів і перебирали ліміти ресурсів Docker, щоб знайти реальний мінімум.

+Працюєте на нижній межі цих рівнів (Pi, старий ноутбук, VPS із 2 GB)? Сторінка [Робота на слабкому обладнанні](/uk/guide/low-resource) перетворює ці цифри на конкретний покроковий посібник із підібраними лімітами.
+
 ### Швидка довідка {#quick-reference}

 | Рівень | Сценарій використання | CPU | RAM | GPU | Сховище |
@@ -1,7 +1,7 @@
 ---
 description: "Встановіть SnapOtter за допомогою Docker однією командою. Включає налаштування Docker Compose, збирання з вихідного коду й повний огляд функцій."
 i18n_output_hash: a97c15d102b5
-i18n_source_hash: 24724b5595b2
+i18n_source_hash: 68bf7f60b68d
 i18n_provenance: human
 ---

@@ -19,6 +19,8 @@ docker run -d --name SnapOtter -p 1349:1349 -v SnapOtter-data:/data snapotter/sn

 Цей єдиний контейнер запускає все, що йому потрібно: без встановленого `DATABASE_URL` він запускає власні PostgreSQL і Redis на інтерфейсі loopback (вбудований режим) і зберігає всі дані в томі `SnapOtter-data`. Це найшвидший спосіб спробувати SnapOtter або самостійно розмістити його в homelab. Для продакшену запустіть стек [Docker Compose](#docker-compose) нижче, який тримає PostgreSQL і Redis у власних контейнерах. Вбудований режим працює від root (за замовчуванням) і автоматично вимикається, щойно ви встановлюєте `DATABASE_URL`.

+Встановлюєте на Raspberry Pi, старому ноутбуці чи невеликому VPS? Див. [Робота на слабкому обладнанні](/uk/guide/low-resource): там є покроковий посібник із підібраними налаштуваннями й пояснення, чого очікувати від обмеженого обладнання.
+
 Під час першого входу вас попросять змінити пароль.

 ::: tip Анонімна продуктова аналітика
@@ -0,0 +1,103 @@
+---
+i18n_source_hash: f5de74aee1b9
+i18n_provenance: machine
+i18n_output_hash: 27b701493717
+---
+# Робота на слабкому обладнанні {#low-resource-setups}
+
+SnapOtter добре працює на скромному обладнанні: Raspberry Pi 4 чи 5, старому ноутбуці або VPS із 2 GB пам'яті. Ця сторінка є практичним посібником для таких машин: чого очікувати, готове до копіювання налаштування з розумними лімітами й які функції варто пропустити. Повні дані бенчмарків, на яких ґрунтуються ці цифри, наведено в розділі [Вимоги до апаратного забезпечення](/uk/guide/deployment#hardware-requirements).
+
+Два жорсткі обмеження одразу:
+
+- **Тільки 64-бітні системи.** Образ збирається для `linux/amd64` і `linux/arm64`. 32-бітний ARM (`armv7`/`armhf`) не підтримується, тож Pi першого покоління та сімейство Pi Zero відпадають.
+- **Мінімум 2 GB пам'яті.** 512 MB не запустять стек, а 1 GB не витримує пакетів із кількох файлів. Найменша конфігурація, що працює комфортно: 2 GB і 2 ядра.
+
+## Що добре працює на слабкому обладнанні {#what-runs-well}
+
+Кожен інструмент без AI працює на машині з 2 GB і 2 ядрами: цілі розділи «Зображення» та «Файли», PDF-інструменти, а також відео- та аудіооперації з копіюванням потоку (обрізання, вимкнення звуку, зміна контейнера). Більшість завершується менш ніж за секунду.
+
+Винятками є два типи навантаження:
+
+- **Перекодування відео** (конвертація між кодеками) обмежене процесором. Кліп 1080p, який на швидкому десктопному CPU займає ~40 с, на процесорі класу Pi може тривати кілька хвилин. Операції з копіюванням потоку залишаються миттєвими.
+- **AI-інструменти** потребують RAM (рекомендовано 4 GB) і диска (більші бандли займають по 4-5 GB кожен), а важкі з них (масштабування, відновлення фото, видалення фону) непрактичні на процесорах класу Pi. Легкий AI, як-от виявлення облич і OCR, цілком придатний, якщо вистачає пам'яті.
+
+Жодне з цих навантажень не встановлюється й не запускається, доки ви ним не користуєтеся: без встановлених AI-бандлів застосунок у простої займає близько 360 MB, а AI-бандли завантажуються лише тоді, коли адміністратор їх вмикає.
+
+## Покрокове налаштування Raspberry Pi / старого ноутбука {#walkthrough}
+
+Це стандартне встановлення через Compose зі сторінки [Початок роботи](/uk/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` (див. [Конфігурація](/uk/guide/configuration)). Compose дає точніший контроль на рівні окремих сервісів, саме тому цей посібник використовує його.
+- **Додайте swap на пристроях із 2 GB.** Це вбереже від того, щоб випадковий сплеск (великий PDF, пакет, який ви забули обмежити) закінчився аварійним завершенням через брак пам'яті. Для SD-карт найдружніший варіант: zram.
+- Образ arm64 працює лише на CPU; CUDA на платах ARM немає.
+
+## Параметри тонкого налаштування {#tuning-knobs}
+
+Усі ліміти задаються змінними середовища й повністю задокументовані на сторінці [Конфігурація](/uk/guide/configuration). `0` означає «без обмежень» або «авто». Ось ті, що мають значення на слабкому обладнанні:
+
+| Змінна | Порада для слабкої машини | Що вона захищає |
+|---|---|---|
+| `CONCURRENT_JOBS` | `1` | Скільки завдань виконується паралельно. Автовизначення бере кількість ядер CPU мінус одне: це нормально для потужних машин і занадто агресивно для 2-ядерної під тиском пам'яті. |
+| `MAX_WORKER_THREADS` | `2` | Пул потоків обробки зображень. |
+| `MAX_BATCH_SIZE` | `5` | Саме на пакетах машини з 1-2 GB найпершими вичерпують пам'ять. |
+| `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}
+
+- **Важкі AI-бандли.** Масштабування, відновлення фото й видалення фону потребують GPU або швидкого багатоядерного CPU, а кожен бандл займає 4-5 GB диска. На слабкій машині просто не встановлюйте їх; інструменти, чий бандл відсутній, показують запит на встановлення замість запуску.
+- **Перекодування відео як регулярне навантаження.** Поодинокі перекодування цілком прийнятні (вони просто повільні); постійна черга перекодувань потребує ядер CPU, а не Pi.
+- **Загалом невикористовувані інструменти.** Адміністратор може вимкнути окремі інструменти в Settings, що прибирає їх з інтерфейсу та припиняє реєстрацію їхніх API-маршрутів. Саме по собі це не економить пам'ять, але не дає використовувати спільний невеликий екземпляр для того єдиного навантаження, якого обладнання не витримує.
+
+Якщо згодом ви перенесете екземпляр на потужніше обладнання, приберіть ліміти (поверніть їх до `0`), і той самий том даних переїде разом з ним.
@@ -1,7 +1,7 @@
 ---
 description: "Посібник із посилення безпеки для SnapOtter. Безпека контейнерів, мережева ізоляція, секрети Docker, розгортання в Kubernetes та артефакти відповідності."
 i18n_source_hash: 986f7658430c
-i18n_provenance: machine
+i18n_provenance: human
 i18n_output_hash: 6b9158af7666
 ---