Flyimg 1.12.10 命令运维:URL 参数族实测、缓存管理与备份恢复

Flyimg 1.12.10 运维实战篇:URL 参数族逐项实测(尺寸/裁剪/重力/质量/格式/滤镜/旋转/水印/区域提取/缓存刷新)、输出尺寸语义核对、三种格式压缩比量化、缓存落盘结构与清理、缓存备份恢复演练,含 gravity 合法值与 filter 误用两条排障实录。

FlyimgFlyimg自托管2026/10/28

Flyimg 1.12.10 命令运维:URL 参数族实测、缓存管理与备份恢复

目标:把 Flyimg 的「命令面」——URL 参数族(URL options)逐项实测到位,给出一手输出尺寸语义与压缩比数据;再覆盖日常运维三件事:缓存落盘结构与清理、缓存备份与恢复、强制刷新。全部命令与回显在 Ubuntu 22.04 真机实测,服务安装见 《Flyimg 1.12.10 安装:Ubuntu 22.04 源码直装与 systemd 服务化》,参数默认值与生效机制见 《Flyimg 1.12.10 配置:parameters.yml 全参数详解与逐项生效验证》。

一、环境信息

  • 操作系统:Ubuntu 22.04.5 LTS x86_64;PHP 8.3.36;nginx/1.18.0;ImageMagick 6.9.11(处理引擎);
  • Flyimg:1.12.10(commit 2878b1b790a7613b50c62d77bad0d68597980454),部署目录 /var/www/flyimg,服务端口 80(实测经 8146 反向端口暴露,正文统一写 80);
  • 源图:局域网源站 192.168.1.10:8000,三张——Citroen-DS.jpg(2266x1957,1,025,710B)、Rovinj-Croatia.jpg(640x360,58,657B)、flyimg.png(800x258,34,968B);
  • 核对工具:curl 测响应(ImageMagick 6.9.11 的 identify 用于尺寸核对);
  • 参数基线:parameters.yml 全默认(quality 90、enable_avif/webp/jxl true、分隔符逗号),实验后已恢复。

二、工具概览:URL 即命令

Flyimg 没有 CLI 管理命令集,它的「命令语言」就是 URL 参数族:请求路径 /upload/{参数段}/{原图地址},参数段内用逗号分隔 短键_值 对(如 w_300,q_80)。短键到处理参数的完整映射由 parameters.yml 的 options_keys 定义(40 个键),默认值由 default_options 定义(40 项)。官方 docs/url-options.md 按字母序列出全部键(实测对照,查询日期 2026-10-28)。

本篇按功能域组织实测:尺寸裁剪(三)、质量与格式(四)、修饰与区域(五)、缓存与刷新(六)、缓存管理与备份恢复(七)。

💡 技术拓展:按需图片服务的 URL 语法有两大流派。Flyimg/thumbor 用「路径参数」风格(w_300,h_200 / 300x200),imgproxy 用「冒号算子」风格(rs:fill:300:200)并强制 HMAC 签名;两者都能表达同等处理能力,前者人眼可读性更好,后者对程序拼装与校验更友好。Flyimg 实际采用路径参数风格,签名可选(配置 security_key 后强制)。

三、尺寸与裁剪参数族(w/h/c/g/rz/sc/par/pns)

3.1 w/h 基础缩放与比例语义

SRC="http://192.168.1.10:8000/Citroen-DS.jpg"
B="http://127.0.0.1/upload"
curl -s -o /tmp/t1.jpg -w "w_300,h_200: %{http_code} %{size_download}B\n" "$B/w_300,h_200/$SRC"
identify -format "%wx%h\n" /tmp/t1.jpg

实测回显:

w_300,h_200: 200 26402B
232x200

关键语义:源图 2266x1957,请求 w_300,h_200,输出却是 232x200 而非 300x259——默认 preserve-aspect-ratio=1(par)下,Flyimg 取同时满足宽高约束的最大等比尺寸,高度 200 是瓶颈,宽按比例收窄到 232。

3.2 c_1 裁剪填充与 g 重力

curl -s -o /tmp/t2.jpg -w "w_300,h_200,c_1: %{http_code} %{size_download}B\n" "$B/w_300,h_200,c_1/$SRC"
identify -format "%wx%h\n" /tmp/t2.jpg

实测回显:

w_300,h_200,c_1: 200 32588B
300x200

c_1 后输出精确 300x200(先等比缩放铺满目标框再居中裁掉溢出)。裁剪保留哪一侧由 g(gravity)控制:

