imgproxy 4.0 配置参数详解
imgproxy v4.0.19 全部 IMGPROXY_* 环境变量详解：签名 KEY/SALT/SIGNATURE_SIZE、图源与白名单、TTL/ETag/调试头、质量与 WebP/AVIF 自动协商、分辨率与体积上限、超时、水印、日志，每项配修改-重启-实测回显闭环，附两套生产配置模板
imgproxy 4.0 配置参数详解
目标：系统梳理 imgproxy v4.0.19 的全部
IMGPROXY_*环境变量——签名与安全、图源控制、缓存协商、质量与格式、安全上限、超时、水印、可观测性八大类。每个影响运行时行为的参数均给出「修改 → 重启 → 实测验证」完整闭环，响应头、状态码、日志逐条照录实测结果；文末附两套生产配置模板与 FAQ。已在 Ubuntu 24.04.5 LTS（x86_64）+ imgproxy 4.0.19 环境实测通过。
一、环境信息
- 操作系统：Ubuntu 24.04.5 LTS（x86_64）
- imgproxy：v4.0.19（
imgproxy version实测输出4.0.19） - 服务监听：127.0.0.1:8140
- 演示源站：内部 HTTP 图片服务器 http://origin（另经 127.0.0.1:8141 暴露同一批文件，用于白名单对照实验）
- 本地图源根目录：/images（内含 photo-1920x1080.jpg 104248 字节、two-tone-320x240.jpg 2352 字节、watermark-300x120.png 等）
- 配置方式：imgproxy 无配置文件，全部配置经
IMGPROXY_*环境变量注入；本文以/etc/imgproxy/imgproxy.env+ systemdEnvironmentFile=托管为例 - 签名密钥对（演示环境实测值）：IMGPROXY_KEY=
e2f29550ff27f4f6b6475b16b1af3cb648434daa215361c03ca61efab13c04f0，IMGPROXY_SALT=b858fad4bd3ec36662d606c13c0d6fdda3ba980689163ff6128022ded3a662c9（openssl rand -hex 32 生成） - 参考底稿：官方文档 Configuration 页（docs.imgproxy.net，2026-10-25 查询）；标注「官方口径」的参数为官方默认值转述、未单独复现，其余均附实测小节
二、前置条件
- imgproxy 4.0.19 已部署并监听 8140 端口，部署全过程见《imgproxy 4.0 Docker Compose 部署指南》；
- 理解签名 URL 结构
/<签名>/<处理选项>/<Base64编码源URL>[.<输出格式>]。本文全部实验 URL 由以下 Python 代码生成（HMAC-SHA256 + URL-safe Base64，算法逐字段验证与更多选项示例见《imgproxy 4.0 API 使用详解》）：
import base64, hashlib, hmac
KEY = "e2f29550ff27f4f6b6475b16b1af3cb648434daa215361c03ca61efab13c04f0"
SALT = "b858fad4bd3ec36662d606c13c0d6fdda3ba980689163ff6128022ded3a662c9"
def b64(data: bytes) -> str:
return base64.urlsafe_b64encode(data).decode().rstrip("=")
def sign(path: str) -> str:
digest = hmac.new(bytes.fromhex(KEY), bytes.fromhex(SALT) + path.encode(), hashlib.sha256).digest()
return b64(digest)
path = "/rs:fill:800:600:1/" + b64(b"http://origin/photo-1920x1080.jpg") + ".jpg"
url = "http://127.0.0.1:8140/" + sign(path) + path
print(url)
实测输出（即下文「远程图源基线 URL」）：
http://127.0.0.1:8140/D0J1LxFduGjvsfIGlAocpMdUkGUSHn8gX0AqSQaRf48/rs:fill:800:600:1/aHR0cDovL29yaWdpbi9waG90by0xOTIweDEwODAuanBn.jpg
- 本文基线环境变量（未单独说明的实验均在此基线上改动单项）：
IMGPROXY_KEY=e2f29550ff27f4f6b6475b16b1af3cb648434daa215361c03ca61efab13c04f0
IMGPROXY_SALT=b858fad4bd3ec36662d606c13c0d6fdda3ba980689163ff6128022ded3a662c9
IMGPROXY_LOCAL_FILESYSTEM_ROOT=/images
IMGPROXY_WATERMARK_PATH=/images/watermark-300x120.png
IMGPROXY_WATERMARK_OPACITY=0.8
IMGPROXY_TTL=86400
IMGPROXY_QUALITY=80
IMGPROXY_USE_ETAG=true
IMGPROXY_ENABLE_DEBUG_HEADERS=true
三、参数查看与修改方式
imgproxy 没有配置文件，官方只提供环境变量一种配置方式：全部参数以 IMGPROXY_ 前缀的环境变量在进程启动时读取，运行时修改不生效，必须重启进程。
修改与生效流程（systemd 托管形态）：
vi /etc/imgproxy/imgproxy.env # 增删改 IMGPROXY_* 变量
sudo systemctl restart imgproxy # 重启进程使变量生效
imgproxy health # 验证服务已恢复
实测回显：
imgproxy is running
💡 说明：以其他方式启动 imgproxy（直接 export 变量后前台运行、编排工具注入环境变量等）等价——核心规则只有一条：变量在进程启动时读取，改后必须重建进程。
imgproxy health是二进制自带的健康检查子命令，返回imgproxy is running即表示服务正常。
验证参数是否生效的通用手段（下文逐参数演示）：缓存类看响应头 Cache-Control/ETag；格式协商类用 curl -H 'Accept: image/webp,image/*' 等请求头对照 Content-Type；安全上限类看 422/404 状态码与响应体；签名校验类看 403 与启动日志。
四、参数总览
按官方文档口径整理运行时参数（本文实测项打 ✅，其余为官方口径转述）：
| 变量 | 默认值 | 作用 | 实测 |
|---|---|---|---|
| IMGPROXY_KEY / IMGPROXY_SALT | 未设（签名校验关闭） | URL 签名密钥/盐（hex，可逗号分隔多组轮换） | ✅ |
| IMGPROXY_SIGNATURE_SIZE | 32（字节） | 签名校验时比对的前 N 字节，可截短签名 | ✅ |
| IMGPROXY_TRUSTED_SIGNATURES | 未设 | 免校验的签名清单（官方口径） | — |
| IMGPROXY_LOCAL_FILESYSTEM_ROOT | 未设（local:// 关闭） | 本地图源根目录 | ✅ |
| IMGPROXY_ALLOWED_SOURCES | 未设（全部允许） | 来源白名单（协议/主机/前缀） | ✅ |
| IMGPROXY_S3_ENABLED / GCS / ABS / SWIFT | false | 各对象存储图源开关（官方口径） | — |
| IMGPROXY_TTL | 3600 | 结果缓存秒数 → Cache-Control max-age | ✅ |
| IMGPROXY_USE_ETAG | false | 输出 ETag 并支持 304 条件请求 | ✅ |
| IMGPROXY_ENABLE_DEBUG_HEADERS | false | 输出 X-Origin-/X-Result- 调试头 | ✅ |
| IMGPROXY_QUALITY | 80 | 默认输出质量（1–100） | ✅ |
| IMGPROXY_AUTO_WEBP / IMGPROXY_AUTO_AVIF | false | 按 Accept 头自动协商 WebP/AVIF | ✅ |
| IMGPROXY_ENFORCE_WEBP / ENFORCE_AVIF | false | 强制输出某格式（官方口径） | — |
| IMGPROXY_MAX_SRC_RESOLUTION | 16.8（百万像素） | 原图分辨率上限，超限 422 | ✅ |
| IMGPROXY_MAX_SRC_FILE_SIZE | 0（不限） | 原图字节上限，超限 422 | ✅ |
| IMGPROXY_MAX_ANIMATION_FRAMES | 0（不限） | 动图帧数上限（官方口径） | — |
| IMGPROXY_DOWNLOAD_TIMEOUT | 5（秒） | 拉取源图总超时，超时 504 | ✅ |
| IMGPROXY_WORKERS | CPU 核数 × 2 | 并发处理数上限（官方口径） | — |
| IMGPROXY_REQUEST_QUEUE_SIZE | 0（不限） | 排队请求数上限，超限 429（官方口径） | — |
| IMGPROXY_WATERMARK_PATH / OPACITY | 未设 / 1 | 水印图路径与默认不透明度 | ✅ |
| IMGPROXY_PRESETS | 未设 | 服务端固化选项组合 pr:名称（官方口径） | — |
| IMGPROXY_LOG_LEVEL / LOG_FORMAT | info / text | 日志级别与格式（官方口径） | — |
| IMGPROXY_OPEN_TELEMETRY_* | 未启用 | OpenTelemetry 指标/追踪（Pro 功能为主，官方口径） | — |
读表要点：生产必备的「安全三件套」是 KEY/SALT（签名）+ ALLOWED_SOURCES（白名单）+ MAX_SRC_RESOLUTION/MAX_SRC_FILE_SIZE（上限）；缓存三件套 TTL/USE_ETAG 配合 CDN 使用；AUTO_WEBP/AUTO_AVIF 是零成本省流量的两个开关。下文逐项实测。
五、核心参数分类详解
5.1 URL 签名：IMGPROXY_KEY / IMGPROXY_SALT / IMGPROXY_SIGNATURE_SIZE
KEY 与 SALT 是 imgproxy 安全模型的根基：设置后所有请求必须携带用二者计算的 HMAC-SHA256 签名，签名覆盖 URL 路径（处理选项 + 源地址），攻击者无法篡改任何一段。二者均为十六进制字符串，支持逗号分隔多组（用于密钥轮换时新旧并存）。
未设置的后果（实测）：从基线 env 中删掉 KEY/SALT 并重启，启动日志明确告警签名校验已关闭：
time="2026-10-25 15:13:28" level="WARNING" msg="No keys defined, signature checking is disabled" name="IMGPROXY_KEY" format="comma-separated hex-encoded strings" value=""
time="2026-10-25 15:13:28" level="WARNING" msg="No salts defined, signature checking is disabled" name="IMGPROXY_SALT" format="comma-separated hex-encoded strings" value=""
此时任意签名字段都能通过——用 /unsafe/ 作为签名段请求也返回 200（实测，源图被正常处理）：
HTTP/1.1 200 OK
Cache-Control: max-age=86400, public
Content-Disposition: inline; filename="photo-1920x1080.jpg"
Content-Length: 10046
Content-Type: image/jpeg
X-Origin-Content-Length: 104248
X-Origin-Height: 1080
X-Origin-Width: 1920
X-Result-Height: 300
X-Result-Width: 400
body-bytes: 10046
即实例沦为开放代理：任何人都可借它处理任意来源图片。仅限本机体验，严禁暴露公网。
只设 KEY 不设 SALT（实测）：服务直接无法启动，日志反复输出 CRITICAL：
time="2026-10-25 15:13:43" level="CRITICAL" msg="number of keys and number of salts should be equal. Keys: 1, salts: 0"
KEY 与 SALT 必须成对且数量相等（多组轮换时一一对应）。
IMGPROXY_SIGNATURE_SIZE（截短签名）：默认比对完整 32 字节签名；设为 16 后只比对前 16 字节，URL 更短。实测设置 IMGPROXY_SIGNATURE_SIZE=16 后，16 字节截短签名的 URL 通过校验：
$ curl -sS -D - -o /dev/null "http://127.0.0.1:8140/AIvWRA-L4Lt8H4IlHvXC9w/rs:fill:300:300:1/aHR0cDovL29yaWdpbi9waG90by0xOTIweDEwODAuanBn.jpg"
HTTP/1.1 200 OK
Cache-Control: max-age=86400, public
Content-Disposition: inline; filename="photo-1920x1080.jpg"
Content-Length: 7727
Content-Type: image/jpeg
X-Origin-Content-Length: 104248
X-Origin-Height: 1080
X-Origin-Width: 1920
X-Result-Height: 300
X-Result-Width: 300
body-bytes: 7727
而完整 32 字节签名的同路径 URL 反而被拒（签名段长度与配置不符）：
HTTP/1.1 403 Forbidden
Content-Type: text/plain
Content-Length: 9
body-bytes: 9
⚠️ 注意：改 SIGNATURE_SIZE 等于切换签名格式，全网已分发 URL 必须同步重新生成；16 字节（128 bit）截短在暴力枚举层面仍足够安全，但不要再往小调。
5.2 图源控制：IMGPROXY_LOCAL_FILESYSTEM_ROOT / IMGPROXY_ALLOWED_SOURCES
IMGPROXY_LOCAL_FILESYSTEM_ROOT 开启 local:// 图源并把访问收进指定根目录（目录之外的路径不可达，防路径穿越）。基线中已设为 /images，故 local:///photo-1920x1080.jpg 可正常处理。实测未设置该变量时，同一条 local:// 签名 URL 直接 404：
$ curl -sS -D - -o /dev/null "http://127.0.0.1:8140/m0cQ_tO539CqwcwynyLwbB_KAr_U6EdX0TSFJAyrq3U/rs:fill:400:300:1/bG9jYWw6Ly8vcGhvdG8tMTkyMHgxMDgwLmpwZw.jpg"
HTTP/1.1 404 Not Found
Content-Type: text/plain
Content-Length: 21
body-bytes: 21
IMGPROXY_ALLOWED_SOURCES 限定允许拉取的源站（逗号分隔，支持 http://host、https://host/path 等前缀），把 imgproxy 从「开放代理」收口为「指定源站的处理器」。实测设置 IMGPROXY_ALLOWED_SOURCES=http://origin 后：
白名单内源站（http://origin/photo-1920x1080.jpg）正常处理：
HTTP/1.1 200 OK
Cache-Control: max-age=86400, public
Content-Length: 23416
Content-Type: image/jpeg
X-Origin-Height: 1080
X-Origin-Width: 1920
X-Result-Height: 600
X-Result-Width: 800
body-bytes: 23416
白名单外地址（同一批文件的另一个地址 http://127.0.0.1:8141/photo-1920x1080.jpg）被拒：
HTTP/1.1 404 Not Found
Content-Type: text/plain
Content-Length: 18
body-bytes: 18
⚠️ 注意：白名单按 URL 前缀匹配，
http://origin与http://origin:80之外的同源别名（IP、其他端口、其他主机名）一律视为不同来源。生产环境建议同时配合网络层 ACL 双保险。
5.3 缓存与内容协商：IMGPROXY_TTL / IMGPROXY_USE_ETAG / IMGPROXY_ENABLE_DEBUG_HEADERS
IMGPROXY_TTL 直接映射为结果图的 Cache-Control: max-age=<值>, public，是 CDN/浏览器缓存的唯一时效依据。基线 86400 时实测响应头：
HTTP/1.1 200 OK
Cache-Control: max-age=86400, public
Content-Disposition: inline; filename="photo-1920x1080.jpg"
Content-Length: 23416
Content-Type: image/jpeg
Etag: "6ade0950-19738"
Last-Modified: Sun, 25 Oct 2026 13:51:12 GMT
X-Origin-Content-Length: 104248
X-Origin-Height: 1080
X-Origin-Width: 1920
X-Result-Height: 600
X-Result-Width: 800
body-bytes: 23416
改为 600 重启后，同一 URL 实测（Cache-Control 同步变为 600；字节数变化来自同批实验把 QUALITY 一并改为 50，见 5.4）：
HTTP/1.1 200 OK
Cache-Control: max-age=600, public
Content-Disposition: inline; filename="photo-1920x1080.jpg"
Content-Length: 14814
Content-Type: image/jpeg
Etag: "6ade0950-19738"
Last-Modified: Sun, 25 Oct 2026 13:51:12 GMT
Vary: Accept
X-Origin-Content-Length: 104248
X-Origin-Height: 1080
X-Origin-Width: 1920
X-Result-Height: 600
X-Result-Width: 800
body-bytes: 14814
IMGPROXY_USE_ETAG：true 时输出 ETag 头并支持条件请求。实测带 If-None-Match 请求返回 304 且零字节传输：
$ curl -sS -o /dev/null -D - -H "If-None-Match: \"6ade0950-19738\"" "http://127.0.0.1:8140/D0J1LxFduGjvsfIGlAocpMdUkGUSHn8gX0AqSQaRf48/rs:fill:800:600:1/aHR0cDovL29yaWdpbi9waG90by0xOTIweDEwODAuanBn.jpg"
HTTP/1.1 304 Not Modified
Cache-Control: max-age=86400, public
Etag: "6ade0950-19738"
Last-Modified: Sun, 25 Oct 2026 13:51:12 GMT
body-bytes:
IMGPROXY_ENABLE_DEBUG_HEADERS：true 时输出 X-Origin-Width/Height、X-Result-Width/Height、X-Origin-Content-Length 调试头（以上回显中可见），排障期极有用。实测把 USE_ETAG 与 ENABLE_DEBUG_HEADERS 同设为 false 后，响应头收敛为最小集（无 ETag、无调试头）：
HTTP/1.1 200 OK
Cache-Control: max-age=86400, public
Content-Disposition: inline; filename="photo-1920x1080.jpg"
Content-Length: 23416
Content-Type: image/jpeg
Last-Modified: Sun, 25 Oct 2026 13:51:12 GMT
body-bytes: 23416
💡 说明：ETag 内容派生自源图的 Last-Modified/大小等元信息（本例
"6ade0950-19738"），源图不变则 ETag 不变，CDN 回源校验可命中 304，显著节省回源带宽。生产建议 TTL 拉长（如 86400 以上）+ USE_ETAG=true，调试头在排障期过后关闭。
5.4 质量与格式：IMGPROXY_QUALITY / IMGPROXY_AUTO_WEBP / IMGPROXY_AUTO_AVIF
IMGPROXY_QUALITY（默认 80）是输出质量的默认值，URL 中 q: 选项可逐请求覆盖。实测同一张 1920×1080 原图、同为 fill 800×600：QUALITY=80 时输出 23416 字节；改为 QUALITY=50 后输出 14814 字节，体积降 36.7%。
IMGPROXY_AUTO_WEBP / IMGPROXY_AUTO_AVIF（默认 false）开启按请求 Accept 头的自动格式协商：URL 不带扩展名时，按客户端能力输出 JPEG/WebP/AVIF，并自动附加 Vary: Accept 保证缓存正确分叉。实测设置 IMGPROXY_AUTO_WEBP=true、IMGPROXY_AUTO_AVIF=true（TTL=600、QUALITY=50）后，同一条无扩展名 URL：
声明 Accept: image/jpeg 时：
HTTP/1.1 200 OK
Cache-Control: max-age=600, public
Content-Disposition: inline; filename="photo-1920x1080.jpg"
Content-Length: 14814
Content-Type: image/jpeg
Vary: Accept
X-Result-Height: 600
X-Result-Width: 800
body-bytes: 14814
声明 Accept: image/webp,image/* 时：
HTTP/1.1 200 OK
Cache-Control: max-age=600, public
Content-Disposition: inline; filename="photo-1920x1080.webp"
Content-Length: 10158
Content-Type: image/webp
Etag: "6ade0950-19738"
Last-Modified: Sun, 25 Oct 2026 13:51:12 GMT
Vary: Accept
X-Origin-Content-Length: 104248
X-Origin-Height: 1080
X-Origin-Width: 1920
X-Result-Height: 600
X-Result-Width: 800
body-bytes: 10158
声明 Accept: image/avif,image/* 时：
HTTP/1.1 200 OK
Cache-Control: max-age=600, public
Content-Disposition: inline; filename="photo-1920x1080.avif"
Content-Length: 9280
Content-Type: image/avif
Etag: "6ade0950-19738"
Last-Modified: Sun, 25 Oct 2026 13:51:12 GMT
Vary: Accept
X-Origin-Content-Length: 104248
X-Origin-Height: 1080
X-Origin-Width: 1920
X-Result-Height: 600
X-Result-Width: 800
body-bytes: 9280
同图同尺寸三种格式体积对比：JPEG 14814 B → WebP 10158 B（-31.4%）→ AVIF 9280 B（-37.4%）。零代码改动、仅靠两个开关即为现代浏览器省约三分之一图片流量，且 Vary: Accept 已自动带上，CDN 可安全按 Accept 分叉缓存。
💡 技术拓展：图片格式选型不止「能转就行」。常见输出格式对比——
格式 压缩效率 浏览器支持 适用场景 JPEG 基准 全部 兜底格式、照片 WebP 比 JPEG 省约 30% 全现代浏览器 通用首选 AVIF 比 JPEG 省约 35–50% 现代浏览器（老旧终端无） 流量敏感大图 PNG 无损、体积大 全部 截图/透明底/图形 JXL 高（无损+有损） 支持面窄 前瞻性归档/实验 本文自动协商采用「AVIF > WebP > JPEG 按 Accept 择优」，URL 固定扩展名（如
.webp）则强制单格式输出（实测见《imgproxy 4.0 API 使用详解》）。
5.5 安全上限：IMGPROXY_MAX_SRC_RESOLUTION / IMGPROXY_MAX_SRC_FILE_SIZE
这两个参数是防「解压炸弹」的硬闸门：攻击者即使拿到合法签名，也无法用超大原图耗尽解码内存。
IMGPROXY_MAX_SRC_RESOLUTION（默认 16.8，单位百万像素）：原图宽×高超出即拒。实测临时调为 1（百万像素）做边界验证：1920×1080（约 2.07 MP）的远程图被 422 拒绝：
HTTP/1.1 422 Unprocessable Entity
Content-Type: text/plain
Content-Length: 20
body-bytes: 20
320×240（0.077 MP）的小图仍正常处理：
HTTP/1.1 200 OK
Cache-Control: max-age=86400, public
Content-Disposition: inline; filename="two-tone-320x240.jpg"
Content-Length: 4012
Content-Type: image/jpeg
X-Origin-Content-Length: 2352
X-Origin-Height: 240
X-Origin-Width: 320
X-Result-Height: 600
X-Result-Width: 800
body-bytes: 4012
IMGPROXY_MAX_SRC_FILE_SIZE（默认 0=不限，单位字节）：原图体积超出即拒。实测设为 50000 后，104248 字节的 photo-1920x1080.jpg 被 422 拒绝，响应体明确为 Invalid source image：
HTTP/1.1 422 Unprocessable Entity
Content-Type: text/plain
Content-Length: 20
body: Invalid source image
💡 说明：生产建议显式设置这两个上限（如 MAX_SRC_RESOLUTION=50 即 50MP、MAX_SRC_FILE_SIZE 按业务原图量级设 10–50MB），不要依赖默认值——默认 16.8MP 对手机直出大图已偏紧，不限字节则给超大文件留了口子。
5.6 网络与超时：IMGPROXY_DOWNLOAD_TIMEOUT
IMGPROXY_DOWNLOAD_TIMEOUT（默认 5 秒）是拉取源图的总超时。源站慢/不可达时，该值决定请求挂起多久——过短会误杀慢源站，过长会堆积 worker。实测调为 1 秒后请求一个不可达源地址（http://10.255.255.1/slow.jpg，签名 URL 合法）：
$ curl -sS -o /dev/null -D - -w 'time_total=%{time_total}s http_code=%{http_code}\n' "http://127.0.0.1:8140/AeAwK0YnAdIQd42tZtY-jbJNsEBg43KKqlSCxcheTaI/rs:fit:200:200:1/aHR0cDovLzEwLjI1NS4yNTUuMS9zbG93LmpwZw.jpg"
time_total=1.001502s http_code=504
HTTP/1.1 504 Gateway Timeout
Content-Type: text/plain
Content-Length: 21
body: Source is unreachable
1.00 秒整断开并返回 504，超时控制精确生效。生产建议保持默认 5 秒或更短，把慢源站问题暴露在监控里而不是用长超时掩盖。
5.7 水印：IMGPROXY_WATERMARK_PATH / IMGPROXY_WATERMARK_OPACITY
IMGPROXY_WATERMARK_PATH 指定水印图片路径（可为 local 路径或远程 URL），IMGPROXY_WATERMARK_OPACITY（默认 1）设默认不透明度；URL 中 wm: 选项控制开关、位置与缩放。基线设为 /images/watermark-300x120.png + 0.8 后，同一条 rs:fit:800:450 请求实测对照：
叠加水印（wm:0.5:soea:10:10:0.2，右下角、不透明度 0.5、按比例 0.2）：
HTTP/1.1 200 OK
Cache-Control: max-age=86400, public
Content-Disposition: inline; filename="photo-1920x1080.jpg"
Content-Length: 19806
Content-Type: image/jpeg
X-Result-Height: 450
X-Result-Width: 800
不带 wm 选项的同图处理：
HTTP/1.1 200 OK
Cache-Control: max-age=86400, public
Content-Disposition: inline; filename="photo-1920x1080.jpg"
Content-Length: 18486
Content-Type: image/jpeg
X-Result-Height: 450
X-Result-Width: 800
两者尺寸一致（800×450），含水印版本大 1320 字节（水印叠加引入的额外像素信息）。注意水印不会在 URL 未声明 wm 选项时自动叠加——WATERMARK_PATH/OPACITY 只是提供素材与默认值，这为「同一图源按业务场景决定是否打水印」留了灵活性。
5.8 日志与可观测性：IMGPROXY_LOG_LEVEL / IMGPROXY_LOG_FORMAT / OpenTelemetry
imgproxy 默认向 stdout 输出文本日志（启动两行 INFO + 每请求一条），IMGPROXY_LOG_LEVEL（默认 info，可选 debug/warn/error）控制级别，IMGPROXY_LOG_FORMAT（默认 text，可选 json）切结构化输出便于采集。基线启动日志实测：
time="2026-10-25 16:05:25" level="INFO" msg="OpenTelemetry monitoring" enabled=false logs=false metrics=false
time="2026-10-25 16:05:25" level="INFO" msg="Source URL scheme registered, you can now use local:// source URLs" scheme="local"
time="2026-10-25 16:05:25" level="INFO" msg="Starting server at :8080"
⚠️ 注意：第一行 OpenTelemetry 显示
enabled=false——指标/追踪导出（Prometheus、OTLP 等IMGPROXY_OPEN_TELEMETRY_*族）主要属 Pro 版能力（开源/Pro 边界见《imgproxy 4.0 介绍与选型指南》2.2 节），开源版可观测性以日志 + 每请求响应头（X-Request-Id）为主。
六、生产配置模板
以下两套模板在本文基线上按场景调整，均为实测变量的组合（内存/磁盘占用以 libvips 流式管线的公开特征为参考：单请求处理内存数十 MB 级，imgproxy 自身无磁盘存储）：
6.1 模板 A：中小站点源站一体机（1–2 vCPU / 2–4 GB 内存，本地图源）
IMGPROXY_KEY=<openssl rand -hex 32 生成>
IMGPROXY_SALT=<openssl rand -hex 32 生成>
IMGPROXY_LOCAL_FILESYSTEM_ROOT=/images
IMGPROXY_ALLOWED_SOURCES=http://origin,https://img.example.com
IMGPROXY_TTL=86400
IMGPROXY_QUALITY=80
IMGPROXY_AUTO_WEBP=true
IMGPROXY_AUTO_AVIF=true
IMGPROXY_USE_ETAG=true
IMGPROXY_MAX_SRC_RESOLUTION=50
IMGPROXY_MAX_SRC_FILE_SIZE=20971520
IMGPROXY_DOWNLOAD_TIMEOUT=5
IMGPROXY_ENABLE_DEBUG_HEADERS=false
要点：本地图源 + 白名单双收口；自动协商省流量；调试头关闭。
6.2 模板 B：CDN 前置的多实例处理层（4 vCPU+ / 8 GB+ 内存 ×N 实例，S3/远程图源）
IMGPROXY_KEY=<与模板 A 同一把或独立密钥对>
IMGPROXY_SALT=<配套盐>
IMGPROXY_ALLOWED_SOURCES=https://bucket.s3.amazonaws.com,https://cdn-origin.example.com
IMGPROXY_TTL=604800
IMGPROXY_QUALITY=80
IMGPROXY_AUTO_WEBP=true
IMGPROXY_AUTO_AVIF=true
IMGPROXY_USE_ETAG=true
IMGPROXY_MAX_SRC_RESOLUTION=80
IMGPROXY_MAX_SRC_FILE_SIZE=52428800
IMGPROXY_DOWNLOAD_TIMEOUT=5
IMGPROXY_WORKERS=8
IMGPROXY_REQUEST_QUEUE_SIZE=100
IMGPROXY_ENABLE_DEBUG_HEADERS=false
IMGPROXY_LOG_FORMAT=json
要点：TTL 拉长到 7 天配合 CDN 充分固化；WORKERS 按 vCPU×2 显式钉住、REQUEST_QUEUE_SIZE 给过载保护（超出即 429 快速失败，把回弹压力交给 CDN 重试）；json 日志接采集管道；多实例挂同一密钥对水平扩展。
七、常见问题（FAQ）
Q1：改了 imgproxy.env 后请求行为没变？
A：环境变量只在进程启动时读取。确认已重启 imgproxy 进程（systemctl restart imgproxy 后 imgproxy health 返回 imgproxy is running），再核对变量名拼写（官方清单区分极细，如 AUTO_AVIF 与 ENABLE_AVIF_DETECTION 是不同项）。
Q2：配置 KEY/SALT 后全部请求 403？ A：URL 是用旧密钥/旧 SIGNATURE_SIZE 签的。用 5.1 节的算法按当前 KEY/SALT 重新生成；SIGNATURE_SIZE 非默认值时签名段需按该长度截短。
Q3：为什么同一 URL 有的客户端拿到 WebP 有的拿到 JPEG？
A：AUTO_WEBP/AUTO_AVIF 开启后按请求 Accept 头分叉（5.4 节实测）。若前置缓存没透传/分叉 Accept，会出现串格式——确认响应含 Vary: Accept 且缓存层尊重该头。
Q4：大图 422 但小图正常？ A：命中 MAX_SRC_RESOLUTION（百万像素）或 MAX_SRC_FILE_SIZE（字节）上限（5.5 节）。按业务原图分布上调，或在上传侧预压缩。
Q5：远程源偶发 504？ A：DOWNLOAD_TIMEOUT 内拉不完（5.6 节实测超时精确生效）。先查源站慢日志/链路，再考虑调大超时；不建议超过 10 秒，否则 worker 被慢请求占满。
Q6：如何判断某个变量在 v4.0.19 是否存在？ A：以官方 Configuration 页（见参考链接）为准，变量旁标注引入版本；写错名字的变量会被静默忽略（服务正常启动但不生效），改完务必用本文各节的验证手段实测确认。
八、参考链接
- 官方配置项清单（含引入版本与默认值）：https://docs.imgproxy.net/configuration/options
- URL 处理选项与签名算法：https://docs.imgproxy.net/usage/processing 、https://docs.imgproxy.net/usage/signing_url
- GitHub Releases（版本核实）：https://github.com/imgproxy/imgproxy/releases
- 站内：《imgproxy 4.0 介绍与选型指南》（定位与开源/Pro 边界）、《imgproxy 4.0 Docker Compose 部署指南》（部署全过程）、《imgproxy 4.0 API 使用详解》（签名算法逐字段验证与全量处理选项实测）