Nginx 常用反向代理配置与 HTTPS 证书自动化部署备忘

在自建个人网站、部署后端 API 接口或微服务时，Nginx 作为反向代理网关几乎是标准底座。它既能接管 80/443 端口集中管理 TLS/SSL 证书，又能将不同的子路径分发给不同的本地服务端口（如 Node.js、Python FastAPI、Go 等）。本文记录一份经过生产检验的标准模板。

一、反向代理标准基础块（保留真实客户端 IP）

直接将所有 HTTP 请求转发给运行在 127.0.0.1:3000 的后端程序。务必配置 Host 与 X-Real-IP 头，否则后端日志记录的将全都是 127.0.0.1：

server {
    listen 80;
    server_name api.ucncn.cn;

    location / {
        proxy_pass http://127.0.0.1:3000;
        
        # 传递原始客户端真实信息
        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;

        # 超时设置
        proxy_connect_timeout 60s;
        proxy_read_timeout 60s;
    }
}

二、支持 WebSocket 长连接透传

现代 Web 经常使用 Socket.IO 或原生 WebSocket。Nginx 默认会把 HTTP 升级请求当成普通短连接断开，需要显式声明升级协议头：

location /ws/ {
    proxy_pass http://127.0.0.1:8080;
    
    # WebSocket 必须的 HTTP 升级声明
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    proxy_set_header Host $host;
    proxy_read_timeout 3600s; # 保持长连接一小时无数据不中断
}

三、结合 Certbot 自动化申请与续期 Let's Encrypt 证书

不用再每三个月手动登录云控制台下载替换证书。在 Ubuntu/Debian 上通过 Certbot 可以实现一键部署与定时自动续签：

# 1. 安装 snapd 及 certbot
sudo apt install snapd
sudo snap install core; sudo snap refresh core
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot

# 2. 自动检测 Nginx 配置并申请绑定域名证书
sudo certbot --nginx -d ucncn.cn -d www.ucncn.cn

# 3. 模拟测试自动续签任务（测试无报错即代表完全正常）
sudo certbot renew --dry-run

四、配置修改后的热生效操作

切忌盲目 nginx -s reload！每次改完配置文件后，先进行语法检查：

# 1. 语法正确性检查
sudo nginx -t

# 2. 输出 syntax is ok 后，平滑无缝重载
sudo nginx -s reload