shumc/imagor Docker 镜像 - 轩辕镜像 | Docker 镜像高效稳定拉取服务

imagor

镜像概述和主要用途

imagor 是一个快速、安全的图像处理服务器和 Go 库。它基于高效的图像处理库 libvips，通常比 ImageMagick 和 GraphicsMagick 的最快配置快 4-8 倍。imagor 实现了 libvips 的流式处理，支持并行处理管道，实现高网络吞吐量。作为 HTTP 服务器提供服务，原生支持 Docker，采用 thumbor URL 语法，可作为其高性能替代品。同时，imagor 也是一个以速度、安全性和可扩展性为核心的 Go 库，配合 imagorvideo 可通过 ffmpeg C 绑定实现视频缩略图功能。

核心功能和特性

高效图像处理

• 基于 libvips 库，具备高效的图像处理能力，处理速度远超传统工具
• 支持流式处理，实现并行处理管道，提升网络吞吐量

丰富的图像处理能力

• 支持裁剪、缩放（fit-in、stretch 模式）、旋转、翻转、填充、水印、文字标签等多种操作
• 提供多种滤镜：模糊、亮度、对比度、饱和度、色调调整、灰度化、圆角等
• 支持多种输出格式：jpeg、png、gif、webp、tiff、avif，自动 WebP 转换

灵活的存储与加载

• 支持多种加载器（Loader）：HTTP(s)、文件系统、AWS S3、Google Cloud Storage 等
• 支持多种存储（Storage）和结果存储（Result Storage）：文件系统、AWS S3、GCS 等，可缓存原始图像和处理结果

安全特性

• URL 签名机制，防止 URL 篡改和 DDoS ***
• 支持自定义 HMAC 签名算法（sha1、sha256、sha512）
• 图像炸弹防护，限制最大分辨率和尺寸
• 允许源白名单，限制图像加载来源

其他功能

• 元数据提取端点，支持获取图像格式、分辨率、Exif 信息
• 兼容 thumbor URL 语法，可无缝替换
• 作为 Go 库提供，支持自定义扩展

使用场景和适用范围

适用场景

• 动态图像处理服务：实时生成缩略图、裁剪图像、转换格式
• 内容分发网络（CDN）前置处理：优化图像大小和格式，提升加载速度
• 电商平台：商品图片水印、尺寸标准化、高清缩略图
• 社交媒体：用户头像处理、图片滤镜应用、动态内容生成
• 企业应用：文档扫描件优化、报表图像生成、安全图像服务

适用范围

• 需要高性能图像处理的 Web 应用
• 对图像安全有要求的系统（防止 URL 篡改、***请求）
• 多存储源（本地文件、云存储）的图像管理
• 需兼容 thumbor 语法的现有系统升级
• 基于 Go 开发的自定义图像处理流程

详细的使用方法和配置说明

快速开始

Docker 快速启动

bash
docker run -p 8000:8000 shumc/imagor -imagor-unsafe -imagor-auto-webp

• -imagor-unsafe：启用不安全模式（无需 URL 签名，仅测试用）
• -imagor-auto-webp：自动为支持的浏览器输出 WebP 格式

测试图像 URL 示例

原始图像：

• https://raw.githubusercontent.com/cshum/imagor/master/testdata/gopher.png
• https://raw.githubusercontent.com/cshum/imagor/master/testdata/dancing-banana.gif

处理后图像示例：

• 等比缩放至 200x200，白色填充：
  http://localhost:8000/unsafe/fit-in/200x200/filters:fill(white)/https://raw.githubusercontent.com/cshum/imagor/master/testdata/gopher.png
• 裁剪并转换为 JPEG（质量 80）：
  http://localhost:8000/unsafe/200x200/smart/filters:fill(white):format(jpeg):quality(80)/https://raw.githubusercontent.com/cshum/imagor/master/testdata/gopher.png

图像端点

图像端点 URL 结构定义了图像处理操作，格式如下：

/HASH|unsafe/trim/AxB:CxD/fit-in/stretch/-Ex-F/GxH:IxJ/HALIGN/VALIGN/smart/filters:NAME(ARGS):NAME(ARGS):.../IMAGE

URL 各部分说明

