> [!NOTE]
> This README was generated by [SKILL](https://github.com/agenvoy/skill-readme-generate), get the ZH version from [here](https://github.com/pardnio/go-image-server/blob/master/doc/README.zh.md).

***

<p align="center">
<strong>RESIZE ONCE, CACHE EVERYWHERE!</strong>
</p>

<p align="center">
<a href="https://github.com/pardnchiu/go-image-server/releases"><img src="https://img.shields.io/github/v/tag/pardnchiu/go-image-server?include_prereleases&style=for-the-badge" alt="Release"></a>
<a href="https://github.com/pardnio/go-image-server/blob/master/LICENSE"><img src="https://img.shields.io/github/license/pardnchiu/go-image-server?include_prereleases&style=for-the-badge" alt="License"></a>
</p>

***

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

## Table of Contents

- [Features](#features)
- [Architecture](#architecture)
- [License](#license)
- [Author](#author)

## Features

> `docker compose up -d` · [Documentation](https://github.com/pardnio/go-image-server/blob/master/doc/doc.md)

- **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](https://github.com/pardnio/go-image-server/blob/master/doc/architecture.md)

```mermaid
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](https://github.com/pardnio/go-image-server/blob/master/LICENSE).

## Author

Just [open an issue](https://github.com/pardnchiu/go-image-server/issues/new) to share an idea.

<a href="https://github.com/pardnchiu/go-image-server/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=pardnchiu/go-image-server&cache_bust=2026-10-04" alt="go-image-server contributors" />
</a>

***

©️ 2025 [邱敬幃 Pardn Chiu](https://www.linkedin.com/in/pardnchiu)