Deployment

SnapOtter ปรับใช้เป็นสแตก Docker Compose แบบ 3 คอนเทนเนอร์: อิมเมจแอป SnapOtter, PostgreSQL 17 และ Redis 8 อิมเมจแอปรองรับ linux/amd64 (พร้อม NVIDIA CUDA สำหรับการเร่งความเร็ว AI) และ linux/arm64 (CPU) จึงทำงานได้แบบเนทีฟบนเซิร์ฟเวอร์ Intel/AMD, Mac ที่ใช้ Apple Silicon และอุปกรณ์ ARM อย่าง Raspberry Pi 4/5 ปัจจุบันยังไม่รองรับการเร่งความเร็วด้วย iGPU ของ Intel/AMD ผ่าน VA-API, Quick Sync หรือ OpenCL สำหรับการอนุมาน AI

ดู Docker Image สำหรับการตั้งค่า GPU ตัวอย่าง Docker Compose และการปักหมุดเวอร์ชัน

Quick Start (CPU)

yaml

# docker-compose.yml - Copy this file and run: docker compose up -d
services:
  SnapOtter:
    image: snapotter/snapotter:latest    # or ghcr.io/snapotter-hq/snapotter:latest
    container_name: SnapOtter
    ports:
      - "1349:1349"                # Web UI + API
    volumes:
      - SnapOtter-data:/data           # AI models, user files (PERSISTENT)
      - SnapOtter-workspace:/tmp/workspace  # Temp processing files (can be tmpfs)
    environment:
      # --- Authentication ---
      - AUTH_ENABLED=true          # Set to false to disable login entirely
      - DEFAULT_USERNAME=admin     # First-run admin username
      - DEFAULT_PASSWORD=admin     # First-run admin password (you'll be forced to change it)

      # --- Database + Queue ---
      - DATABASE_URL=postgres://snapotter:snapotter@postgres:5432/snapotter
      - REDIS_URL=redis://redis:6379

      # --- Limits (set 0 for unlimited) ---
      # - MAX_UPLOAD_SIZE_MB=100   # Per-file upload limit in MB
      # - MAX_BATCH_SIZE=100       # Max files per batch request
      # - RATE_LIMIT_PER_MIN=1000  # API rate limit per IP, default shown (0 = disabled)
      # - MAX_USERS=0              # Max user accounts

      # --- Networking ---
      # - TRUST_PROXY=true         # Trust X-Forwarded-For headers (set false if not behind a proxy)

      # --- Bind mount permissions ---
      # - PUID=1000                # Match your host user's UID (run: id -u)
      # - PGID=1000                # Match your host user's GID (run: id -g)
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:1349/api/v1/health"]
      interval: 30s
      timeout: 5s
      start_period: 60s
      retries: 3
    shm_size: "2gb"            # Needed for Python ML shared memory
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  postgres:
    image: postgres:17-alpine
    container_name: SnapOtter-postgres
    environment:
      POSTGRES_USER: snapotter
      POSTGRES_PASSWORD: snapotter     # Change this for non-local deployments
      POSTGRES_DB: snapotter
    volumes:
      - SnapOtter-pgdata:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U snapotter"]
      interval: 10s
      timeout: 5s
      retries: 12
      start_period: 15s

  redis:
    image: redis:8-alpine
    container_name: SnapOtter-redis
    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
      start_period: 10s

volumes:
  SnapOtter-data:       # Named volume - Docker manages permissions automatically
  SnapOtter-workspace:
  SnapOtter-pgdata:
  SnapOtter-redisdata:

bash

docker compose up -d

จากนั้นแอปจะพร้อมใช้งานที่ http://localhost:1349

โดน Docker Hub จำกัดอัตราการดึงหรือเปล่า? แทนที่ snapotter/snapotter:latest ด้วย ghcr.io/snapotter-hq/snapotter:latest เพื่อดึงจาก GitHub Container Registry แทน ทั้งสอง registry จะได้รับอิมเมจเดียวกันในทุกรีลีส

Quick Start (NVIDIA CUDA)

สำหรับการเร่งความเร็วด้วย NVIDIA CUDA บนเครื่องมือ AI (การลบพื้นหลัง, การขยายภาพ, การปรับปรุงใบหน้า, OCR):

yaml