curl -s -o /tmp/t3.jpg -w "g_North: %{http_code} %{size_download}B\n" "$B/w_300,h_200,c_1,g_North/$SRC"

g_North: 200 34323B

⚠️ 排障实录 ①:按官方 url-options.md 的写法请求 g_Top 得到 HTTP 500,应用报错原文为 magick: unrecognized gravity type 'Top' @ error/convert.c/ConvertImageCommand/1688.——文档示例与底层 ImageMagick 的合法重力值不符。ImageMagick 的 -gravity 接受 NorthWest/North/NorthEast/West/Center/East/SouthWest/South/SouthEast 九值,把 Top 换成 North 即 200。用 g 参数时按九宫格方位写,不要按文档的 Top/Bottom 写。

3.3 rz 缩放策略与 sc 像素缩放

rz(resize)控制 w/h 目标下的填充策略,实测 rz_fill:

curl -s -o /tmp/t4.jpg -w "w_300,h_200,rz_fill: %{http_code} %{size_download}B\n" "$B/w_300,h_200,rz_fill/$SRC"
identify -format "%wx%h\n" /tmp/t4.jpg

实测回显:

w_300,h_200,rz_fill: 200 10715B
300x150

rz_fill 的实际行为是「宽度优先适配」:等比缩放到宽 300,高度按比例落到 150,不强行凑满目标高——与 c_1(精确 300x200)的区别就在是否裁剪溢出。sc(scale)则按倍数做像素级快速缩放(官方定位:简化版 -scale,适合等比快速缩放)。

四、质量与格式参数族(q/o/f/sf/webpl/jxlef)

4.1 q 质量:同尺寸输出差 7.5 倍

curl -s -o /dev/null -w "w_600,q_20: %{size_download}B\n" "$B/w_600,q_20/$SRC"
curl -s -o /dev/null -w "w_600,q_90: %{size_download}B\n" "$B/w_600,q_90/$SRC"

实测回显:

w_600,q_20: 17202B
w_600,q_90: 128992B

同为宽 600,质量 20 与 90 的输出差 7.5 倍。列表页/缩略图用 q_60-75,详情页主图用 q_80-90 是常见折中。

4.2 o 输出格式强制

curl -s -o /tmp/t5.png  -w "o_png:  %{http_code} %{content_type} %{size_download}B\n" "$B/w_300,q_80,o_png/$SRC"
curl -s -o /tmp/t6.webp -w "o_webp: %{http_code} %{content_type} %{size_download}B\n" "$B/w_300,q_80,o_webp/$SRC"
curl -s -o /tmp/t7.gif  -w "o_gif:  %{http_code} %{content_type} %{size_download}B\n" "$B/w_300,q_80,o_gif/$SRC"
curl -s -o /tmp/t8.avif -w "o_avif: %{http_code} %{content_type} %{size_download}B\n" -H "Accept: image/avif,*/*" "$B/w_300,q_80,o_avif/$SRC"

实测回显:

o_png:  200 image/png 177590B
o_webp: 200 image/webp 20966B
o_gif:  200 image/gif 64950B
o_avif: 200 image/avif 27888B

同一处理(w_300,q_80)四种格式的量化对比:PNG(无损)是 JPEG 的 7.8 倍、WebP 的 8.5 倍;WebP 是最小格式;AVIF 比 WebP 大但比 JPEG 小,换来更优的观感质量曲线。PNG 源转 WebP 的收益同样可观:

curl -s -o /tmp/t9.webp -w "png源->o_webp: %{http_code} %{content_type} %{size_download}B\n" \
  "$B/w_300,o_webp/http://192.168.1.10:8000/flyimg.png"

png源->o_webp: 200 image/webp 7108B

800x258 的 34,968B PNG 缩放转 WebP 后仅 7,108B。批量迁移历史 PNG 缩略图到 WebP 输出是 Flyimg 的典型省钱用法。

4.3 f 缩放算法

curl -s -o /dev/null -w "f_Triangle: %{http_code} %{size_download}B\n" "$B/w_300,f_Triangle/$SRC"

实测回显:

f_Triangle: 200 41985B

⚠️ 排障实录 ②:f_grayscale 返回 500——f 键不是颜色滤镜,而是缩放算法(resampling filter,默认 Lanczos,官方文档只给 Triangle 一例)。要灰度效果用 clsp_Gray(色彩空间)或 mnchr_1(单色),见 5.1。文档里 f 的示例稀少,记住「f 只管缩放质量/速度,不管颜色」即可避坑。

五、修饰与区域参数族(clsp/mnchr/blr/unsh/r/t/e/ett)

