Certbot DNS-LuaDNS 插件 Docker 镜像文档

镜像概述和主要用途

本镜像为 Electronic Frontier Foundation (EFF) 官方构建的 Certbot Docker 镜像，集成了用于 DNS-01 挑战的 LuaDNS 插件。Certbot 是一款自动化工具，用于从 Let's Encrypt 等证书颁发机构获取和续期 SSL/TLS 证书。该镜像专门针对需要通过 LuaDNS 进行 DNS 验证的场景，提供证书申请、续期的全流程自动化支持。

版本信息：当前稳定版本 v1.7.0
官方仓库：certbot/certbot

核心功能和特性

核心功能

• 集成 Certbot 核心与 LuaDNS DNS-01 挑战插件，支持通过 LuaDNS 完成域名所有权验证
• 自动化执行 DNS-01 挑战流程，无需手动添加 DNS TXT 记录
• 支持 Let's Encrypt 证书的申请、续期、吊销等全生命周期管理
• 兼容 ACME v2 协议，支持通配符证书（如 *.example.com）

关键特性

• 官方维护：由 EFF 官方构建和维护，确保安全性与兼容性
• 轻量设计：基于精简基础镜像，降低资源占用
• 灵活配置：支持通过环境变量、命令行参数或配置文件自定义行为
• 无状态运行：证书和配置可通过外部卷持久化，便于容器编排管理

使用场景和适用范围

适用场景

• 无法使用 HTTP-01 挑战的环境：如服务器位于防火墙后、无公网 HTTP 端口暴露，或需为多服务器共享的域名颁发证书（如通配符证书）
• 自动化证书管理：需定期自动续期证书的生产环境，避免手动操作遗漏
• LuaDNS 用户：已使用 LuaDNS 管理域名 DNS 记录，希望通过其 API 自动化完成 DNS 验证

适用范围

• 系统管理员、DevOps 工程师及需要管理 SSL/TLS 证书的技术人员
• 基于 Docker 或 Kubernetes 的容器化部署环境
• 需合规使用可信 SSL/TLS 证书的 Web 服务、API 服务等

详细使用方法和配置说明

前置条件

1. 已注册 LuaDNS 账户，并拥有待验证域名的 DNS 管理权限
2. 获取 LuaDNS API 凭证（通常为 API Token 或 API Key，需在 LuaDNS 账户设置中生成）
3. Docker 环境已安装（版本 18.06+ 推荐）

环境变量说明

LuaDNS 插件需通过环境变量传入 API 凭证，常用变量如下：

Docker 部署示例

1. 基础运行命令（获取证书）

通过 docker run 命令执行证书申请，需挂载本地目录存储证书，并传入 LuaDNS 凭证：

docker run -it --rm \
  -v /etc/letsencrypt:/etc/letsencrypt \  # 持久化证书和配置
  -v /var/lib/letsencrypt:/var/lib/letsencrypt \  # 存储临时文件
  -e "LUA_DNS_API_KEY=your_luadns_api_token" \  # 替换为实际 LuaDNS API Token
  certbot/dns-luadns:v1.7.0 \
  certonly \
  --dns-luadns \  # 指定使用 LuaDNS 插件
  --dns-luadns-credentials /etc/letsencrypt/luadns.ini \  # 或通过文件传入凭证（二选一）
  -d example.com \  # 待验证域名（支持多个 -d 参数）
  -d *.example.com \  # 通配符域名（需 DNS-01 挑战）
  --email *** \  # 管理员邮箱（用于证书到期通知）
  --agree-tos \  # 同意 Let's Encrypt 服务条款
  --non-interactive  # 非交互式运行（适合自动化脚本）

注意：若不使用环境变量，可通过 --dns-luadns-credentials 指定凭证文件（格式见下文），文件内容需包含 dns_luadns_api_key = your_token。

2. 凭证文件格式（可选）

若通过文件传入 LuaDNS 凭证，需在宿主机创建 luadns.ini 文件（如 /etc/letsencrypt/luadns.ini），内容示例：

# /etc/letsencrypt/luadns.ini
dns_luadns_api_key = your_luadns_api_token

运行时需挂载该文件，并通过 --dns-luadns-credentials 指定路径（如上述 docker run 命令所示）。

3. docker-compose 配置示例

创建 docker-compose.yml 文件，定义证书申请服务：

version: '3.8'

services:
  certbot-luadns:
    image: certbot/dns-luadns:v1.7.0
    volumes:
      - ./letsencrypt/etc:/etc/letsencrypt  # 本地目录挂载，持久化证书
      - ./letsencrypt/lib:/var/lib/letsencrypt
    environment:
      - LUA_DNS_API_KEY=your_luadns_api_token  # 替换为实际 API Token
    command: >
      certonly
      --dns-luadns
      -d example.com
      -d *.example.com
      --email ***
      --agree-tos
      --non-interactive
      --force-renewal  # 强制续期（首次运行可移除）

启动命令：docker-compose up

常用命令示例

1. 申请新证书（交互式）

docker run -it --rm \
  -v /etc/letsencrypt:/etc/letsencrypt \
  -v /var/lib/letsencrypt:/var/lib/letsencrypt \
  -e "LUA_DNS_API_KEY=your_token" \
  certbot/dns-luadns:v1.7.0 \
  certonly --dns-luadns -d example.com

2. 自动续期所有证书

Certbot 默认会检查即将过期的证书（剩余 30 天内）并自动续期，可通过 renew 命令触发：

docker run -it --rm \
  -v /etc/letsencrypt:/etc/letsencrypt \
  -v /var/lib/letsencrypt:/var/lib/letsencrypt \
  -e "LUA_DNS_API_KEY=your_token" \
  certbot/dns-luadns:v1.7.0 \
  renew --dns-luadns

3. 吊销证书

docker run -it --rm \
  -v /etc/letsencrypt:/etc/letsencrypt \
  certbot/dns-luadns:v1.7.0 \
  revoke --cert-path /etc/letsencrypt/live/example.com/cert.pem

注意事项

1. 数据持久化：证书和配置文件需通过外部卷（如 -v /etc/letsencrypt:/etc/letsencrypt）持久化，避免容器重启后丢失。
2. 凭证安全：API 凭证（如 LUA_DNS_API_KEY）需妥善保管，避免暴露在日志或配置文件中（建议通过环境变量注入，而非硬编码）。
3. 定期更新：建议定期更新镜像至最新版本，以获取安全补丁和功能更新。
4. 挑战超时：DNS-01 挑战依赖 DNS 记录 propagation，若验证失败可增加 --dns-luadns-propagation-seconds 参数（默认 10 秒，可调整为 30-60 秒）。