ImageFlow：自托管图片管理与智能分发平台，一个 API 搞定图片优化

前言

网站上的图片是个麻烦事。

一张照片拍出来 5MB，直接放网页上加载半秒钟。转成 WebP 缩小到 200KB，但 Safari 旧版本不支持。换成 AVIF 更小，但 Firefox 的支持又滞后了几个版本。

手动转格式、维护多套分辨率、给不同设备配不同图片 —— 这些体力活在 2026 年应该自动化了。

ImageFlow 就是干这个的。它像一个图片中间层：你把原图丢进去，它自动转成 WebP 和 AVIF，然后根据访问者的浏览器和设备类型，智能选择最优格式返回。

它到底做了什么

简化版流程：

上传原图 → ImageFlow 接收
           ├── 存储原始文件
           ├── 异步转 WebP + AVIF
           └── 元数据入库（Redis）


访问图片 → 分析 User-Agent
           ├── 检测浏览器支持（AVIF > WebP > 原图）
           ├── 检测设备方向（横屏/竖屏）
           └── 返回最佳格式

关键在于「智能选择」—— 不是简单转个格式，而是根据访问者的实际情况动态决策。Chrome 用户拿 AVIF，Safari 用户拿 WebP，老浏览器拿原图。这个决策过程发生在每次请求时，不需要你手动维护多套 URL。

Docker 部署

Terminal window
git clone https://github.com/Yuri-NagaSaki/ImageFlow.git
cd ImageFlow
cp .env.example .env

编辑 .env，至少改两个：

Terminal window
API_KEY=your-strong-key-here    # 管理 API 认证
STORAGE_TYPE=local              # 或 s3

启动：

Terminal window
docker compose up -d

三个容器：前端（Next.js,

）、后端（Go + libvips, 
）、Redis（缓存 + 元数据）。

存储方案

本地存储（默认）

Terminal window
STORAGE_TYPE=local
LOCAL_STORAGE_PATH=static/images

图片存在容器卷里，Docker Compose 映射到宿主机 ./data/images。小站点够用。

S3 存储（生产推荐）

Terminal window
STORAGE_TYPE=s3
S3_ENDPOINT=https://xxx.r2.cloudflarestorage.com
S3_ACCESS_KEY=xxx
S3_SECRET_KEY=xxx
S3_BUCKET=imageflow
CUSTOM_DOMAIN=https://cdn.yourdomain.com    # 可选 CDN 加速

支持 AWS S3、Cloudflare R2、MinIO 等所有 S3 兼容存储。CUSTOM_DOMAIN 可选，配了之后返回的图片 URL 走 CDN。

在网站中使用

上传图片后，通过 API 获取：

<!-- 随机图片（自动根据浏览器选格式） -->
<img src="https://img.yourdomain.com/api/random?format=webp">


<!-- 按标签过滤 + 强制方向（移动端） -->
<img src="https://img.yourdomain.com/api/random?tags=nature&orientation=portrait">

API 支持的参数：

参数作用
format指定格式（webp / avif），也可不指定让系统自动选
tags按标签过滤
orientation横屏 landscape / 竖屏 portrait

ImageFlow 返回的图片带 Cache-Control: max-age=31536000，浏览器缓存一年。建议在前面套一层 CDN，CDN 缓存 + ImageFlow 自动格式 = 最佳体验。

管理界面

前端 :3000 端口提供 Web 管理界面，支持拖拽上传、标签管理、图片浏览。API 也支持批量上传：

Terminal window
curl -X POST https://img.yourdomain.com/api/upload \
  -H "Authorization: Bearer $API_KEY" \
  -F "images[]=@photo1.jpg" \
  -F "images[]=@photo2.png" \
  -F "tags=blog,2026"

跟传统图床的区别

传统图床（PicList + R2）是你手动转格式然后上传固定 URL。ImageFlow 的思路是：你只管传原图，格式和分发它帮你做决策。

ImageFlowPicList + R2
格式转换自动（上传时转）手动（PicList 可设规则）
智能分发根据浏览器自动选格式固定 URL
管理界面Web UI + APIPicList 客户端
适用场景网站图片服务、动态分发博客写作、固定配图

两者不冲突 —— 写文章配图用 PicList，网站需要动态图片服务用 ImageFlow。

性能调优

关键参数在 .env 里：

Terminal window
IMAGE_QUALITY=80          # 画质 75-85 是网页最佳区间
WORKER_THREADS=4          # 等于 CPU 核心数
WORKER_POOL_SIZE=4        # 核心数 ×2
  • CPU 多就拉高 WORKER_THREADS，上传后转换更快
  • 内存小就降低 WORKER_POOL_SIZE，减少并发处理
  • 全是照片（照片细节多）→ IMAGE_QUALITY=85；图标截图类 → IMAGE_QUALITY=75

总结

ImageFlow 解决的是「网站图片多了之后怎么管」这个问题。自动转格式 + 智能分发 + S3 存储 + CDN 前置，适合博客、图库、电商等需要大量图片的网站。

Docker 一条命令部署，配好 .env 就能用。跟 PicList 的区别在于：PicList 是写作工具，ImageFlow 是网站基础设施。如果只是博客配图，PicList 够了；如果需要给用户提供图片服务，ImageFlow 值得一试。