让 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 值。




评论