组态

imgproxy已支持十二因子应用程序，可以使用ENV变量进行配置。

URL签名

imgproxy允许使用密钥和盐对URL进行签名。默认情况下禁用此功能，但强烈建议在生产中启用此功能。要启用URL签名检查，请定义密钥/盐对：

• IMGPROXY_KEY：十六进制编码的密钥；
• IMGPROXY_SALT：十六进制编码的盐；
• IMGPROXY_SIGNATURE_SIZE：在编码为Base64之前用于签名的字节数。默认值：32;

您可以通过用逗号（,）划分键和盐来指定多个键/盐对。imgproxy将检查每对URL签名。当您需要在零停机时间内更改应用程序中的键/盐对时很有用。

您还可以逐行指定具有十六进制编码的键和盐的文件路径（在开发环境中有用）：

imgproxy -keypath /path/to/file/with/key -saltpath /path/to/file/with/salt

如果您需要真正快速的随机键/盐对，则可以使用以下片段快速生成它：

echo $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n')

服务器

• IMGPROXY_BIND：要侦听的TCP地址和端口。默认值：:8080;
• IMGPROXY_READ_TIMEOUT：读取整个图像请求（包括正文）的最大持续时间（以秒为单位）。默认值：10;
• IMGPROXY_WRITE_TIMEOUT：写入响应的最大持续时间（以秒为单位）。默认值：10;
• IMGPROXY_KEEP_ALIVE_TIMEOUT：关闭连接之前等待下一个请求的最大持续时间（以秒为单位）。设置0为时，将禁用保持活动状态。默认值：10;
• IMGPROXY_DOWNLOAD_TIMEOUT：下载源图像的最大持续时间（以秒为单位）。默认值：5;
• IMGPROXY_CONCURRENCY：要同时处理的最大图像请求数。默认值：CPU内核数乘以2；
• IMGPROXY_MAX_CLIENTS：最大同时活动连接数。默认值：IMGPROXY_CONCURRENCY * 10;
• IMGPROXY_TTL：发送的持续时间（以秒为单位）Expires和Cache-Control: max-ageHTTP标头。默认值：3600（1小时）；
• IMGPROXY_SO_REUSEPORT：当时true，启用SO_REUSEPORT套接字选项（当前仅在linux和darwin上）；
• IMGPROXY_USER_AGENT：将与源图像请求一起发送的User-Agent标头。默认值：imgproxy/%current_version;
• IMGPROXY_USE_ETAG：当时true，启用使用ETag HTTP标头进行HTTP缓存控制。默认值：false；

安全

imgproxy保护您免受所谓的图像炸弹袭击。这是您可以指定合理的最大图像分辨率的方法：

• IMGPROXY_MAX_SRC_RESOLUTION：源图像的最大分辨率，以百万像素为单位。实际尺寸较大的图像将被拒绝。默认值：16.8;
• IMGPROXY_MAX_SRC_FILE_SIZE：源图像的最大大小，以字节为单位。具有较大文件大小的图像将被拒绝。为时0，禁用文件大小检查。默认值：0;

imgproxy可以处理动画图像（GIF，WebP），但是由于此操作非常繁琐，因此默认情况下仅处理一帧。您可以使用以下变量来增加要处理的动画帧的最大值：

• IMGPROXY_MAX_ANIMATION_FRAMES：要处理的最大动画图像帧。默认值：1。

注意： imgproxy在检查源图像分辨率时会汇总所有帧分辨率。

您还可以指定一个机密，Authorization以使用HTTP 标头启用授权以用于生产环境：

• IMGPROXY_SECRET：授权令牌。如果指定，则HTTP请求应包含Authorization: Bearer %secret%标头。

imgproxy默认情况下不发送CORS标头。指定允许的来源以启用CORS标头：

• IMGPROXY_ALLOW_ORIGIN：设置时，启用具有提供的来源的CORS标头。默认情况下，CORS标头是禁用的。

在开发环境中使用imgproxy时，忽略SSL验证可能很有用：

