stephenneal/certbot

Certbot Docker镜像文档

镜像概述

Certbot Docker镜像是EFF（电子前哨基金会）开发的Certbot工具的容器化版本。Certbot是一款开源工具，用于自动获取、部署和续期Let's Encrypt提供的免费SSL/TLS证书，旨在简化HTTPS配置流程。该Docker镜像封装了Certbot的核心功能，提供跨平台、隔离化的运行环境，适用于各类需要SSL证书的Web服务场景。

核心功能与特性

• 自动证书获取：通过Let's Encrypt CA自动申请免费SSL/TLS证书，支持单域名、多域名及通配符域名
• 自动续期管理：内置证书续期机制，默认在证书过期前30天自动触发续期流程，确保证书持续有效
• 多验证方式支持：兼容HTTP-01（Web服务器文件验证）、DNS-01（DNS记录验证）等多种域名所有权验证方式
• 轻量级设计：基于官方Python/Alpine基础镜像构建，镜像体积小，资源占用低，适合容器化部署
• 跨平台兼容：支持Linux、macOS及Windows（WSL2）等Docker环境，可与Nginx、Apache等主流Web服务器配合使用

使用场景

• Web服务器SSL配置：为Nginx、Apache等Web服务器快速配置HTTPS，通过挂载证书目录实现容器间证书共享
• 自动化证书管理：在CI/CD流程或容器编排平台（Kubernetes、Docker Swarm）中集成，实现证书的自动化部署与续期
• Docker环境证书部署：在Docker Compose或多容器架构中，作为独立服务统一管理所有容器的SSL证书
• 开发/测试环境：在非生产环境中快速获取测试证书，验证HTTPS配置有效性

使用方法与配置说明

基本使用（docker run命令示例）

1. HTTP-01验证获取证书（适用于可公开访问的Web服务）

需临时暴露80端口，让Let's Encrypt服务器访问验证文件：

bash
docker run -it --rm \
  -v "/etc/letsencrypt:/etc/letsencrypt" \
  -v "/var/www/html:/var/www/html" \
  -p 80:80 \
  docker.xuanyuan.run/certbot/certbot certonly \
  --webroot \
  --webroot-path=/var/www/html \
  --email your@email.com \
  --agree-tos \
  --no-eff-email \
  -d example.com \
  -d www.example.com

2. DNS-01验证获取通配符证书（适用于无法暴露80端口的场景）

需手动添加DNS TXT记录完成域名验证：

bash
docker run -it --rm \
  -v "/etc/letsencrypt:/etc/letsencrypt" \
  docker.xuanyuan.run/certbot/certbot certonly \
  --manual \
  --preferred-challenges dns \
  --email your@email.com \
  --agree-tos \
  -d "*.example.com" \
  -d example.com

3. 证书续期

bash
docker run -it --rm \
  -v "/etc/letsencrypt:/etc/letsencrypt" \
  docker.xuanyuan.run/certbot/certbot renew

Docker Compose配置示例

yaml
version: '3'
services:
  certbot:
    image: docker.xuanyuan.run/certbot/certbot
    volumes:
      - ./letsencrypt:/etc/letsencrypt  # 持久化存储证书
      - ./webroot:/var/www/html         # Web根目录（用于HTTP验证）
    ports:
      - "80:80"                         # 暴露80端口用于验证
    command: certonly \
      --webroot \
      --webroot-path=/var/www/html \
      --email your@email.com \
      --agree-tos \
      --no-eff-email \
      -d example.com \
      -d www.example.com

核心配置参数说明

证书存储路径

证书默认存储在/etc/letsencrypt/live/<domain>/目录下，核心文件包括：

• fullchain.pem: 完整证书链（服务器证书+中间CA证书）
• privkey.pem: 私钥文件（需严格保护）
• cert.pem: 服务器证书
• chain.pem: 中间CA证书

注意事项

• 持久化存储：务必通过-v参数将/etc/letsencrypt目录挂载到本地存储，避免容器删除导致证书丢失
• 权限管理：证书目录权限建议设置为0700，私钥文件权限设置为0600，防止未授权访问
• 自动续期配置：生产环境建议通过crontab或Docker健康检查配置自动续期任务（如每日执行certbot renew）
• 防火墙配置：HTTP-01验证需确保80端口可从公网访问（Let's Encrypt验证服务器需访问http://<domain>/.well-known/acme-challenge/路径）
• 测试环境：首次配置建议使用--dry-run参数测试，避免因配置错误触发Let's Encrypt的请求频率限制