imgproxy 4.0 Docker Compose 部署指南

Docker Compose 部署 imgproxy v4.0.19：官方镜像选型与私有 libvips 查验、HMAC 密钥对生成、env_file 环境变量表、local:// 与 http:// 双图源签名 URL 实测、无状态持久化边界、等价 docker run、运维命令与启动失败/端口冲突 FAQ

imgproxyimgproxy图片处理DockerCompose2026/10/26

imgproxy 4.0 Docker Compose 部署指南

目标：用 Docker Compose 从 0 到 1 部署 imgproxy v4.0.19 图片即时处理服务——官方镜像选型、HMAC 签名密钥对生成、env_file 环境变量配置、本地图源（local://）与远程图源（http://）双路签名 URL 实测验证、数据持久化边界说明、等价 docker run 与常用运维命令、启动失败与端口冲突排障 FAQ。已在 Ubuntu 24.04.5 LTS + Docker 29.9.2 + Docker Compose v5.6.1 环境实测通过。

一、环境信息

  • 宿主系统：Ubuntu 24.04.5 LTS，x86_64
  • 容器运行时：Docker 29.9.2；Docker Compose v5.6.1
  • imgproxy 镜像：ghcr.io/imgproxy/imgproxy:v4.0.19（官方发布；2026-10-25 经 GitHub Releases 核实为 v4.0 系列最新稳定版）
  • 演示源站镜像：nginx:alpine（模拟业务图源站；生产环境替换为自有 Nginx / S3 / GCS 等真实源站）
  • 端口映射：宿主机 8140 → imgproxy 容器 8080；宿主机 8141 → origin 容器 80
  • 项目目录：/opt/imgproxy-compose（docker-compose.yml、imgproxy.env、images/、origin/）
  • 签名密钥对：openssl rand -hex 32 生成的两串 64 位十六进制字符串（IMGPROXY_KEY / IMGPROXY_SALT）
  • 测试素材：images/ 下 photo-1920x1080.jpg（104248 字节）、watermark-300x120.png 等；origin/ 下同名文件作为远程图源

二、镜像选型说明

imgproxy 官方的分发形态就是容器镜像，无需自建：

  • 官方镜像地址：GitHub Container Registry 的 ghcr.io/imgproxy/imgproxy，与 GitHub Releases 同步发布；Docker Hub 的 darthsim/imgproxy 同为作者维护的镜像，二者取其一即可，本文以 GHCR 为准。
  • 固定版本号：生产环境使用明确 tag（本文 v4.0.19），禁止 latest——v4.0 系列补丁发布密集且多次含安全修复（SSRF 防护绕过、SVG 消毒等，详见《imgproxy 4.0 介绍与选型指南》），锁版本便于可控升级与回滚。
  • 镜像内置私有 libvips：v4.0.19 基础镜像为 ubuntu:26.04，imgproxy 二进制链接的是镜像内 /opt/imgproxy/lib/ 下的私有 libvips，与宿主机及系统库完全隔离，不存在宿主依赖问题。实测容器内动态链接结果：
$ docker exec imgproxy-stack-imgproxy-1 ldd /usr/local/bin/imgproxy | grep -E "vips|glib"
	libvips.so.42 => /opt/imgproxy/lib/libvips.so.42 (0x000074635bcc7000)
	libglib-2.0.so.0 => /opt/imgproxy/lib/libglib-2.0.so.0 (0x000074635bb72000)
  • origin 服务的定位：本文 compose 中的 nginx:alpine 仅用于模拟「远程 HTTP 图源站」，让签名 URL 的 http:// 图源有真实可拉取的对象；已有业务图源站（Nginx、对象存储网关）时可将 origin 服务整体删除。

三、前置条件

  • 宿主机已安装 Docker 与 Docker Compose v2+，当前用户在 docker 组或具备 sudo 权限。
  • 规划端口未被占用。实测检查命令：
ss -ltn | grep -E ':(8140|8141) '    # 无输出表示空闲
  • 准备项目目录与测试素材：
mkdir -p /opt/imgproxy-compose/images /opt/imgproxy-compose/origin
# 将源图放入 images/（本地图源）与 origin/（远程图源），如 photo-1920x1080.jpg、watermark-300x120.png
  • 生成签名密钥对（KEY 与 SALT 各一串 64 位十六进制，生产必须配置）。实测生成过程：