• IMGPROXY_IGNORE_SSL_VERIFICATION：如果为true，则禁用SSL验证，因此imgproxy可以在具有自签名SSL证书的开发环境中使用。

另外，您可能希望imgproxy使用与写入日志相同的错误消息进行响应：

• IMGPROXY_DEVELOPMENT_ERRORS_MODE：当为true时，imgproxy将响应并提供详细的错误消息。不建议将其用于生产，因为某些错误可能包含堆栈跟踪。

压缩

• IMGPROXY_QUALITY：结果图像的默认质量，百分比。默认值：80;
• IMGPROXY_GZIP_COMPRESSION：GZip压缩级别。默认值：5。

先进的JPEG压缩

• IMGPROXY_JPEG_PROGRESSIVE：为true时，启用渐进式JPEG压缩。默认值：false；
• IMGPROXY_JPEG_NO_SUBSAMPLE：如果为true，则禁用色度二次采样。这将以更大的文件大小为代价来提高质量。默认值：false；
• IMGPROXY_JPEG_TRELLIS_QUANT：如果为true，则为每个8x8块启用网格量化。减小文件大小，但增加压缩时间。默认值：false；
• IMGPROXY_JPEG_OVERSHOOT_DERINGING：如果为true，则启用具有极高值的样本的过冲。过冲可能会减少压缩引起的振铃伪影，尤其是在白色背景上出现黑色文本的区域。默认值：false；
• IMGPROXY_JPEG_OPTIMIZE_SCANS：如果为true，则将DCT系数的频谱分成单独的扫描。减小文件大小，但增加压缩时间。要求IMGPROXY_JPEG_PROGRESSIVE是真实的。默认值：false；
• IMGPROXY_JPEG_QUANT_TABLE：要使用的量化表。支持的值为：
  • 0：来自JPEG附件K的表格（默认）；
  • 1：平板
  • 2：针对柯达图像集上的MSSIM调整的表；
  • 3：N。Robidoux的ImageMagick表格；
  • 4：针对柯达影像集上的PSNR-HVS-M调整的表格；
  • 5：从人类视觉与JPEG-DCT压缩的相关性表（1992年）；
  • 6：来自DCTune压缩牙科X射线感知优化的表格（1997年）；
  • 7：来自DCT系数量化的视觉检测模型的表格（1993）；
  • 8：表来自改进的DCT系数量化检测模型（1993）。

注： IMGPROXY_JPEG_TRELLIS_QUANT，IMGPROXY_JPEG_OVERSHOOT_DERINGING，IMGPROXY_JPEG_OPTIMIZE_SCANS，并IMGPROXY_JPEG_QUANT_TABLE要求libvips与建MozJPEG因为标准的libjpeg不支持这些优化。

先进的PNG压缩

• IMGPROXY_PNG_INTERLACED：为true时，启用隔行PNG压缩。默认值：false；
• IMGPROXY_PNG_QUANTIZE：为true时，启用PNG量化。libvips应该在libimagequant支持下构建。默认值：false；
• IMGPROXY_PNG_QUANTIZATION_COLORS：量化调色板条目的最大数量。应该在2到256之间。默认值：256；

WebP支持检测

imgproxy可以使用AcceptHTTP标头检测浏览器是否支持WebP并将其用作默认格式。默认情况下，此功能是禁用的，可以通过以下选项启用：

• IMGPROXY_ENABLE_WEBP_DETECTION：启用WebP支持检测。如果在imgproxy URL中省略了文件扩展名，并且浏览器支持WebP，则imgproxy将使用它作为结果格式；
• IMGPROXY_ENFORCE_WEBP：启用WebP支持检测并强制使用WebP。如果浏览器支持WebP，则即使在imgproxy URL中指定了另一个扩展名，它也将用作结果格式。

启用WebP支持检测后，请小心配置CDN或缓存代理，以便在缓存时考虑AcceptHTTP标头。

警告：标题无法签名。这意味着攻击者可以通过更改AcceptHTTP标头来绕过CDN缓存。在配置生产缓存设置时，请记住这一点。

客户提示支持

