Certbot Linode DNS插件 Docker镜像文档

镜像概述与主要用途

概述

本镜像为Certbot的官方Docker镜像，集成了Linode DNS插件，用于通过DNS-01挑战（DNS-01 challenge）自动化获取和续期SSL/TLS证书。Certbot是由电子前哨基金会（EFF）开发的开源证书管理工具，支持与Let's Encrypt等证书颁发机构（CA）交互，实现证书的全自动管理。Linode DNS插件通过Linode DNS API自动添加/删除DNS TXT记录，完成域名所有权验证，无需暴露服务器80/443端口。

主要用途

• 通过Linode DNS服务执行DNS-01挑战，验证域名所有权
• 自动化申请、续期单域名、多域名及通配符SSL/TLS证书（如*.example.com）
• 在Docker环境中集成Certbot证书管理能力，简化部署流程

核心功能与特性

使用场景与适用范围

适用场景

• 通配符证书需求：需申请*.example.com等通配符证书（HTTP-01挑战不支持通配符域名）。
• 无公网端口暴露：服务器无法对外暴露80/443端口（如内网服务、防火墙限制），无法使用HTTP-01挑战。
• 多域名统一管理：需为多个子域名或跨域域名批量申请证书。

适用范围

• 拥有Linode账户及DNS管理权限的用户。
• 域名通过Linode DNS服务解析。
• 采用Docker容器化部署的环境（如Kubernetes、Docker Compose集群）。

使用方法与配置说明

前置条件

1. Linode API令牌：需在Linode账户中创建API令牌（具有domain读写权限），获取方式：
   • 登录Linode控制台 → 个人资料 → API令牌 → 创建令牌 → 勾选domain权限 → 保存令牌。
2. 域名解析：目标域名需通过Linode DNS管理（即域名的NS记录指向Linode DNS服务器）。

环境变量

配置参数

通过Certbot命令行参数配置插件行为，常用参数如下：

Docker部署示例

1. docker run命令（首次获取证书）

通过docker run直接运行容器，获取证书并持久化存储至本地目录：

docker run -it --rm \
  -v /etc/letsencrypt:/etc/letsencrypt \  # 挂载证书存储目录（本地持久化）
  -v /var/lib/letsencrypt:/var/lib/letsencrypt \  # 挂载Certbot工作目录
  -e LINODE_API_TOKEN="your_linode_api_token" \  # 替换为实际Linode API令牌
  certbot/dns-linode:v1.7.0 \  # 镜像版本（当前v1.7.0）
  certonly \  # 仅获取证书（不自动配置服务器）
  --dns-linode \  # 使用Linode DNS插件
  --dns-linode-propagation-seconds 60 \  # 设置DNS传播等待时间（根据网络延迟调整）
  -d "example.com" \  # 目标域名（支持多个-d参数，如-d "*.example.com"）
  -d "*.example.com" \
  --email "***" \  # 管理员邮箱（用于证书到期通知）
  --agree-tos \  # 同意CA服务条款
  --non-interactive  # 非交互式运行（适合自动化脚本）

2. docker run命令（证书续期）

Certbot默认会自动续期剩余有效期＜30天的证书，通过renew命令触发续期：

docker run -it --rm \
  -v /etc/letsencrypt:/etc/letsencrypt \
  -v /var/lib/letsencrypt:/var/lib/letsencrypt \
  -e LINODE_API_TOKEN="your_linode_api_token" \
  certbot/dns-linode:v1.7.0 \
  renew \  # 续期命令
  --dns-linode \
  --dns-linode-propagation-seconds 60 \
  --non-interactive

3. docker-compose配置示例

通过docker-compose.yml定义服务，便于集成到现有Docker环境：

version: '3.8'

services:
  certbot-linode:
    image: certbot/dns-linode:v1.7.0
    volumes:
      - /etc/letsencrypt:/etc/letsencrypt
      - /var/lib/letsencrypt:/var/lib/letsencrypt
    environment:
      - LINODE_API_TOKEN=your_linode_api_token  # 替换为实际令牌
    command: >
      certonly
      --dns-linode
      --dns-linode-propagation-seconds 60
      -d example.com
      -d *.example.com
      --email ***
      --agree-tos
      --non-interactive
    restart: "no"  # 证书获取为一次性任务，无需持续运行

续期配置：可通过cron任务定期执行续期命令，例如添加系统定时任务：

# 每天凌晨3点执行续期（输出日志至/var/log/certbot-renew.log）
0 3 * * * docker run --rm -v /etc/letsencrypt:/etc/letsencrypt -v /var/lib/letsencrypt:/var/lib/letsencrypt -e LINODE_API_TOKEN="your_linode_api_token" certbot/dns-linode:v1.7.0 renew --dns-linode --non-interactive >> /var/log/certbot-renew.log 2>&1

注意事项

1. API令牌安全：LINODE_API_TOKEN需严格保密，避免泄露（建议通过环境变量或加密凭据文件传递，不直接写入命令行）。
2. 证书目录持久化：/etc/letsencrypt和/var/lib/letsencrypt目录必须通过Docker Volume挂载至宿主机，否则容器重启后证书将丢失。
3. DNS传播延迟：若证书申请失败，可适当增加--dns-linode-propagation-seconds（如60-120秒），确保Linode DNS记录生效。
4. 版本锁定：建议指定镜像版本（如:v1.7.0），避免自动升级导致兼容性问题。

参考链接

• Certbot官方文档
• Linode DNS API文档
• Certbot核心镜像