$ openssl rand -hex 32
e2f29550ff27f4f6b6475b16b1af3cb648434daa215361c03ca61efab13c04f0

$ openssl rand -hex 32
b858fad4bd3ec36662d606c13c0d6fdda3ba980689163ff6128022ded3a662c9

⚠️ 注意：KEY/SALT 是 URL 签名的全部秘密，泄露等于任何人都能构造合法处理 URL。生产环境应通过密钥管理系统注入，本文按演示环境直接写入 env_file。

四、部署步骤

4.1 编写 imgproxy.env

创建 /opt/imgproxy-compose/imgproxy.env（imgproxy 全部配置均通过 IMGPROXY_* 环境变量注入，无配置文件）：

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_MAX_SRC_RESOLUTION=50
IMGPROXY_USE_ETAG=true
IMGPROXY_ENABLE_DEBUG_HEADERS=true

逐项含义与实测影响见「六、环境变量表」；完整参数族（超时时长、并发、来源白名单、签名长度等）的逐项实测见《imgproxy 4.0 配置参数详解》。

4.2 编写 docker-compose.yml

创建 /opt/imgproxy-compose/docker-compose.yml：

name: imgproxy-stack

services:
  imgproxy:
    image: ghcr.io/imgproxy/imgproxy:v4.0.19
    env_file:
      - ./imgproxy.env
    ports:
      - "8140:8080"
    volumes:
      - ./images:/images:ro
    restart: unless-stopped
    networks:
      - imgnet

  origin:
    image: nginx:alpine
    ports:
      - "8141:80"
    volumes:
      - ./origin:/usr/share/nginx/html:ro
    restart: unless-stopped
    networks:
      - imgnet

networks:
  imgnet:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.60.0/24

要点：name: imgproxy-stack 固定项目名，使容器名可预期；./images:/images:ro 以只读挂载本地图源目录（与 imgproxy.env 的 IMGPROXY_LOCAL_FILESYSTEM_ROOT=/images 对应）；自定义子网 10.89.60.0/24 便于在源站侧按网段做访问控制。

4.3 拉取镜像

cd /opt/imgproxy-compose
docker compose pull

实测回显：

 Image ghcr.io/imgproxy/imgproxy:v4.0.19 Pulling 
 Image nginx:alpine Pulling 
 Image nginx:alpine Pulled 
 Image ghcr.io/imgproxy/imgproxy:v4.0.19 Pulled

4.4 启动服务

docker compose up -d

实测回显：

 Network imgproxy-stack_imgnet Creating 
 Network imgproxy-stack_imgnet Created 
 Container imgproxy-stack-origin-1 Creating 
 Container imgproxy-stack-imgproxy-1 Creating 
 Container imgproxy-stack-imgproxy-1 Created 
 Container imgproxy-stack-origin-1 Created 
 Container imgproxy-stack-origin-1 Starting 
 Container imgproxy-stack-imgproxy-1 Starting 
 Container imgproxy-stack-origin-1 Started 
 Container imgproxy-stack-imgproxy-1 Started

4.5 验证部署

查看运行状态：

docker compose ps

实测回显（两服务 Up，端口映射正确）：

NAME                        IMAGE                               COMMAND                  SERVICE    CREATED                  STATUS                  PORTS
imgproxy-stack-imgproxy-1   ghcr.io/imgproxy/imgproxy:v4.0.19   "entrypoint.sh imgpr…"   imgproxy   Less than a second ago   Up Less than a second   0.0.0.0:8140->8080/tcp, [::]:8140->8080/tcp
imgproxy-stack-origin-1     nginx:alpine                        "/docker-entrypoint.…"   origin     Less than a second ago   Up Less than a second   0.0.0.0:8141->80/tcp, [::]:8141->80/tcp

容器内置健康检查与版本查询：

docker compose exec imgproxy imgproxy health
docker compose exec imgproxy imgproxy version

实测回显：

imgproxy is running
4.0.19

查看启动日志，确认 local:// 图源协议已注册、服务监听 8080：

docker compose logs --no-log-prefix imgproxy

实测回显：

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"

