🚀 使用 Docker Compose 部署 WebP Server Go
🚀 使用 Docker Compose 部署 WebP Server Go
WebP Server Go 是一款基于 Go 语言开发的开源 WebP 实时转换服务器。它能够自动将 JPEG、PNG、BMP、GIF 等格式的图片转换为 WebP 格式，从而有效减小图片体积、节省带宽并提升网页加载速度。
📦 项目简介
核心优势： - 智能格式转换：自动根据浏览器支持情况返回 WebP 或原始图片，所有操作对用户透明。 - 性能提升显著：通常可将图片体积减小 20%-70%，提升页面加载速度。 - 无侵入式部署：无需修改现有图片 URL 或网站结构。 - 开箱即用：提供 Docker 镜像，简化部署流程。
主要特性： - 支持 JPEG、PNG、BMP、GIF、SVG、HEIC 等多种源格式 - 可配置输出 WebP、AVIF 等现代图片格式 - 支持元数据处理和智能裁剪参数 - 提供灵活的缓存管理和内存优化
⚙️ 部署前准备
- 环境要求
- 已安装 Docker 和 Docker Compose
- 系统内存：建议 1GB 以上
-
确保 3333 端口 未被占用
-
环境检查 在终端执行以下命令确认环境正常：
bash docker --version docker-compose --version -
创建项目目录 建议创建独立目录管理所有文件：
bash mkdir -p /opt/docker/webp-server cd /opt/docker/webp-server
🛠️ 配置 Docker Compose
基于你提供的配置，创建 docker-compose.yml 文件：
#version: '3'
services:
webp:
image: webpsh/webp-server-go # 官方镜像（稳定更新，国内访问速度快）
# image: ghcr.io/webp-sh/webp_server_go # 备选：GitHub Container Registry 镜像（海外推荐）
container_name: webp-server # 容器名称，便于管理
restart: always # 容器退出后自动重启（开机自启，确保服务不中断）
ports:
- 3333:3333 # 端口映射：主机 3333 → 容器 3333（服务访问端口）
volumes:
##- ./config.json:/etc/config.json #Custom config 自定义配置
#- ./pics:/opt/pics # 原图目录
#- ./exhaust:/opt/exhaust # 转换缓存
#- ./metadata:/opt/metadata # 元数据
# 1. 原图目录：主机 /mnt/10t/.../pics → 容器 /opt/pics（核心，需存放待转换图片）
- /mnt/10t/file/webdav/images/pics:/opt/pics # 原图目录
# 2. 转换缓存目录：主机 /mnt/10t/.../exhaust → 容器 /opt/exhaust
- /mnt/10t/file/webdav/images/exhaust:/opt/exhaust # 转换缓存
# 3. 元数据目录：主机 /mnt/10t/.../metadata → 容器 /opt/metadata
- /mnt/10t/file/webdav/images/metadata:/opt/metadata # 元数据
# 4. 配置文件：主机 ./config.json → 容器 /etc/config.json（自定义配置）
- ./config.json:/etc/config.json
environment:
#- PUID=0
#- PGID=0
- PUID=1000 # 运行用户 ID（1000 为默认普通用户，避免权限问题；报错可改为 0（root））
- PGID=1000 # 运行用户组 ID（与 PUID 一致）
#- PUID=101
#- PGID=65533
#更多参数请查阅：https://docs.webp.sh/usage/configuration/
- MALLOC_ARENA_MAX=1 # 内存优化参数（限制内存碎片，降低占用）
#- ENABLE_EXTRA_PARAMS=true # 开启高级参数
#实战效果展示
#访问http://IP:3333/产品图.jpg，肉眼可见的变化
#支持?width=800&height=600参数智能缩放（图2）
# 启用 URL 参数控制（如缩放、裁剪）
- WEBP_ENABLE_EXTRA_PARAMS=true #表示是否启用额外参数，基本上它允许你对图像进行一些变换，如 https://img.webp.sh/path/tsuki.jpg?width=20 ，你可以在额外参数页面找到更多信息。
- WEBP_MAX_CACHE_SIZE=100 #50 # 缓存最大容量（单位：MiB，超过自动清理旧缓存）
#以 MiB 为单位，默认值为 0，这意味着不会清理本地缓存文件。如果设置此值为 50，例如，那么 WebP Server Go 将每分钟运行一个后台任务，以确保本地缓存目录（ ./metadata 、 ./exhaust 和 ./remote-raw （如果使用远程后端））分别保持在 50MiB 以下。
#- WEBP_CACHE_TTL=0
#远程后端（代理模式）的缓存 TTL（分钟）我们使用 HEAD 请求获取远程图片信息，因此您的后端需要支持 HEAD 请求，在第一次成功 HEAD 请求后，它将被缓存 CACHE_TTL 分钟，在此期间，我们将不再发送 HEAD 请求，而是使用本地缓存进行渲染。Setting this value to 0 means cache forever.将此值设置为 0 表示永久缓存。
#- WEBP_DISABLE_KEEPALIVE="" #字符串 禁用长连接，服务器在向客户端发送第一个响应后关闭传入的连接
- WEBP_CONCURRENCY=4 # 最大并发转换数（根据 CPU 核心调整，4 核建议设 4-8）
#- WEBP_READ_BUFFER_SIZE=0 #连接请求的读取缓冲区大小。这也限制了最大头部长度。如果您的客户端发送多 KB 的 RequestURIs 和/或多 KB 的头信息（例如，大的 cookies），请增加此缓冲区。
#- WEBP_EXTRA_PARAMS_CROP_INTERESTING="InterestingAttention" #定义当 ENABLE_EXTRA_PARAMS 开启且图像请求同时包含 width 和 height 时，WebP Server 如何裁剪图像，可选参数有：“InterestingNone”，“InterestingEntropy”，“InterestingCentre”，“InterestingAttention”，“InterestringLow”，“InterestingHigh”，“InterestingAll”，你可以在额外参数页面找到更多信息。
- WEBP_STRIP_METADATA=true #false # 不删除图片 EXIF 元数据（如需隐私保护可设为 true）
- WEBP_CONVERT_TYPES=webp # 转换目标格式（仅 WebP，可改为 ["webp","avif"] 支持多格式）
#- WEBP_CONVERT_TYPES=avif #WebP Server 尝试转换的图像类型列表，默认为 ["webp"] ，表示它将仅尝试将图像转换为 WebP，可用选项： ["webp","avif","jxl"] 。#avif没法播放gif动图,这点不需要动图就能用。
#- WEBP_ALLOWED_TYPES="*" #允许的图像类型列表，如果您想允许所有图像类型，只需在此处使用 ["*"] 。
#- WEBP_EXHAUST_PATH='' #WebP 图像的缓存目录路径，例如，当 EXHAUST_PATH 设置为 /var/cache/webp 时，您的 webp 图像将保存在 /var/cache/webp/pics/tsuki.jpg.1582558990.webp 。
#- WEBP_IMG_PATH="" #图像目录路径（原始图像），如果您想使用远程后端（例如外部 Nginx 提供的静态网站、阿里云 OSS 或腾讯 COS），请参考远程后端。
#- WEBP_QUALITY=50 #图像质量，从 0 到 100，100 表示无损转换。粗糙最低30值，建议30-80之间，我的是75。设50时，jpg>avif=86>1.93m，这个压缩比例我很满意。
#应用场景：原件图片批量上传得到链接，访问加工后的链接得到转换后的图片，提升加载速度。
- WEBP_QUALITY=80 # 转换质量（0-100，80 兼顾质量与体积，建议 50-80 之间）
#- WEBP_PORT="" #监听的端口
#- WEBP_HOST="" #监听的地址
deploy: # 在单机模式下使用deploy.resources # 单机模式也支持这种语法
resources:
limits: # 资源限制（避免占用过多服务器资源）
cpus: '0.7' # 最多使用 0.7 个 CPU 核心
memory: 512M # 最多使用 512MB 内存
#VPS版配置
#version: '3'
services:
webp:
image: webpsh/webp-server-go
# image: ghcr.io/webp-sh/webp_server_go
container_name: webp-server
restart: always
ports:
- 3333:3333
volumes:
##- ./config.json:/etc/config.json #Custom config 自定义配置
#- ./pics:/opt/pics # 原图目录
#- ./exhaust:/opt/exhaust # 转换缓存
#- ./metadata:/opt/metadata # 元数据
- /home/compose/go_webdav/mnt/images/pics:/opt/pics # 原图目录
- /home/compose/go_webdav/mnt/images/exhaust:/opt/exhaust # 转换缓存
- /home/compose/go_webdav/mnt/images/metadata:/opt/metadata # 元数据
- ./config.json:/etc/config.json
environment:
#- PUID=0
#- PGID=0
- PUID=1000
- PGID=1000
#- PUID=101
#- PGID=65533
#更多参数请查阅：https://docs.webp.sh/usage/configuration/
- MALLOC_ARENA_MAX=1 # 内存优化参数
#- ENABLE_EXTRA_PARAMS=true # 开启高级参数
#实战效果展示
#访问http://IP:3333/产品图.jpg，肉眼可见的变化
#支持?width=800&height=600参数智能缩放（图2）
- WEBP_ENABLE_EXTRA_PARAMS=true #表示是否启用额外参数，基本上它允许你对图像进行一些变换，如 https://img.webp.sh/path/tsuki.jpg?width=20 ，你可以在额外参数页面找到更多信息。
- WEBP_MAX_CACHE_SIZE=100 #50
#以 MiB 为单位，默认值为 0，这意味着不会清理本地缓存文件。如果设置此值为 50，例如，那么 WebP Server Go 将每分钟运行一个后台任务，以确保本地缓存目录（ ./metadata 、 ./exhaust 和 ./remote-raw （如果使用远程后端））分别保持在 50MiB 以下。
#- WEBP_CACHE_TTL=0
#远程后端（代理模式）的缓存 TTL（分钟）我们使用 HEAD 请求获取远程图片信息，因此您的后端需要支持 HEAD 请求，在第一次成功 HEAD 请求后，它将被缓存 CACHE_TTL 分钟，在此期间，我们将不再发送 HEAD 请求，而是使用本地缓存进行渲染。Setting this value to 0 means cache forever.将此值设置为 0 表示永久缓存。
#- WEBP_DISABLE_KEEPALIVE="" #字符串 禁用长连接，服务器在向客户端发送第一个响应后关闭传入的连接
- WEBP_CONCURRENCY=4 #最大并发连接数
#- WEBP_READ_BUFFER_SIZE=0 #连接请求的读取缓冲区大小。这也限制了最大头部长度。如果您的客户端发送多 KB 的 RequestURIs 和/或多 KB 的头信息（例如，大的 cookies），请增加此缓冲区。
#- WEBP_EXTRA_PARAMS_CROP_INTERESTING="InterestingAttention" #定义当 ENABLE_EXTRA_PARAMS 开启且图像请求同时包含 width 和 height 时，WebP Server 如何裁剪图像，可选参数有：“InterestingNone”，“InterestingEntropy”，“InterestingCentre”，“InterestingAttention”，“InterestringLow”，“InterestingHigh”，“InterestingAll”，你可以在额外参数页面找到更多信息。
- WEBP_STRIP_METADATA=true #false # 不删除图片 EXIF 元数据（如需隐私保护可设为 true）
- WEBP_CONVERT_TYPES=webp
#- WEBP_CONVERT_TYPES=avif #WebP Server 尝试转换的图像类型列表，默认为 ["webp"] ，表示它将仅尝试将图像转换为 WebP，可用选项： ["webp","avif","jxl"] 。#avif没法播放gif动图,这点不需要动图就能用。
#- WEBP_ALLOWED_TYPES="*" #允许的图像类型列表，如果您想允许所有图像类型，只需在此处使用 ["*"] 。
#- WEBP_EXHAUST_PATH='' #WebP 图像的缓存目录路径，例如，当 EXHAUST_PATH 设置为 /var/cache/webp 时，您的 webp 图像将保存在 /var/cache/webp/pics/tsuki.jpg.1582558990.webp 。
#- WEBP_IMG_PATH="" #图像目录路径（原始图像），如果您想使用远程后端（例如外部 Nginx 提供的静态网站、阿里云 OSS 或腾讯 COS），请参考远程后端。
#- WEBP_QUALITY=50 #图像质量，从 0 到 100，100 表示无损转换。粗糙最低30值，建议30-80之间，我的是75。设50时，jpg>avif=86>1.93m，这个压缩比例我很满意。
#应用场景：原件图片批量上传得到链接，访问加工后的链接得到转换后的图片，提升加载速度。
- WEBP_QUALITY=80
#- WEBP_PORT="" #监听的端口
#- WEBP_HOST="" #监听的地址
deploy: # 在单机模式下使用deploy.resources # 单机模式也支持这种语法
resources:
limits:
#cpus: '0.7'
#memory: 512M
cpus: '0.1'
memory: 356M
关键配置说明：
| 配置项 | 说明与建议 |
|---|---|
volumes |
/mnt/10t/file/webdav/images/pics:/opt/pics 是源图片目录；/mnt/10t/file/webdav/images/exhaust:/opt/exhaust 存储转换后的图片；./config.json:/etc/config.json 挂载配置文件。 |
environment |
WEBP_QUALITY：图片质量 (1-100)，建议 70-85；WEBP_CONCURRENCY：并发处理数，根据 CPU 核心数调整；WEBP_MAX_CACHE_SIZE：缓存大小限制 (MiB)，0 表示无限制。 |
PUID/PGID |
设置为有权限访问图片目录的用户/组 ID，避免权限问题。 |
⚙️ 配置 config.json
创建 config.json 配置文件：
{
"HOST": "0.0.0.0", // 监听地址（0.0.0.0 允许外部访问）
"PORT": "3333", // 监听端口（与 docker-compose.yml 一致）
"QUALITY": "80", // 转换质量（环境变量 WEBP_QUALITY 会覆盖此值）#质量80默认
"IMG_PATH": "./pics", // 容器内原图目录（与 volumes 挂载一致）
"EXHAUST_PATH": "./exhaust", // 容器内缓存目录（与 volumes 挂载一致）
"IMG_MAP": {}, // 图片路径映射（默认无需配置，新手留空）#“IMG映射”：
"ALLOWED_TYPES": ["jpg", "png", "jpeg", "bmp", "gif", "svg", "heic", "nef", "webp"],// 允许转换的原图格式（支持 10+ 格式）
"CONVERT_TYPES": ["webp"], // 转换目标格式（环境变量 WEBP_CONVERT_TYPES 会覆盖此值）#“转换类型”默认 webp/avif
"STRIP_METADATA": true, // 删除 EXIF 元数据（环境变量 WEBP_STRIP_METADATA 会覆盖此值）#“条形元数据
"ENABLE_EXTRA_PARAMS": false,// 启用 URL 参数（环境变量 WEBP_ENABLE_EXTRA_PARAMS 会覆盖此值）#“启用额外参数
"EXTRA_PARAMS_CROP_INTERESTING": "InterestingAttention",// 裁剪策略（优先保留图片核心区域）#额外的参数作物
"READ_BUFFER_SIZE": 4096, // 读取缓冲区大小（默认即可，无需修改）
"CONCURRENCY": 262144, // 并发连接数（环境变量 WEBP_CONCURRENCY 会覆盖此值）
"DISABLE_KEEPALIVE": false, // 禁用长连接（默认关闭，保持连接复用）#禁用保持活动
"CACHE_TTL": 259200, // 远程图片缓存过期时间（分钟，本地图片无需关注）#“缓存TTL
"MAX_CACHE_SIZE": 0 // 缓存大小（环境变量 WEBP_MAX_CACHE_SIZE 会覆盖此值）#“最大缓存大小
}
配置要点：
- ALLOWED_TYPES：指定要转换的源图片格式
- CONVERT_TYPES：输出格式，如 ["webp"] 或 ["webp", "avif"]
- STRIP_METADATA：设为 true 可移除 EXIF 数据，减小文件体积
- CACHE_TTL：缓存生存时间（分钟），0 为永久缓存
- WEBP_QUALITY ：建议设 50-80：50 体积小但质量略低，80 质量接近原图但体积仍比 JPG 小 50%+。
- WEBP_ENABLE_EXTRA_PARAMS=true ：必须设为 true，才能使用 ?width=800 等参数缩放图片，否则仅返回默认尺寸的 WebP 图片。
🚀 启动与验证
-
启动服务
bash docker-compose up -d -
检查服务状态
bash docker-compose ps确认容器状态为Up。 -
查看日志
bash docker-compose logs -f webp -
测试转换效果 在浏览器中访问进行测试：
http://你的服务器IP:3333/测试图片.jpg支持的额外参数格式：http://IP:3333/图片.jpg?width=800&height=600
🌐 Nginx 反向代理配置
要让现有网站使用 WebP Server Go，需要在 Nginx 配置中添加反向代理规则：
server {
listen 80;
server_name your-domain.com;
# WebP 转换规则
location ~* \.(?:jpg|jpeg|gif|png|bmp)$ {
proxy_pass http://127.0.0.1:3333;
proxy_set_header X-Real-IP $remote_addr;
proxy_hide_header X-Powered-By;
proxy_set_header HOST $http_host;
add_header Cache-Control 'no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0';
}
# 其他文件正常处理
location / {
root /var/www/html;
# 其他配置...
}
}
配置后重启 Nginx：
nginx -t && nginx -s reload
⚙️ 基础配置与使用
- 图片更新与缓存管理
- WebP Server Go 采用两级缓存机制：
remote-raw目录存储原始图片，exhaust目录存储优化后的图片 - 强制更新图片时，需要手动删除
exhaust和remote-raw目录中的对应缓存文件 -
通过环境变量
WEBP_CACHE_TTL可设置缓存过期时间（单位：分钟） -
高级功能使用
- 智能裁剪：启用
WEBP_ENABLE_EXTRA_PARAMS=true后，支持 URL 参数裁剪 - 多格式输出：
WEBP_CONVERT_TYPES可配置多种输出格式，如webp,avif - 元数据保留：根据需求设置
WEBP_STRIP_METADATA，保留 EXIF 等信息
🔒 维护与管理
- 服务管理： ```bash # 停止服务 docker-compose down
# 重启服务 docker-compose restart
# 查看状态 docker-compose ps ```
-
数据备份： 定期备份
config.json配置文件，以及重要的源图片目录。 -
版本更新：
bash docker-compose down docker-compose pull docker-compose up -d -
缓存清理： 如需清理所有缓存，可删除
exhaust和metadata目录内容。
🐛 常见问题排查
| 问题现象 | 可能原因与解决方法 |
|---|---|
| 无法访问 WebP 服务 | 1. 检查防火墙是否开放 3333 端口 2. 确认容器运行状态： docker-compose ps3. 查看服务日志： docker-compose logs webp |
| 图片转换失败 | 1. 检查源图片目录权限，确保 PUID/PGID 有读取权限 2. 验证 config.json 中 ALLOWED_TYPES 包含该图片格式3. 查看具体错误日志 |
| 图片更新后未生效 | 1. 清理 exhaust 和 remote-raw 目录中的缓存文件2. 检查 CACHE_TTL 设置是否过长 |
| 内存占用过高 | 1. 调整 WEBP_CONCURRENCY 减少并发数2. 设置 WEBP_MAX_CACHE_SIZE 限制缓存大小3. 确保 MALLOC_ARENA_MAX=1 已设置 |
💡 性能提示：对于高流量网站，建议将缓存目录挂载到 SSD 硬盘，并适当增加 WEBP_CONCURRENCY 值以提升并发处理能力。
通过以上配置，你的网站将能够自动为支持 WebP 的浏览器提供优化后的图片，同时为不支持的浏览器回退到原始格式，有效提升网站加载速度并节省带宽成本。