Конфігурація

Уся конфігурація виконується через змінні середовища. Кожна змінна має розумне значення за замовчуванням, тож SnapOtter працює «з коробки» без задання жодної з них.

Змінні середовища

Сервер

Змінна	За замовчуванням	Опис
PORT	1349	Порт, який слухає сервер.
RATE_LIMIT_PER_MIN	1000	Максимальна кількість запитів за хвилину на одну IP. Задайте 0, щоб вимкнути обмеження частоти запитів.
CORS_ORIGIN	(порожньо)	Розділені комами дозволені джерела для CORS або порожньо лише для того самого джерела.
LOG_LEVEL	info	Детальність журналювання. Одне з: fatal, error, warn, info, debug, trace.
TRUST_PROXY	loopback,linklocal,uniquelocal	Яким вузлам дозволено задавати IP клієнта через X-Forwarded-For. Значення за замовчуванням вірить лише вузлу з приватної мережі, тож зворотному проксі в мережі Docker або в локальній мережі довіра є, а підробленому заголовку від публічного клієнта немає. Задавайте true, лише якщо попереду стоїть підконтрольний вам проксі з публічною адресою.

Автентифікація

Дві булеві змінні нижче приймають лише true і false. Будь-що інше, чи то 1, yes чи on, не проходить перевірку, і сервер завершує роботу, так і не почавши слухати.

Змінна	За замовчуванням	Опис
AUTH_ENABLED	true	Вимагати вхід. Задайте false, щоб працювати взагалі без облікових записів: тоді будь-який запит отримує права адміністратора, тож лишайте так лише в довіреній мережі.
DEFAULT_USERNAME	admin	Ім'я користувача для початкового облікового запису адміністратора. Використовується лише під час першого запуску.
DEFAULT_PASSWORD	admin	Пароль для початкового облікового запису адміністратора. Змініть його після першого входу.
MAX_USERS	0 (необмежено)	Максимальна кількість зареєстрованих облікових записів користувачів. Задайте 0 для необмеженої кількості.
SESSION_DURATION_HOURS	168	Тривалість сеансу входу в годинах (за замовчуванням 7 днів).
SKIP_MUST_CHANGE_PASSWORD	false	Задайте true, щоб пропустити примусовий запит на зміну пароля під час першого входу.

Сховище

Змінна	За замовчуванням	Опис
STORAGE_MODE	local	local або s3. S3 і MinIO потребують ліцензії з функцією s3_storage, а також змінних S3_* нижче.
DATABASE_URL	postgres://snapotter:snapotter@localhost:5432/snapotter	Рядок підключення до PostgreSQL. Стек Compose спрямовує його на власний сервіс postgres; лишіть його незаданим (разом із REDIS_URL), щоб отримати вбудований режим.
REDIS_URL	redis://localhost:6379	Рядок підключення до Redis (використовується для черг завдань BullMQ). Compose спрямовує його на власний сервіс redis.
WORKSPACE_PATH	./tmp/workspace	Каталог для тимчасових файлів під час обробки. Очищується автоматично. Образ задає /tmp/workspace.
FILES_STORAGE_PATH	./data/files	Каталог для постійних файлів користувача (завантажені зображення, збережені результати). Образ задає /data/files.

Об'єктне сховище S3

Читається лише тоді, коли задано STORAGE_MODE=s3. Пропустіть будь-яку з трьох обов'язкових змінних, і запуск завершиться помилкою з назвою тієї змінної, яку ви не задали.

Змінна	За замовчуванням	Опис
S3_BUCKET	(порожньо)	Бакет, у якому зберігаються завантаження та результати. Обов'язкова.
S3_ACCESS_KEY_ID	(порожньо)	Ключ доступу. Обов'язкова. У контейнері його можна натомість змонтувати файлом через S3_ACCESS_KEY_ID_FILE.
S3_SECRET_ACCESS_KEY	(порожньо)	Секретний ключ. Обов'язкова. Та сама домовленість щодо файлів: S3_SECRET_ACCESS_KEY_FILE.
S3_REGION	us-east-1	Регіон бакета.
S3_ENDPOINT	(порожньо)	Власна кінцева точка для MinIO, R2, Backblaze та інших S3-сумісних сховищ. Порожньо означає AWS.
S3_FORCE_PATH_STYLE	false	Задайте true для MinIO та всього іншого, що очікує endpoint/bucket/key замість адресації за віртуальним хостом.
S3_PREFIX	(порожньо)	Префікс ключів, щоб один бакет міг обслуговувати кілька екземплярів.

