Caddy 扩展功能镜像文档

镜像概述

本镜像为通过xcaddy工具构建的Caddy Web服务器镜像，基于Caddy v2.4.6版本，集成了多个实用插件，提供比标准Caddy更丰富的功能支持。

核心功能与特性

• 基础版本：基于Caddy v2.4.6稳定版构建，保留Caddy原生的自动HTTPS、反向代理、静态文件服务等核心能力。
• 集成插件：
  • github.com/vrongmeal/caddygit：支持通过Git仓库自动拉取和部署网站内容。
  • github.com/caddy-dns/cloudflare：提供Cloudflare DNS解析支持，用于自动HTTPS证书申请（DNS-01验证）。
  • github.com/porech/caddy-maxmind-geolocation：集成MaxMind地理位置数据库，可获取访问者的地理位置信息。
  • github.com/kirsch33/realip：修复经过代理/CDN后的客户端真实IP地址。
  • github.com/WingLim/caddy-webhook：支持Webhook触发操作，如配置重载、服务重启等。
  • github.com/techknowlogick/caddy-s3browser：提供S3兼容对象存储的Web浏览界面。
  • github.com/lindenlab/caddy-s3-proxy：将S3兼容对象存储内容代理为Web可访问资源。

使用场景与适用范围

• 需要通过Git自动部署静态网站或动态内容的场景。
• 使用Cloudflare DNS管理域名，需自动申请HTTPS证书的Web服务。
• 需根据访问者地理位置限制或定制内容的应用。
• 部署在CDN/代理后端，需获取真实客户端IP的服务。
• 需要通过Webhook触发配置更新、内容同步的自动化流程。
• 需将S3兼容对象存储（如MinIO、AWS S3）内容以Web形式展示或代理的场景。

使用方法与配置说明

基本运行

通过以下命令启动容器，默认使用Caddyfile配置（需挂载自定义配置文件）：

docker run -d \
  -p 80:80 \
  -p 443:443 \
  -v /path/to/Caddyfile:/etc/caddy/Caddyfile \
  -v caddy_data:/data \
  -v caddy_config:/config \
  --name caddy-extended \
  [镜像名称]

注：/path/to/Caddyfile需替换为本地Caddyfile路径，[镜像名称]为实际镜像标签。

配置示例

以下为集成插件的Caddyfile配置片段示例：

1. Git集成（自动拉取网站内容）

example.com {
  root * /srv
  git {
    repo [***]
    branch main
    pull_interval 3600s
  }
  file_server
}

2. Cloudflare DNS（自动HTTPS证书）

example.com {
  tls {
    dns cloudflare {env.CLOUDFLARE_API_TOKEN}
  }
  reverse_proxy localhost:8080
}

需通过环境变量CLOUDFLARE_API_TOKEN传入Cloudflare API令牌。

3. MaxMind地理位置（获取访问者位置）

example.com {
  geolocation {
    db_path /etc/caddy/GeoLite2-City.mmdb
  }
  respond "Your location: {geolocation.city}, {geolocation.country_name}"
}

需挂载MaxMind数据库文件至/etc/caddy/GeoLite2-City.mmdb。

4. S3代理与浏览

s3.example.com {
  s*** {
    aws_region us-east-1
    bucket my-bucket
    endpoint [***]
    access_key {env.AWS_ACCESS_KEY}
    secret_key {env.AWS_SECRET_KEY}
  }
  s3browser /browse {
    bucket my-bucket
    endpoint [***]
  }
}

环境变量与数据卷

• 环境变量：根据插件需求配置，如CLOUDFLARE_API_TOKEN（Cloudflare DNS）、AWS_ACCESS_KEY/AWS_SECRET_KEY（S3相关）等。
• 数据卷：
  • /etc/caddy/Caddyfile：Caddy配置文件，需持久化挂载。
  • /data：Caddy数据目录（含证书、缓存等），建议持久化。
  • /config：Caddy配置存储目录，建议持久化。
  • 其他插件依赖文件（如MaxMind数据库）需按需挂载。

注意事项

• 镜像基于Caddy v2.4.6，插件兼容性以该版本为准。
• 部分插件（如MaxMind）需额外提供依赖文件（如数据库），需手动准备并挂载。
• 生产环境建议限制容器权限，通过--user指定非root用户运行。