Certbot DigitalOcean DNS 插件 Docker 镜像文档

镜像概述

本镜像为 Electronic Frontier Foundation (EFF) 官方构建的 Certbot Docker 镜像，集成了 DigitalOcean DNS 插件。主要用于通过 DNS-01 挑战（DNS-01 challenge）自动化获取和续期 Let's Encrypt SSL/TLS 证书，适用于使用 DigitalOcean 作为 DNS 服务提供商的用户。

核心功能与特性

核心功能

• DNS-01 挑战自动化：通过 DigitalOcean DNS 插件自动完成 Let's Encrypt 的 DNS-01 验证流程，无需手动添加 TXT 记录。
• DigitalOcean API 集成：与 DigitalOcean DNS API 深度对接，支持动态创建/删除验证所需的 DNS TXT 记录。
• 证书生命周期管理：支持 SSL/TLS 证书的申请、续期、吊销及导出，全程自动化。
• 多域名支持：可同时为单个或多个域名（含通配符域名，如 *.example.com）申请证书。

特性

• 轻量级：基于官方 Certbot 基础镜像，体积精简，仅包含必要依赖。
• 安全设计：支持通过文件或环境变量注入 DigitalOcean API 令牌，避免硬编码敏感信息。
• 兼容性：兼容 Certbot 核心功能（如钩子脚本、证书存储格式）及 Let's Encrypt ACME v2 协议。

使用场景与适用范围

典型场景

• 无公网 HTTP 访问的服务：需为无法通过 HTTP-01 挑战（如内网服务、防火墙隔离的服务）验证的域名申请证书。
• 通配符证书需求：需为通配符域名（如 *.example.com）或跨子域名批量申请证书。
• 自动化运维环境：在容器化部署（如 Kubernetes、Docker Compose）中集成证书自动管理流程。

适用范围

• DNS 服务提供商为 DigitalOcean 的用户。
• 需要长期自动化管理 SSL/TLS 证书的个人或企业用户。
• 需符合 Let's Encrypt 证书政策（如 90 天有效期、续期提醒）的场景。

使用方法与配置说明

前提条件

1. DigitalOcean API 令牌：需在 DigitalOcean 控制台创建具备 dns:edit 权限的个人访问令牌（Personal Access Token），用于操作 DNS 记录。
2. Docker 环境：已安装 Docker Engine（20.10+ 版本推荐）或 Docker Compose。

Docker Run 快速示例

以下示例通过 docker run 命令申请证书，使用环境变量传入 DigitalOcean API 令牌：

docker run --rm \
  -v /etc/letsencrypt:/etc/letsencrypt \  # 挂载证书存储目录（持久化证书和配置）
  -v /var/log/letsencrypt:/var/log/letsencrypt \  # 挂载日志目录
  -e DO_API_TOKEN="your_digitalocean_api_token" \  # DigitalOcean API 令牌（必填）
  certbot/dns-digitalocean \
  certonly \  # 仅申请证书（不自动配置服务器）
  --dns-digitalocean \  # 启用 DigitalOcean DNS 插件
  --dns-digitalocean-token-env DO_API_TOKEN \  # 指定 API 令牌环境变量名
  --email "***" \  # 管理员邮箱（用于证书过期提醒）
  --agree-tos \  # 同意 Let's Encrypt 服务条款
  --no-eff-email \  # 不向 EFF 发送邮件（可选）
  -d "example.com" \  # 目标域名（可重复 -d 参数添加多个域名）
  -d "*.example.com"  # 通配符域名（需 DNS-01 挑战支持）

Docker Compose 配置示例

通过 docker-compose.yml 定义服务，实现证书申请与续期自动化：

version: '3'
services:
  certbot:
    image: certbot/dns-digitalocean
    volumes:
      - ./letsencrypt:/etc/letsencrypt  # 本地目录挂载，持久化证书和配置
      - ./logs:/var/log/letsencrypt     # 日志目录
      - ./credentials:/etc/certbot/credentials  # 凭证文件目录（可选，替代环境变量）
    environment:
      - TZ=Asia/Shanghai  # 时区设置（可选）
    command: >
      certonly
      --dns-digitalocean
      --dns-digitalocean-credentials /etc/certbot/credentials/digitalocean.ini  # 凭证文件路径
      --email ***
      --agree-tos
      --non-interactive  # 非交互式模式（适合脚本/定时任务）
      --keep-until-expiring  # 仅在证书即将过期时续期
      -d example.com
      -d *.example.com

凭证文件示例（./credentials/digitalocean.ini，需设置权限 chmod 600）：

dns_digitalocean_token = your_digitalocean_api_token

配置参数说明

通用参数（Certbot 核心）

DigitalOcean DNS 插件参数

注意事项

1. API 令牌权限：DigitalOcean API 令牌需至少包含 dns:edit 权限，否则无法添加/删除 TXT 记录。
2. 凭证安全：避免通过命令行参数直接传递 API 令牌，优先使用环境变量或文件挂载（文件权限需设为 600，仅 root 可读写）。
3. 证书持久化：务必通过 volumes 挂载本地目录存储 /etc/letsencrypt，避免容器删除导致证书丢失。
4. 续期配置：建议通过 crontab 或 Docker 定时任务（如 docker run --rm ... renew）定期执行证书续期，例如：

   # 每日凌晨 3 点执行续期检查
   0 3 * * * docker run --rm -v /etc/letsencrypt:/etc/letsencrypt certbot/dns-digitalocean renew --non-interactive
   

5. 日志排查：若证书申请失败，可通过挂载的 /var/log/letsencrypt 目录查看详细日志定位问题。