⚠️ 注意：若启动日志出现 level="WARNING" msg="No keys defined, signature checking is disabled"，说明 KEY/SALT 未生效（如 env_file 路径写错），此时签名校验关闭、实例等同开放代理，严禁直接暴露公网；排障见「十一、常见问题 Q4」。

4.6 首次处理验证（本地图源 + 远程图源）

imgproxy 的处理请求是签名 URL，结构为 /<签名>/<处理选项>/<Base64编码的源URL>[.<输出格式>]，签名由 KEY/SALT 经 HMAC-SHA256 计算（签名算法与生成代码见《imgproxy 4.0 API 使用详解》）。以下两条签名 URL 分别验证本地图源与远程图源：

本地图源（local:///photo-1920x1080.jpg，等比缩放至 640×360 内）：

curl -sS -D - -o /dev/null "http://127.0.0.1:8140/p51gY5DRYxZ5K1rBTD9vkT0vvU8MFuRG4gPD_KIejRs/rs:fit:640:360:1/bG9jYWw6Ly8vcGhvdG8tMTkyMHgxMDgwLmpwZw"

实测回显（200，源图 1920×1080 被缩放为 640×360，Cache-Control 与调试头均来自 imgproxy.env 配置）：

Cache-Control: max-age=86400, public
Content-Disposition: inline; filename="photo-1920x1080.jpg"
Content-Length: 13768
Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; img-src data:; sandbox
Content-Type: image/jpeg
Etag: "FS_7xMa7AW6Xs0WLY5Edu2aMdhH2h8UNwFcMFQ3vwq8"
Last-Modified: Sun, 25 Oct 2026 14:02:44 GMT
Server: imgproxy
X-Origin-Content-Length: 104248
X-Origin-Height: 1080
X-Origin-Width: 1920
X-Request-Id: HH0n6dKogRxn5zGjN154p
X-Result-Height: 360
X-Result-Width: 640
Date: Sun, 25 Oct 2026 16:05:40 GMT
Connection: close

body-bytes: 13768

远程图源（http://origin/photo-1920x1080.jpg，经内部网络从 origin 容器拉取，缩放至 600×600 内）：

curl -sS -D - -o /dev/null "http://127.0.0.1:8140/yqn9RVgN4rdgcMmnl7PzWLVDPX3ICh1aXvZVFWWThPQ/rs:fit:600:600:1/aHR0cDovL29yaWdpbi9waG90by0xOTIweDEwODAuanBn"

实测回显（200，原图 1920×1080 等比缩放为 600×338）：

Cache-Control: max-age=86400, public
Content-Disposition: inline; filename="photo-1920x1080.jpg"
Content-Length: 12875
Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; img-src data:; sandbox
Content-Type: image/jpeg
Etag: "6ade0950-19738"
Last-Modified: Sun, 25 Oct 2026 13:51:12 GMT
Server: imgproxy
X-Origin-Content-Length: 104248
X-Origin-Height: 1080
X-Origin-Width: 1920
X-Request-Id: qxMc8Vh2QwE6mAQ5CwvRd
X-Result-Height: 338
X-Result-Width: 600
Date: Sun, 25 Oct 2026 16:05:40 GMT
Connection: close

body-bytes: 12875

两条请求均返回 200 且 X-Origin-Width/Height 与 X-Result-Width/Height 符合预期，部署完成。

五、数据持久化说明

imgproxy 是无状态服务：不存结果图、不建索引、无数据库，容器中没有任何需要持久化的运行数据。本部署需要留在宿主机的只有三类「输入」：

路径内容挂载方式说明
./images本地图源素材、水印图只读挂载到 /imageslocal:// 图源与水印的文件来源；imgproxy 只读不写
./origin演示源站文件只读挂载到 nginx html 目录生产环境替换为真实源站后删除
./imgproxy.env全部服务配置env_file 注入配置即代码，建议纳入 Git 版本管理（密钥改用密管注入）

结果缓存不在 imgproxy 内：服务按 IMGPROXY_TTL 输出 Cache-Control: max-age=86400, public 与 ETag/Last-Modified（见 4.6 回显），缓存职责交给 CDN 或前置 Nginx。

重启不丢任何状态的实测验证（restart 后签名 URL 立即恢复 200）：