# docker-compose-gpu.yml - Requires: NVIDIA GPU + nvidia-container-toolkit
# Install toolkit: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
services:
  SnapOtter:
    image: snapotter/snapotter:latest
    container_name: SnapOtter
    ports:
      - "1349:1349"
    volumes:
      - SnapOtter-data:/data
      - SnapOtter-workspace:/tmp/workspace
    environment:
      - AUTH_ENABLED=true
      - DEFAULT_USERNAME=admin
      - DEFAULT_PASSWORD=admin
      - DATABASE_URL=postgres://snapotter:snapotter@postgres:5432/snapotter
      - REDIS_URL=redis://redis:6379
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:1349/api/v1/health"]
      interval: 30s
      timeout: 5s
      start_period: 60s
      retries: 3
    shm_size: "2gb"                # Required for PyTorch CUDA shared memory
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all           # Or set to 1 for a specific GPU
              capabilities: [gpu]
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  postgres:
    image: postgres:17-alpine
    container_name: SnapOtter-postgres
    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"]
      interval: 10s
      timeout: 5s
      retries: 12
      start_period: 15s

  redis:
    image: redis:8-alpine
    container_name: SnapOtter-redis
    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
      start_period: 10s

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

bash

docker compose -f docker-compose-gpu.yml up -d

ตรวจสอบการตรวจพบ CUDA ในบันทึกล็อก:

bash

docker logs SnapOtter 2>&1 | head -20
# Look for: [gpu] CUDA available via torch

Hardware Requirements

ตัวเลขเหล่านี้มาจากการทดสอบประสิทธิภาพบนระบบหลากหลาย ตั้งแต่เวิร์กสเตชัน amd64 รุ่นใหม่ที่มี NVIDIA RTX 4070 ไปจนถึง Raspberry Pi โดยรันแคตตาล็อกเครื่องมือทั้งชุดบนแต่ละเครื่อง และกวาดค่าขีดจำกัดทรัพยากรของ Docker เพื่อหาขีดต่ำสุดที่แท้จริง

Quick Reference

ระดับ	กรณีใช้งาน	CPU	RAM	GPU	พื้นที่เก็บข้อมูล
ขั้นต่ำ	เครื่องมือรูปภาพ ไฟล์ และ PDF แบบเบา; ผู้ใช้คนเดียว; ชุดงานเล็ก	2 คอร์	2 GB	ไม่มี	~7 GB
แนะนำ	ครบทั้งห้าโมดัลลิตี รวมถึงวิดีโอ, PDF และ AI บน CPU; ชุดงาน; ผู้ใช้ไม่กี่คน	4 คอร์	4 GB	ไม่มี	~25 GB
เต็มรูปแบบ	ทุกอย่างแบบเร็ว รวมถึง GPU AI; ชุดงานขนาดใหญ่; ผู้ใช้จำนวนมาก	6-8 คอร์	8 GB	NVIDIA VRAM 8 GB ขึ้นไป (12 GB จะสบายกว่า)	~35 GB

สถาปัตยกรรม: 64 บิตเท่านั้น (linux/amd64 หรือ linux/arm64) SnapOtter ทำงานแบบเนทีฟบนเซิร์ฟเวอร์ Intel/AMD, Mac ที่ใช้ Apple Silicon และบอร์ด ARM แบบ 64 บิต รวมถึง Raspberry Pi 4 และ 5 (4-8 GB) มัน ไม่ ทำงานบน ARM แบบ 32 บิต (armv7/armhf) เพราะไม่มีการสร้างอิมเมจสำหรับสถาปัตยกรรมนั้น และไม่ทำงานบนบอร์ดระดับ 512 MB อย่าง Pi Zero ซึ่งอยู่ต่ำกว่าขีดต่ำสุดของหน่วยความจำ (ดูด้านล่าง)

Minimum (เครื่องมือรูปภาพ ไฟล์ และ PDF แบบเบา; ไม่มี AI)

ทรัพยากร	ความต้องการ
CPU	2 คอร์
RAM	2 GB
ดิสก์	~5.5 GB (อิมเมจ) + วอลุ่มข้อมูล
GPU	ไม่จำเป็น

เครื่องมือในแคตตาล็อกที่ไม่ใช่ AI ทั้ง 222 รายการ ได้แก่ รูปภาพ (ปรับขนาด, ครอป, แปลง, บีบอัด, ปรับแต่ง, ลายน้ำ), วิดีโอ (ตัด, ปิดเสียง, remux), เสียง (แปลง, นอร์มัลไลซ์, ตัด), PDF (รวม, แยก, บีบอัด, หมุน, ป้องกัน), การแปลงไฟล์ และพรีเซ็ตการแปลงเฉพาะทาง ล้วนทำงานได้บนฮาร์ดแวร์ธรรมดา การดำเนินการส่วนใหญ่เสร็จภายในเวลาต่ำกว่าหนึ่งวินาทีมากแม้กับไฟล์ขนาดใหญ่: รูปภาพขนาด 2.7 MB ปรับขนาดในเวลา ~0.05 วินาที และเข้ารหัสใหม่เป็น WebP ใน ~2 วินาที

