mirror of https://github.com/snapotter-hq/SnapOtter.git synced 2026-08-03 07:46:42 +02:00

Files

T

SnapOtterandGitHub d10d0f544f fix: release QA hardening across processing, media, security, and CI gates (#649 )

A release-readiness QA pass over the whole product. The commits split into
defects a user would hit and gates that were reporting green while measuring
nothing.

## Fixes that change behaviour

Rate limiting was bypassable on every install: TRUST_PROXY defaulted to true, so
request.ip came from a client-set header and a forged X-Forwarded-For got past
the login limiter. The default is now a private-network trust list.

A transient Postgres outage stranded in-flight jobs, leaving finished output on
disk with no row pointing at it. A reconciler now resolves those rows and adopts
the bytes rather than dropping the work.

A Redis connection that moved to a new address wedged every read-blocked
consumer, so completions stopped signalling while health still answered 200.
Socket timeouts plus subscriber pings recover it.

Installing more than one AI bundle left the shared venv multi-versioned and
silently broke three tools. The installer now reconciles distributions to one
version each.

Converting an image to JXL at quality 1 through 4 returned a 500, because
libjxl 0.7 rejects the distance those values compute. The quality is floored at
what the encoder honours. A missing ffmpeg was also reported to the user as a
corrupt upload; it now says the engine is unavailable.

RAW uploads reached an unpatched LibRaw on arm64, so it is built from source at
0.22.2, and the release scan was split so it can fail on an unfixed critical
instead of hiding it behind ignore-unfixed.

## Gates that could not fail

Two mutation lanes ran zero mutants because Stryker crawled the gitignored docs
build; coverage discarded its whole report on any failing test; the lint gate
skipped root tests, scripts, and two workspaces; and several generated matrices
counted a host missing ffmpeg as a passing tool. Each now measures what it
claims.

Full evidence and the outstanding release items are tracked locally and are not
part of this branch.

2026-07-27 15:37:30 +08:00

12 KiB

Raw Blame History

i18n_source_hash, i18n_provenance, i18n_output_hash, i18n_hash_version

i18n_source_hash	i18n_provenance	i18n_output_hash	i18n_hash_version
521c03a6416c	machine	9c99a77621ae	2

Low-Resource Setups

SnapOtter ทำงานได้ดีบนฮาร์ดแวร์ขนาดเล็ก: Raspberry Pi 4 หรือ 5 แล็ปท็อปเครื่องเก่า หรือ VPS ขนาด 2 GB หน้านี้คือคู่มือภาคปฏิบัติสำหรับเครื่องเหล่านั้น: สิ่งที่ควรคาดหวัง การตั้งค่าแบบคัดลอกไปใช้ได้เลยพร้อมขีดจำกัดที่สมเหตุสมผล และฟีเจอร์ใดที่ควรข้าม ข้อมูลการทดสอบประสิทธิภาพฉบับเต็มเบื้องหลังตัวเลขเหล่านี้อยู่ใน Hardware Requirements

ข้อจำกัดตายตัวสองข้อก่อนอื่น:

64 บิตเท่านั้น อิมเมจถูก build สำหรับ linux/amd64 และ linux/arm64 ไม่รองรับ ARM แบบ 32 บิต (armv7/armhf) ดังนั้น Pi รุ่นแรกและตระกูล Pi Zero จึงใช้ไม่ได้
หน่วยความจำขั้นต่ำ 2 GB 512 MB สตาร์ตสแตกไม่ได้ และ 1 GB จะล้มเหลวกับชุดงานหลายไฟล์ 2 GB กับ 2 คอร์คือคอนฟิกที่เล็กที่สุดที่ทำงานได้อย่างสบาย

What runs well on small hardware

เครื่องมือที่ไม่ใช่ AI ทุกตัวทำงานได้บนเครื่อง 2 GB / 2 คอร์: หมวดรูปภาพและไฟล์ทั้งหมด เครื่องมือ PDF และงานวิดีโอ/เสียงแบบ stream copy (ตัด ปิดเสียง เปลี่ยนคอนเทนเนอร์) ส่วนใหญ่เสร็จภายในไม่ถึงหนึ่งวินาที

เวิร์กโหลดสองแบบคือข้อยกเว้น:

การเข้ารหัสวิดีโอใหม่ (แปลงระหว่าง codec) ถูกจำกัดด้วย CPU คลิป 1080p ที่ใช้เวลา ~40 วินาทีบน CPU เดสก์ท็อปที่เร็ว อาจใช้เวลาหลายนาทีบน CPU ระดับ Pi ส่วนงานแบบ stream copy ยังคงเสร็จแทบจะทันที
เครื่องมือ AI ต้องการ RAM (แนะนำ 4 GB) และดิสก์ (บันเดิลขนาดใหญ่กินพื้นที่ชุดละ 4-5 GB) และตัวที่หนัก (การอัปสเกล การฟื้นฟูภาพถ่าย การลบพื้นหลัง) ไม่เหมาะกับ CPU ระดับ Pi ส่วน AI แบบเบา เช่น การตรวจจับใบหน้าและ OCR ยังใช้งานได้ถ้าคุณมีหน่วยความจำพอ

ทั้งสองอย่างจะไม่ถูกติดตั้งหรือทำงานจนกว่าคุณจะใช้มัน: เมื่อไม่ได้ติดตั้งบันเดิล AI ใด ๆ แอปจะใช้หน่วยความจำตอนว่างราว 360 MB และบันเดิล AI จะถูกดาวน์โหลดก็ต่อเมื่อผู้ดูแลระบบเปิดใช้งานเท่านั้น

Raspberry Pi / old laptop walkthrough

นี่คือการติดตั้งด้วย Compose แบบมาตรฐานจาก Getting Started บวกกับลิมิตทรัพยากรและขีดจำกัดแบบระมัดระวัง โดยสมมติว่าใช้ OS แบบ 64 บิต (บน Pi: Raspberry Pi OS 64-bit หรือ Ubuntu Server arm64)

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:

เลือกใช้ SSD แบบ USB แทนการ์ด SD สำหรับวอลุ่มข้อมูลและ Postgres เวิร์กสเปซของงานมีการอ่านเขียนดิสก์จริง และการ์ด SD ทั้งช้าและสึกหรอเร็ว
คอนเทนเนอร์เดียวแบบ all-in-one ก็ใช้ได้ที่นี่เช่นกัน (Postgres และ Redis แบบ embedded เมื่อไม่ได้ตั้งค่า DATABASE_URL/REDIS_URL) และบนโฮสต์ที่หน่วยความจำจำกัด คุณควรลดเพดานของ Redis แบบ embedded ด้วย REDIS_MAXMEMORY (ดู Configuration) แต่ Compose ให้การควบคุมรายเซอร์วิสที่ละเอียดกว่า ซึ่งเป็นเหตุผลที่คู่มือนี้ใช้ Compose
เพิ่ม swap บนอุปกรณ์ 2 GB มันช่วยไม่ให้สไปก์ที่เกิดขึ้นนาน ๆ ครั้ง (PDF ขนาดใหญ่ หรือชุดงานที่คุณลืมจำกัด) จบลงด้วยการที่โปรเซสถูกฆ่าเพราะหน่วยความจำหมด ตัวเลือกที่เป็นมิตรกับการ์ด SD คือ zram
อิมเมจ arm64 ใช้ได้เฉพาะ CPU ไม่มี CUDA บนบอร์ด ARM

The tuning knobs

ขีดจำกัดทั้งหมดเป็นตัวแปรสภาพแวดล้อม ซึ่งมีเอกสารครบถ้วนใน 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+ MP กิน 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 ซึ่งจะเอาเครื่องมือออกจาก UI และหยุดลงทะเบียนเส้นทาง API ของมัน ตัวมันเองไม่ได้ช่วยประหยัดหน่วยความจำ แต่ช่วยกันไม่ให้อินสแตนซ์เล็กที่ใช้ร่วมกันถูกใช้กับเวิร์กโหลดเดียวที่ฮาร์ดแวร์รับไม่ไหว

ถ้าภายหลังคุณย้ายอินสแตนซ์ไปยังฮาร์ดแวร์ที่ใหญ่ขึ้น ให้เอาขีดจำกัดออก (ตั้งกลับเป็น 0) แล้ววอลุ่มข้อมูลเดิมจะใช้ต่อได้ทันที

12 KiB Raw Blame History