$ docker compose restart
 Container imgproxy-stack-origin-1 Restarting 
 Container imgproxy-stack-imgproxy-1 Restarting 
 Container imgproxy-stack-imgproxy-1 Started 
 Container imgproxy-stack-origin-1 Started 

$ docker compose ps
NAME                        IMAGE                               COMMAND                  SERVICE    CREATED         STATUS                  PORTS
imgproxy-stack-imgproxy-1   ghcr.io/imgproxy/imgproxy:v4.0.19   "entrypoint.sh imgpr…"   imgproxy   3 minutes ago   Up Less than a second   0.0.0.0:8140->8080/tcp, [::]:8140->8080/tcp
imgproxy-stack-origin-1     nginx:alpine                        "/docker-entrypoint.…"   origin     3 minutes ago   Up Less than a second   0.0.0.0:8141->80/tcp, [::]:8141->80/tcp

$ curl -sS -o /dev/null -w "after-restart=%{http_code}\n" <本地签名URL>
after-restart=200

六、环境变量表

本文 imgproxy.env 的逐项说明（行为均已实测，回显见 4.6 与《imgproxy 4.0 配置参数详解》）：

变量本文取值说明
IMGPROXY_KEYe2f29550…c04f0（64 位 hex）URL 签名密钥，openssl rand -hex 32 生成；必须设为 hex，非法值导致启动失败（见 FAQ Q1）
IMGPROXY_SALTb858fad4…62c9（64 位 hex）URL 签名盐；KEY 与 SALT 数量必须相等，否则启动失败（见 FAQ Q2）
IMGPROXY_LOCAL_FILESYSTEM_ROOT/images开启 local:// 本地图源并指定根目录；未设置时 local:// 请求返回 404（见 FAQ Q5）
IMGPROXY_WATERMARK_PATH/images/watermark-300x120.png水印图片路径（指向容器内挂载路径）
IMGPROXY_WATERMARK_OPACITY0.8水印默认不透明度（0–1）
IMGPROXY_TTL86400结果缓存秒数，直接映射为响应头 Cache-Control: max-age=86400
IMGPROXY_QUALITY80输出质量默认值（1–100），URL 中 q 选项可覆盖
IMGPROXY_MAX_SRC_RESOLUTION50原图分辨率上限（百万像素），超限返回 422
IMGPROXY_USE_ETAGtrue输出 ETag 头并支持 If-None-Match 条件请求（304）
IMGPROXY_ENABLE_DEBUG_HEADERStrue输出 X-Origin-/X-Result- 调试头；生产稳定后可关闭

💡 说明：imgproxy 没有配置文件，全部可调项都是 IMGPROXY_* 环境变量（官方配置项清单见参考链接）；超时、并发 workers、来源白名单 ALLOWED_SOURCES、签名截短 SIGNATURE_SIZE 等参数的逐项实测见《imgproxy 4.0 配置参数详解》。

七、配置参数说明（Compose 关键项）

项本文取值说明
nameimgproxy-stack固定 Compose 项目名，容器/网络名可预期（imgproxy-stack-imgproxy-1 等）
imageghcr.io/imgproxy/imgproxy:v4.0.19官方镜像固定版本 tag
env_file./imgproxy.env环境变量集中管理，避免在 yml 中散落敏感值
ports8140:8080imgproxy 监听端口映射；容器内固定 8080
volumes./images:/images:ro本地图源与水印目录，只读挂载（ro），imgproxy 不需要写权限
restartunless-stopped宿主机重启后自动拉起；手动 stop 后不拉起
networks.imgnetbridge，10.89.60.0/24自定义子网，imgproxy 与 origin 同网互通；便于源站侧按网段 ACL

八、配置文件挂载

imgproxy 没有配置文件，这是它与多数服务的显著差异：官方只提供环境变量一种配置方式。因此本节需要挂载进容器的只有「文件类素材」：

  • 本地图源根目录：./images:/images:ro，与 IMGPROXY_LOCAL_FILESYSTEM_ROOT=/images 对应；新增源图只需拷入宿主机 ./images，无需重启。
  • 水印图：随 ./images 一并挂载，IMGPROXY_WATERMARK_PATH 指向容器内路径 /images/watermark-300x120.png；替换水印图后 docker compose restart imgproxy 生效。
  • 配置变更路径：修改 imgproxy.env 后执行 docker compose up -d 触发容器重建使环境变量生效——docker compose restart 不会重读 env_file，这是新手最常见的「改了配置没生效」原因。