ขีดต่ำสุดของหน่วยความจำเป็นเรื่องจริง จากการกวาดค่าขีดจำกัดทรัพยากรของ Docker: 512 MB ไม่สามารถเริ่มสแตกได้ (แม้แต่การปรับขนาดรูปภาพไฟล์เดียวก็ถูกฆ่า), 1 GB จัดการการดำเนินการไฟล์เดียวได้ แต่ชุดงานหลายไฟล์จะหน่วยความจำหมด และ 2 GB / 2 คอร์ คือคอนฟิกที่เล็กที่สุดซึ่งจัดการชุดงานได้อย่างสบาย

yaml

deploy:
  resources:
    limits:
      cpus: '2'
      memory: 2G

ข้อยกเว้นเดียวที่กิน CPU หนักคือการเข้ารหัสวิดีโอใหม่ การดำเนินการแบบ stream-copy (ตัด, ปิดเสียง, remux คอนเทนเนอร์) เกิดขึ้นทันที แต่การทรานส์โค้ดไปยัง codec อื่นถูกจำกัดด้วย CPU คลิป 1080p ยาว 45 วินาทีที่เข้ารหัสใหม่เป็น VP9 (WebM) ใช้เวลาราว ~40 วินาที บน CPU รุ่นใหม่ที่เร็ว, ~45 วินาทีบน Apple Silicon, ~80 วินาทีบน mobile 4 คอร์รุ่นเก่า และ ~130 วินาที บนเซิร์ฟเวอร์ 4 คอร์รุ่นเก่า หากงานของคุณเน้นวิดีโอ ให้เน้นจำนวนคอร์ CPU และความเร็วสัญญาณนาฬิกา หรือเพิ่มขีดจำกัด cpus: ของคอนเทนเนอร์ โดยค่าเริ่มต้น compose ที่ให้มาจำกัดแอปไว้ที่ 4 คอร์ (8 คอร์บน compose ของ GPU)

Recommended (เครื่องมือ AI บน CPU)

ทรัพยากร	ความต้องการ
CPU	4 คอร์
RAM	4 GB
ดิสก์	3 GB (อิมเมจ) + 24 GB (โมเดล AI) + พื้นที่ทำงาน
GPU	ไม่จำเป็น (สำรองด้วย CPU)

การติดตั้งบันเดิล AI คือสิ่งที่ดัน RAM ไปถึง 4 GB เมื่อไม่ได้ติดตั้ง AI แอปจะเดินเบาที่ราว 360 MB; เมื่อติดตั้งบันเดิลครบทั้งเจ็ดชุด มันจะครองหน่วยความจำ ~2.6 GB เพราะ Python AI sidecar โหลดโมเดลไว้ล่วงหน้า (การลบพื้นหลัง, การขยายภาพ, OCR, การถอดเสียง, การตรวจจับใบหน้า, การฟื้นฟู) ตอนเริ่มทำงาน การติดตั้งที่ไม่ใช่ AI ยังคงเบา; การติดตั้ง AI ต้องการ ≥4 GB

เครื่องมือ AI ส่วนใหญ่ใช้งานได้ดีบน CPU; มีบางตัวที่ต้องการ GPU จริงๆ วัดผลบน CPU 4 คอร์รุ่นใหม่:

เครื่องมือ AI	เวลาบน CPU	ใช้งานบน CPU ได้ไหม?
การตรวจจับใบหน้า (เบลอใบหน้า, ครอปอัจฉริยะ, ตาแดง), การลบสัญญาณรบกวน	ต่ำกว่า 1 วินาที	ได้
OCR, การถอดเสียง, คำบรรยาย	1-3 วินาที	ได้
ลงสี, ปรับปรุงใบหน้า	~10 วินาที	ได้
การลบ / แทนที่ / เบลอพื้นหลัง	~29 วินาที	ได้ (ต้องรอ)
การขยายภาพ AI (RealESRGAN)	~33 วินาทีสำหรับภาพเล็ก; หลายนาทีสำหรับภาพใหญ่	ก้ำกึ่ง แนะนำให้ใช้ GPU อย่างยิ่ง
การฟื้นฟูภาพถ่าย (ไปป์ไลน์เต็มรูปแบบ)	หลายนาที	ไม่ได้ ต้องการ GPU หรือ CPU หลายคอร์ที่เร็ว

SnapOtter จงใจไม่อบการดาวน์โหลดโมเดลเหล่านี้ลงในอิมเมจ Docker บันเดิล AI จะถูกดึงเมื่อผู้ดูแลระบบเปิดใช้เครื่องมือที่เกี่ยวข้องเท่านั้น เก็บไว้ในวอลุ่มถาวร /data/ai และแชร์ร่วมกันโดยทุกเครื่องมือที่พึ่งพาชุดโมเดลเดียวกัน วิธีนี้ทำให้อิมเมจคอนเทนเนอร์สุดท้ายมีขนาดเล็ก ในขณะที่ยังปล่อยให้การติดตั้ง AI เต็มรูปแบบไปถึงตัวเลขพื้นที่เก็บข้อมูลที่ใหญ่ขึ้นด้านล่าง

