# pardnio/node-image-server

> Self-hosted Node.js image resizing server by Pardn Chiu (邱敬幃): on-the-fly sharp WebP/AVIF conversion, Nginx and CDN caching, date-sorted trash.

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

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

## Overview

- [Home](https://node-image-server.pardn.io/index.md): Self-hosted Node.js image resizing server by Pardn Chiu (邱敬幃): on-the-fly sharp WebP/AVIF conversion, Nginx and CDN caching, date-sorted trash.
- [Getting Started](https://node-image-server.pardn.io/getting-started.md): Start node-image-server with Docker Compose or on the host, then upload and fetch your first resized WebP or AVIF image.

## Concepts

- [Architecture](https://node-image-server.pardn.io/architecture.md): One-diagram overview of node-image-server: Cloudflare Worker, Nginx proxy_cache, Express cluster, handlers, sharp, and storage.
- [Caching Layers](https://node-image-server.pardn.io/caching.md): Cache keys, lifetimes, and purging for the browser, Cloudflare Worker, Nginx, and local cache-file layers of node-image-server.
- [Image Pipeline](https://node-image-server.pardn.io/image-pipeline.md): How GET /c/img streams originals or converts with sharp: parameter parsing, cache lookup, encoding defaults, and fallbacks.

## HTTP API

- [HTTP API Reference](https://node-image-server.pardn.io/api-reference.md): All node-image-server HTTP endpoints, shared User-Agent and CORS behavior, request logging, and Nginx routing.
- [Image Parameters](https://node-image-server.pardn.io/api-reference-image.md): Query parameters for GET /c/img: size, width, height, quality, WebP/AVIF/JPG/PNG type, origin, and dark 404 image.
- [Sizing Rules](https://node-image-server.pardn.io/api-reference-sizing.md): How node-image-server computes output size from s, w, and h, the 1024px default, the no-upscale rule, and edge cases.
- [Upload API](https://node-image-server.pardn.io/api-reference-upload.md): POST /upload multipart request, supported MIME types, random filename format, 201 JSON response, and error messages.
- [Delete API](https://node-image-server.pardn.io/api-reference-delete.md): DELETE /del moves files or folders into a UTC date-bucketed .trash; collision rules, responses, and restoring.

## Deployment

- [Configuration](https://node-image-server.pardn.io/configuration.md): NODE_PORT, NODE_ENV, and DOMAIN variables, PM2 and cluster settings, and the storage/image directory layout.
- [Nginx](https://node-image-server.pardn.io/deployment-nginx.md): Nginx routing blocks, proxy_cache settings, security headers, and restricting upload and delete by source IP.
- [Cloudflare Worker](https://node-image-server.pardn.io/deployment-cloudflare-worker.md): Cloudflare Worker edge cache for node-image-server: accepted extensions, query-string cache key, and deployment.

## Reference

- [Known Limitations](https://node-image-server.pardn.io/known-limitations.md): Known node-image-server issues: unlocked type dependencies, port mismatch, cache-hit Content-Type, and cache purging.

## Symbols

Exported symbol -> page that documents it.

- `DeleteFromPath` (app/src/router/delete): [HTTP API Reference](https://node-image-server.pardn.io/api-reference.md), [Architecture](https://node-image-server.pardn.io/architecture.md)
- `GetFromPath` (app/src/router/get): [HTTP API Reference](https://node-image-server.pardn.io/api-reference.md), [Architecture](https://node-image-server.pardn.io/architecture.md)
- `PostToPath` (app/src/router/post): [HTTP API Reference](https://node-image-server.pardn.io/api-reference.md), [Architecture](https://node-image-server.pardn.io/architecture.md)

## 中文文件

- [首頁](https://node-image-server.pardn.io/zh/index.md): 邱敬幃（Pardn Chiu）的自架 Node.js 圖片伺服器：sharp 即時轉 WebP 縮圖，Nginx 與 CDN 快取，日期歸檔垃圾桶。
- [快速開始](https://node-image-server.pardn.io/zh/getting-started.md): 以 Docker Compose 或本機啟動 node-image-server，完成第一次上傳並讀取轉檔後的 WebP 或 AVIF 圖片。
- [架構](https://node-image-server.pardn.io/zh/architecture.md): node-image-server 架構概覽：Cloudflare Worker、Nginx、Express cluster、sharp 與儲存目錄。
- [快取層](https://node-image-server.pardn.io/zh/caching.md): 瀏覽器、Cloudflare Worker、Nginx 與本機快取檔四層快取的快取鍵、存活時間與清除方式。
- [圖片處理流程](https://node-image-server.pardn.io/zh/image-pipeline.md): GET /c/img 如何串流原檔或以 sharp 轉檔：參數解析、快取查找、編碼預設值與失敗處理。
- [HTTP API 參考](https://node-image-server.pardn.io/zh/api-reference.md): node-image-server 全部 HTTP 端點、User-Agent 與 CORS 共用行為、請求日誌與 Nginx 路由。
- [圖片參數](https://node-image-server.pardn.io/zh/api-reference-image.md): GET /c/img 的 query 參數：尺寸、寬高、品質、WebP／AVIF／JPG／PNG 格式、原檔與深色 404 圖。
- [尺寸規則](https://node-image-server.pardn.io/zh/api-reference-sizing.md): s、w、h 如何換算輸出尺寸，預設長邊 1024px、不放大規則與邊界情況。
- [上傳 API](https://node-image-server.pardn.io/zh/api-reference-upload.md): POST /upload 的 multipart 請求、支援格式、隨機檔名規則、201 JSON 回應與錯誤訊息。
- [刪除 API](https://node-image-server.pardn.io/zh/api-reference-delete.md): DELETE /del 將檔案或資料夾搬入依 UTC 日期分類的 .trash：同名規則、回應與還原方式。
- [設定](https://node-image-server.pardn.io/zh/configuration.md): NODE_PORT、NODE_ENV、DOMAIN 環境變數，PM2 與 cluster 設定，以及 storage/image 目錄配置。
- [Nginx](https://node-image-server.pardn.io/zh/deployment-nginx.md): Nginx 路由區塊、proxy_cache 設定、安全標頭，以及依來源 IP 限制上傳與刪除。
- [Cloudflare Worker](https://node-image-server.pardn.io/zh/deployment-cloudflare-worker.md): node-image-server 的 Cloudflare Worker 邊緣快取：接受的副檔名、query string 快取鍵與部署步驟。
- [已知限制](https://node-image-server.pardn.io/zh/known-limitations.md): node-image-server 已知問題：型別依賴未鎖版、埠號不一致、快取命中 Content-Type 與快取清除。