wemakeservices/caddy-gen

caddy-gen

caddy-gen是Caddy、docker-gen和forego的完美组合，灵感来源于nginx-proxy。它通过docker-gen监听容器生命周期事件，动态生成Caddy配置，解决了Caddy静态配置在应用扩展时的局限性，实现轻松扩展。

核心功能与特性

• 动态配置生成：基于docker-gen，在容器启动或停止时自动更新Caddy配置
• 标签驱动配置：通过容器标签定义反向代理规则，无需手动修改配置文件
• 多域名支持：通过virtual.host指定主域名，支持空格分隔多个域名
• 域名别名与重定向：使用virtual.alias设置域名别名，自动重定向至主域名
• 自动HTTPS：配置virtual.tls-email即可启用Let's Encrypt证书自动申请与续期
• 灵活的自定义选项：支持自定义Caddyfile指令、导入外部配置文件、设置基础认证
• 可扩展架构：支持自定义模板和全局配置，满足复杂场景需求

适用场景

• 多容器应用的动态反向代理
• 需要自动扩展的微服务架构
• 开发/测试环境中快速部署多个Web服务
• 需要自动管理HTTPS证书的生产环境
• 需根据容器生命周期自动更新配置的场景

配置选项

caddy-gen通过Docker容器标签进行配置，核心思想是：每个带标签的服务通过virtual.host暴露域名，每个容器作为一个上游服务处理请求。

注意：v0.3.0版本引入Caddy2，带来不兼容变更。

主要配置标签

基础认证选项

同时配置以下标签启用HTTP基础认证：

• virtual.auth.path：认证生效的路径
• virtual.auth.username：认证用户名
• virtual.auth.password：base64编码的bcrypt哈希密码（可通过bcrypt-generator.com生成哈希，再用base64encode.org编码）

反向代理选项

自定义模板与全局配置

通过环境变量支持自定义配置：

• CADDY_TEMPLATE：挂载自定义模板文件路径，替换默认Caddy模板
• CADDY_SNIPPET：挂载自定义片段文件路径，内容会前置到模板中，用于设置全局选项、定义代码片段或添加自定义地址块

构建时参数

支持通过构建参数自定义组件版本：

• FOREGO_VERSION：指定forego版本
• DOCKER_GEN_VERSION：指定docker-gen版本

使用方法

基础部署示例

以下示例通过docker-compose部署caddy-gen作为反向代理，代理whoami服务：

yaml
version: "3"
services:
  caddy-gen:
    container_name: caddy-gen
    image: "wemakeservices/caddy-gen:latest"
    restart: always
    volumes:
      - /var/run/docker.sock:/tmp/docker.sock:ro  # 需挂载Docker socket监听容器事件
      - ./caddy-info:/data/caddy  # 挂载卷备份证书
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - whoami

  whoami:  # 被代理的服务
    image: "katacoda/docker-http-server:v2"
    labels:
      - "virtual.host=myapp.com"  # 主域名（必填）
      - "virtual.alias=www.myapp.com"  # 域名别名（可选）
      - "virtual.port=80"  # 容器暴露端口
      - "virtual.tls-email=admin@myapp.com"  # 启用HTTPS（必填邮箱）
      - "virtual.auth.path=/secret/*"  # 基础认证路径
      - "virtual.auth.username=admin"  # 基础认证用户名
      - "virtual.auth.password=JDJ5JDEyJEJCdzJYM0pZaWtMUTR4UVBjTnRoUmVJeXQuOC84QTdMNi9ONnNlbDVRcHltbjV3ME1pd2pLCg=="  # base64编码的bcrypt密码

证书备份

为确保HTTPS证书持久化，需挂载/data/caddy目录：

yaml
services:
  caddy-gen:
    volumes:
      - ./caddy-info:/data/caddy  # 证书将存储在本地./caddy-info目录

自定义反向代理请求头

通过virtual.proxy.directives修改反向代理请求头，如下示例使上游服务获取自身地址：

yaml
services:
  whoami:
    labels:
      virtual.host: myapp.com
      virtual.port: 80
      virtual.tls: admin@myapp.com
      virtual.proxy.directives: |
        header_up Host {http.reverse_proxy.upstream.hostport}

静态文件服务配置

通过virtual.host.directives配置静态文件服务，如下示例使myapp.com提供www目录下的文件，并将/api/*请求代理到whoami服务：

yaml
version: "3"
services:
  caddy-gen:
    image: "wemakeservices/caddy-gen:latest"
    restart: always
    volumes:
      - /var/run/docker.sock:/tmp/docker.sock:ro
      - ./caddy-info:/data/caddy
      - ./www:/srv/myapp/www  # 挂载静态文件目录到容器
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - whoami

  whoami:
    image: "katacoda/docker-http-server:v2"
    labels:
      virtual.host: myapp.com
      virtual.port: 80
      virtual.tls: admin@myapp.com
      virtual.proxy.matcher: /api/*  # 仅代理/api/*路径
      virtual.host.directives: |
        root * /srv/myapp/www  # 静态文件根目录
        templates  # 启用模板功能
        file_server  # 启用文件服务

使用自定义Caddy模板

以下示例自定义模板实现HTTPS重定向和按域名日志分割：

自定义模板文件（./caddy/template）：

jinja
(redirectHttps) {
  @http {
    protocol http
  }
  redir @http https://{host}{uri}
}

(logFile) {
  log {
    output file /var/caddy/{host}/logs {
      roll_keep_for 7
    }
  }
}

{{ $hosts := groupByLabel $ "virtual.host" }}
{{ range $h, $containers := $hosts }}
{{ range $t, $host := split (trim (index $c.Labels "virtual.host")) " " }}
{{ $tls = trim (index $c.Labels "virtual.tls") }}
{{ $host }} {
  {{ if $tls }}
  tls {{ $tls }}
  import redirectHttps
  {{ end }}
  reverse_proxy {
    lb_policy round_robin
    {{ range $i, $container := $containers }}
    {{ range $j, $net := $container.Networks }}
    to {{ $net.IP}}:{{ or (trim (index $container.Labels "virtual.port")) "80" }}
    {{ end }}
    {{ end }}
  }
  encode zstd gzip
  import logFile
}

docker-compose配置：

yaml
services:
  caddy-gen:
    volumes:
      - ./caddy/template:/tmp/caddy/template  # 挂载模板文件
    environment:
      CADDY_TEMPLATE: /tmp/caddy/template  # 指定自定义模板路径

设置Caddy全局选项

通过CADDY_SNIPPET设置全局选项，如下示例使用Let's Encrypt测试环境（避免证书申请频率限制）：

全局选项片段文件（./caddy/global_options）：

jinja
{
  acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

docker-compose配置：

yaml
services:
  caddy-gen:
    volumes:
      - ./caddy/global_options:/tmp/caddy/global_options  # 挂载片段文件
    environment:
      CADDY_SNIPPET: /tmp/caddy/global_options  # 指定片段路径