imgproxy可以使用Width，Viewport-Width或DPRHTTP标头，以确定默认宽度和使用客户机提示DPR选项。此功能默认情况下处于禁用状态，可以通过以下选项启用：

• IMGPROXY_ENABLE_CLIENT_HINTS：启用“客户提示”支持以确定默认宽度和DPR选项。在此处阅读有关客户提示的详细信息。

警告：标题无法签名。这意味着攻击者可以通过改变绕过CDN缓存Width，Viewport-Width或DPRHTTP标头。在配置生产缓存设置时，请记住这一点。

水印

• IMGPROXY_WATERMARK_DATA：Base64编码的图像数据。您可以轻松地用它计算base64 tmp/watermark.png | tr -d '\n'；
• IMGPROXY_WATERMARK_PATH：本地存储图像的路径；
• IMGPROXY_WATERMARK_URL：水印图片网址；
• IMGPROXY_WATERMARK_OPACITY：水印基本不透明度；
• IMGPROXY_WATERMARKS_CACHE_SIZE：自定义水印缓存的大小。设置0为时，禁用水印缓存。默认情况下，将缓存256个水印。

在水印指南中阅读有关水印的更多信息。

预设值

在“ 预设”指南中了解有关imgproxy预设的信息。

有两种定义预设的方法：

使用环境变量

• IMGPROXY_PRESETS：一组预设定义，以逗号分隔。范例：default=resizing_type:fill/enlarge:1,sharp=sharpen:0.7,blurry=blur:2。默认值：空白。

使用命令行参数

imgproxy -presets /path/to/file/with/presets

该文件应包含预设定义，每行一个。以开头的行#被视为注释。例：

default=resizing_type:fill/enlarge:1

# Sharpen the image to make it look better
sharp=sharpen:0.7

# Blur the image to hide details
blurry=blur:2

仅使用预设

imgproxy可以切换到“仅预设模式”。在这种模式下，imgproxy仅接受preset选项参数作为处理选项。例：http://imgproxy.example.com/unsafe/thumbnail:blurry:watermarked/plain/http://example.com/images/curiosity.jpg@png

• IMGPROXY_ONLY_PRESETS：禁用所有网址格式并启用仅预设模式。

提供本地文件

imgproxy可以提供您的本地图像，但是默认情况下禁用此功能。要启用它，请指定本地文件系统根目录：

• IMGPROXY_LOCAL_FILESYSTEM_ROOT：本地文件系统的根。保留为空以禁用本地文件服务。

查看服务本地文件指南以了解更多信息。

从Amazon S3提供文件

imgproxy可以处理Amazon S3存储桶中的文件，但默认情况下禁用此功能。要启用它，请设置IMGPROXY_USE_S3为true：

• IMGPROXY_USE_S3：当时true，启用从Amazon S3存储桶中提取图像。默认值：false；
• IMGPROXY_S3_ENDPOINT：由imgproxy使用的自定义S3端点。

请查看S3指南中的Serving文件以了解更多信息。

从Google Cloud Storage提供文件

imgproxy可以处理Google Cloud Storage存储桶中的文件，但是默认情况下此功能处于禁用状态。要启用它，请设置IMGPROXY_GCS_KEY为Google Cloud JSON密钥的内容：

• IMGPROXY_GCS_KEY：Google Cloud JSON密钥。设置后，启用从Google Cloud Storage存储桶中提取图像。默认值：空白。

查阅Google Cloud Storage提供的服务文件指南以了解更多信息。

新的文物指标

imgproxy可以将其指标发送给New Relic。指定您的New Relic许可证密钥以激活此功能：

• IMGPROXY_NEW_RELIC_KEY：新的Relic许可证密钥；
• IMGPROXY_NEW_RELIC_APP_NAME：新的Relic应用程序名称。默认值：imgproxy。

查看新文物指南以了解更多信息。

普罗米修斯指标

imgproxy可以收集其针对Prometheus的指标。为Prometheus指标服务器指定绑定以激活此功能：

• IMGPROXY_PROMETHEUS_BIND：Prometheus指标服务器绑定。不能与相同IMGPROXY_BIND。默认值：空白。

