如何使用Nginx反向代理为API接口添加SSL证书？

如何使用Nginx反向代理为API接口添加SSL证书？

如果 API 服务运行在 8080、8000 或 3000 等 HTTP 端口，并不需要为了支持 HTTPS 而修改后端程序。比较常见的做法是在 API 前面增加 Nginx，由 Nginx 负责 443 端口和 SSL/TLS 连接，再把请求转发给后端 API。

例如：

客户端
   ↓ HTTPS :443
Nginx
   ↓ HTTP :8080
API服务

这样证书只需要部署在 Nginx 上，Node.js、Java、Python、Go 等后端程序继续监听原来的 HTTP 端口即可。

如果 API 服务已经可以正常通过 HTTP 访问，下面直接从 Nginx 的 HTTPS 配置开始。

一、配置前先确认这几个条件

开始配置之前，先确认四件事：

第一，API 域名已经解析到 Nginx 服务器。

例如准备使用：

api.example.com

那么 api.example.com 的 DNS 记录需要指向 Nginx 所在服务器。

第二，SSL 证书已经签发。

Nginx 一般使用证书文件和私钥文件，例如：

api.example.com.crt
api.example.com.key

如果 CA 提供的是完整证书链，证书文件应包含服务器证书和中间证书。

第三，Nginx 已经安装。

可以执行：

nginx -V

检查 Nginx 是否正常安装。

第四，后端 API 可以正常访问。

例如后端程序运行在：

127.0.0.1:8080

可以先在服务器上测试：

curl http://127.0.0.1:8080

如果这里都访问不了，先解决后端服务问题，再配置 Nginx。

二、把SSL证书配置到Nginx

假设证书文件放在：

/etc/nginx/cert/

目录下：

/etc/nginx/cert/api.example.com.crt
/etc/nginx/cert/api.example.com.key

然后创建 API 对应的 Nginx 配置，例如：

/etc/nginx/conf.d/api.conf

配置 HTTPS：

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

    ssl_certificate /etc/nginx/cert/api.example.com.crt;
    ssl_certificate_key /etc/nginx/cert/api.example.com.key;

    ssl_protocols TLSv1.2 TLSv1.3;

    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;

        proxy_connect_timeout 60s;
        proxy_read_timeout 60s;
        proxy_send_timeout 60s;
    }
}

这里有几个配置需要特别注意。

ssl_certificate 指向服务器证书，ssl_certificate_key 指向对应私钥。​证书和私钥必须是一对​，否则 Nginx 在启动或重新加载配置时会报错。

proxy_pass 则决定 HTTPS 请求最终转发到哪里。

例如：

proxy_pass http://127.0.0.1:8080;

表示：

https://api.example.com/user
        ↓
Nginx
        ↓
http://127.0.0.1:8080/user

后端并不知道客户端是通过 HTTPS 还是 HTTP 访问的，因此需要通过：

proxy_set_header X-Forwarded-Proto $scheme;

把原始请求协议传递给后端。

这一点对 Spring Boot、Node.js 等应用比较重要，否则应用生成回调地址、重定向地址时，可能错误地生成 http://。

三、先检查 Nginx 配置，再重新加载

不要修改完配置直接重启 Nginx。

先执行：

nginx -t

看到：

syntax is ok
test is successful

再重新加载：

nginx -s reload

或者根据服务器安装方式执行对应的 systemd 命令：

systemctl reload nginx

然后直接访问：

https://api.example.com

先确认 SSL 证书是否正确，再检查 API 返回结果。

如果浏览器提示证书错误，先不要排查后端 API。此时问题还在 Nginx 的 HTTPS 层。

如果 HTTPS 已经正常，但返回：

502 Bad Gateway

再去检查后端服务。

关于证书部署和常见 HTTPS 错误，也可以参考 SSL证书安装与部署 和 如何修复SSL证书错误？。

四、API的HTTP请求要不要跳转HTTPS？

如果 API 同时开放了 80 端口，可以配置 HTTP 跳转：

server {
    listen 80;
    server_name api.example.com;

    return 301 https://$host$request_uri;
}

这样访问：

http://api.example.com/test

就会跳转到：

https://api.example.com/test

不过，对于 API 接口，有一点需要特别注意：

不要依赖 HTTP → HTTPS 的 301 作为客户端正常调用 API 的主要方式。

浏览器访问网页时，301 跳转很常见，但 API 的 POST、PUT、DELETE 请求涉及请求体和客户端实现，不同 HTTP 客户端对重定向的处理并不完全一致。

因此，正式环境最好直接让前端、APP、小程序或其他调用方使用：

https://api.example.com

而不是先访问 HTTP 再等待服务器跳转。