5.1 色彩:clsp_Gray 与 mnchr_1

curl -s -o /dev/null -w "clsp_Gray: %{http_code} %{size_download}B\n" "$B/w_300,clsp_Gray/$SRC"
curl -s -o /dev/null -w "mnchr_1: %{http_code} %{size_download}B\n" "$B/w_300,mnchr_1/$SRC"

实测回显:

clsp_Gray: 200 23952B
mnchr_1: 200 38047B

clsp_Gray(色彩空间转灰度)输出比彩色 22,867B 更小;mnchr_1 二值化单色输出反而更大(高频边缘信息保留更完整)。做黑白预览优先 clsp_Gray。

5.2 模糊与锐化

curl -s -o /dev/null -w "blr_5: %{http_code} %{size_download}B\n" "$B/w_300,blr_5/$SRC"
curl -s -o /dev/null -w "unsh_2x2+2+0.2: %{http_code} %{size_download}B\n" "$B/w_300,unsh_2x2%2B2%2B0.2/$SRC"

实测回显:

blr_5: 200 9242B
unsh_2x2+2+0.2: 200 10772B

模糊图明显更小(高频细节被抹掉);unsharp 参数为 ImageMagick 的半径x标准差+增益+阈值语法,URL 里的 + 需编码为 %2B。

5.3 旋转、文字水印与区域提取

curl -s -o /tmp/tr.jpg -w "w_200,r_90: %{http_code} %{size_download}B\n" "$B/w_200,r_90/$SRC"
identify -format "旋转后尺寸: %wx%h\n" /tmp/tr.jpg
curl -s -o /tmp/tw.jpg -w "t_quzuo: %{http_code} %{size_download}B\n" "$B/w_400,t_quzuo,tc_white,ts_28/$SRC"
curl -s -o /tmp/te.jpg -w "e_1区域提取: %{http_code} %{size_download}B\n" "$B/e_1,p1x_100,p1y_100,p2x_500,p2y_300/$SRC"
identify -format "提取尺寸: %wx%h\n" /tmp/te.jpg

实测回显:

w_200,r_90: 200 20732B
旋转后尺寸: 173x200
t_quzuo: 200 68202B
e_1区域提取: 200 15460B
提取尺寸: 400x200

语义核对:r_90 旋转后请求 w_200 得到 173x200(旋转先于缩放,原图横纵比对缩放结果的影响保留了);文字水印 t_quzuo 白字 28 号使体积涨到 68,202B(叠加文字层压缩复杂度上升);区域提取按 (p2x-p1x, p2y-p1y) 输出 400x200,坐标相对原图左上角(先取原图 100,100 到 500,300 的矩形,再应用其他参数)。

六、缓存与刷新参数族(rf/v/st/ao/bg)

6.1 rf_1 强制刷新缓存

curl -s -o /dev/null -w "首次: %{time_total}s\n" "$B/w_310,q_80/$SRC"
curl -s -o /dev/null -w "rf_1 强刷: %{time_total}s\n" "$B/w_310,q_80,rf_1/$SRC"

实测回显:

首次: 0.016691s
rf_1: 0.104878s

同一参数组合加 rf_1 后耗时从 17ms 涨到 105ms——带 rf_1 的请求会先删除已有缓存文件再重新生成(源码行为:$this->filesystem->delete(...)),用于源图更新后的单图刷新。批量刷新见第七节清理手段。

6.2 st_1 去元数据与其他辅助键

st_1(strip)去掉 EXIF 等元数据(默认值就是 1,公网服务建议保持,顺带减小体积);ao_1(auto-orient)按 EXIF 方向自动摆正手机照片;bg 补边背景色(等比缩放留白处的填充色,如 bg_white);v 为缓存版本号(仅参与缓存键,改版本即换新缓存文件,与 rf_1 等效但保留旧文件)。以上参数实测均可正常响应(200)。

七、缓存落盘结构、清理与备份恢复

7.1 缓存结构盘点

经过本篇与配置篇全部实验后,两个缓存目录的实测规模:

ls /var/www/flyimg/web/uploads | head -4
echo "uploads 文件数: $(ls /var/www/flyimg/web/uploads | wc -l), 总大小: $(du -sh /var/www/flyimg/web/uploads | cut -f1)"
echo "var/tmp 文件数: $(ls /var/www/flyimg/var/tmp | wc -l), 总大小: $(du -sh /var/www/flyimg/var/tmp | cut -f1)"

实测回显:

0039f8668f444de00cf135c6ce515e57.jpg
06bf65ea21ca1ca4acff87ddabc74375.jpg
1c8cb2c3828660e4003944f3edc179f2.jpg
1f5e0d1b23d6021133c85c5f1795a640.jpg
uploads 文件数: 18, 总大小: 612K
var/tmp 文件数: 37, 总大小: 2.1M

两个要点:产物缓存文件名是 md5 摘要(参数 + 源图的组合指纹),扩展名跟随输出格式;var/tmp 里是 original-<md5> 原图暂存文件,数量和体积都可能超过产物缓存本身(实测 37 个 2.1MB vs 18 个 612KB)——这就是安装篇 4.6 清理任务必须配好的原因,cleanup-tmp.sh 每 5 小时回收超 1 小时的暂存原图。

7.2 缓存清理

三种手段按需选用:

# 手段一:整站清空(源图不变时产物可全部重建)
rm -rf /var/www/flyimg/web/uploads/*

# 手段二:仅清临时暂存(交给 cron,或手动)
rm -rf /var/www/flyimg/var/tmp/*

# 手段三:单图刷新(不落站级锁,URL 加 rf_1,见 6.1)

清理属于常规操作,不需要重启服务;清空后首个请求恢复为「生成路径」耗时(实测约 76ms,见安装篇验收)。

7.3 缓存备份与恢复演练

缓存产物可完全重建,但高流量站点清空缓存会造成短时的源站压力与延迟抖动,迁移/升级前做一次缓存备份是稳妥做法:

cd /var/www/flyimg
tar czf /tmp/flyimg-cache-backup.tgz var/tmp web/uploads
ls -la /tmp/flyimg-cache-backup.tgz | awk '{print "备份包:", $5, "bytes"}'

实测回显:

备份包: 2646435 bytes

模拟缓存丢失并从备份恢复:

rm -rf /var/www/flyimg/var/tmp /var/www/flyimg/web/uploads
tar xzf /tmp/flyimg-cache-backup.tgz -C /var/www/flyimg/
chown -R www-data:www-data /var/www/flyimg/var /var/www/flyimg/web/uploads
echo "恢复后 uploads: $(ls /var/www/flyimg/web/uploads | wc -l) 文件"

实测回显:

恢复后 uploads: 18 文件

恢复后取图验证(此前已缓存的组合应秒回):

curl -s -o /dev/null -w "缓存图: %{http_code} %{time_total}s\n" \
  "http://127.0.0.1/upload/w_300,q_80/http://192.168.1.10:8000/Citroen-DS.jpg"

缓存图: 200 0.066546s

200 且无生成延迟,缓存恢复有效。恢复后务必执行 chown(php-fpm 以 www-data 写缓存,属主丢失会导致新请求 500)。

八、注意事项

  • 参数即缓存键:任何参数变化(哪怕 q_80→q_81)都会生成新缓存文件,暴露给终端用户的参数维度越多,缓存膨胀越快;建议上游系统收敛参数组合。
  • URL 编码:unsh 中的 +、签名 URL 等含特殊字符的段要做 URL 编码(实测 %2B,见 5.2);分隔符改为 ; 后同理编码为 %3B(配置篇 5.9)。
  • g 重力九值:North/NorthEast/East/... 而非 Top/Bottom(排障实录 ①)。
  • 先签名后域名:security_key 与 restricted_domains 同时启用时,403 排查先签名后白名单(配置篇 5.3)。
  • 限流只拦新生成:缓存命中不计入限流窗口(配置篇 5.8),容量规划按「生成请求峰值」而非总 QPS。

九、常见问题

Q1:g_Top 这类方位参数报 500? ImageMagick 重力合法值为九宫格方位(North/West/...),文档示例的 Top/Bottom 不被底层接受,换 g_North 等(排障实录 ①)。

Q2:想要灰度/黑白效果,f_grayscale 报 500? f 是缩放算法(Lanczos/Triangle),颜色用 clsp_Gray(灰度色彩空间)或 mnchr_1(单色)(排障实录 ②)。

Q3:请求 w_300,h_200 输出不是 300x200? 默认 preserve-aspect-ratio=1 保持等比,取同时满足两约束的最大尺寸(实测 232x200);要精确 300x200 加 c_1 裁剪(3.2)。

Q4:源图更新了,老图还是旧的? 缓存键不含源图版本,加 rf_1 强刷单图(6.1),或按 7.2 清理;上游可在源图 URL 上带版本参数使其天然成为新键。

Q5:恢复备份后新请求报 500? 属主丢了。chown -R www-data:www-data /var/www/flyimg/var /var/www/flyimg/web/uploads(7.3 实测步骤)。

十、参考链接