在Caddy Docker Proxy中实现通配符证书自动管理的最佳实践

背景介绍

随着Caddy 2.9.1版本的发布，新增了auto_https prefer_wildcard功能，这项功能允许优先使用已有的通配符证书而不是为每个子域名单独申请证书。本文将详细介绍如何在Caddy Docker Proxy（CDP）环境中实现这一功能。

核心概念解析

通配符证书的优势

通配符证书（如*.example.com）可以覆盖一个域名下的所有子域名，相比为每个子域名单独申请证书有以下优势：

1. 减少证书申请次数
2. 简化证书管理
3. 降低Let's Encrypt等CA的请求限制风险

Caddy 2.9.1新特性

prefer_wildcard选项让Caddy优先检查是否存在匹配的通配符证书，如果存在则直接使用，否则才会为特定子域名申请独立证书。

实现步骤详解

1. 构建自定义CDP镜像

由于官方CDP尚未发布支持Caddy 2.9的版本，需要自定义构建：

ARG CADDY_VERSION=2.9.1
FROM caddy:${CADDY_VERSION}-builder AS builder
RUN xcaddy build ${CADDY_VERSION} \
  --with github.com/lucaslorentz/caddy-docker-proxy/v2

FROM caddy:${CADDY_VERSION}-alpine
COPY --from=builder /usr/bin/caddy /usr/bin/caddy
CMD ["caddy", "docker-proxy"]

2. Docker Compose配置要点

services:
  reverse-proxy:
    image: localhost/caddy-docker-proxy:2.9.1
    labels:
      # 全局设置，优先使用通配符证书
      caddy.auto_https: prefer_wildcard
      # 通配符证书配置
      caddy_1: "*.example.internal"
      caddy_1.respond: "fallback"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp" # HTTP/3支持

3. 关键配置说明

1. 通配符域名定义：必须使用引号包裹，如"*.example.com"，否则Docker Compose会解析错误
2. fallback响应：为未明确配置的子域名提供默认响应
3. 网络配置：确保容器间网络互通，特别是DNS解析

测试验证方法

1. 启动服务后，使用curl测试子域名访问：

curl --insecure https://whoami.example.internal

2. 验证证书信息：

step certificate inspect --insecure https://whoami.example.internal | jq -c .extensions.subject_alt_name.dns_names

3. 测试通配符匹配：

curl https://random-subdomain.example.internal

常见问题解决方案

1. 配置语法错误：确保通配符域名使用双引号包裹
2. 证书不更新：使用docker compose up --force-recreate强制重建容器
3. DNS解析问题：检查容器网络配置和DNS设置

最佳实践建议

1. 生产环境应考虑使用正式的CA而不是自签名证书
2. 合理规划域名结构，确保通配符证书覆盖范围符合需求
3. 定期监控证书到期时间，虽然Caddy会自动续期，但仍需确保服务正常运行
4. 考虑证书缓存策略，提高服务可用性

通过以上配置，可以充分利用Caddy 2.9.1的通配符证书优先特性，简化证书管理流程，提高服务可靠性。这种方案特别适合需要管理大量子域名的场景，能显著降低运维复杂度。