九、等价 docker run 运行方式

不使用 Compose 时，以下命令与本文 imgproxy 服务等价（origin 演示源站需另行启动或省略）：

docker run -d --name imgproxy-run \
  --restart unless-stopped \
  --env-file /opt/imgproxy-compose/imgproxy.env \
  -p 8142:8080 \
  -v /opt/imgproxy-compose/images:/images:ro \
  ghcr.io/imgproxy/imgproxy:v4.0.19

实测回显：

$ docker run -d --name imgproxy-run --restart unless-stopped --env-file /opt/imgproxy-compose/imgproxy.env -p 8142:8080 -v /opt/imgproxy-compose/images:/images:ro ghcr.io/imgproxy/imgproxy:v4.0.19
c0252ce946ca43ebd96a001380cd5ac6f003f29a92b9c8c5d08ebf48a68823c6

$ docker ps --filter name=imgproxy-run
CONTAINER ID   IMAGE                               COMMAND                  CREATED        STATUS                  PORTS                                         NAMES
c0252ce946ca   ghcr.io/imgproxy/imgproxy:v4.0.19   "entrypoint.sh imgpr…"   1 second ago   Up Less than a second   0.0.0.0:8142->8080/tcp, [::]:8142->8080/tcp   imgproxy-run

$ docker exec imgproxy-run imgproxy health
imgproxy is running

用同一条本地图源签名 URL 验证（签名只与 URL 路径有关，与端口无关，可直接复用）：

$ curl -sS -o /dev/null -w "%{http_code} %{content_type} %{size_download}B\n" http://127.0.0.1:8142/p51gY5DRYxZ5K1rBTD9vkT0vvU8MFuRG4gPD_KIejRs/rs:fit:640:360:1/bG9jYWw6Ly8vcGhvdG8tMTkyMHgxMDgwLmpwZw
200 image/jpeg 13768B

返回 200 且字节数与 Compose 部署的 4.6 节完全一致，等价性验证通过。验证后清理：docker rm -f imgproxy-run。

十、常用运维命令

docker compose ps                              # 查看服务状态与端口映射
docker compose logs -f imgproxy                # 跟踪处理日志（每请求一条，含耗时）
docker compose exec imgproxy imgproxy health   # 健康检查
docker compose exec imgproxy imgproxy version  # 版本查询
docker compose restart imgproxy                # 重启（水印图替换等场景）
docker compose up -d                           # imgproxy.env / compose 变更后重建生效
docker compose pull && docker compose up -d    # 升级镜像版本（先改 tag 再执行）
docker compose down                            # 停止并删除容器与网络（images/origin/env 保留）

docker compose down 实测回显：

 Container imgproxy-stack-origin-1 Stopping 
 Container imgproxy-stack-imgproxy-1 Stopping 
 Container imgproxy-stack-imgproxy-1 Stopped 
 Container imgproxy-stack-imgproxy-1 Removing 
 Container imgproxy-stack-imgproxy-1 Removed 
 Container imgproxy-stack-origin-1 Stopped 
 Container imgproxy-stack-origin-1 Removing 
 Container imgproxy-stack-origin-1 Removed 
 Network imgproxy-stack_imgnet Removing 
 Network imgproxy-stack_imgnet Removed

再次 docker compose up -d 即可完整恢复服务（网络与容器重建，健康检查通过）：

 Network imgproxy-stack_imgnet Creating 
 Network imgproxy-stack_imgnet Created 
 Container imgproxy-stack-origin-1 Creating 
 Container imgproxy-stack-imgproxy-1 Creating 
 Container imgproxy-stack-imgproxy-1 Created 
 Container imgproxy-stack-origin-1 Created 
 Container imgproxy-stack-imgproxy-1 Starting 
 Container imgproxy-stack-origin-1 Starting 
 Container imgproxy-stack-imgproxy-1 Started 
 Container imgproxy-stack-origin-1 Started 

$ docker compose exec imgproxy imgproxy health
imgproxy is running

十一、常见问题（FAQ）