• HASH|unsafe：URL 签名哈希（生产环境）或 unsafe（测试模式）
• trim：按左上角像素颜色裁剪图像周围空白区域
• AxB:CxD：手动裁剪，左上角坐标 AxB，右下角坐标 CxD（支持 0-1 浮点数表示百分比）
• fit-in：缩放图像以适应 ExF 尺寸，不自动裁剪
• stretch：拉伸图像至 ExF 尺寸，不保持宽高比
• -Ex-F：缩放至 ExF 尺寸，负号表示水平/垂直翻转
• GxH:IxJ：添加内边距，左上角 GxH，右下角 IxJ
• HALIGN：水平对齐方式，可选 left（左）、right（右）、center（中，默认）
• VALIGN：垂直对齐方式，可选 top（上）、bottom（下）、middle（中，默认）
• smart：智能检测焦点区域
• filters：图像滤镜管道，格式 NAME(ARGS):NAME(ARGS)...
• IMAGE：图像路径或 URI（含 ? 时需用 encodeURIComponent 编码）

滤镜（Filters）

滤镜通过 filters:NAME(ARGS):NAME(ARGS)... 定义，按顺序应用于图像。

常用滤镜说明

滤镜示例

• 白色填充 + JPEG 格式：filters:fill(white):format(jpeg)
• 色调调整 + 饱和度 + 黄色填充：filters:hue(290):saturation(100):fill(yellow)
• 重复水印（底部对齐）：filters:watermark(uri,repeat,bottom,0,40,40)

加载器、存储和结果存储

imagor 通过加载器（Loader）加载原始图像，存储（Storage）缓存原始图像，结果存储（Result Storage）缓存处理后的图像，支持多种存储后端。

文件系统存储

通过 Docker Compose 配置本地文件系统存储：

yaml
version: "3"
services:
  imagor:
    image: shumc/imagor:latest
    volumes:
      - ./data:/mnt/data  # 挂载本地目录到容器
    environment:
      PORT: 8000
      IMAGOR_UNSAFE: 1  # 测试用不安全模式
      
      # 文件加载器配置
      FILE_LOADER_BASE_DIR: /mnt/data  # 加载器根目录
      
      # 文件存储配置（缓存原始图像）
      FILE_STORAGE_BASE_DIR: /mnt/data
      FILE_STORAGE_MKDIR_PERMISSION: 0755  # 目录权限（默认 0755）
      FILE_STORAGE_WRITE_PERMISSION: 0666  # 文件权限（默认 0666）
      
      # 文件结果存储配置（缓存处理后图像）
      FILE_RESULT_STORAGE_BASE_DIR: /mnt/data/result
    ports:
      - "8000:8000"

AWS S3 存储

支持 AWS S3 及兼容服务（MinIO、DigitalOcean Spaces）：

yaml
version: "3"
services:
  imagor:
    image: shumc/imagor:latest
    environment:
      PORT: 8000
      IMAGOR_SECRET: mysecret  # URL 签名密钥
      
      # AWS 全局配置
      AWS_ACCESS_KEY_ID: YOUR_ACCESS_KEY
      AWS_SECRET_ACCESS_KEY: YOUR_SECRET_KEY
      AWS_REGION: us-east-1
      
      # S3 加载器配置
      S3_LOADER_BUCKET: mybucket  # 存储桶名称
      S3_LOADER_BASE_DIR: images  # 可选，基础路径
      
      # S3 存储配置（缓存原始图像）
      S3_STORAGE_BUCKET: mybucket
      S3_STORAGE_BASE_DIR: images
      S3_STORAGE_ACL: public-read  # 访问控制列表（可选）
      
      # S3 结果存储配置（缓存处理后图像）
      S3_RESULT_STORAGE_BUCKET: mybucket
      S3_RESULT_STORAGE_BASE_DIR: images/result
      
      # 自定义 S3 端点（如 MinIO）
      S3_ENDPOINT: http://minio:9000
      S3_FORCE_PATH_STYLE: 1  # 启用路径风格访问（http://endpoint/bucket/key）
    ports:
      - "8000:8000"

独立凭证配置：可为加载器/存储/结果存储配置独立 AWS 凭证：

dotenv
# S3 加载器独立配置
AWS_LOADER_REGION=us-west-2
AWS_LOADER_ACCESS_KEY_ID=LOADER_KEY
AWS_LOADER_SECRET_ACCESS_KEY=LOADER_SECRET
S3_LOADER_ENDPOINT=http://loader-minio:9000

# S3 存储独立配置
AWS_STORAGE_REGION=us-east-1
AWS_STORAGE_ACCESS_KEY_ID=STORAGE_KEY
AWS_STORAGE_SECRET_ACCESS_KEY=STORAGE_SECRET
S3_STORAGE_ENDPOINT=http://storage-s3:9000

Google Cloud Storage 存储

