nginx Roadmap
Nginx / HTTPS 专题
Nginx / HTTPS 排障专题：聚合 502 Bad Gateway、upstream timed out、反向代理 proxy_pass、SSL 证书过期与 fullchain、WebSocket Upgrade、client_max_body_size 413 等常见问题的完整排障流程。
Nginx 故障重点看 error.log 具体错误、upstream 后端可达性、证书链是否完整以及 nginx -s reload 是否真正生效，改配置前必先 nginx -t 校验语法并保留旧文件，避免线上服务中断。
Troubleshooting Path
推荐排障路线图
- 01
先确认配置语法和加载状态
执行 nginx -t、systemctl status nginx，确认当前配置是否真的被加载。
- 02
再看 access.log 和 error.log
用日志判断是 upstream 连接失败、超时、请求体过大还是证书问题。
- 03
继续验证 upstream 可达性
从 Nginx 所在机器 curl 后端地址，区分应用挂了、端口错了还是网络不通。
- 04
最后处理 HTTPS、WebSocket 和路径转发
核对 fullchain、proxy_set_header、Upgrade、proxy_pass 尾斜杠和 client_max_body_size。
Common Issues
高频问题入口
Before You Change
执行前检查
- 上线前必须 nginx -t
- reload 前保留旧配置
- 证书更新后确认 fullchain 路径
- 502 先查 upstream 再改 Nginx 参数
Start Here
优先阅读
Certbot 证书自动续期失败排查
Certbot 自动续期 Let's Encrypt 证书失败时，用 certbot renew --dry-run 复现真实错误，覆盖 80 端口 HTTP-01 验证不通、Nginx 未放行 .well-known/acme-challenge、DNS TXT 记录未生效和 certbot.timer 未触发等常见根因。
排障Git 保存用户名密码的正确方式
Git 通过 HTTPS 拉代码每次都要输入用户名密码时，配置 credential.helper 选择 store 明文、cache 内存缓存或 Windows 下的 manager 加密存储，SSH 仓库改用密钥认证，避免把密码明文写在 remote URL 里。
排障Nginx 301/302 跳转配置与常见问题
Nginx 配置 HTTP→HTTPS、旧域名迁移或路径重写时，用 return 301 https://example.com$request_uri 做永久跳转、302 做临时跳转，避免 rewrite + if 组合，配合 curl -I -L 验证 Location 头，跳转循环则检查 server 块之间是否互指。
排障Nginx 504 Gateway Timeout 排查方法
Nginx 返回 504 Gateway Timeout 时，error.log 会打印 upstream timed out (110: Connection timed out)，先测后端接口真实响应时间区分偶发/持续超时，再决定是优化后端慢查询/依赖阻塞还是调整 proxy_read_timeout 与 proxy_send_timeout。
Tools
相关工具
Cheatsheets
相关速查表
Nginx 配置与命令速查表
Nginx 配置与命令一页速查：nginx -t/-s reload/-T 语法测试与重载、location 匹配优先级、proxy_pass 反向代理片段与超时上传限制、access/error 日志排查，改配置和查 502/413 时直接对照。
速查OpenSSL 证书与加密速查表
OpenSSL 常用命令一页速查：证书查看与生成、CSR 和自签名证书、私钥处理、TLS 连接测试和常见加密操作等 30+ 高频操作，含参数说明与典型排障场景示例。
速查HTTP 状态码速查表
HTTP 状态码一页速查：1xx 信息、2xx 成功、3xx 重定向、4xx 客户端错误、5xx 服务端错误的完整列表，含含义说明和常见排障场景，适合接口调试和 Nginx 排障。
Latest Updates
最近更新
All Runbooks
全部相关内容
Certbot 证书自动续期失败排查
Certbot 自动续期 Let's Encrypt 证书失败时，用 certbot renew --dry-run 复现真实错误，覆盖 80 端口 HTTP-01 验证不通、Nginx 未放行 .well-known/acme-challenge、DNS TXT 记录未生效和 certbot.timer 未触发等常见根因。
排障curl 使用代理连接超时排查
curl -x 通过 HTTP/SOCKS5 代理访问超时或 Failed to connect to proxy 时，用 curl -v 定位卡在代理还是目标站，区分 http 与 socks5/socks5h 协议、代理端 DNS 解析和 NO_PROXY 环境变量是否排除了目标域名。
排障Git 保存用户名密码的正确方式
Git 通过 HTTPS 拉代码每次都要输入用户名密码时，配置 credential.helper 选择 store 明文、cache 内存缓存或 Windows 下的 manager 加密存储，SSH 仓库改用密钥认证，避免把密码明文写在 remote URL 里。
排障Git SSL certificate problem 解决方法
Git clone/pull 报 SSL certificate problem: unable to get local issuer certificate 时，用 GIT_CURL_VERBOSE=1 打印真实证书链，确认是否走了公司代理，把代理 CA 加入 http.sslCAInfo 或系统信任，避免直接关闭 sslVerify。
排障Kubernetes Ingress 404/502 排查流程
Kubernetes Ingress 返回 404 或 502 时，用 curl -H Host 精确复现路由，再 kubectl describe ingress 检查 rules/pathType/IngressClass，404 多为 host 或 path 没命中，502 多为 Service Endpoints 为空或 targetPort、Pod readiness 有问题。
排障Nginx 301/302 跳转配置与常见问题
Nginx 配置 HTTP→HTTPS、旧域名迁移或路径重写时，用 return 301 https://example.com$request_uri 做永久跳转、302 做临时跳转，避免 rewrite + if 组合，配合 curl -I -L 验证 Location 头，跳转循环则检查 server 块之间是否互指。
排障Nginx 413 Request Entity Too Large 排查方法
上传大文件被 Nginx 返回 413 Request Entity Too Large 时，先确认错误页来自 Nginx、Ingress、CDN 还是后端框架，再用 nginx -T | grep client_max_body_size 检查是否被更近的 location 覆盖，逐层统一 http/server/location 的 body size 限制。
排障Nginx 502 Bad Gateway 排查方法
按 upstream 连接、端口监听、防火墙规则、proxy_timeout 超时和 error.log 日志顺序排查 Nginx 502 Bad Gateway，覆盖 Connection refused、upstream timed out 和 no live upstreams 等常见错误。
排障Nginx 504 Gateway Timeout 排查方法
Nginx 返回 504 Gateway Timeout 时，error.log 会打印 upstream timed out (110: Connection timed out)，先测后端接口真实响应时间区分偶发/持续超时，再决定是优化后端慢查询/依赖阻塞还是调整 proxy_read_timeout 与 proxy_send_timeout。
排障HTTPS 混合内容(Mixed Content)排查
HTTPS 页面加载 http:// 资源被浏览器提示 Mixed Content blocked 时，用 F12 Console 定位被阻止的 script/stylesheet/image，区分 active/passive 混合内容并逐个改成 https 或相对协议，也可在 Nginx 加 CSP upgrade-insecure-requests 兜底。
排障Nginx HTTPS 证书过期与链不完整排查
浏览器提示 NET::ERR_CERT_DATE_INVALID、curl 返回 SSL certificate problem: certificate has expired 时，用 openssl s_client -connect 查线上实际证书 dates，再对比服务器文件、确认 ssl_certificate 指向 fullchain.pem 且 certbot 续期后 reload 了 Nginx。
排障Nginx 反向代理 WebSocket 配置与排障
Nginx 反向代理 WebSocket 出现 1006 异常关闭、连接建立后很快断开或收不到消息时，必须设置 proxy_http_version 1.1、透传 Upgrade 与 Connection: upgrade 头，并调大 proxy_read_timeout 让长连接不被 60s idle 超时断开，握手成功会返回 101。
命令Git 配置和取消代理命令
Git 配置和取消 HTTP/HTTPS/SOCKS5 代理的常用命令，git config --show-origin --get-regexp proxy 找出代理配置来自 system/global/local 哪一级，http.proxy 只影响 HTTP 仓库，SSH 仓库需要单独配置 ssh ProxyCommand 或 IdentityFile。
命令Nginx 限流配置命令
Nginx 常用限流配置命令，limit_req_zone 在 http 块定义速率与共享内存，limit_req 在 location 启用并配合 burst/nodelay 控制突发，limit_conn 限制单 IP 并发连接数，limit_rate 限制响应带宽，配合 geo/map 实现 IP 白名单豁免。
命令Nginx 测试配置与平滑重载命令
Nginx 修改配置后安全上线的标准命令，先 nginx -t 校验语法、nginx -T 查看最终合并配置，再 systemctl reload nginx 平滑加载新配置（reload 失败会保留旧配置），最后 tail error.log 检查启动错误，避免直接 restart。
命令openssl 检查 HTTPS 证书命令
openssl s_client 检查线上 HTTPS 证书的常用命令，openssl s_client -connect example.com:443 -servername 触发 SNI 拿到真实证书，用 openssl x509 -noout -dates -issuer -subject 提取有效期与颁发者，-showcerts 查看完整证书链。