บางเครื่องมือพึ่งพาบันเดิลที่แชร์กันมากกว่าหนึ่งชุด ตัวอย่างเช่น Passport Photo ต้องการทั้ง background-removal และ face-detection; หากติดตั้ง background-removal ไว้แล้ว การเปิดใช้ Passport Photo จะดาวน์โหลดเฉพาะบันเดิล face-detection ที่ขาดไปเท่านั้น การนำกลับมาใช้ซ้ำแบบเดียวกันนี้ใช้กับเครื่องมือ AI ทั้งหมด

ขนาดการดาวน์โหลดโมเดล AI:

บันเดิล	ขนาดดิสก์
การลบพื้นหลัง	4-5 GB
การขยายภาพ + ปรับปรุงใบหน้า + ลบสัญญาณรบกวน	5-6 GB
การตรวจจับใบหน้า	200-300 MB
ลบวัตถุ + ลงสี	1-2 GB
OCR	5-6 GB
การฟื้นฟูภาพถ่าย	4-5 GB
บันเดิลทั้งหมด	~24 GB

yaml

deploy:
  resources:
    limits:
      cpus: '4'
      memory: 4G

Full (เครื่องมือ AI บน NVIDIA CUDA)

ทรัพยากร	ความต้องการ
CPU	6-8 คอร์ (การเตรียมวิดีโอ + การทำงานพร้อมกันรันบน CPU แม้จะใช้ GPU AI)
RAM	8 GB
GPU	NVIDIA ที่มี VRAM 8 GB ขึ้นไป (แนะนำ 12 GB)
ดิสก์	~35 GB รวม

GPU ของ NVIDIA (CUDA) เร่งความเร็วโมเดล AI ที่หนักได้อย่างมาก วัดผลบน RTX 4070 เทียบกับ CPU รุ่นใหม่:

เครื่องมือ AI	ความเร็วที่เพิ่มขึ้นด้วย GPU	หมายเหตุ
การขยายภาพ AI (RealESRGAN 2×)	~47×	ชัยชนะที่ใหญ่ที่สุด ต่ำกว่าหนึ่งวินาที เทียบกับ ~33 วินาที (หลายนาทีสำหรับภาพใหญ่)
การปรับปรุงใบหน้า (CodeFormer)	~12×	~0.9 วินาที เทียบกับ ~11 วินาที
การถอดเสียง (Whisper)	~4.5×
การลบ / แทนที่ / เบลอพื้นหลัง	~4×	~7 วินาทีบน GPU เทียบกับ ~29 วินาทีบน CPU
ลงสี	~1.8×
OCR, การตรวจจับใบหน้า, ตาแดง, การลบสัญญาณรบกวน	~1×	เร็วอยู่แล้วบน CPU GPU ไม่ช่วย
การฟื้นฟูภาพถ่าย	ไม่มี	ถูกจำกัดด้วย CPU แม้บน GPU (ใช้ GPU 0%); CPU ที่เร็วสำคัญกว่า GPU ในกรณีนี้

เครื่องมือที่คุ้มค่ากับ GPU คือ การขยายภาพ, การปรับปรุงใบหน้า, การถอดเสียง และการลบพื้นหลัง การตรวจจับใบหน้า, OCR และตาแดงถูกจำกัดด้วย CPU และเร็วอยู่แล้ว ดังนั้น GPU จึงไม่เพิ่มอะไร

การใช้ VRAM สูงสุดพุ่งถึง 7.5 GB ระหว่างการขยายภาพพร้อมการปรับปรุงใบหน้า GPU ของ NVIDIA ขนาด 6 GB ใช้ได้กับเครื่องมือ AI ส่วนใหญ่ทีละตัว แต่จะล้มเหลวกับการขยายภาพ VRAM 8-12 GB จัดการได้ทุกอย่าง

ปัจจุบันยังไม่รองรับการเร่งความเร็วด้วย iGPU ของ Intel/AMD ผ่าน VA-API, Quick Sync หรือ OpenCL สำหรับการอนุมาน AI การแมป /dev/dri เข้าไปในคอนเทนเนอร์ไม่ได้เปิดใช้การเร่งความเร็ว AI ด้วย GPU; SnapOtter จะรันเครื่องมือ AI บน CPU เว้นแต่จะมี NVIDIA CUDA

yaml

deploy:
  resources:
    limits:
      cpus: '4'
      memory: 8G
    reservations:
      devices:
        - driver: nvidia
          count: all
          capabilities: [gpu]

Concurrent Users