yaml
version: "3"
services:
  imagor:
    image: shumc/imagor:latest
    volumes:
      - ./gcp-credentials.json:/etc/secrets/gcp.json  # GCP 凭证文件
    environment:
      PORT: 8000
      IMAGOR_SECRET: mysecret
      GOOGLE_APPLICATION_CREDENTIALS: /etc/secrets/gcp.json  # 凭证文件路径
      
      # GCS 加载器配置
      GCLOUD_LOADER_BUCKET: mybucket
      GCLOUD_LOADER_BASE_DIR: images
      
      # GCS 存储配置
      GCLOUD_STORAGE_BUCKET: mybucket
      GCLOUD_STORAGE_BASE_DIR: images
      GCLOUD_STORAGE_ACL: publicRead  # 访问控制（可选）
      
      # GCS 结果存储配置
      GCLOUD_RESULT_STORAGE_BUCKET: mybucket
      GCLOUD_RESULT_STORAGE_BASE_DIR: images/result
    ports:
      - "8000:8000"

存储路径风格

可通过环境变量配置存储路径哈希规则：

• IMAGOR_STORAGE_PATH_STYLE=digest：原始图像路径按哈希分目录（如 e6/86/1a810ff186b4f747ef85f7c53946f0e6d8cb）
• IMAGOR_RESULT_STORAGE_PATH_STYLE=suffix：处理结果路径添加哈希后缀（如 foobar.45d8ebb31bd4ed80c26e.jpg）

安全配置

URL 签名

生产环境必须禁用 IMAGOR_UNSAFE，启用 URL 签名防止篡改。签名基于 SHA 哈希和密钥，计算方式如下（Node.js 示例）：

javascript
const crypto = require('crypto');

function sign(path, secret) {
  const hash = crypto.createHmac('sha1', secret)  // 默认 SHA1
    .update(path)
    .digest('base64')
    .replace(/\+/g, '-').replace(/\//g, '_');  // Base64 URL 编码
  return hash + '/' + path;
}

// 示例：生成签名 URL
const signedPath = sign('500x500/top/raw.githubusercontent.com/cshum/imagor/master/testdata/gopher.png', 'mysecret');
// 输出：cST4Ko5_FqwT3BDn-Wf4gO3RFSk=/500x500/top/raw.githubusercontent.com/cshum/imagor/master/testdata/gopher.png

使用时 URL 为 http://localhost:8000/${signedPath}。

自定义 HMAC 签名器

默认使用 SHA1，可配置更安全的算法：

dotenv
IMAGOR_SIGNER_TYPE=sha256  # 支持 sha1/sha256/sha512
IMAGOR_SIGNER_TRUNCATE=40  # 截断哈希长度（默认 28）

图像炸弹防护

限制最大图像分辨率和尺寸，防止大图像：

dotenv
VIPS_MAX_RESOLUTION=16800000  # 最大像素数（宽×高），默认 16800000（4MP）
VIPS_MAX_WIDTH=5000  # 最大宽度，默认 5000
VIPS_MAX_HEIGHT=5000  # 最大高度，默认 5000

允许的源

限制仅从白名单主机加载图像：

dotenv
HTTP_LOADER_ALLOWED_SOURCES=*.example.com,cdn.example.com,s3.amazonaws.com  # CSV 格式，支持通配符

元数据和参数端点

元数据端点

添加 /meta 前缀获取图像元数据（格式、分辨率、Exif 等）：

http://localhost:8000/unsafe/meta/fit-in/50x50/raw.githubusercontent.com/cshum/imagor/master/testdata/Canon_40D.jpg

返回 JSON 示例：

json
{
  "format": "jpeg",
  "content_type": "image/jpeg",
  "width": 50,
  "height": 34,
  "orientation": 1,
  "exif": {
    "Make": "Canon",
    "Model": "Canon EOS 40D",
    "DateTime": "2008:07:31 10:38:11"
  }
}

参数端点

添加 /params 前缀获取端点参数解析结果：

bash
curl 'http://localhost:8000/params/g5bMqZvxaQK65qFPaP1qlJOTuLM=/fit-in/500x400/0x20/filters:fill(white)/raw.githubusercontent.com/cshum/imagor/master/testdata/gopher.png'

Go 库使用示例

imagor 可作为 Go 库集成到自定义应用：

go
package main

import (
  "context"
  "io"
  "os"

  "github.com/cshum/imagor"
  "github.com/cshum/imagor/imagorpath"
  "github.com/cshum/imagor/loader/httploader"
  "github.com/cshum/imagor/vips"
)

func main() {
  // 创建 imagor 实例，配置加载器和处理器
  app := imagor.New(
    imagor.WithLoaders(httploader.New()),  // HTTP