本文档说明如何在 Linux 服务器上使用 Certbot 为 NGINX 自动申请、安装和续签 HTTPS 证书。

适用场景：

  • 域名已解析到服务器公网 IP

  • 服务器使用 NGINX 提供 Web 服务

  • 希望通过 Let's Encrypt + Certbot 自动管理证书

1. 原理说明

Let's Encrypt 是一个免费证书颁发机构Certbot 是官方推荐的自动化客户端。

对 NGINX 场景，常见有两种工作方式：

  • --nginx：Certbot 直接读取并修改 NGINX 配置，自动完成证书签发和 HTTPS 配置

  • --webroot：Certbot 不修改 NGINX 主配置，只通过网站根目录完成域名验证，适合对线上配置改动要求更严格的场景

如果服务器上 NGINX 配置较规范，优先推荐 --nginx 方式，因为部署最省事。

2. 前置条件

开始前需要满足以下条件：

  • 已有可访问的域名，例如 example.com

  • 域名 A 记录或 AAAA 记录已指向当前服务器

  • 服务器已开放 80 和 443 端口

  • NGINX 已安装并正常运行

  • 当前用户具备 sudo 权限

建议先确认以下内容：


sudo nginx -t

sudo systemctl status nginx

如果 NGINX 配置本身有错误，Certbot 通常也无法正常接管配置。

3. 安装 Certbot

不同发行版安装方式略有差异，以下为常见方式。

3.1 Ubuntu / Debian


sudo apt update

sudo apt install -y certbot python3-certbot-nginx

3.2 CentOS / Rocky / AlmaLinux

如果系统仓库中已有 Certbot，可直接安装：


sudo dnf install -y certbot python3-certbot-nginx

如果系统较旧，也可能需要通过 snap 或额外仓库安装，此时以系统官方文档为准。

3.3 验证安装


certbot --version

4. NGINX 基础配置要求

在申请证书前，建议先有一个可正常响应 80 端口的站点配置。

一个最小可用示例如下：


server {

    listen 80;

    server_name example.com www.example.com;




    root /var/www/html;

    index index.html index.htm;




    location / {

        try_files $uri $uri/ =404;

    }

}

配置完成后执行：


sudo nginx -t

sudo systemctl reload nginx

然后浏览器访问 http://example.com，确认网站可以正常打开。

5. 使用 Certbot 自动签发并写入 NGINX

这是最常用方式。

执行命令：


sudo certbot --nginx -d example.com -d www.example.com

执行过程中通常会要求：

  • 输入邮箱地址，用于接收证书到期提醒

  • 同意服务协议

  • 选择是否接收 EFF 邮件

  • 选择是否将 HTTP 自动跳转到 HTTPS

推荐选择自动跳转 HTTPS。

如果执行成功，Certbot 会自动完成以下动作：

  • 向 Let's Encrypt 申请证书

  • 将证书保存到系统目录

  • 修改 NGINX 配置，加入 ssl_certificate 和 ssl_certificate_key

  • 按需加入 80 -> 443 跳转配置

  • 自动重载 NGINX

6. 证书文件位置

成功申请后，证书通常位于：


/etc/letsencrypt/live/example.com/

常见文件说明：

  • fullchain.pem：完整证书链

  • privkey.pem：私钥文件

例如在 NGINX 中通常会使用：


ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;

ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

注意：不要随意修改 live 目录内的文件，也不要把私钥暴露给无关用户。

7. 自动续签说明

Let's Encrypt 证书默认有效期通常为 90 天，因此必须配置自动续签。

多数新版系统在安装 Certbot 后，会自动创建 systemd timer 或 cron 任务。可通过以下命令检查：


systemctl list-timers | grep certbot

也可以手动测试续签流程：


sudo certbot renew --dry-run

如果显示测试成功，说明自动续签链路基本正常。

8. 续签后自动重载 NGINX

很多情况下，Certbot 插件会在续签后自动处理 NGINX 重载。

如果希望显式指定，可使用 deploy hook：


sudo certbot renew --deploy-hook "systemctl reload nginx"

如果要做成固定配置，可在续签 hook 目录中放置脚本，例如：


/etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh

脚本内容示例：


#!/usr/bin/env bash

systemctl reload nginx

赋予执行权限：


sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh

9. 推荐的 HTTPS 配置示例

Certbot 自动写入后通常已经可用。如果需要手工核对，可参考如下结构：


server {

    listen 80;

    server_name example.com www.example.com;

    return 301 https://$host$request_uri;

}




server {

    listen 443 ssl http2;

    server_name example.com www.example.com;




    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;

    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;




    root /var/www/html;

    index index.html index.htm;




    location / {

        try_files $uri $uri/ =404;

    }

}

如果站点是反向代理服务，也可以写成：


server {

    listen 80;

    server_name example.com;

    return 301 https://$host$request_uri;

}