Шифрування збережених даних

Змінна	За замовчуванням	Опис
DATA_ENCRYPTION_KEY	(порожньо)	64 шістнадцяткові символи (32 байти). Шифрує чутливі налаштування, збережені в базі даних. Будь-що, що не є 64 шістнадцятковими символами, відхиляється під час запуску.
DATA_ENCRYPTION_KEY_PREVIOUS	(порожньо)	Ключ, від якого ви відходите під час ротації, у тому самому форматі. Задайте обидва на час ротації, щоб наявні рядки й далі розшифровувалися, а потім приберіть цей.

Вбудований режим

Запустіть образ без DATABASE_URL і без REDIS_URL, і він запустить власні PostgreSQL 17 і Redis усередині контейнера, прив'язані до loopback, з усіма даними на томі /data. Це відновлює однокомандний досвід docker run для швидкого старту, домашньої лабораторії та оновлень з 1.x. Це шлях для зручності, а не продакшн-розгортання: для продакшну запускайте стек Compose з 3 контейнерів з окремими PostgreSQL і Redis. Вбудований режим вимагає запуску контейнера від root і несумісний із середовищами з довільним UID (OpenShift, Kubernetes runAsNonRoot); там використовуйте Compose.

Змінна	За замовчуванням	Опис
EMBEDDED	auto	Автоматично вмикається, коли і DATABASE_URL, і REDIS_URL не задано. Задайте 0, щоб вимкнути (тоді застосунок швидко завершує роботу, якщо не задано зовнішні DATABASE_URL/REDIS_URL, замість тихого запуску бази даних усередині контейнера).
REDIS_MAXMEMORY	512mb	Обмеження пам'яті для вбудованого Redis (лише вбудований режим). Знизьте його на хостах з обмеженою пам'яттю, як-от Raspberry Pi.

Оновлення з 1.x: покладіть вашу стару snapotter.db за адресою /data/snapotter.db у томі, і вбудований режим імпортує її у вбудований PostgreSQL під час першого запуску. Імпорт виконується один раз; наступні запуски його пропускають.

Примітка про телеметрію: вбудований режим успадковує стандартну аналітику образу, як і будь-яка інша конфігурація. Опублікований образ постачається з увімкненою аналітикою; збирайте з --build-arg SNAPOTTER_ANALYTICS=off або скористайтеся адміністративним відмовленням у застосунку, щоб її вимкнути.

Обмеження обробки

Змінна	За замовчуванням	Опис
MAX_UPLOAD_SIZE_MB	0 (необмежено)	Максимальний розмір файлу на одне завантаження в мегабайтах. Задайте 0 для необмеженого. Опублікований образ постачається зі значенням 0; збірка з вихідного коду починає зі 100.
MAX_BATCH_SIZE	0 (необмежено)	Максимальна кількість файлів в одному пакетному запиті. Задайте 0 для необмеженого. Опублікований образ постачається зі значенням 0; збірка з вихідного коду починає зі 100.
CONCURRENT_JOBS	0 (авто)	Кількість пакетних завдань, що виконуються паралельно. Задайте 0 для автовизначення на основі доступних ядер CPU.
MAX_MEGAPIXELS	0 (необмежено)	Максимальна дозволена роздільна здатність зображення в мегапікселях. Задайте 0 для необмеженого.
MAX_WORKER_THREADS	0 (авто)	Максимальна кількість робочих потоків для обробки зображень. Задайте 0 для автовизначення на основі доступних ядер CPU.
PROCESSING_TIMEOUT_S	0 (без обмеження)	Максимальний час обробки на один запит у секундах. Задайте 0 для відсутності таймауту.
MAX_PIPELINE_STEPS	20	Максимальна кількість кроків у конвеєрі. Задайте 0 для відсутності обмеження.
MAX_CANVAS_PIXELS	0 (без обмеження)	Максимальний розмір полотна в пікселях для вихідних зображень. Задайте 0 для відсутності обмеження.
MAX_SVG_SIZE_MB	50	Найбільший SVG, який приймається перед очищенням, у мегабайтах. Тут 0 поводиться інакше, ніж у сусідніх рядках: він повністю знімає обмеження розміру до розбору, а не піднімає його, тож цю змінну краще лишити заданою.
MAX_PDF_PAGES	0 (необмежено)	Максимальна кількість сторінок PDF для конвертації PDF-у-зображення. Задайте 0 для необмеженого.

