Caddy (Layer4 + YAML) 镜像文档

1. 镜像概述和主要用途

本镜像为定制构建的 Caddy 服务器镜像，基于官方 Caddy 核心，集成了 layer4 模块和 YAML 配置支持。主要用途包括：

• 作为高性能 HTTP/HTTPS 服务器及反向代理
• 处理 TCP/UDP 四层流量的代理、负载均衡与端口转发
• 支持 YAML 结构化配置文件，简化复杂场景下的配置管理
• 提供自动 HTTPS 证书管理（Let's Encrypt 集成）、HTTP/2/3 支持等核心能力

2. 核心功能和特性

2.1 Caddy 基础功能

• 自动 HTTPS：自动申请、续期 Let's Encrypt 证书，支持自定义 CA
• HTTP 协议支持：完整支持 HTTP/1.1、HTTP/2、HTTP/3（QUIC）
• 反向代理：支持路径路由、负载均衡（轮询、IP 哈希等策略）、健康检查
• 静态文件服务：高效提供本地文件，支持压缩、范围请求、缓存控制

2.2 Layer4 模块功能

• TCP/UDP 流量处理：支持四层协议代理、端口转发、负载均衡
• 连接管理：配置超时时间、最大连接数、源 IP 限制
• 协议检测：可基于端口或流量特征路由至不同后端服务
• 与 HTTP 功能联动：支持同一实例同时处理七层（HTTP）和四层（TCP/UDP）流量

2.3 YAML 配置支持

• 结构化语法：替代默认 Caddyfile，支持层级嵌套、注释、数组定义
• 配置复用：通过 YAML 锚点（anchor）和引用（alias）减少重复配置
• 易维护性：适合复杂场景（多服务、多协议）下的配置版本控制和团队协作

3. 使用场景和适用范围

• 多协议代理服务器：需同时处理 HTTP/HTTPS（如 Web 服务）和 TCP/UDP（如数据库、SSH、游戏服务器）流量的场景
• YAML 配置偏好者：***惯使用 YAML 进行基础设施配置（如与 Kubernetes、Ansible 等工具联动）的用户或团队
• 边缘网关：作为入口网关，统一处理内外网流量转发、SSL 终结、流量控制
• 自动化运维环境：需自动管理证书、支持动态配置重载（通过 Caddy Admin API）的场景

4. 使用方法和配置说明

4.1 获取镜像

4.1.1 从 Docker Hub 获取（示例）

docker pull your-registry/caddy-layer4-yaml:latest  # 替换为实际镜像地址

4.1.2 自行构建

若需自定义构建，可基于官方 Caddy 构建工具，添加 layer4 和 yaml 模块：

FROM caddy:builder AS builder
RUN xcaddy build \
    --with github.com/mholt/caddy-l4 \  # Layer4 模块
    --with github.com/caddyserver/yaml  # YAML 配置模块

FROM caddy:latest
COPY --from=builder /usr/bin/caddy /usr/bin/caddy

4.2 基本使用（docker run）

4.2.1 快速启动（默认配置）

docker run -d \
  --name caddy \
  -p 80:80 -p 443:443 \  # HTTP/HTTPS 端口
  -p 2222:2222/tcp \     # 示例：暴露 TCP 端口（按需添加）
  your-registry/caddy-layer4-yaml:latest

4.2.2 挂载自定义 YAML 配置文件

docker run -d \
  --name caddy \
  -p 80:80 -p 443:443 \
  -p 5432:5432/tcp \     # 转发 PostgreSQL 流量（示例）
  -v /path/to/your/caddy.yaml:/etc/caddy/caddy.yaml:ro \  # 挂载 YAML 配置
  -v caddy-data:/data \  # 持久化证书和状态数据
  -v caddy-config:/config \  # 持久化配置（如需）
  your-registry/caddy-layer4-yaml:latest \
  caddy run --config /etc/caddy/caddy.yaml  # 指定 YAML 配置文件

4.3 Docker Compose 配置示例

version: "3.8"
services:
  caddy:
    image: your-registry/caddy-layer4-yaml:latest
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"       # HTTP
      - "443:443"     # HTTPS
      - "443:443/udp" # HTTP/3 (QUIC)
      - "2222:2222/tcp" # TCP 服务端口（示例）
    volumes:
      - ./caddy.yaml:/etc/caddy/caddy.yaml:ro  # YAML 配置文件
      - caddy-data:/data                       # 证书和状态存储
      - caddy-logs:/var/log/caddy              # 日志持久化
    command: ["caddy", "run", "--config", "/etc/caddy/caddy.yaml", "--log", "info"]

volumes:
  caddy-data:
  caddy-logs:

4.4 YAML 配置文件说明

4.4.1 配置结构

YAML 配置文件需遵循 Caddy 配置规范，核心结构包含 apps 块，用于定义 HTTP、Layer4 等模块的配置：

# 全局配置（可选）
admin:
  listen: :2019  # 管理 API 地址（默认 :2019）
log:
  level: info    # 日志级别（debug/info/warn/error）

# 应用模块配置
apps:
  http:  # HTTP 模块配置（七层）
    servers:
      srv0:  # 服务器实例名称
        listen: [:80, :443]  # 监听端口
        routes:  # 路由规则
          - match: [{ host: ["example.com"] }]
            handle:
              - handler: reverse_proxy
                upstreams: [{ dial: "webapp:8080" }]
        tls:  # HTTPS 配置
          certificates:
            automation:
              policies:
                - issuers: [{ module: acme, email: "***" }]

  layer4:  # Layer4 模块配置（四层）
    servers:
      srv1:  # 服务器实例名称
        listen: [:2222]  # 监听 TCP 端口
        routes:  # 四层路由规则
          - match: [{ tcp: {} }]  # 匹配所有 TCP 流量
            handle:
              - handler: proxy
                upstreams: [{ dial: "ssh-server:22" }]  # 转发至后端 SSH 服务

4.4.2 典型场景配置示例

场景 1：HTTP 反向代理 + TCP 端口转发

apps:
  http:
    servers:
      web:
        listen: [:443]
        routes:
          - match: [{ host: ["app.example.com"] }]
            handle:
              - handler: reverse_proxy
                upstreams: [{ dial: "192.168.1.100:8080" }]
        tls:
          automation:
            policies: [{ issuers: [{ module: acme, email: "***" }] }]

  layer4:
    servers:
      tcp-proxy:
        listen: [:3306]  # 暴露 MySQL 端口
        routes:
          - match: [{ tcp: {} }]
            handle:
              - handler: proxy
                upstreams: [{ dial: "mysql-server:3306" }]  # 转发至 MySQL 后端

5. 配置参数和环境变量

5.1 命令行参数

5.2 环境变量

6. 注意事项

• 配置文件权限：挂载的 YAML 配置文件需确保容器内 caddy 用户（UID 101）有读取权限，建议宿主机文件权限设为 644。
• 证书持久化：Caddy 自动生成的证书默认存储在 /data/caddy，需通过卷挂载（如 -v caddy-data:/data）持久化，避免容器重建后证书丢失。
• 端口冲突：若宿主机已有服务占用 80/443 等端口，需调整容器端口映射（如 -p 8080:80）并更新配置文件中的监听端口。
• Layer4 与 HTTP 端口隔离：避免同一端口同时被 http 和 layer4 模块监听，可能导致启动失败。