zxavier/caddy

caddy2-docker

https://github.com/z-xavier/caddy-docker/actions/workflows/docker-linux-build_2.9.yaml/badge.svg](https://github.com/z-xavier/caddy-docker/actions/workflows/docker-linux-build_2.9.yaml) https://github.com/z-xavier/caddy-docker/actions/workflows/docker-linux-build_2.10.yaml/badge.svg](https://github.com/z-xavier/caddy-docker/actions/workflows/docker-linux-build_2.10.yaml)

镜像概述

这是一个基于Caddy 2构建的Docker镜像，预编译集成了多个扩展组件，提供增强的Web服务器功能，适用于需要动态DNS解析、数据压缩、四层流量处理等高级特性的场景。

核心功能与集成组件

已集成组件

• https://github.com/caddy-dns/cloudflare%EF%BC%9ACloudflare DNS解析支持
• https://github.com/caddy-dns/duckdns%EF%BC%9ADuckDNS%E5%8A%A8%E6%80%81DNS%E6%A8%A1%E5%9D%97
• https://github.com/hairyhenderson/caddy-teapot-module%EF%BC%9AHTTP 418状态码支持模块
• https://github.com/ueffel/caddy-brotli%EF%BC%9ABrotli%E5%8E%8B%E7%BC%A9%E7%AE%97%E6%B3%95%E6%94%AF%E6%8C%81
• https://github.com/mholt/caddy-l4%EF%BC%9A%E5%9B%9B%E5%B1%82(TCP/UDP)%E4%BB%A3%E7%90%86%E6%A8%A1%E5%9D%97

已移除组件

• https://github.com/mastercactapus/caddy2-proxyprotocol
• https://github.com/caddyserver/nginx-adapter%EF%BC%88%E5%9C%A8%602.4%60%E7%89%88%E6%9C%AC%E4%B8%AD%E7%A7%BB%E9%99%A4%EF%BC%89
• https://github.com/greenpau/caddy-security%EF%BC%88%E5%9C%A8%602.7.4%60%E7%89%88%E6%9C%AC%E4%B8%AD%E7%A7%BB%E9%99%A4%EF%BC%8C%E5%9B%A0%E4%BD%BF%E7%94%A8authelia%E6%9B%BF%E4%BB%A3%EF%BC%89

已知问题

• s390x架构支持：自2.4.6版本起提供s390x架构镜像（此前因golang编译问题暂停，相关修复见https://github.com/kyverno/kyverno/pull/3277%EF%BC%89
• DockerHub描述更新限制：不支持使用Token更新存储库描述，相关问题见https://github.com/docker/hub-feedback/issues/1927%E3%80%81https://github.com/docker/hub-feedback/issues/1914%E3%80%81https://github.com/docker/roadmap/issues/115
• 平台限制：暂不提供macOS与Windows版本镜像

使用说明

版本选择

• 推荐使用latest标签，与Caddy官方最新稳定版同步
• 镜像地址：
  • Docker Hub: https://hub.docker.com/r/zxavier/caddy
  • GitHub Container Registry: ghcr.io/z-xavier/caddy
• ⚠️mainline标签包含最新发布版（含rc和beta版），建议仅在测试环境使用

v2.3.0及后续版本注意事项

1. UDP接收缓冲区调整
   高带宽QUIC传输需调整net.core.rmem_max参数，默认值过小会导致以下日志提示：

   failed to sufficiently increase receive buffer size (was: 208 kiB, wanted: 2048 kiB, got: 416 kiB). See [https://github.com/lucas-clemente/quic-go/wiki/UDP-Receive-Buffer-Size](https://github.com/lucas-clemente/quic-go/wiki/UDP-Receive-Buffer-Size) for details.
   

   • Docker Run配置：--sysctl net.core.rmem_max=2500000
   • Docker Compose配置（v2.1+）：

     yaml
     sysctls:
       net.core.rmem_max: 2500000
     

2. remote_ip匹配器行为变更
   默认不再读取X-Forwarded-For标头，如需保持原行为，需在Caddyfile中显式启用forwarded：

   caddyfile
   @trusted forwarded remote_ip 192.168.1.0/24
   

3. HTTP/3配置变更
   experimental_http3全局选项已移除，需在JSON配置中设置：

   json
   {
     "servers": {
       "": {
         "protocol": {
           "experimental_http3": true
         }
       }
     }
   }
   

   相关日志提示：

   sh
   [WARNING][caddyfile] :0: the 'experimental_http3' global option is deprecated, please use the 'servers > protocol > experimental_http3' option instead
   

适用场景

• 需动态DNS解析（Cloudflare/DuckDNS）的Web服务
• 需Brotli压缩提升传输性能的静态资源服务
• 需要处理TCP/UDP四层流量的网络环境
• 需自定义HTTP响应状态码的特殊应用场景

部署示例

Docker Run

bash
docker run -d \
  --name caddy \
  --restart unless-stopped \
  -p 80:80 \
  -p 443:443 \
  -v /path/to/Caddyfile:/etc/caddy/Caddyfile \
  -v caddy_data:/data \
  -v caddy_config:/config \
  --sysctl net.core.rmem_max=2500000 \
  zxavier/caddy:latest

Docker Compose

yaml
version: "3.8"

services:
  caddy:
    image: zxavier/caddy:latest
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
      - caddy_config:/config
    sysctls:
      net.core.rmem_max: 2500000

volumes:
  caddy_data:
  caddy_config:

鸣谢

• https://github.com/caddyserver/caddy
• https://github.com/caddyserver/xcaddy
• https://github.com/caddyserver/caddy-docker
• https://github.com/caddy-dns/cloudflare
• https://github.com/caddy-dns/duckdns
• https://github.com/hairyhenderson/caddy-teapot-module
• https://github.com/ueffel/caddy-brotli
• https://github.com/mholt/caddy-l4

许可证

Apache License 2.0