jonasal/nginx-certbot

docker-nginx-certbot 镜像文档

镜像概述

docker-nginx-certbot 是一个集成了 Nginx 和 Certbot 的 Docker 镜像，旨在简化 HTTPS 部署流程。该镜像实现了自动化获取、配置和续期 Let's Encrypt SSL 证书，无需手动干预证书管理，让用户能够快速搭建支持 HTTPS 的 Web 服务。

核心功能与特性

• 自动化证书管理：自动向 Let's Encrypt 申请 SSL 证书，无需手动执行 Certbot 命令
• 证书自动续期：内置定时任务，在证书过期前自动续期，确保服务持续使用有效证书
• Nginx 无缝集成：预配置 Nginx 与 Certbot 协作，证书获取后自动应用到 Nginx 配置
• 多域名支持：支持为单个服务配置多个域名，一次性申请多域名证书
• 轻量级设计：基于官方 Nginx 镜像构建，保持精简的镜像体积
• 灵活配置：支持自定义 Nginx 配置文件、证书存储路径及 Certbot 参数

使用场景与适用范围

• 个人博客/网站：快速为个人站点部署 HTTPS，提升安全性
• 小型企业服务：简化企业官网、内部系统的 HTTPS 配置流程
• 开发测试环境：在开发阶段快速模拟生产环境的 HTTPS 配置
• 临时项目：短期项目需要快速上线并支持 HTTPS 时的理想选择
• 资源受限环境：适合服务器资源有限，需要自动化减少维护成本的场景

使用方法与配置说明

基本部署（docker run）

首次启动（申请证书）

bash
docker run -d \
  --name nginx-certbot \
  -p 80:80 \
  -p 443:443 \
  -e "DOMAINS=example.com www.example.com" \
  -e "EMAIL=admin@example.com" \
  -v ./nginx/conf.d:/etc/nginx/conf.d \
  -v ./certbot/conf:/etc/letsencrypt \
  -v ./certbot/www:/var/www/certbot \
  jonasal/nginx-certbot

参数说明：

• -p 80:80：映射 HTTP 端口（Let's Encrypt 验证需通过 80 端口）
• -p 443:443：映射 HTTPS 端口
• -e "DOMAINS=..."：指定需要申请证书的域名，多个域名用空格分隔
• -e "EMAIL=..."：Let's Encrypt 注册***（用于证书过期通知及恢复）
• 卷挂载：
  • ./nginx/conf.d：本地 Nginx 配置目录，映射到容器内 /etc/nginx/conf.d
  • ./certbot/conf：本地证书存储目录，映射到容器内 /etc/letsencrypt（持久化证书）
  • ./certbot/www：Let's Encrypt 验证文件目录，映射到容器内 /var/www/certbot

Docker Compose 部署

创建 docker-compose.yml 文件：

yaml
version: '3'

services:
  nginx-certbot:
    image: jonasal/nginx-certbot
    container_name: nginx-certbot
    ports:
      - "80:80"
      - "443:443"
    environment:
      - DOMAINS=example.com www.example.com
      - EMAIL=admin@example.com
      - STAGING=0  # 1 启用测试环境（避免 Let's Encrypt 速率限制），0 禁用
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d
      - ./certbot/conf:/etc/letsencrypt
      - ./certbot/www:/var/www/certbot
    restart: unless-stopped

启动服务：

bash
docker-compose up -d

环境变量配置

目录结构与卷挂载

推荐本地目录结构

./
├── docker-compose.yml
├── nginx/
│   └── conf.d/          # Nginx 站点配置目录（需手动创建）
│       └── example.conf # 自定义站点配置文件
└── certbot/
    ├── conf/            # 证书存储目录（自动生成）
    └── www/             # Let's Encrypt 验证文件目录（自动生成）

卷挂载说明

• ./nginx/conf.d:/etc/nginx/conf.d：挂载自定义 Nginx 站点配置，需提前创建并添加站点配置文件（示例见下文）
• ./certbot/conf:/etc/letsencrypt：持久化存储 Let's Encrypt 证书文件，避免容器重建后证书丢失
• ./certbot/www:/var/www/certbot：Let's Encrypt ACME 验证文件存放目录，用于域名所有权验证

示例配置

Nginx 站点配置示例（./nginx/conf.d/example.conf）

nginx
server {
    listen 80;
    server_name example.com www.example.com;

    # 将 HTTP 请求重定向到 HTTPS
    location / {
        return 301 https://$host$request_uri;
    }

    # Let's Encrypt 验证文件访问路径
    location /.well-known/acme-challenge/ {
        root /var/www/certbot;
    }
}

server {
    listen 443 ssl;
    server_name example.com www.example.com;

    # SSL 证书配置（证书由 Certbot 自动生成，路径固定）
    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    
    # 推荐的 SSL 安全配置（可选）
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # 网站根目录（根据实际需求修改）
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

多域名支持示例

若需为多个独立域名配置证书，可在 DOMAINS 中指定多个域名（空格分隔），并为每个域名创建对应的 Nginx 配置文件。例如：

yaml
environment:
  - DOMAINS=example.com www.example.com blog.example.com

证书管理

证书申请流程

1. 容器启动后，Certbot 会自动检查 DOMAINS 中指定的域名
2. 若证书不存在，自动向 Let's Encrypt 发起申请，通过 HTTP-01 验证（利用 /.well-known/acme-challenge/ 路径）
3. 验证通过后，证书保存至 /etc/letsencrypt/live/<主域名>/ 目录
4. Nginx 自动加载证书，服务开始提供 HTTPS 访问

证书续期机制

• 容器内置定时任务（cron），每日检查证书过期时间
• 当证书剩余有效期小于 RENEW_BEFORE 天数（默认 30 天）时，自动执行续期操作
• 续期完成后，Nginx 会自动 reload 配置，应用新证书

注意事项

• 端口占用：确保主机的 80 和 443 端口未被其他服务占用，否则 Let's Encrypt 验证会失败
• 域名解析：申请证书前需确保 DOMAINS 中指定的域名已正确解析至主机 IP
• 速率限制：Let's Encrypt 对证书申请有速率限制，测试环境（STAGING=1）可避免触发限制
• 配置修改：修改 Nginx 配置后，需重启容器或执行 docker exec nginx-certbot nginx -s reload 使配置生效
• 数据备份：定期备份 ./certbot/conf 目录，防止证书文件丢失导致服务中断