个人技术文档

这里记录个人在搭建与维护自有服务过程中沉淀的配置与排查笔记， 内容偏运维侧：反向代理、容器编排、内网穿透、证书管理。 全部为本人实践总结，仅作技术备忘与学习参考，不提供任何对外服务。

一、Nginx 反向代理的两个易错点

add_header 默认只在 2xx/3xx 响应上生效。若接口可能返回 413、502，必须补 always，否则错误响应不带 CORS 头， 前端读不到响应体，表现为原因不明的网络错误，排查成本很高。

add_header Access-Control-Allow-Origin "https://example.com" always;
add_header Vary Origin always;

另一个是上传体积。client_max_body_size 默认 1m， 音频、图片一类请求很容易超限，典型症状是「小文件正常、大文件全失败」， 容易被误判成偶发 bug。按实际峰值放宽即可。

二、HTTP/2 指令的版本差异

独立的 http2 on; 指令要 nginx 1.25.1 及以上版本。 旧镜像（如部分 nginx:alpine 标签）不认识它， 会直接报 unknown directive 导致容器起不来。 兼容写法把它作为 listen 参数，新版本仅打一条弃用警告：

listen 443 ssl http2;

三、证书链不全的典型表现

只部署服务器证书、漏掉中间证书时，桌面浏览器往往正常 （本地缓存过中间证书），移动端与内置 WebView 则直接握手失败。 curl 测试通过不代表手机能用，部署前确认链完整：

openssl s_client -connect example.com:443 -showcerts </dev/null

同时留意有效期，到期前安排续签，避免服务整体不可用。

四、内网穿透的带宽认知

一个常见误解是「用了 proxy_pass 转发，流量就不经过这台机器」。 实际上转发意味着它先完整收下再完整发出，同一份数据占用双倍带宽， 延迟还受其上行速度制约。网关部署在哪台机器，和数据经过哪台机器， 是两件需要分开判断的事。

五、容器化部署备忘

• network_mode: host 下容器内 127.0.0.1 即宿主回环，可直接访问宿主端口，也因此无需 ports 映射；
• 证书、密钥一律以只读方式挂载，私钥权限收紧到 600；
• 仅对外暴露确实需要的端口，内部通信走回环，减少暴露面；
• 改完配置先 nginx -t 校验，再 reload，避免线上中断。

六、排查顺序

遇到问题按「由外到内」逐层确认，比凭感觉改配置快得多： DNS 能否解析 → 端口是否放行 → TLS 握手是否成功 → HTTP 状态码落在哪一层 → 应用日志。 多数故障在前两步就能定位。