五、API跨域时，Nginx怎么配置CORS？

如果网站和 API 使用不同域名，例如：

https://www.example.com
https://api.example.com

浏览器会执行跨域检查。

可以由后端处理 CORS，也可以在 Nginx 层统一处理。

例如：

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;

    add_header Access-Control-Allow-Origin "https://www.example.com" always;
    add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
    add_header Access-Control-Allow-Headers "Content-Type, Authorization" always;

    if ($request_method = OPTIONS) {
        return 204;
    }
}

这里不要为了省事直接使用：

Access-Control-Allow-Origin: *

如果 API 涉及 Cookie、登录状态或其他凭证，应明确指定允许访问的 Origin，而不是允许所有网站调用。

六、API使用 WebSocket，HTTPS后还需要改什么？

如果 API 中还使用 WebSocket，例如：

ws://api.example.com/ws/

启用 HTTPS 后，对外应该使用：

wss://api.example.com/ws/

Nginx 需要增加 WebSocket 协议升级配置：

location /ws/ {
    proxy_pass http://127.0.0.1:8080;

    proxy_http_version 1.1;

    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    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;
}

如果普通 HTTPS API 可以访问，但 WebSocket 一直连接失败，重点检查 Upgrade、Connection 以及后端 WebSocket 路径是否一致。

七、Nginx配置完成后，遇到这些错误怎么查？

1. HTTPS 可以打开，但 API 返回 502

这时候 SSL 证书大概率已经工作了。

重点检查：

proxy_pass http://127.0.0.1:8080;

对应的 8080 服务是否正常。

可以直接执行：

curl http://127.0.0.1:8080

如果这里也无法访问，就应该检查后端程序，而不是继续修改 SSL 配置。

如果后端运行在另一台服务器，还需要检查服务器之间的网络、防火墙以及安全组。

2. 浏览器提示证书不受信任

先检查 Nginx 使用的是否是正确证书：

ssl_certificate /etc/nginx/cert/api.example.com.crt;

然后确认：

• 证书是否包含 api.example.com
• 证书是否已经过期
• 证书链是否完整
• Nginx 是否加载了最新证书

如果刚刚更换证书，需要执行：

nginx -t
nginx -s reload

仅仅把新证书文件上传到服务器，并不会让已经运行的 Nginx 自动读取新证书。

3. HTTPS 已经正常，但后端认为请求是 HTTP

检查：

proxy_set_header X-Forwarded-Proto $scheme;

同时确认后端框架是否正确读取 X-Forwarded-Proto。

这类问题经常出现在登录回调、OAuth、支付回调以及应用生成绝对 URL 的场景。

4. WebSocket 连接不上

检查是否配置：

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

同时确认客户端已经从：

ws://

改成：

wss://

常见问题 FAQ

Q：后端 API 还需要再安装一张 SSL 证书吗？

如果 Nginx 和 API 在同一台服务器，并且 API 只监听 127.0.0.1:8080，一般不需要。公网客户端到 Nginx 这一段已经使用 HTTPS。

如果 Nginx 和 API 分布在不同服务器之间，而且中间网络并不完全可信，则需要根据实际网络环境考虑 Nginx 到后端是否也使用 HTTPS。

Q：API 使用 HTTPS 后，后端端口 8080 还需要开放公网吗？

不需要。

如果 API 只供 Nginx 调用，可以让后端只监听：

127.0.0.1:8080

或者通过防火墙限制 8080 只允许 Nginx 所在服务器访问。

公网只开放：

443

这样比直接把 8080 暴露在公网更容易管理。

Q：修改 SSL 证书后为什么 API 还是显示旧证书？

最常见的原因是 Nginx 没有重新加载配置。

检查证书文件后执行：

nginx -t
nginx -s reload

如果前面还有 CDN、WAF 或负载均衡，则还需要检查这些节点是否仍然使用旧证书。

Q：通配符 SSL 证书可以给 API 使用吗？

可以。

例如证书覆盖：

*.example.com

那么：

api.example.com
www.example.com
m.example.com

都可以使用这张证书。

但 *.example.com 一般不能覆盖：

api.test.example.com

因此购买证书时要根据实际 API 域名层级选择单域名、多域名或通配符证书。

Q：Nginx反向代理 HTTPS 后，后端还需要修改代码吗？

多数情况下不需要修改业务代码。

Nginx 负责 TLS 连接和请求转发，后端继续监听 HTTP 即可。但如果应用需要判断原始请求是否 HTTPS，就需要正确处理：

X-Forwarded-Proto

否则可能出现 HTTPS 页面生成 HTTP 回调地址、登录重定向异常等问题。