跳至主要內容

14 本地网关与研发入口工具

前端调用三个后端服务时，直接记住 3000、8081 和 9000 这些端口似乎最快。等 OAuth 回调、Secure Cookie、WebSocket 和跨域预检同时出现，随机端口就会把问题搅在一起：浏览器访问的是哪个域名，TLS 在哪里终止，/api 是否被剥离，客户端地址由谁确认，已经很难从应用日志里还原。

本地网关把这些变化收敛到一个稳定入口。读者要解决的不是“让代理进程启动”，而是让一次请求从域名解析、监听端口、TLS、路由、转发头、上游选择直到应用响应都有证据可查，并且在配置出错时能够恢复到上一份正常状态。

先走通一条最短任务路径

第一次接入本地网关，可以沿着同一条请求逐步增加能力：

  1. 直接访问后端健康接口，保存状态码和实例标识，先排除应用自身故障。
  2. 通过网关域名访问同一接口，确认 Host、输入路径、上游实际路径和 request ID。
  3. 给入口增加受信任的本地证书，最终验证不能依赖跳过证书检查。
  4. 增加第二个上游，观察请求分配，再停止一个实例验证被动失败处理。
  5. 分别验证 WebSocket、CORS、限流、缓存和灰度，避免用一个 200 代替所有协议证据。
  6. 注入错误端口、错误路径和错误证书，确认日志能指出故障所在层。
  7. 发布一份语法正确但路由错误的配置，再执行原子回滚和业务复验。

Nginx 本地入口 的 Compose 实验覆盖 HTTP、HTTPS、路径改写、WebSocket、限流、缓存、灰度、故障注入与回滚；CORS 的跨实现配置和浏览器验证集中在协议排障文章。其他工具沿用相同输入与证据字段，切换实现时仍按产品实际语义记录差异。

根据配置变化方式选择入口

固定域名、显式路径反代以及对 location、proxy_pass 行为的精确复现，优先使用 Nginx。它的规则稳定、资料丰富，代价是 URI 变化、转发头和 reload 后的业务语义都需要主动验证。

希望尽快得到可信本地 HTTPS，并由工具管理证书申请与续期时，可以使用 Caddy。团队仍要管理 internal CA 的分发范围、/data 持久化和自动行为的升级变化。

Compose 服务频繁增删，希望路由跟随 label 自动发现时，可以使用 Traefik。动态发现减少手工配置，同时把 Docker socket、Dashboard 和 label 变成需要审计的控制入口。

需要逐层观察 listener、route、cluster、filter、超时、重试或 xDS 行为时，可以使用 Envoy。更细的证据意味着更高的配置和控制面维护成本。

只需要给一个本地 HTTP 端口临时增加 HTTPS，可以使用 local-ssl-proxy。当需求出现多上游、身份认证、流量治理或共享环境发布时，应切换到具备配置校验、日志和回滚能力的入口。

路径剥离、重定向、Cookie Path、WebSocket 升级和 CORS 预检会跨越所有实现。路由重写、WebSocket 与 CORS 使用同一组请求比较不同代理的协议结果。

请求失败时沿链路找第一处异常

排障从后端直连开始，再向入口逐层推进。直连已经失败时，修改代理配置只会增加噪声；直连成功而代理返回 502，才继续检查容器 DNS、目标端口、网络和上游协议。代理状态码与上游状态码必须同时记录，否则无法区分“网关没有找到上游”和“应用自己返回错误”。

一份可用的入口证据至少能够回答：

  • 请求使用了哪个 Host、规范化后的 URI 和协议；查询参数默认不进入共享诊断日志。
  • 命中了哪条路由、选择了哪个上游、代理与上游分别返回什么状态。
  • 总耗时和上游耗时分别是多少，是否发生连接、TLS 或读取超时。
  • request ID 是否从入口传到应用，并能反向关联同一次调用。
  • WebSocket 是否得到 101 并完成真实消息往返，CORS 预检是否返回正确来源与方法。

看到 404 时先对比代理状态与上游状态；看到 502 时从代理所在网络直接访问上游；看到证书错误时检查 SAN、证书链、SNI 和客户端信任。每次修复都用原请求复验，不能用“进程仍在运行”作为恢复证据。

配置变更要经过可回退的两条路径

单实例共享环境采用“静态校验 → reload → 业务 smoke test → 故障注入 → 观察窗口”的顺序。任何业务检查失败，都立即恢复上一份已知正常配置，再次静态校验、reload，并用同一组 smoke test 证明恢复。

能够并行启动候选实例时，先在独立端口加载新配置，完成最小请求、WebSocket、CORS、限流、缓存、灰度和故障注入，再切换入口流量。旧实例保留到连接排空和观察窗口结束。WebSocket、SSE 和大上传可能让旧连接长期存在，不能只看新请求成功就删除旧实例。

配置仓库可以采用下面的结构，让路由、证书说明、验证脚本和回滚步骤一起评审：

gateway/
  README.md
  compose.yaml
  routes/
  certificates/
    README.md
  smoke/
    http.ps1
    websocket.ps1
    cors.ps1
  rollback.md

路由、证书、上游和管理面分别设置 owner，同一条规则只保留一个配置权威。管理端口只绑定本机或受控网络，不能公开 Dashboard、Admin API 或 Docker API。

证书目录只提交生成说明和占位文件。私钥、内部 CA 私钥、ACME 状态、Authorization、Cookie、真实域名和认证材料不能进入仓库、镜像层、label、截图或日志。访问日志不记录完整查询参数；完整配置导出和故障材料在共享前也要扫描静态认证头、内部地址和证书路径。

入口层能力要服从业务语义

应用常根据 X-Forwarded-For 判断来源，根据 X-Forwarded-Proto 生成回调 URL 和 Secure Cookie。只有明确的可信代理可以建立这些事实。直接信任客户端传入的转发头，会造成 IP 白名单绕过、错误跳转和审计失真。

剥离 /api 不只是修改字符串，还会影响重定向 Location、Cookie Path、OpenAPI server URL、静态资源、WebSocket 地址和签名校验。任何 rewrite 都要同时观察输入路径、上游实际路径和应用响应。

限流保护的是容量边界，不是身份认证；缓存改善的是可复用读取，不适合带 Authorization、用户 Cookie 或强实时一致性的响应；灰度路由控制的是版本流量，不得把客户端可伪造的标签当成授权。负载均衡也不等于健康管理，只有真实请求、外部探测、日志和指标共同证明节点可用。

当入口需要跨地域调度、WAF、全局证书、正式高可用、变更窗口、值班接管和容量告警时，责任已经进入生产流量平台与部署运维体系。本地实验仍然有价值，因为它提供了路由语义、故障模型和回滚证据，但不能代替生产运行机制。

跳到正文