本文档说明如何在 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 权限

建议先确认以下内容：

```bash

sudo nginx -t

sudo systemctl status nginx

```

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

## 3. 安装 Certbot

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

### 3.1 Ubuntu / Debian

```bash

sudo apt update

sudo apt install -y certbot python3-certbot-nginx

```

### 3.2 CentOS / Rocky / AlmaLinux

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

```bash

sudo dnf install -y certbot python3-certbot-nginx

```

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

### 3.3 验证安装

```bash

certbot --version

```

## 4. NGINX 基础配置要求

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

一个最小可用示例如下：

```nginx

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;

}

}

```

配置完成后执行：

```bash

sudo nginx -t

sudo systemctl reload nginx

```

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

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

这是最常用方式。

执行命令：

```bash

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. 证书文件位置

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

```bash

/etc/letsencrypt/live/example.com/

```

常见文件说明：

- fullchain.pem：完整证书链

- privkey.pem：私钥文件

例如在 NGINX 中通常会使用：

```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 任务。可通过以下命令检查：

```bash

systemctl list-timers | grep certbot

```

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

```bash

sudo certbot renew --dry-run

```

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

## 8. 续签后自动重载 NGINX

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

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

```bash

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

```

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

```bash

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

```

脚本内容示例：

```bash

#!/usr/bin/env bash

systemctl reload nginx

```

赋予执行权限：

```bash

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

```

## 9. 推荐的 HTTPS 配置示例

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

```nginx

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;

}

}

```

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

```nginx

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 模式。

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

```nginx

server {

listen 80;

server_name example.com;

root /var/www/html;

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

root /var/www/html;

}

}

```

然后执行：

```bash

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 提示无法验证域名

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

排查方法：

```bash

dig example.com

ping example.com

```

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

### 11.2 80 端口未放行

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

需要检查：

- 云服务器安全组

- 本机防火墙，例如 ufwfirewalld

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

例如 Ubuntu ufw：

```bash

sudo ufw allow 80/tcp

sudo ufw allow 443/tcp

```

### 11.3 NGINX 配置冲突

现象：

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

- 多个 server_name 冲突

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

排查命令：

```bash

sudo nginx -t

sudo nginx -T

```

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

### 11.4 证书申请频率限制

Let's Encrypt 有速率限制。

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

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

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

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

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

现象：

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

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

排查：

```bash

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

sudo nginx -t

```

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

## 12. 常用命令速查

### 查看已申请证书

```bash

sudo certbot certificates

```

### 为 NGINX 自动申请并部署证书

```bash

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

```

### 仅测试续签

```bash

sudo certbot renew --dry-run

```

### 正式执行续签

```bash

sudo certbot renew

```

### 续签后重载 NGINX

```bash

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. 示例：完整安装流程

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

```bash

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://example.com

- https://example.com

预期结果：

- HTTP 自动跳转到 HTTPS

- 浏览器证书显示正常

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

## 16. 总结

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

```bash

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

```

该方式能够自动完成：

- 域名校验

- 证书申请

- NGINX HTTPS 配置写入

- 后续续签流程接入

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