黄兵的个人博客

Caddy Docker 镜像启用 Brotli 压缩

在上篇文章中，我们详细介绍了 Caddy 的一些特性。

在这篇文章中我们来介绍一下在 Docker 中如何增加 Brotli 压缩。

在 Docker 版本的 Caddy 中启用 Brotli 和 Zstd 压缩，情况略有不同：

1. Zstd (zstd)：Caddy 官方镜像（v2.4+）原生支持，无需额外安装，只需配置。

2. Brotli (br)：Caddy 官方镜像默认不包含该模块（因为它是 C 语言库绑定，编译较复杂）。你需要构建一个自定义的 Docker 镜像来添加 Brotli 插件。

以下是完整的步骤指南。

第一步：构建包含 Brotli 的自定义镜像

我们需要使用 Caddy 提供的 builder 镜像来编译一个包含 caddy-brotli 插件的新二进制文件。

在你的项目目录下创建一个名为 Dockerfile 的文件：

# 阶段 1: 构建 Caddy
FROM caddy:builder AS builder

# 【修正点1】添加 --output 参数，确保覆盖系统原有的 caddy 二进制文件
RUN xcaddy build \
    --with github.com/ueffel/caddy-brotli \
    --output /usr/bin/caddy

# 阶段 2: 生成最终镜像
FROM caddy:alpine

# 将构建好的 caddy 二进制文件复制到最终镜像中
COPY --from=builder /usr/bin/caddy /usr/bin/caddy

需要加上 --output 参数，强制覆盖 /usr/bin/caddy，确保复制的是带插件的版本。

如果出现了错误，我们可以使用如下命令重写构建：

# 1. 停止并移除旧容器
docker-compose down

# 2. 强制不使用缓存重新构建，并重新创建容器
docker-compose up -d --build --force-recreate

第二步：配置 Caddyfile

在你的 Caddyfile 中，使用 encode 指令来启用压缩。建议将压缩算法按优先顺序排列（通常 Zstd 和 Brotli 优于 Gzip）。

example.com {
    # 启用 zstd, brotli 和 gzip
    # Caddy 会根据客户端请求头 Accept-Encoding 自动选择最合适的
    encode zstd br gzip

    # 你的其他配置，例如反向代理或文件服务
    reverse_proxy app:8080
    # file_server
}

注意：gzip 是作为兜底方案，因为它是兼容性最好的。

第三步：使用 Docker Compose 运行

创建一个 docker-compose.yml 文件，使用刚才创建的 Dockerfile 进行构建。

services:
  caddy:
    build: .  # 指向包含 Dockerfile 的当前目录
    container_name: caddy_custom
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp" # HTTP/3 需要 UDP
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
      - caddy_config:/config

volumes:
  caddy_data:
  caddy_config:

运行以下命令启动：

docker compose up -d --build

第四步：验证是否生效

你可以使用 curl 命令来检查响应头，看看是否成功启用了压缩。

1. 测试 Brotli (br):

curl -I -H "Accept-Encoding: br" https://example.com

查看输出中的 content-encoding 字段，应该显示 br。

2. 测试 Zstd (zstd):

curl -I -H "Accept-Encoding: zstd" https://example.com

查看输出中的 content-encoding 字段，应该显示 zstd。

常见问题排查

• 配置顺序： 确保 encode 指令放在站点块内部。

• 浏览器支持： 目前主流浏览器（Chrome, Firefox, Edge）都支持 Brotli。Zstd 的浏览器支持正在普及中（Chrome 118+ 已支持），所以同时保留 gzip 非常重要。

• 构建失败： 由于 caddy-brotli 依赖 CGO（C 语言库），构建过程可能比纯 Go 插件稍慢，且必须基于 caddy:builder 镜像。

其它相关推荐：

1、Caddy 服务器

2、Zstd 压缩 Brotli 压缩 Gzip 压缩对比

3、

4、

5、