让 Halo 支持 webp 图片输出

发布于 2025年11月03日

[服务已经成功部署上,但没有转换成功。可能是配置哪里没有配置正确,文章就不删除了,留个记录。]

使用开源工具WebP Server Go

使用自定义配置启动容器

简单说明

确保您已安装 Docker 和 docker-compose。如果您希望使用自定义的 config.json配置文件,然后将其挂载到容器内的 /etc/config.json路径下。创建一个目录,并在其中创建 docker-compose.yml文件,示例如下:

version: '3'

services:
  webp:
    image: webpsh/webp-server-go
    # 也可以使用: ghcr.io/webp-sh/webp_server_go
    restart: always
    volumes:
      - ./path/to/pics:/opt/pics
      - ./path/to/exhaust:/opt/exhaust
      - ./path/to/metadata:/opt/metadata
      - ./config.json:/etc/config.json
    ports:
      -  127.0.0.1:3333:3333

假设您的网站和图片遵循以下路径模式:

图片实际路径

网站访问路径

/opt/halo/halo2/attachments/upload/wx.jpg

https://rongtech.top/upload/wx.jpg

那么:

  • ./path/to/pics应改为您本地存放图片的目录,例如 /opt/halo/halo2/attachments/

  • ./exhaust是输出图片的缓存文件夹,默认会放在与 docker-compose.yml文件同级的 exhaust目录下。如果您希望将缓存图片保存在其他路径,可以将 ./exhaust改为 /opt/halo/halo2/attachments/exhaust

  • ./metadata是图片元数据的缓存文件夹,默认会放在与 docker-compose.yml文件同级的 metadata目录下。

正式开始部署适合用于我自己网站情况的WebP Server Go

创建项目目录:

mkdir - p /opt/halo/halo2/attachments/exhaust
mkdir -p /opt/webp-go
cd /opt/webp-go
vi config.json

config.json文件内容如下:

{
        "HOST": "127.0.0.1",
        "PORT": "3333",
        "QUALITY": "100",
        "IMG_PATH": "/opt/halo/halo2/attachments",
        "EXHAUST_PATH": "/opt/halo/halo2/attachments/exhaust",
        "ALLOWED_TYPES": ["*"],
        "CONVERT_TYPES":["webp"]

}

最后适合用于我自己halo的docker-compose.yml文件内容如下:

vi docker-compose.yml
version: '3'

services:
  webp:
    image: webpsh/webp-server-go
    # 也可以使用: ghcr.io/webp-sh/webp_server_go
    restart: always
    volumes:
      - /opt/halo/halo2/attachments:/opt/pics
      - /opt/halo/halo2/attachments/exhaust:/opt/exhaust
      - ./metadata:/opt/metadata
      - ./config.json:/etc/config.json
    ports:
      -  127.0.0.1:3333:3333

使用以下命令启动容器:

docker-compose up -d

现在服务器应运行在 127.0.0.1:3333。访问 http://127.0.0.1:3333/upload/wx.jpg将会看到 /opt/halo/halo2/attachments/upload/wx.jpg的优化版本。

修改Nginx全局配置文件

修改 nginx.conf

vi /etc/nginx/nginx.conf

在 配置文件的server{}中添加:

location ^~ /upload/ {
        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';
}

重载 Nginx 配置:

# 检查配置文件是否有问题
nginx -t 

nginx -s reload

这样您的 WebP 服务器就可以实时转换图片了!

验证图片类型是否改变

附录:config.json每个配置字段的中文描述:

字段

环境变量

类型 (Type)

描述 (Description)

HOST

WEBP_HOST

string

服务器监听的主机地址

PORT

WEBP_PORT

string

服务器监听的端口号

QUALITY

WEBP_QUALITY

string

输出图片的质量,范围从 0 到 100。100 表示无损转换。

IMG_PATH

WEBP_IMG_PATH

string

原始图片目录的路径。如果你想使用远程后端(如外部 Nginx 托管的静态站点、阿里云 OSS 或腾讯云 COS),请参考 Remote Backend文档。

EXHAUST_PATH

WEBP_EXHAUST_PATH

string

缓存目录的路径​(用于存储转换后的 WebP 等格式图片)。例如,将 EXHAUST_PATH设置为 /var/cache/webp,那么你的 WebP 图片将保存在 /var/cache/webp/pics/tsuki.jpg.1582558990.webp

IMG_MAP

/

dict

URI/主机到图片路径的映射字典。如果设置了此字段,则 IMG_PATH将被忽略。更多信息请参阅 MultiPath页面。

ALLOWED_TYPES

WEBP_ALLOWED_TYPES

list

允许处理的原始图片类型列表。如果你想允许所有图片类型,只需在此处使用 ["*"]

CONVERT_TYPES

WEBP_CONVERT_TYPES

string

WebP Server 将尝试转换成的目标图片格式列表,默认为 ["webp"],表示仅尝试转换为 WebP 格式。可用选项:["webp","avif","jxl"]

STRIP_METADATA

WEBP_STRIP_METADATA

bool

是否从图片中剥离 EXIF 元数据

ENABLE_EXTRA_PARAMS

WEBP_ENABLE_EXTRA_PARAMS

bool

是否启用额外参数功能。启用后,允许在图片 URL 中添加参数进行转换操作,例如 https://img.webp.sh/path/tsuki.jpg?width=20。更多信息请参阅 Extra Parameters页面。

EXTRA_PARAMS_CROP_INTERESTING

WEBP_EXTRA_PARAMS_CROP_INTERESTING

string

定义当 ENABLE_EXTRA_PARAMS开启且图片请求同时包含宽度和高度参数时,WebP Server 应如何裁剪图片。可用选项有:“InterestingNone”(无焦点模式), “InterestingEntropy”(熵焦点), “InterestingCentre”(中心焦点), “InterestingAttention”(注意力焦点), “InterestringLow”(低焦点), “InterestingHigh”(高焦点), “InterestingAll”(全焦点)。更多信息请参阅 Extra Parameters页面。

READ_BUFFER_SIZE

WEBP_READ_BUFFER_SIZE

number

每个连接用于读取请求的缓冲区大小(字节)​。这也限制了最大请求头大小。如果客户端发送包含数千字节的请求 URI 或多千字节的请求头(例如,大型 Cookie),请增加此缓冲区大小。

CONCURRENCY

WEBP_CONCURRENCY

number

最大并发连接数

DISABLE_KEEPALIVE

WEBP_DISABLE_KEEPALIVE

string

禁用 Keep-Alive 连接。启用后,服务器在向客户端发送第一个响应后将关闭传入的连接。

CACHE_TTL

WEBP_CACHE_TTL

number

远程后端(代理模式)的缓存生存时间(TTL,单位:分钟)​。我们使用 HEAD 请求来获取远程图片信息,因此你的后端需要支持 HEAD 请求。在首次成功的 HEAD 请求后,其结果将被缓存 CACHE_TTL分钟。在此期间,我们将不再发送 HEAD 请求,而是使用本地缓存进行渲染。将此值设置为 0表示永久缓存。

MAX_CACHE_SIZE

WEBP_MAX_CACHE_SIZE

number

最大缓存大小(单位:兆字节 MiB)​。默认值为 0,表示不清理本地缓存文件。如果设置了此值(例如 50),则 WebP Server Go 会运行一个后台任务(每分钟检查一次),确保本地缓存目录(./metadata, ./exhaust以及如果使用远程后端时的 ./remote-raw)​各自的大小均低于设定的 MiB 值。




评论