Let's Encrypt (webroot) Docker镜像

!Let's Encrypt Logo

基于letsencrypt基础镜像构建的Let's Encrypt证书自动获取与续期工具，通过webroot验证方式管理SSL证书。

• GitHub
• DockerHub

镜像概述与主要用途

本镜像提供了一种简单高效的方式，通过Let's Encrypt自动获取和续期SSL证书，采用webroot验证方式（即通过Web服务器的特定目录进行域名所有权验证）。适用于需要为Web服务（如Nginx、Apache等）配置HTTPS且希望自动管理证书生命周期的场景，避免手动操作证书续期的繁琐流程。

核心功能与特性

• 自动证书管理：自动完成证书的获取、续期流程，无需人工干预
• webroot验证：通过Web服务器的指定目录进行域名验证，兼容各类Web服务
• 续期钩子机制：支持配置证书续期后的触发动作（如重载Nginx配置、重启服务容器）
• 灵活的权限控制：可自定义证书文件的所有者和权限
• 单次运行模式：支持仅执行一次证书更新后退出容器，适用于定时任务场景
• 完整证书链支持：提供私钥、证书、中间证书及完整证书链文件，满足不同服务需求

使用场景

• 需要为Nginx、Apache等Web服务器配置HTTPS证书的场景
• 希望自动处理Let's Encrypt证书90天续期周期的服务
• 需要在证书更新后自动通知并更新依赖服务配置的环境
• 容器化部署环境中统一管理SSL证书的需求

使用方法与配置说明

1. 配置Web服务器

首先需配置Web服务器，确保其能正确响应/.well-known/acme-challenge路径的请求。以Nginx为例，添加如下配置：

location '/.well-known/acme-challenge' {
    default_type "text/plain";  # 设置默认MIME类型为纯文本
    root        /tmp/letsencrypt;  # 指定验证文件存放目录（需与后续挂载路径一致）
}

2. 挂载必要卷

运行Web服务器容器时，需挂载两个卷以与letsencrypt-webroot容器共享：

-v /data/letsencrypt:/etc/letsencrypt  # 存储证书的持久化目录
-v /data/letsencrypt-www:/tmp/letsencrypt  # webroot验证目录（需与Web服务器配置的root一致）

3. 运行letsencrypt-webroot容器

执行以下命令启动证书管理容器，替换示例中的域名和邮箱：

docker run \
  --name some-letsencrypt \
  -v /data/letsencrypt:/etc/letsencrypt \  # 挂载证书存储目录
  -v /data/letsencrypt-www:/tmp/letsencrypt \  # 挂载webroot验证目录
  -e 'DOMAINS=example.com [***] \  # 需申请证书的域名（空格分隔多个域名）
  -e 'EMAIL=***' \  # 用于紧急通知和密钥恢复的邮箱
  -e 'WEBROOT_PATH=/tmp/letsencrypt' \  # webroot验证目录路径（需与Web服务器配置一致）
  kvaps/letsencrypt-webroot

4. 配置应用使用证书

证书生成后，应用可通过以下路径访问证书文件：

• 私钥：/etc/letsencrypt/live/example.com/privkey.pem
• 证书：/etc/letsencrypt/live/example.com/cert.pem
• 中间证书：/etc/letsencrypt/live/example.com/chain.pem
• 完整证书链（证书+中间证书）：/etc/letsencrypt/live/example.com/fullchain.pem

注意：必须完整挂载/etc/letsencrypt目录，不可仅挂载/etc/letsencrypt/live子目录，否则该目录下证书文件的符号链接将无法正常工作！

证书续期钩子（Renew Hook）

可配置证书续期后的触发动作（如重载服务配置），实现依赖服务的自动更新。

配置步骤：

1. 挂载Docker Socket：需将主机的Docker Socket挂载到容器，以允许操作其他容器：

   -v /var/run/docker.sock:/var/run/docker.sock
   

2. 链接目标容器：通过--link参数链接需要操作的服务容器（如Nginx）：

   --link some-nginx  # "some-nginx"为目标容器名称
   

3. 设置续期钩子环境变量：通过LE_RENEW_HOOK环境变量定义触发动作，支持以下示例：

   • 重载Nginx配置（发送HUP信号）：

     -e 'LE_RENEW_HOOK=docker kill -s HUP @CONTAINER_NAME@'
     

   • 重启目标容器：

     -e 'LE_RENEW_HOOK=docker restart @CONTAINER_NAME@'
     

   注：@CONTAINER_NAME@会自动替换为通过--link指定的容器名称。

Docker Compose配置示例

以下是结合Nginx和letsencrypt-webroot的完整Docker Compose配置示例：

docker-compose.yml

nginx:
  restart: always  # 容器退出时自动重启
  image: nginx  # 使用官方Nginx镜像
  hostname: example.com  # 主机名（需替换为实际域名）
  volumes:
    - /etc/localtime:/etc/localtime:ro  # 同步主机时间
    - ./nginx:/etc/nginx:ro  # 挂载本地Nginx配置（只读）
    - ./letsencrypt/conf:/etc/letsencrypt  # 共享证书目录
    - ./letsencrypt/html:/tmp/letsencrypt  # 共享webroot验证目录
  ports:
    - 80:80  # HTTP端口（用于证书验证）
    - 443:443  # HTTPS端口
  environment:
    - LE_RENEW_HOOK=docker kill -s HUP @CONTAINER_NAME@  # Nginx重载钩子（示例）

letsencrypt:
  restart: always  # 容器退出时自动重启
  image: kvaps/letsencrypt-webroot  # 当前letsencrypt镜像
  volumes:
    - /etc/localtime:/etc/localtime:ro  # 同步主机时间
    - /var/run/docker.sock:/var/run/docker.sock  # 挂载Docker Socket以操作其他容器
    - ./letsencrypt/conf:/etc/letsencrypt  # 证书存储目录（与Nginx共享）
    - ./letsencrypt/html:/tmp/letsencrypt  # webroot验证目录（与Nginx共享）
  links:
    - nginx  # 链接Nginx容器，用于续期钩子
  environment:
    - DOMAINS=example.com [***]  # 需申请证书的域名（空格分隔，替换为实际域名）
    - EMAIL=***  # 联系邮箱（替换为实际邮箱）
    - WEBROOT_PATH=/tmp/letsencrypt  # webroot验证目录（需与Nginx配置一致）
    - EXP_LIMIT=30  # 证书到期前30天开始尝试续期（默认值）
    - CHECK_FREQ=30  # 每30天检查一次证书状态（默认值）

单次运行模式（Once Run）

支持单次运行模式，即执行一次证书更新后立即退出容器，适用于通过外部定时任务（如Cron）触发的场景。只需在docker run命令末尾添加once参数：

docker run \
  --name some-letsencrypt \
  -v /data/letsencrypt:/etc/letsencrypt \
  -v /data/letsencrypt-www:/tmp/letsencrypt \
  -e 'DOMAINS=example.com [***] \
  -e 'EMAIL=***' \
  -e 'WEBROOT_PATH=/tmp/letsencrypt' \
  kvaps/letsencrypt-webroot \
  once  # 单次运行模式

环境变量配置说明