Go 编写的 高性能图片处理服务器picfit快速使用手册

picfit（GitHub 项目地址：https://github.com/thoas/picfit）是一个用 Go 编写的 高性能图片处理服务器，支持动态调整尺寸、裁剪、旋转、格式转换等操作。它通常作为 图片处理微服务 部署在后端，配合 CDN 或缓存层（如 Varnish）使用。

下面为你详细介绍 如何部署和使用 picfit，包括安装、配置、启动和调用方式。

 一、核心功能

• 支持的操作：resize（缩放）、thumbnail（缩略图+裁剪）、rotate、flip、noop（原图）、effect（模糊）等
• 支持的格式：JPEG、PNG、GIF、BMP、WebP
• 存储后端：本地文件系统（fs）、HTTP、Amazon S3、DigitalOcean Spaces、Google Cloud Storage 等
• 缓存机制：可搭配 Redis 或内存缓存避免重复生成
• 安全机制：支持请求签名（HMAC-SHA1）防止滥用
• 输出方式：直接显示图片（/display）、重定向（/redirect）、返回元信息（/get）

 二、快速开始（最简示例）

1. 安装（通过 Docker，推荐）

# 拉取镜像
docker pull thoas/picfit

# 启动（仅处理来自 URL 的图片，无持久化存储）
docker run -p 3001:3001 thoas/picfit

默认监听 http://localhost:3001

2. 调用示例（直接处理网络图片）

假设你要将一张网络图片缩放到 200x200：

<img src="http://localhost:3001/display?url=https%3A%2F%2Fexample.com%2Fphoto.jpg&w=200&h=200&op=resize">

或直接访问：

http://localhost:3001/display?url=https://example.com/photo.jpg&w=200&h=200&op=resize

 效果：自动下载 photo.jpg，缩放为 200x200 并返回 JPEG/PNG 图片。

 三、配置文件详解（config.json）

picfit 通过 JSON 配置文件控制行为。以下是一个 常用生产配置示例（从本地目录读图，结果缓存在内存，图片存本地）：

{
  "port": 3001,
  "debug": false,
  "storage": {
    "src": {
      "type": "fs",
      "location": "/var/www/images/original/"
    }
  },
  "kvstore": {
    "type": "cache"
  }
}

常见配置项说明：

💡 更多配置参考官方 README.rst

 四、支持的请求参数（URL Query）

通用格式：

http://picfit-host/{method}?{params}

常用参数：

方法（Method）：

• /display：直接返回图片（适合 <img> 标签）
• /redirect：生成后 302 重定向到结果 URL（需配置 dst 存储）
• /get：返回 JSON 元信息（filename, path, url）

 五、安全建议

1. 启用请求签名（防止任意图片处理）：

   {
     "secret_key": "your-secret-key-here"
   }
   

   客户端需用 HMAC-SHA1 对查询字符串签名，并附加 sig=xxx。

2. 限制允许尺寸（防资源耗尽）：

   {
     "options": {
       "allowed_sizes": [
         {"width": 100, "height": 100},
         {"width": 800}
       ]
     }
   }
   

3. 关闭上传/删除接口（默认已关闭）：

   • 如需启用，显式设置 "enable_upload": true，并用 Nginx 限制 IP。

 六、Docker 部署示例（带配置文件）

1. 创建 config.json：

   {
     "port": 3001,
     "storage": {
       "src": { "type": "fs", "location": "/data/images/" }
     },
     "kvstore": { "type": "cache" }
   }
   

2. 启动容器：

   docker run -d \
     --name picfit \
     -p 3001:3001 \
     -v $(pwd)/config.json:/app/config.json \
     -v /your/image/dir:/data/images \
     thoas/picfit -c /app/config.json
   

 七、典型使用场景

• 用户头像自动裁剪：/display?path=avatars/123.png&w=100&h=100&op=thumbnail
• 商品图统一尺寸：/display?path=products/456.jpg&w=800&h=600&op=resize
• 移动端 WebP 优化：/display?path=img.png&fmt=webp&q=75

 官方资源

• GitHub: https://github.com/thoas/picfit
• 文档（README）: https://github.com/thoas/picfit/blob/main/README.rst
• Docker Hub: https://hub.docker.com/r/thoas/picfit

如果你有具体需求（比如“如何对接 S3”、“如何加签名”），可以告诉我，我会给出针对性配置！

© 本文著作权归作者所有。转载请联系授权，禁止商用。