الإعداد

يتم كل الإعداد عبر متغيّرات البيئة. لكل متغيّر قيمة افتراضية معقولة، لذا يعمل 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	(فارغ)	الحاوية (bucket) التي تحتفظ بالملفات المرفوعة والمخرجات. مطلوب.
S3_ACCESS_KEY_ID	(فارغ)	مفتاح الوصول. مطلوب. داخل حاوية Docker يمكنك تحميله كملف بدلًا من ذلك عبر S3_ACCESS_KEY_ID_FILE.
S3_SECRET_ACCESS_KEY	(فارغ)	المفتاح السري. مطلوب. الاصطلاح نفسه للملفات: S3_SECRET_ACCESS_KEY_FILE.
S3_REGION	us-east-1	منطقة الحاوية (bucket).
S3_ENDPOINT	(فارغ)	نقطة نهاية مخصّصة لـ MinIO وR2 وBackblaze وغيرها من المخازن المتوافقة مع S3. الفراغ يعني AWS.
S3_FORCE_PATH_STYLE	false	اضبطه على true لـ MinIO وكل ما يتوقع endpoint/bucket/key بدل العنونة بالمضيف الافتراضي.
S3_PREFIX	(فارغ)	بادئة المفاتيح، لتستوعب حاوية (bucket) واحدة عدة نسخ.

تشفير البيانات المخزّنة

المتغيّر	الافتراضي	الوصف
DATA_ENCRYPTION_KEY	(فارغ)	64 خانة ست عشرية (32 بايت). يشفّر الإعدادات الحساسة المخزّنة في قاعدة البيانات. وأي قيمة ليست 64 خانة ست عشرية تُرفض عند الإقلاع.
DATA_ENCRYPTION_KEY_PREVIOUS	(فارغ)	المفتاح الذي تنتقل منه أثناء التدوير، بالصيغة نفسها. اضبط الاثنين خلال التدوير حتى تبقى الصفوف الموجودة قابلة لفك التشفير، ثم احذف هذا.

الوضع المدمج

شغّل الصورة دون DATABASE_URL ودون REDIS_URL فتبدأ PostgreSQL 17 وRedis خاصتين بها داخل الحاوية، مقيَّدتين بالحلقة المحلية، مع كل البيانات على وحدة تخزين /data. يستعيد هذا تجربة docker run بأمر واحد للبدء السريع والمعمل المنزلي والترقيات من الإصدار 1.x. إنه مسار ملائم، لا نشر إنتاجي: للإنتاج، شغّل حزمة Compose من 3 حاويات مع PostgreSQL وRedis منفصلين. يتطلب الوضع المدمج تشغيل الحاوية بصلاحية الجذر وهو غير متوافق مع أنظمة التشغيل بمعرّف مستخدم اعتباطي (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	مدة الاحتفاظ بنتائج المعالجة غير المحفوظة (عمليات الرفع الخام ومُخرَجات الأدوات) قبل الحذف التلقائي. الملفات التي تحفظها صراحةً في مكتبة الملفات لا تتأثر وتبقى حتى تحذفها.
CLEANUP_INTERVAL_MINUTES	60	عدد مرات تشغيل مهمة التنظيف.

المظهر

المتغيّر	الافتراضي	الوصف
DEFAULT_THEME	light	السمة الافتراضية للجلسات الجديدة. light أو dark أو system.
DEFAULT_LOCALE	en	لغة الواجهة الافتراضية.
DEFAULT_TOOL_VIEW	sidebar	تخطيط الأداة الافتراضي. sidebar أو fullscreen.

أذونات Docker

المتغيّر	الافتراضي	الوصف
PUID	999	شغّل عملية الحاوية بهذا المعرّف UID. اضبطه ليطابق مستخدم مضيفك للتثبيتات المرتبطة (id -u).
PGID	999	شغّل عملية الحاوية بهذا المعرّف GID. اضبطه ليطابق مجموعة مضيفك للتثبيتات المرتبطة (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 (التطبيق) - نماذج الذكاء الاصطناعي، وبيئة Python الافتراضية، وملفات المستخدم. ثبّتها للحفاظ على الملفات المرفوعة وحزم الذكاء الاصطناعي المثبَّتة عبر عمليات إعادة التشغيل.
• /tmp/workspace (التطبيق) - تخزين مؤقت للملفات قيد المعالجة. يمكن أن يكون عابرًا، لكن تثبيته يتجنّب ملء الطبقة القابلة للكتابة في الحاوية.
• SnapOtter-pgdata (postgres) - مجلد بيانات PostgreSQL. يحفظ كل البيانات العلائقية (المستخدمون، والإعدادات، وخطوط الأنابيب، والمهام، وسجل التدقيق). انسخه احتياطيًا عبر pg_dump أو لقطة وحدة تخزين.
• SnapOtter-redisdata (redis) - ملف Redis للإلحاق فقط لطوابير مهام دائمة.