คำขอปรับขนาดรูปภาพแบบขนานที่ยิงไปยังคอนเทนเนอร์แอปซึ่งจำกัดไว้ที่ 4 คอร์โดยค่าเริ่มต้น:

คำขอพร้อมกัน	เวลาตอบสนองเฉลี่ย	ข้อผิดพลาด
1	0.4 วินาที	0
5	1.2 วินาที	0
10	2.1 วินาที	0

เวลาตอบสนองลดลงแบบต่ำกว่าเชิงเส้นโดยไม่มีข้อผิดพลาดเมื่อ worker pool เต็ม การเพิ่มขีดจำกัด cpus: ของคอนเทนเนอร์แอป (หรือใช้โฮสต์ที่มีคอร์มากกว่า) จะยกเพดานขึ้น โปรดทราบว่างานหนัก (การทรานส์โค้ดวิดีโอ, CPU AI) จะยึด worker ไว้ตลอดระยะเวลาทั้งหมด ดังนั้นให้กำหนดขนาด CPU ตามจำนวนงานหนักที่คาดว่าจะทำพร้อมกัน ไม่ใช่แค่จำนวนคำขอ

Supported Image Formats

SnapOtter รองรับ รูปแบบอินพุต 55+ รูปแบบ และ รูปแบบเอาต์พุต 14 รูปแบบ รวมถึงไฟล์ RAW จากกล้อง 20+ แบรนด์ รูปแบบระดับมืออาชีพ (PSD, EPS, OpenEXR, HDR), codec สมัยใหม่ (JPEG XL, AVIF, HEIC, QOI) และรูปแบบทางวิทยาศาสตร์/เกม (FITS, DDS)

ดู รายการรูปแบบทั้งหมด สำหรับรายละเอียดของทุกรูปแบบที่รองรับ ตัวถอดรหัสที่ใช้ และตัวควบคุมคุณภาพที่มีให้

Known Limitations

Content-aware resize ล้มเหลวกับภาพขนาดใหญ่ (>5 MP) เนื่องจากข้อจำกัดในไบนารี caire ทำงานได้ดีกับภาพขนาดเล็กกว่า
การถอดรหัส HEIF ใช้เวลา 13-23 วินาที HEIC (รุ่นของ Apple) เร็วกว่ามากที่ 0.3-0.9 วินาที
OCR ภาษาญี่ปุ่น ล้มเหลวบน CPU เนื่องจากบั๊ก MKLDNN ของ PaddlePaddle ทำงานได้บน GPU
การขยายภาพ หมดเวลาบน CPU สำหรับทุกอย่างที่เกินภาพขนาดเล็ก ต้องใช้ GPU สำหรับการใช้งานจริง
CodeFormer ปรับปรุงใบหน้าช้ากว่า GFPGAN อย่างมีนัยสำคัญ (53 วินาที เทียบกับ 2 วินาทีบน GPU) แนะนำ GFPGAN สำหรับกรณีใช้งานส่วนใหญ่

Volumes

เมานต์ / วอลุ่ม	วัตถุประสงค์	จำเป็นไหม?
`/data` (แอป)	โมเดล AI, Python venv, ไฟล์ผู้ใช้	ใช่ ไฟล์จะสูญหายหากไม่มี
`/tmp/workspace` (แอป)	ไฟล์ประมวลผลชั่วคราว (ทำความสะอาดอัตโนมัติ)	แนะนำ
`SnapOtter-pgdata` (postgres)	ไดเรกทอรีข้อมูล PostgreSQL (ผู้ใช้, การตั้งค่า, ไปป์ไลน์, งาน)	ใช่ ข้อมูลจะสูญหายหากไม่มี
`SnapOtter-redisdata` (redis)	ไฟล์ append-only ของ Redis สำหรับคิวงานแบบทนทาน	แนะนำ

Bind mounts vs. named volumes

Named volumes (แนะนำ) Docker จัดการสิทธิ์ให้โดยอัตโนมัติ:

yaml

volumes:
  - SnapOtter-data:/data

Bind mounts คุณจัดการสิทธิ์เอง ตั้งค่า PUID/PGID ให้ตรงกับผู้ใช้บนโฮสต์ของคุณ:

yaml

volumes:
  - ./SnapOtter-data:/data
environment:
  - PUID=1000    # Your host UID (run: id -u)
  - PGID=1000    # Your host GID (run: id -g)

Storage permissions

