serfriz/caddy-duckdns

Caddy Docker 镜像（含 DuckDNS DNS 模块）

![GitHub]([] ![Quay]([]

1. 镜像概述

本镜像是基于官方 https://hub.docker.com/_/caddy 镜像构建的自定义版本，集成了 DuckDNS DNS 模块，用于支持通过 DNS-01 挑战完成 ACME 证书验证。镜像通过 GitHub Actions 自动构建更新，当 https://github.com/caddyserver/caddy 官方发布新版本时，会自动同步更新。

2. 核心功能与特性

2.1 核心功能

• DuckDNS DNS-01 验证支持：集成 https://github.com/caddy-dns/duckdns 模块，可通过 DuckDNS 完成 ACME 证书的 DNS-01 挑战验证，适用于动态 IP 环境或无法直接暴露 80/443 端口的场景。

2.2 主要特性

• 与官方 Caddy 镜像兼容：支持官方镜像的所有卷挂载、端口映射、绑定挂载等配置方式。
• 自动更新机制：通过 GitHub Actions 监听 Caddy 官方版本更新，自动触发构建流程，确保镜像版本与 Caddy 官方同步。
• 多平台支持：提供 Caddy 官方支持的所有架构平台镜像，可从 Docker Hub、GitHub Packages、Quay 等多个容器仓库拉取。

3. 使用场景与适用范围

3.1 典型使用场景

• 动态 IP 环境下的 HTTPS 部署：通过 DuckDNS 动态域名解析，结合本镜像实现家庭服务器、NAS 等设备的 HTTPS 访问。
• 无法暴露 80/443 端口的场景：无需开放 HTTP/HTTPS 端口，通过 DNS-01 挑战完成证书申请与续期。
• 自托管服务的证书管理：为各类自托管服务（如 Nextcloud、Home Assistant 等）自动配置和续期 SSL/TLS 证书。

3.2 适用用户

• 需要通过 DuckDNS 管理域名的个人用户或小型团队。
• 使用 Caddy 作为反向代理或 Web 服务器，并需自动管理 SSL 证书的用户。

4. 使用方法与配置说明

4.1 镜像拉取

可从以下容器仓库拉取镜像：

4.2 标签说明

镜像提供以下标签：

• latest：最新稳定版，跟踪 Caddy 官方最新版本。
• <version>：特定版本标签，如 2.7.4、2.7、2 等，对应 Caddy 官方版本号。

4.3 基本部署配置

4.3.1 Docker Run 部署

bash
docker run -d \
  --name caddy-duckdns \
  --restart unless-stopped \
  -p 80:80 \
  -p 443:443 \
  -v /path/to/Caddyfile:/etc/caddy/Caddyfile \
  -v caddy_data:/data \
  -v caddy_config:/config \
  -e DUCKDNS_TOKEN="your_duckdns_token" \
  serfriz/caddy-duckdns:latest

参数说明：

• -p 80:80/-p 443:443：映射 HTTP/HTTPS 端口（根据实际需求调整）。
• -v /path/to/Caddyfile:/etc/caddy/Caddyfile：绑定挂载自定义 Caddyfile 配置文件。
• -v caddy_data:/data：持久化存储证书、日志等数据（推荐使用卷而非绑定挂载）。
• -v caddy_config:/config：存储 Caddy 运行时配置。
• -e DUCKDNS_TOKEN：DuckDNS 令牌（必填，用于 DNS-01 验证，从 DuckDNS 控制台获取）。

4.3.2 Docker Compose 部署

创建 docker-compose.yml 文件：

yaml
version: "3.8"

services:
  caddy:
    image: serfriz/caddy-duckdns:latest
    container_name: caddy-duckdns
    restart: unless-stopped
    ports:
      - "80:80"    # HTTP 端口（可根据需求调整）
      - "443:443"  # HTTPS 端口（可根据需求调整）
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile  # 绑定自定义 Caddyfile
      - caddy_data:/data                  # 持久化证书和数据
      - caddy_config:/config              # 持久化运行时配置
    environment:
      - DUCKDNS_TOKEN=your_duckdns_token  # 替换为实际的 DuckDNS 令牌

volumes:
  caddy_data:
  caddy_config:

启动服务：

bash
docker-compose up -d

4.4 Caddyfile 配置示例

以下为集成 DuckDNS 模块的 Caddyfile 配置示例，用于为 DuckDNS 域名自动申请 SSL 证书：

caddyfile
# 替换为你的 DuckDNS 域名（如 example.duckdns.org）
example.duckdns.org {
  reverse_proxy 192.168.1.100:8080  # 反向代理到后端服务（根据实际情况调整）

  # 配置 TLS 证书，使用 DuckDNS 模块进行 DNS-01 验证
  tls {
    dns duckdns {
      token {$DUCKDNS_TOKEN}  # 引用环境变量中的 DuckDNS 令牌
    }
  }
}

说明：

• {$DUCKDNS_TOKEN}：从环境变量读取 DuckDNS 令牌，需确保容器启动时通过 -e DUCKDNS_TOKEN=xxx 传入。
• dns duckdns：指定使用 DuckDNS 模块进行 DNS-01 挑战验证。

4.5 环境变量说明

5. 注意事项

• 数据持久化：建议使用卷（volumes）而非绑定挂载（bind mounts）持久化 /data 和 /config 目录，避免容器重建导致证书和配置丢失。
• 端口映射：若仅使用 DNS-01 验证，无需暴露 80/443 端口；若需同时提供 HTTP 服务，需映射对应端口。
• DuckDNS 令牌获取：登录 DuckDNS 控制台，在对应域名的配置页面获取 API 令牌。

6. 许可证信息

本镜像的构建脚本及相关代码基于 https://github.com/serfriz/caddy-custom-builds/blob/main/LICENSE 开源，确保用户可自由使用、修改和分发，同时要求源代码保持公开可访问。