Q1：容器反复重启，日志报 invalid IMGPROXY_KEY value？ A：KEY（或 SALT）不是合法的十六进制字符串。imgproxy 要求 KEY/SALT 为 hex 编码（推荐 openssl rand -hex 32 生成）。故意写入 not-a-hex-key 的实测复现：

$ docker compose ps imgproxy
NAME                             IMAGE                               COMMAND                  SERVICE    CREATED         STATUS                                  PORTS
imgproxy-4019-stack-imgproxy-1   ghcr.io/imgproxy/imgproxy:v4.0.19   "entrypoint.sh imgpr…"   imgproxy   3 seconds ago   Restarting (1) Less than a second ago   

$ docker compose logs --tail=8 imgproxy
imgproxy-1  | time="2026-10-25 15:03:55" level="CRITICAL" msg="invalid IMGPROXY_KEY value (format: comma-separated hex-encoded strings): parse error: not-a-hex-key expected to be hex-encoded string: encoding/hex: invalid byte: U+006E 'n', see https://docs.imgproxy.net/configuration/options#IMGPROXY_KEY"

处置：用 openssl rand -hex 32 重新生成并替换 imgproxy.env 中的值，docker compose up -d 重建。

Q2：只设置了 KEY、没设 SALT，容器起不来？ A：KEY 与 SALT 必须成对出现且数量相等（二者均支持逗号分隔多组用于密钥轮换）。只设 KEY 的实测日志：

$ docker compose logs --no-log-prefix --tail=4 imgproxy
time="2026-10-25 15:13:43" level="INFO" msg="OpenTelemetry monitoring" enabled=false logs=false metrics=false
time="2026-10-25 15:13:43" level="CRITICAL" msg="number of keys and number of salts should be equal. Keys: 1, salts: 0"

处置：补齐 IMGPROXY_SALT 后 docker compose up -d。

Q3：启动报 Bind for 0.0.0.0:xxxx failed: port is already allocated？ A：规划端口被其他进程占用。以 8131 被占用为例的实测复现：

$ ss -ltn | grep 8131
LISTEN 0      4096         0.0.0.0:8131       0.0.0.0:*          
LISTEN 0      4096            [::]:8131          [::]:*          
$ docker compose -f conflict-compose.yml up -d
 Network imgproxy-4019-conflict_default Creating 
 Network imgproxy-4019-conflict_default Created 
 Container imgproxy-4019-conflict-imgproxy-1 Creating 
 Container imgproxy-4019-conflict-imgproxy-1 Created 
 Container imgproxy-4019-conflict-imgproxy-1 Starting 
Error response from daemon: failed to set up container networking: driver failed programming external connectivity on endpoint imgproxy-4019-conflict-imgproxy-1 (7dc6f50b51a4541c5d1e088fe1353317f8cf22f034e85d290a6b3448e184af77): Bind for 0.0.0.0:8131 failed: port is already allocated

处置：ss -ltnp 找到占用进程并停用，或修改 compose 的 ports 左端换端口。

Q4：日志出现 No keys defined, signature checking is disabled 警告？ A：KEY/SALT 未生效（env_file 路径错误、变量名拼错或未重建容器）。实测日志：

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=""

此状态下签名校验整体关闭、任何人可构造任意处理 URL（等同开放代理），只允许在本机体验时短暂出现，严禁暴露公网。处置：修正 env_file 后 docker compose up -d，复查日志无 WARNING。

Q5：local:// 本地图源请求返回 404？ A：未设置 IMGPROXY_LOCAL_FILESYSTEM_ROOT 时 local:// 图源不启用，所有 local:// URL 返回 404（实测响应体 Source is unreachable 风格纯文本）。处置：设置该变量并确认 ./images 已只读挂载到同一路径。

Q6：如何升级到 imgproxy 新版本？ A：改 compose 中 image tag（如 v4.0.20）→ docker compose pull && docker compose up -d；imgproxy 无状态，升级即换容器，imgproxy.env 与 images 目录沿用。跨大版本升级前先读官方 CHANGELOG 与升级说明。

Q7：ghcr.io 拉取缓慢或超时？ A：为 Docker 配置可用的镜像加速/代理（/etc/docker/daemon.json 的 registry-mirrors 或 HTTP_PROXY），或在内网 Harbor 等私有仓库做 ghcr.io/imgproxy/imgproxy 的代理缓存后改 image 地址。

十二、参考链接