SnapOtter เขียนลงสองตำแหน่งขณะรันไทม์: /data (ไฟล์ผู้ใช้, ล็อก, โมเดล AI และ Python venv) และ /tmp/workspace (พื้นที่ประมวลผลชั่วคราว) ทั้งสองตำแหน่งต้องเขียนได้โดยผู้ใช้ที่คอนเทนเนอร์รันอยู่ หากตำแหน่งใดเขียนไม่ได้ คอนเทนเนอร์จะ ล้มเหลวทันทีตอนเริ่มทำงาน พร้อมข้อความที่ระบุชื่อไดเรกทอรี, UID/GID ที่กำลังรัน และวิธีแก้ไข แทนที่จะบูตแบบ "สุขภาพดี" แล้วล้มเหลวตอนอัปโหลดครั้งแรกด้วยข้อผิดพลาดที่เข้าใจยาก

วิธีจัดการสิทธิ์ขึ้นอยู่กับวิธีที่คอนเทนเนอร์ถูกเปิดใช้:

ค่าเริ่มต้น (เริ่มเป็น root แล้วลดสิทธิ์เป็น snapotter) entrypoint เริ่มเป็น root แก้ไขความเป็นเจ้าของของวอลุ่มที่เมานต์ไว้ จากนั้นลดสิทธิ์เป็นผู้ใช้ snapotter ที่ไม่มีสิทธิ์พิเศษผ่าน gosu Named volumes ทำงานได้โดยไม่ต้องตั้งค่าใด สำหรับ bind mounts ให้ตั้งค่า PUID/PGID เป็นผู้ใช้บนโฮสต์ของคุณ (ด้านบน) เพื่อให้ไฟล์ที่มันเขียนเป็นของคุณ

Kubernetes / OpenShift (non-root ผ่าน runAsUser) เมื่อเปิดใช้เป็นผู้ใช้ที่ไม่ใช่ root โดยตรง คอนเทนเนอร์ไม่สามารถ chown วอลุ่มได้เอง ดังนั้น orchestrator ต้องทำให้มันเขียนได้ ตั้งค่า fsGroup:

yaml

securityContext:
  runAsUser: 999
  runAsGroup: 999
  fsGroup: 999        # makes mounted volumes writable by the pod

ไดเรกทอรีที่เขียนได้ของอิมเมจเป็นของกลุ่ม GID 0 และกลุ่มสามารถเขียนได้ ดังนั้น pod ที่รันด้วย UID ใดก็ได้ พร้อมกลุ่มเสริม root (ค่าเริ่มต้นของ OpenShift) สามารถเขียนได้โดยไม่ต้อง chown

TrueNAS Scale (และการตั้งค่า "UID ต่างถิ่น" อื่นๆ) TrueNAS รันแอปเป็นผู้ใช้ที่ไม่ใช่ root (มักเป็น 568:568) และเมานต์ dataset ของโฮสต์ที่เป็นของผู้ใช้อื่น ดังนั้นทั้ง entrypoint และ fsGroup ต่างก็ไม่ทำให้มันเขียนได้ด้วยตัวเอง เลือกอย่างใดอย่างหนึ่ง:

รันแอปเป็น root (แนะนำ) ปล่อยให้ผู้ใช้ของแอปไม่ได้ตั้งค่า หรือตั้งเป็น 0 แล้วให้ entrypoint ค่าเริ่มต้นแก้ไขสิทธิ์และลดสิทธิ์เป็น snapotter
รันเป็น UID 999 ตั้งค่าผู้ใช้/กลุ่มของแอปเป็น 999:999 (ผู้ใช้ snapotter ในตัวของ SnapOtter) เพื่อให้ตรงกับความเป็นเจ้าของของอิมเมจ

chown dataset ของโฮสต์ เป็น UID ที่คอนเทนเนอร์รันอยู่ จากเชลล์ของ TrueNAS:

bash

# ใช้ UID จากข้อผิดพลาดตอนเริ่มทำงาน (หรือรัน `id` ในคอนเทนเนอร์)
chown -R 568:568 /mnt/<pool>/<dataset>

ข้อผิดพลาดตอนเริ่มทำงานจะระบุ UID ที่แน่นอนให้ใช้ ดังนั้นเส้นทางที่เร็วที่สุดคือเริ่มแอปหนึ่งครั้ง อ่านข้อความ แล้ว chown (หรือปรับผู้ใช้) ตามนั้น

Environment Variables