查阅Prometheus指南以了解更多信息。

错误报告

imgproxy可以向Bugsnag，Honeybadger和Sentry报告发生的错误：

• IMGPROXY_BUGSNAG_KEY：Bugsnag API密钥。提供时，启用向Bugsnag的错误报告；
• IMGPROXY_BUGSNAG_STAGE：向Bugsnag阶段报告。默认值：production;
• IMGPROXY_HONEYBADGER_KEY：Honeybadger API密钥。如果提供，则启用向Honeybadger的错误报告；
• IMGPROXY_HONEYBADGER_ENV：Honeybadger env向其报告。默认值：production;
• IMGPROXY_SENTRY_DSN：哨兵项目DSN。如果提供，则启用向Sentry报告错误；
• IMGPROXY_SENTRY_ENVIRONMENT：向哨兵环境报告。默认值：production;
• IMGPROXY_SENTRY_RELEASE：哨兵释放报告。默认值：imgproxy/{imgproxy version};
• IMGPROXY_REPORT_DOWNLOADING_ERRORS：当时true，imgproxy将报告下载错误。默认值：true。

日志记录

• IMGPROXY_LOG_FORMAT：日志格式。支持以下格式：
  • pretty：（默认）彩色的人类可读格式；
  • structured：机器可读格式；
  • json：JSON格式；
• IMGPROXY_LOG_LEVEL：日志级别。以下级别的支持error，warn，info和debug。默认值：info;

imgproxy可以将日志发送到syslog，但是默认情况下禁用此功能。要启用它，请设置IMGPROXY_SYSLOG_ENABLE为true：

• IMGPROXY_SYSLOG_ENABLE：当时true，启用将日志发送到syslog；
• IMGPROXY_SYSLOG_LEVEL：发送到syslog的最大日志级别。已知的水平是：crit，error，warning和info。默认值：info;
• IMGPROXY_SYSLOG_NETWORK：用于连接到syslog的网络。如果为空，将使用本地syslog服务器。已知网络是tcp，tcp4，tcp6，udp，udp4，udp6，ip，ip4，ip6，unix，unixgram和unixpacket。默认值：空白；
• IMGPROXY_SYSLOG_ADDRESS：syslog服务的地址。如果IMGPROXY_SYSLOG_NETWORK为空，则不使用。默认值：空白；
• IMGPROXY_SYSLOG_TAG：特定的syslog标签。默认值：imgproxy;

注意： imgproxy始终对syslog使用结构化日志格式。

内存使用调整

警告：强烈建议您在更改此设置之前阅读“ 内存使用调整指南”。

• IMGPROXY_DOWNLOAD_BUFFER_SIZE：单个下载缓冲区的初始大小（以字节为单位）。为零时，初始化空的下载缓冲区。默认值：0;
• IMGPROXY_GZIP_BUFFER_SIZE：单个GZip缓冲区的初始大小（以字节为单位）。为零时，初始化空的GZip缓冲区。仅在启用GZip压缩时才有意义。默认值：0;
• IMGPROXY_FREE_MEMORY_INTERVAL：将未使用的内存返回到操作系统的间隔（以秒为单位）。默认值：10;
• IMGPROXY_BUFFER_POOL_CALIBRATION_THRESHOLD：校准前应返回到缓冲池的缓冲区数。默认值：1024。

其他

• IMGPROXY_BASE_URL：将添加到每个请求的图像URL的基本URL前缀。例如，如果请求了基本URL http://example.com/images，/path/to/image.png则imgproxy将从中下载源图像http://example.com/images/path/to/image.png。默认值：空白。
• IMGPROXY_USE_LINEAR_COLORSPACE：时true，imgproxy将处理线性色彩空间中的图像。这将减慢处理速度。请注意，启用“按比例缩小”功能后，在线性色彩空间中无法完全处理图像（请参见下文）。
• IMGPROXY_DISABLE_SHRINK_ON_LOAD：当时true，禁用JPEG和WebP的加载时收缩。允许在线性色彩空间中处理整个图像，但在处理大图像时会大大减慢调整大小并增加内存使用量。
• IMGPROXY_APPLY_UNSHARPEN_MASKING：当时true，如果imgproxy小于源图像，则imgproxy将对结果图像应用非锐化蒙版。默认值：true。

 

