pardnio/go-image-server

[!NOTE] This README was generated by SKILL, get the ZH version from here.

RESIZE ONCE, CACHE EVERYWHERE!

A Go image caching server with on-the-fly libvips transforms, four-layer caching, and date-based soft-delete trash

Table of Contents

• Features
• Architecture
• License
• Author

Features

docker compose up -d · Documentation

• Four-Layer Cache Chain — Browser, Cloudflare Worker, Nginx proxy_cache, and parameterized local cache files intercept requests layer by layer, so libvips processes each variant only once.
• URL-Driven Transforms — Query parameters control size, quality, Gaussian blur, brightness, and output format (AVIF / WebP / JPG / PNG) with no pre-generated thumbnails.
• WebP by Default — Requests without parameters return WebP, and originals whose short edge exceeds 1024 px have their long edge scaled down to 1024 px to cut bandwidth.
• Date-Bucketed Trash — DELETE never removes files; it moves them into .trash/YYYY-MM-DD/ and returns the trash location for later restore.
• Adaptive Streaming — Responses use chunked transfer with a 2–16 KiB buffer chosen by file size, balancing small-image latency and large-file throughput.

Architecture

Full Architecture

graph TB
    Client[Client] --> Browser[Browser Cache 7d]
    Browser --> Worker[Cloudflare Worker 7d]
    Browser --> Nginx[Nginx proxy_cache 7d]
    Worker --> Nginx
    Nginx --> Gin[Gin Router]
    Gin --> Get[GET Transform]
    Gin --> Post[POST Upload]
    Gin --> Del[DELETE to Trash]
    Get --> Vips[libvips]
    Get --> Storage[(storage/image<br>upload / cache / .trash)]
    Post --> Storage
    Del --> Storage

License

This project is licensed under the MIT LICENSE.

Author

Just open an issue to share an idea.

©️ 2025 邱敬幃 Pardn Chiu