ตัวแปร	ค่าเริ่มต้น	คำอธิบาย
`AUTH_ENABLED`	`true`	เปิด/ปิดข้อกำหนดการล็อกอิน
`DEFAULT_USERNAME`	`admin`	ชื่อผู้ใช้แอดมินเริ่มต้น
`DEFAULT_PASSWORD`	`admin`	รหัสผ่านแอดมินเริ่มต้น (บังคับเปลี่ยนตอนล็อกอินครั้งแรก)
`MAX_UPLOAD_SIZE_MB`	`100`	ขีดจำกัดการอัปโหลดต่อไฟล์
`MAX_BATCH_SIZE`	`100`	จำนวนไฟล์สูงสุดต่อคำขอชุด
`RATE_LIMIT_PER_MIN`	`1000`	คำขอ API ต่อนาทีต่อ IP (ตั้ง 0 เพื่อปิด)
`MAX_USERS`	`0` (ไม่จำกัด)	จำนวนบัญชีผู้ใช้สูงสุด
`TRUST_PROXY`	`true`	เชื่อถือส่วนหัว X-Forwarded-For จาก reverse proxy
`PUID`	`999`	รันเป็น UID นี้ (สำหรับสิทธิ์ bind mount)
`PGID`	`999`	รันเป็น GID นี้ (สำหรับสิทธิ์ bind mount)
`LOG_LEVEL`	`info`	ระดับความละเอียดของล็อก: fatal, error, warn, info, debug, trace
`CONCURRENT_JOBS`	`0` (อัตโนมัติ)	จำนวนงานประมวลผล AI แบบขนานสูงสุด
`SESSION_DURATION_HOURS`	`168`	อายุของเซสชันการล็อกอิน (7 วัน)
`CORS_ORIGIN`	(ว่าง)	origin ที่อนุญาตคั่นด้วยคอมมา หรือปล่อยว่างสำหรับ same-origin

Health Check

คอนเทนเนอร์มี health check ในตัว:

bash

# Check container health status
docker inspect --format='{{.State.Health.Status}}' SnapOtter

# Manual health check
curl http://localhost:1349/api/v1/health
# {"status":"healthy","version":"x.y.z"}

Reverse Proxy

SnapOtter ตั้งค่า TRUST_PROXY=true โดยค่าเริ่มต้น เพื่อให้การจำกัดอัตราและการบันทึกล็อกใช้ IP จริงของไคลเอนต์จากส่วนหัว X-Forwarded-For

Nginx

nginx

server {
    listen 80;
    server_name images.example.com;

    # Match MAX_UPLOAD_SIZE_MB (0 = nginx default 1M, so set high for unlimited)
    client_max_body_size 500M;

    location / {
        proxy_pass http://localhost:1349;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # SSE support (batch progress, feature install progress)
        proxy_buffering off;
        proxy_read_timeout 300s;
    }
}

Nginx Proxy Manager

เพิ่ม Proxy Host ใหม่
ตั้ง Domain Name เป็นโดเมนของคุณ
ตั้ง Scheme เป็น http, Forward Hostname เป็น SnapOtter (หรือ IP ของคอนเทนเนอร์), Forward Port เป็น 1349
เปิดใช้การรองรับ WebSocket
ในส่วน Advanced ให้เพิ่ม: client_max_body_size 500M; และ proxy_buffering off;

Traefik

yaml

# Add these labels to the SnapOtter service in docker-compose.yml
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.snapotter.rule=Host(`images.example.com`)"
  - "traefik.http.routers.snapotter.entrypoints=websecure"
  - "traefik.http.routers.snapotter.tls.certresolver=letsencrypt"
  - "traefik.http.services.snapotter.loadbalancer.server.port=1349"
  # Increase upload limit (default 2MB is too low)
  - "traefik.http.middlewares.snapotter-body.buffering.maxRequestBodyBytes=524288000"
  - "traefik.http.routers.snapotter.middlewares=snapotter-body"

Caddy

txt

images.example.com {
    reverse_proxy localhost:1349 {
        flush_interval -1
        transport http {
            read_timeout 300s
            write_timeout 300s
        }
    }
}

flush_interval -1 ปิดการบัฟเฟอร์การตอบสนอง ซึ่งจำเป็นสำหรับเหตุการณ์ความคืบหน้า SSE (การประมวลผลชุด, เครื่องมือ AI, การติดตั้งฟีเจอร์) การหมดเวลาที่ยืดออกช่วยให้การอัปโหลดไฟล์ขนาดใหญ่เสร็จสมบูรณ์โดยที่ Caddy ไม่ปิดการเชื่อมต่อก่อนกำหนด

Cloudflare Tunnels

bash

cloudflared tunnel --url http://localhost:1349

หมายเหตุ: Cloudflare มีขีดจำกัดการอัปโหลด 100 MB บนแผนฟรี ตั้งค่า MAX_UPLOAD_SIZE_MB=100 ให้ตรงกัน

CI/CD

ที่เก็บ GitHub มีเวิร์กโฟลว์สามชุด:

ci.yml รันอัตโนมัติในทุก push และ PR ทำ lint, typecheck, ทดสอบ, build และตรวจสอบอิมเมจ Docker (โดยไม่ push)
release.yml ทริกเกอร์ด้วยตนเองผ่าน workflow_dispatch รัน semantic-release เพื่อสร้าง version tag และ GitHub release จากนั้นสร้างอิมเมจ Docker แบบหลายสถาปัตยกรรม (amd64 + arm64) และ push ไปยัง Docker Hub (snapotter/snapotter) และ GitHub Container Registry (ghcr.io/snapotter-hq/snapotter)
deploy-docs.yml สร้างไซต์เอกสารนี้และปรับใช้ไปยัง Cloudflare Pages เมื่อ push ไปยัง main