server {

    listen 443 ssl http2;

    server_name example.com;




    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;

    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;




    location / {

        proxy_pass http://127.0.0.1:8080;

        proxy_set_header Host $host;

        proxy_set_header X-Real-IP $remote_addr;

        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        proxy_set_header X-Forwarded-Proto $scheme;

    }

}

10. 使用 webroot 方式签发

如果不希望 Certbot 直接改 NGINX 配置，可以使用 webroot 模式。

先确保站点配置中存在验证目录映射，例如：


server {

    listen 80;

    server_name example.com;




    root /var/www/html;




    location /.well-known/acme-challenge/ {

        root /var/www/html;

    }

}

然后执行：


sudo certbot certonly --webroot -w /var/www/html -d example.com -d www.example.com

说明：

  • certonly 表示只申请证书，不改 NGINX 配置

  • -w /var/www/html 是验证文件写入目录

这种方式适合：

  • 线上 NGINX 配置由运维统一管理

  • 需要严格控制配置文件变更

  • 有多个复杂 server 块，不想让 Certbot 自动改动

11. 常见故障排查

11.1 域名解析错误

现象：

  • Certbot 提示无法验证域名

  • 提示连接超时或返回错误主机

排查方法：


dig example.com

ping example.com

确认域名是否已经解析到当前服务器公网 IP。

11.2 80 端口未放行

Let's Encrypt 在签发时通常需要通过 80 端口完成校验。

需要检查：

  • 云服务器安全组

  • 本机防火墙，例如 ufwfirewalld

  • 上游负载均衡是否放通 80

例如 Ubuntu ufw：


sudo ufw allow 80/tcp

sudo ufw allow 443/tcp

11.3 NGINX 配置冲突

现象：

  • 申请证书时报 nginx: configuration file test failed

  • 多个 server_name 冲突

  • 同一端口被重复配置但逻辑不一致

排查命令：


sudo nginx -t

sudo nginx -T

优先解决 NGINX 自身配置问题，再重新执行 Certbot。

11.4 证书申请频率限制

Let's Encrypt 有速率限制。

如果短时间内多次失败重试，可能触发限制。此时建议：

  • 先用 --dry-run 测试续签流程

  • 确认域名、端口、防火墙都正确后再正式申请

  • 避免脚本中无间隔重复申请

11.5 443 已启用但证书路径错误

现象：

  • NGINX 可以启动，但浏览器提示证书异常

  • NGINX 无法重载，提示证书文件不存在

排查：


sudo ls -l /etc/letsencrypt/live/example.com/

sudo nginx -t

确认 fullchain.pem 与 privkey.pem 路径是否写对。

12. 常用命令速查

查看已申请证书


sudo certbot certificates

为 NGINX 自动申请并部署证书


sudo certbot --nginx -d example.com -d www.example.com

仅测试续签


sudo certbot renew --dry-run

正式执行续签


sudo certbot renew

续签后重载 NGINX


sudo certbot renew --deploy-hook "systemctl reload nginx"

13. 推荐实施流程

建议按以下顺序实施：

  1. 配置域名解析到服务器公网 IP

  2. 确保 NGINX 在 80 端口可正常响应

  3. 执行 sudo nginx -t，先修复原有配置错误

  4. 安装 certbot 和 python3-certbot-nginx

  5. 执行 sudo certbot --nginx -d example.com -d www.example.com

  6. 执行 sudo certbot renew --dry-run 验证续签

  7. 检查系统是否已存在自动续签定时任务

14. 生产环境建议

在生产环境中，建议额外注意以下几点：

  • 证书私钥目录权限要收紧

  • NGINX 改动前先备份原配置

  • 申请前先确认域名和防火墙，避免触发频率限制

  • 如果前面有 CDN 或反向代理，确认验证流量能到达源站

  • 续签测试至少执行一次 dry-run

  • 监控 nginx 状态和证书有效期

15. 示例：完整安装流程

下面给出一个从零到可用的最小流程示例：


sudo apt update

sudo apt install -y nginx certbot python3-certbot-nginx

sudo nginx -t

sudo systemctl enable --now nginx

sudo certbot --nginx -d example.com -d www.example.com

sudo certbot renew --dry-run

执行完成后，可通过浏览器访问：

预期结果：

  • HTTP 自动跳转到 HTTPS

  • 浏览器证书显示正常

  • certbot renew --dry-run 测试通过

16. 总结

对于大多数单机 NGINX 站点，最省事的方法是直接使用：


sudo certbot --nginx -d example.com -d www.example.com

该方式能够自动完成：

  • 域名校验

  • 证书申请

  • NGINX HTTPS 配置写入

  • 后续续签流程接入

如果业务环境对 NGINX 配置改动非常敏感，则可改用 webroot 模式，只让 Certbot 负责签发证书，不直接修改站点配置。