Очищення

Змінна	За замовчуванням	Опис
FILE_MAX_AGE_HOURS	72	Як довго незбережені результати обробки (сирі завантаження та виводи інструментів) зберігаються перед автоматичним видаленням. Файли, які ви явно зберегли до бібліотеки Files, не зачіпаються й лишаються, доки ви їх не видалите.
CLEANUP_INTERVAL_MINUTES	60	Як часто виконується завдання очищення.

Зовнішній вигляд

Змінна	За замовчуванням	Опис
DEFAULT_THEME	light	Типова тема для нових сеансів. light, dark або system.
DEFAULT_LOCALE	en	Типова мова інтерфейсу.
DEFAULT_TOOL_VIEW	sidebar	Типове компонування інструментів. sidebar або fullscreen.

Дозволи Docker

Змінна	За замовчуванням	Опис
PUID	999	Запускати процес контейнера з цим UID. Задайте відповідно до вашого хост-користувача для монтувань bind (id -u).
PGID	999	Запускати процес контейнера з цим GID. Задайте відповідно до вашої хост-групи для монтувань bind (id -g).

Приклад Docker

services:
  SnapOtter:
    image: snapotter/snapotter:latest
    ports:
      - "1349:1349"
    volumes:
      - SnapOtter-data:/data
      - SnapOtter-workspace:/tmp/workspace
    environment:
      - AUTH_ENABLED=true
      - DEFAULT_USERNAME=admin
      - DEFAULT_PASSWORD=changeme
      - DATABASE_URL=postgres://snapotter:snapotter@postgres:5432/snapotter
      - REDIS_URL=redis://redis:6379
      - MAX_UPLOAD_SIZE_MB=200
      - CONCURRENT_JOBS=4
      - FILE_MAX_AGE_HOURS=12
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: snapotter
      POSTGRES_PASSWORD: snapotter     # Змініть це для нелокальних розгортань
      POSTGRES_DB: snapotter
    volumes:
      - SnapOtter-pgdata:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U snapotter -d snapotter"]
      interval: 10s
      timeout: 5s
      retries: 12

  redis:
    image: redis:8-alpine
    command: ["redis-server", "--maxmemory-policy", "noeviction", "--appendonly", "yes"]
    volumes:
      - SnapOtter-redisdata:/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 12

volumes:
  SnapOtter-data:
  SnapOtter-workspace:
  SnapOtter-pgdata:
  SnapOtter-redisdata:

Томи

Стек Docker Compose використовує чотири томи:

• /data (app) - моделі AI, Python venv і файли користувача. Змонтуйте його, щоб зберігати завантажені файли та встановлені пакети AI між перезапусками.
• /tmp/workspace (app) - тимчасове сховище для файлів, що обробляються. Воно може бути ефемерним, але монтування уникає заповнення записуваного шару контейнера.
• SnapOtter-pgdata (postgres) - каталог даних PostgreSQL. Він містить усі реляційні дані (користувачі, налаштування, конвеєри, завдання, журнал аудиту). Робіть резервну копію через pg_dump або знімок тому.
• SnapOtter-redisdata (redis) - файл append-only Redis для стійких черг завдань.