生成URL实现图片处理

本指南描述了一种简单的URL格式，该格式易于使用，但不支持imgproxy的所有功能。为了与imgproxy 1.x向后兼容，主要支持此URL格式。请阅读我们的生成URL（高级）指南，以了解高级URL格式。

 

格式定义

基本网址应包含签名，调整大小参数和源网址，如下所示：

/%signature/%resizing_type/%width/%height/%gravity/%enlarge/plain/%source_url@%extension
/%signature/%resizing_type/%width/%height/%gravity/%enlarge/%encoded_source_url.%extension

请查看本指南末尾的示例。

 

签名

签名可以防止攻击者修改您的URL。强烈建议在生产环境中对imgproxy URL进行签名。

设置URL签名后，请查看“ 签名URL”指南，以了解如何对URL进行签名。否则，请在此处使用任何字符串。

 

调整大小

imgproxy支持以下调整大小类型：

• fit：调整图像大小，同时保持宽高比适合给定尺寸；
• fill：调整图像大小，同时保持宽高比以填充给定的大小并裁剪突出部分；
• auto：如果源尺寸和最终尺寸均具有相同的方向（纵向或横向），则imgproxy将使用fill。否则，它将使用fit。

宽度和高度

宽度和高度参数定义生成的图像的大小（以像素为单位）。根据所应用的调整大小类型，尺寸可能与要求的尺寸不同。

重力

当imgproxy需要剪切图像的某些部分时，它是由重力引导的。支持以下值：

• no：北（上边缘）；
• so：南（底边）；
• ea：东（右边缘）；
• we：西（左边缘）；
• noea：东北（右上角）；
• nowe：西北（左上角）；
• soea：东南（右下角）；
• sowe：西南（左下角）；
• ce： 中央;
• sm： 聪明。libvips检测图像中最“有趣”的部分，并将其视为结果图像的中心；
• fp:%x:%y- 焦点。x和y是介于0和1之间的浮点数，它们描述所得图像中心的坐标。将0和1视为的右/左x和上/下y。

放大

当设置为1，t或true，imgproxy会放大图像，如果小于规定尺寸。

来源网址

有两种方法可以指定源URL：

 

plain

可以按原样提供源URL，并以/plain/部分开头：

/plain/http://example.com/images/curiosity.jpg

 

注意：如果源URL包含查询字符串或@，则需要对其进行转义。

当使用普通的源地址，你可以通过@指定扩展后缀：

/plain/http://example.com/images/curiosity.jpg@png

 

Base64编码

可以使用URL安全的Base64对源URL进行编码。编码后的URL可以根据/您的需要进行拆分：

/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn

当使用编码源URL，你可以通过.指定扩展后缀：

/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn.png

 

延期

扩展名指定结果图像的格式。目前，imgproxy仅支持jpg，png，webp，gif，ico，heic，和tiff，他们是最流行的和有用的图像格式。

您也可以使用mp4扩展名将动画图像转换为MP4。

注意：此处了解有关图像格式支持的更多信息。

延伸部分可以省略。在这种情况下，imgproxy将使用源图像格式作为结果格式。如果结果不支持源图像格式，则imgproxy将使用jpg。您还可以启用WebP支持检测，以在可能的情况下将其用作默认结果格式。

例

已签名的imgproxy URL，该URL的大小可http://example.com/images/curiosity.jpg进行调整以填充300x400智能重力区域而不会放大，并将图像转换为png：

http://imgproxy.example.com/AfrOrF3gWeDA6VOlDG4TzxMv39O7MXnF4CXpKUwGqRM/fill/300/400/sm/0/plain/http://example.com/images/curiosity.jpg@png

具有与Base64编码的源URL相同的URL如下所示：

http://imgproxy.example.com/AfrOrF3gWeDA6VOlDG4TzxMv39O7MXnF4CXpKUwGqRM/fill/300/400/sm/0/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn.png