# pardnio/go-image-server

> Self-hosted Go image caching server by Pardn Chiu (邱敬幃): on-the-fly libvips resizing, AVIF/WebP output, and four-layer caching.

Maintained by 邱敬幃 Pardn Chiu (pardnchiu), Pardn Co., Ltd, Taiwan · Infrastructure Engineering. Source: https://github.com/pardnio/go-image-server

Full text in one file: [English](https://go-image-server.pardn.io/llms-full.txt) · [中文](https://go-image-server.pardn.io/zh/llms-full.txt)

## Overview

- [Home](https://go-image-server.pardn.io/index.md): Self-hosted Go image caching server by Pardn Chiu (邱敬幃): on-the-fly libvips resizing, AVIF/WebP output, and four-layer caching.
- [Getting Started](https://go-image-server.pardn.io/getting-started.md): Install go-image-server with Docker Compose or from source, provide the 404 placeholders, then upload and read your first image.

## Concepts

- [Architecture](https://go-image-server.pardn.io/architecture.md): One-diagram overview of go-image-server: Cloudflare Worker, Nginx proxy_cache, Gin routes, handlers, libvips, and storage.
- [Caching Layers](https://go-image-server.pardn.io/caching.md): Cache keys, lifetimes, and invalidation for the browser, Cloudflare Worker, Nginx, and local cache-file layers of go-image-server.
- [Image Pipeline](https://go-image-server.pardn.io/image-pipeline.md): How GET /c/img decides to stream originals or transform: libvips resize, blur, brightness, export, and chunked streaming.

## HTTP API

- [HTTP API Reference](https://go-image-server.pardn.io/api-reference.md): All go-image-server HTTP endpoints with response formats, 30-second timeouts, health check, and access-control notes.
- [Image Parameters](https://go-image-server.pardn.io/api-reference-image.md): Query parameters for GET /c/img: size, width, height, quality, AVIF/WebP/JPG/PNG type, blur, brightness, and origin.
- [Sizing Rules](https://go-image-server.pardn.io/api-reference-sizing.md): How go-image-server computes output size from s, w, and h, the 1024 px default, no-upscale rule, and edge cases.
- [Upload API](https://go-image-server.pardn.io/api-reference-upload.md): POST /upload multipart request, supported MIME types, random filename format, 201 JSON response, and error codes.
- [Delete API](https://go-image-server.pardn.io/api-reference-delete.md): DELETE /del moves files or folders into a date-bucketed .trash; move rules, responses, and how to restore.

## Deployment

- [Configuration](https://go-image-server.pardn.io/configuration.md): GO_ENV, PORT, and DOMAIN environment variables, Docker Compose defaults, and the storage/image directory layout.
- [Nginx](https://go-image-server.pardn.io/deployment-nginx.md): Nginx routing blocks, proxy_cache settings, security headers, and enabling the upload/delete IP allowlist.
- [Cloudflare Worker](https://go-image-server.pardn.io/deployment-cloudflare-worker.md): Configure and deploy the Cloudflare Worker edge cache: origin placeholder, handled extensions, and cache behavior.

## Reference

- [Known Limitations](https://go-image-server.pardn.io/known-limitations.md): Current defects and limits in go-image-server: panics, goroutine leaks on timeout, cache purge gaps, and path checks.

## 中文文件

- [首頁](https://go-image-server.pardn.io/zh/index.md): 邱敬幃（Pardn Chiu）開發的自架 Go 圖片快取伺服器：libvips 即時縮圖、AVIF／WebP 輸出與四層快取。
- [快速開始](https://go-image-server.pardn.io/zh/getting-started.md): 以 Docker Compose 或原始碼安裝 go-image-server，放置 404 佔位圖，完成第一次上傳與讀取。
- [架構](https://go-image-server.pardn.io/zh/architecture.md): go-image-server 單張概覽圖：Cloudflare Worker、Nginx、Gin 路由、處理器、libvips 與儲存。
- [快取分層](https://go-image-server.pardn.io/zh/caching.md): 瀏覽器、Cloudflare Worker、Nginx 與本地快取檔四層的快取 key、有效期與失效方式。
- [影像處理流程](https://go-image-server.pardn.io/zh/image-pipeline.md): GET /c/img 的分流判斷、libvips 縮放／模糊／亮度／匯出步驟與 chunked 串流輸出。
- [HTTP API 參考](https://go-image-server.pardn.io/zh/api-reference.md): go-image-server 全部 HTTP 端點、回應格式、30 秒逾時、健康檢查與存取控制說明。
- [圖片讀取參數](https://go-image-server.pardn.io/zh/api-reference-image.md): GET /c/img 的 query 參數：尺寸、寬高、品質、AVIF／WebP／JPG／PNG 格式、模糊、亮度與原檔。
- [尺寸計算](https://go-image-server.pardn.io/zh/api-reference-sizing.md): 依 s、w、h 計算輸出尺寸的規則、1024 px 預設縮圖、不放大原則與邊界行為。
- [上傳 API](https://go-image-server.pardn.io/zh/api-reference-upload.md): POST /upload 的 multipart 請求、支援類型、隨機檔名格式、201 JSON 回應與錯誤碼。
- [刪除 API](https://go-image-server.pardn.io/zh/api-reference-delete.md): DELETE /del 將檔案或資料夾移入依日期分類的 .trash：搬移規則、回應與還原方式。
- [設定](https://go-image-server.pardn.io/zh/configuration.md): GO_ENV、PORT、DOMAIN 環境變數、Docker Compose 預設值與 storage/image 目錄結構。
- [Nginx 設定](https://go-image-server.pardn.io/zh/deployment-nginx.md): Nginx 路由區塊、proxy_cache 參數、安全標頭與上傳／刪除 IP 白名單設定。
- [Cloudflare Worker](https://go-image-server.pardn.io/zh/deployment-cloudflare-worker.md): Cloudflare Worker 邊緣快取的部署設定、處理的副檔名範圍與快取行為。
- [已知限制](https://go-image-server.pardn.io/zh/known-limitations.md): go-image-server 目前的缺陷與限制：panic、逾時 goroutine 洩漏、快取未清除與路徑檢查。