certbot/dns-dnsimple

Certbot DNSimple 插件 Docker 镜像文档

镜像概述和主要用途

本镜像为 EFF（电子前哨基金会）官方发布的 Certbot Docker 镜像，集成了用于 DNSimple DNS 验证的专用插件。Certbot 是一款自动化工具，用于从 Let's Encrypt 等 ACME 协议证书颁发机构（CA）获取和续期 SSL/TLS 证书。该镜像专门支持通过 DNSimple 的 DNS 服务执行 DNS-01 挑战验证，适用于需要通过 DNS 记录证明域名所有权以获取证书的场景（如通配符证书、无公网 HTTP 访问的服务器等）。

核心功能和特性

核心功能

• 证书生命周期管理：自动完成证书的申请、续期及吊销流程，支持单域名、多域名及通配符域名证书。
• DNS-01 验证支持：通过 DNSimple API 自动添加/删除 DNS TXT 记录，完成 ACME DNS-01 挑战验证，无需开放 HTTP 端口。
• 官方插件集成：内置 certbot-dns-dnsimple 插件，与 DNSimple DNS 服务深度集成，简化验证流程。
• 跨平台兼容：基于官方 Certbot 核心镜像构建，兼容 Docker 生态，支持 Linux/macOS/Windows（WSL2）环境。

关键特性

• 官方构建：由 EFF 官方维护，确保与 Certbot 主版本同步更新，安全可靠。
• 轻量高效：基于 Alpine 或 Debian 基础镜像（取决于 Certbot 核心版本），体积小，资源占用低。
• 灵活配置：支持通过环境变量、凭据文件或命令行参数自定义验证参数，适配不同部署需求。

使用场景和适用范围

典型使用场景

• 通配符证书申请：需通过 DNS-01 验证获取 *.example.com 格式的通配符证书。
• 无公网 HTTP 访问的服务器：服务器位于内网或防火墙限制 HTTP 访问，无法使用 HTTP-01 验证。
• 多服务器证书共享：通过共享证书存储目录（如 NFS），实现多服务器共用证书。
• 自动化集成：可嵌入 CI/CD 流程或定时任务（如 cron），实现证书续期全自动化。

适用范围

• DNS 服务提供商：需使用 DNSimple 作为域名 DNS 托管服务的用户。
• 技术场景：容器化部署环境（Docker/Kubernetes）、边缘计算节点、私有网络服务器等。
• 用户群体：DevOps 工程师、系统管理员、需要自动化 SSL 证书管理的企业或个人用户。

使用方法和配置说明

前提条件

1. 已安装 Docker 引擎（参考 Docker 官方文档）。
2. 拥有 DNSimple 账户及 API 令牌（需具备域名的 DNS 读写权限，获取方式：DNSimple 控制台 > Account > API Tokens）。
3. 目标域名已在 DNSimple 中完成托管，且 API 令牌有权限操作该域名的 DNS 记录。

获取镜像

从 Docker Hub 拉取最新版本镜像：

bash
docker pull certbot/dns-dnsimple:latest

注：镜像标签与 Certbot 版本同步（如 v2.8.0），建议指定具体版本以确保稳定性。

基本使用示例

1. 申请证书（docker run 命令）

以下命令通过 DNSimple 验证申请 example.com 及 *.example.com 的证书，并将证书存储在本地 /etc/letsencrypt 目录：

bash
docker run -it --rm \
  -v /etc/letsencrypt:/etc/letsencrypt \  # 持久化存储证书及配置
  -v /var/lib/letsencrypt:/var/lib/letsencrypt \  # 存储 Certbot 工作文件
  -v /path/to/dnsimple.ini:/etc/dnsimple.ini:ro \  # 挂载 DNSimple 凭据文件（只读）
  certbot/dns-dnsimple:latest \
  certonly \  # 仅获取证书（不自动安装到服务器）
  --dns-dnsimple \  # 启用 DNSimple 插件
  --dns-dnsimple-credentials /etc/dnsimple.ini \  # 指定凭据文件路径
  --dns-dnsimple-propagation-seconds 60 \  # 等待 DNS 记录传播的时间（默认 10s，建议根据 DNSimple TTL 调整）
  -d example.com \  # 目标域名
  -d *.example.com \  # 通配符域名
  --email admin@example.com \  # 管理员邮箱（用于证书过期通知）
  --agree-tos \  # 同意 CA 服务条款
  --non-interactive  # 非交互式运行（自动化场景）

2. 证书续期

Certbot 默认会在证书过期前 30 天自动续期，也可手动触发：

bash
docker run -it --rm \
  -v /etc/letsencrypt:/etc/letsencrypt \
  -v /var/lib/letsencrypt:/var/lib/letsencrypt \
  -v /path/to/dnsimple.ini:/etc/dnsimple.ini:ro \
  certbot/dns-dnsimple:latest \
  renew \  # 续期所有即将过期的证书
  --dns-dnsimple \
  --dns-dnsimple-credentials /etc/dnsimple.ini \
  --non-interactive

3. docker-compose 配置示例

创建 docker-compose.yml 实现配置持久化：

yaml
version: '3.8'
services:
  certbot-dnsimple:
    image: certbot/dns-dnsimple:latest
    volumes:
      - ./letsencrypt/etc:/etc/letsencrypt  # 证书及配置存储
      - ./letsencrypt/lib:/var/lib/letsencrypt  # 工作文件存储
      - ./credentials:/etc/credentials:ro  # 凭据文件目录（包含 dnsimple.ini）
    command: >
      certonly
      --dns-dnsimple
      --dns-dnsimple-credentials /etc/credentials/dnsimple.ini
      --dns-dnsimple-propagation-seconds 60
      -d example.com
      -d *.example.com
      --email admin@example.com
      --agree-tos
      --non-interactive
    restart: "no"  # 一次性任务，无需持续运行

配置参数与环境变量

凭据文件格式

dnsimple.ini 需包含 DNSimple API 令牌，格式如下（权限设置为 600，仅属主可读写）：

ini
# dnsimple.ini
dns_dnsimple_api_token = YOUR_DNSIMPLE_API_TOKEN

注意：API 令牌需具备 DNS 记录读写权限，获取路径：DNSimple 控制台 > Account > API Tokens > "New Token" > 勾选 "Domain" 权限组。

核心参数说明

环境变量（可选）

若不使用凭据文件，可通过环境变量传递 DNSimple API 令牌（需配合 --dns-dnsimple 参数）：

• DNSIMPLE_API_TOKEN：DNSimple API 令牌（优先级低于凭据文件）。

注意事项

• 凭据安全：凭据文件（dnsimple.ini）包含敏感信息，需设置严格权限（如 chmod 600），避免泄露。
• 证书存储：通过 Docker 卷（-v）持久化 /etc/letsencrypt 和 /var/lib/letsencrypt 目录，防止容器重建导致证书丢失。
• 镜像更新：定期拉取最新镜像（docker pull certbot/dns-dnsimple:latest），确保修复已知漏洞。
• 日志查看：Certbot 日志默认存储在 /var/log/letsencrypt，可通过挂载该目录查看详细验证过程。

相关链接

• Certbot 官方文档
• DNSimple API 文档
• https://hub.docker.com/r/certbot/certbot%EF%BC%88%E6%9C%AC%E9%95%9C%E5%83%8F%E5%9F%BA%E4%BA%8E%E6%AD%A4%E6%9E%84%E5%BB%BA%EF%BC%89