หากต้องการสร้างรีลีส ให้ไปที่ Actions > Release > Run workflow ใน GitHub UI หรือรัน:

bash

gh workflow run release.yml

Semantic-release กำหนดเวอร์ชันจากประวัติคอมมิต แท็ก Docker latest ชี้ไปยังรีลีสล่าสุดเสมอ

Analytics

SnapOtter มีการวิเคราะห์ผลิตภัณฑ์แบบไม่ระบุตัวตน (รูปแบบการใช้เครื่องมือ, รายงานข้อผิดพลาด) เพื่อช่วยจับบั๊กและปรับปรุงฟีเจอร์ โดยเปิดใช้เป็นค่าเริ่มต้น ไฟล์ ชื่อไฟล์ และข้อมูลส่วนบุคคลของคุณไม่เคยเป็นส่วนหนึ่งของสิ่งนี้ SnapOtter ทำงานได้ตามปกติเมื่อปิดการวิเคราะห์

Disabling analytics

การเลือกไม่เข้าร่วมขณะรันไทม์เป็นสวิตช์แอดมินแบบคลิกเดียว เปิด Settings > System > Privacy แล้วปิด Anonymous Product Analytics มันจะหยุดทันทีสำหรับทั้งอินสแตนซ์ โดยไม่ต้อง build ใหม่

สำหรับอิมเมจที่ไม่มีทางส่งการวิเคราะห์ได้เลย ให้ตั้งค่าการปิดแบบถาวรตอน build โดยโคลนที่เก็บและ build ใหม่:

bash

git clone https://github.com/snapotter-hq/SnapOtter.git
cd SnapOtter
docker compose -f docker/docker-compose.yml build --build-arg SNAPOTTER_ANALYTICS=off
docker compose -f docker/docker-compose.yml up -d

หรือเพิ่ม build arg ลงใน docker-compose.yml ที่มีอยู่ของคุณ:

yaml

services:
  snapotter:
    build:
      context: .
      dockerfile: docker/Dockerfile
      args:
        SNAPOTTER_ANALYTICS: "off"

Essentials

Optimization

Adjustments

Watermark & Overlay

Utilities

Layout

Format

AI Tools

Deployment

Quick Start (CPU)

Quick Start (NVIDIA CUDA)

Hardware Requirements

Quick Reference

Minimum (เครื่องมือรูปภาพ ไฟล์ และ PDF แบบเบา; ไม่มี AI)

Recommended (เครื่องมือ AI บน CPU)

Full (เครื่องมือ AI บน NVIDIA CUDA)

Concurrent Users

Supported Image Formats

Known Limitations

Volumes

Bind mounts vs. named volumes

Storage permissions

Environment Variables

Health Check

Reverse Proxy

Nginx

Nginx Proxy Manager

Traefik

Caddy

Cloudflare Tunnels

CI/CD

Analytics

Disabling analytics

Deployment ​

Quick Start (CPU) ​

Quick Start (NVIDIA CUDA) ​

Hardware Requirements ​

Quick Reference ​

Minimum (เครื่องมือรูปภาพ ไฟล์ และ PDF แบบเบา; ไม่มี AI) ​

Recommended (เครื่องมือ AI บน CPU) ​

Full (เครื่องมือ AI บน NVIDIA CUDA) ​

Concurrent Users ​

Supported Image Formats ​

Known Limitations ​

Volumes ​

Bind mounts vs. named volumes ​

Storage permissions ​

Environment Variables ​

Health Check ​

Reverse Proxy ​

Nginx ​

Nginx Proxy Manager ​

Traefik ​

Caddy ​

Cloudflare Tunnels ​

CI/CD ​

Analytics ​

Disabling analytics ​

Deployment

Quick Start (CPU)

Quick Start (NVIDIA CUDA)

Hardware Requirements

Quick Reference

Minimum (เครื่องมือรูปภาพ ไฟล์ และ PDF แบบเบา; ไม่มี AI)

Recommended (เครื่องมือ AI บน CPU)

Full (เครื่องมือ AI บน NVIDIA CUDA)

Concurrent Users

Supported Image Formats

Known Limitations

Volumes

Bind mounts vs. named volumes

Storage permissions

Environment Variables

Health Check

Reverse Proxy

Nginx

Nginx Proxy Manager

Traefik

Caddy

Cloudflare Tunnels

CI/CD

Analytics

Disabling analytics