Certbot Cloudflare DNS插件 Docker镜像文档

一、镜像概述和主要用途

1.1 镜像基本信息

镜像名称：certbot/dns-cloudflare（基于Certbot官方镜像构建）
官方维护：Electronic Frontier Foundation (EFF)
核心用途：该镜像为Certbot的官方Docker镜像，集成了Cloudflare DNS插件，用于通过DNS-01挑战（DNS-01 challenge）自动获取、续期SSL/TLS证书。适用于使用Cloudflare DNS服务的域名，无需暴露服务器80/443端口即可完成域名验证。

二、核心功能和特性

2.1 核心功能

• Cloudflare DNS-01验证：通过Cloudflare DNS API自动添加/删除TXT记录，完成域名所有权验证（DNS-01挑战）。
• 证书全生命周期管理：支持自动申请、续期SSL/TLS证书（包括通配符证书和多域名证书）。
• Certbot核心兼容：完全兼容Certbot标准命令和配置，可结合Certbot其他功能（如证书安装、 renewal-hooks等）使用。

2.2 关键特性

• 轻量级：基于Alpine或Debian slim基础镜像，镜像体积小，资源占用低。
• 官方维护：由EFF官方构建和更新，与Certbot主版本同步，安全性和兼容性有保障。
• 无端口依赖：无需暴露80/443端口，解决服务器端口受限场景下的证书申请问题。

三、使用场景和适用范围

3.1 典型使用场景

• 通配符证书申请：需为*.example.com等通配符域名申请证书（ACME协议要求通配符证书必须通过DNS-01验证）。
• 多域名/子域名管理：同时为多个独立域名或子域名（如a.example.com、b.example.com）申请证书。
• 端口受限环境：服务器无法开放80/443端口（如内网服务、防火墙限制），无法使用HTTP-01挑战。
• Cloudflare DNS用户：域名DNS服务由Cloudflare托管，需通过Cloudflare API自动化DNS记录操作。

3.2 适用范围

• 个人或企业用户使用Cloudflare DNS服务的域名。
• 需要自动化SSL/TLS证书管理的Docker化部署环境。
• 对证书安全性和续期可靠性有较高要求的生产环境。

四、使用方法和配置说明

4.1 前置条件

1. 环境依赖：已安装Docker Engine（20.10+推荐）或Docker Compose。
2. Cloudflare配置：
   • 拥有Cloudflare账户及目标域名的管理权限。
   • 创建Cloudflare API令牌（API Token），需包含以下权限：
     • Zone:Read（读取域名区域信息）
     • DNS:Edit（修改DNS记录，用于添加/删除TXT记录）
   • （可选）记录目标域名的Cloudflare区域ID（Zone ID），用于指定域名区域。

4.2 核心配置参数

4.2.1 环境变量（Cloudflare插件专用）

4.2.2 Certbot通用参数

4.3 部署示例

4.3.1 使用docker run获取证书

首次申请证书（通配符域名示例）

docker run --rm \
  -v /etc/letsencrypt:/etc/letsencrypt \  # 挂载证书存储目录（持久化证书）
  -v /var/lib/letsencrypt:/var/lib/letsencrypt \  # 挂载Certbot工作目录
  -e "CF_DNS_API_TOKEN=your_cloudflare_api_token" \  # Cloudflare API令牌
  -e "CERTBOT_EMAIL=***" \  # 管理员邮箱
  certbot/dns-cloudflare \
  certonly \
  --dns-cloudflare \
  --non-interactive \
  --agree-tos \
  -d example.com \
  -d *.example.com

证书续期（自动续期）

Certbot默认会检查证书有效期（剩余30天内自动续期），可通过以下命令手动触发续期：

docker run --rm \
  -v /etc/letsencrypt:/etc/letsencrypt \
  -v /var/lib/letsencrypt:/var/lib/letsencrypt \
  -e "CF_DNS_API_TOKEN=your_cloudflare_api_token" \
  certbot/dns-cloudflare \
  renew \
  --non-interactive

4.3.2 Docker Compose配置示例

创建docker-compose.yml文件：

version: '3.8'

services:
  certbot:
    image: certbot/dns-cloudflare
    volumes:
      - ./letsencrypt:/etc/letsencrypt  # 本地目录挂载，持久化证书
      - ./letsencrypt-lib:/var/lib/letsencrypt  # 工作目录
    environment:
      - CF_DNS_API_TOKEN=your_cloudflare_api_token  # 替换为实际API令牌
      - CERTBOT_EMAIL=***  # 替换为实际邮箱
    command: >
      certonly
      --dns-cloudflare
      --non-interactive
      --agree-tos
      -d example.com
      -d *.example.com

启动容器申请证书：

docker-compose up

4.4 证书管理

4.4.1 证书存储路径

容器内证书默认存储于/etc/letsencrypt，通过卷挂载到宿主机后，可在宿主机路径（如/etc/letsencrypt）中查看：

• 证书文件：/etc/letsencrypt/live/example.com/fullchain.pem
• 私钥文件：/etc/letsencrypt/live/example.com/privkey.pem

4.4.2 自动续期配置

Certbot证书默认有效期为90天，建议通过定时任务（如crontab）自动续期：

1. 创建续期脚本/opt/certbot/renew.sh：

#!/bin/bash
docker run --rm \
  -v /etc/letsencrypt:/etc/letsencrypt \
  -v /var/lib/letsencrypt:/var/lib/letsencrypt \
  -e "CF_DNS_API_TOKEN=your_cloudflare_api_token" \
  certbot/dns-cloudflare renew --non-interactive

2. 添加可执行权限：

chmod +x /opt/certbot/renew.sh

3. 配置crontab（每日凌晨3点执行）：

echo "0 3 * * * /opt/certbot/renew.sh >> /var/log/certbot-renew.log 2>&1" | crontab -

五、注意事项

1. API令牌权限：确保Cloudflare API令牌至少包含Zone:Read和DNS:Edit权限，避免因权限不足导致验证失败。
2. 证书备份：/etc/letsencrypt目录需持久化存储（通过Docker卷挂载），防止容器删除后证书丢失。
3. 隐私保护：避免将API令牌或密钥直接写入命令行或配置文件，建议通过环境变量或安全文件管理。
4. 日志查看：通过docker logs <容器ID>查看证书申请/续期过程中的详细日志，用于排查错误。

六、参考链接

• Certbot官方文档
• Certbot Cloudflare DNS插件文档
• Cloudflare API令牌创建指南