跳到主要内容

0010 可信代理、路径规范化与快速关闭

  • 状态:已接受(2026-10-23)
  • 相关:ADR 0001、0006;设计文档 03 S01

背景​

M0 代码审查发现:server.trusted_proxies 写在配置模板里却没有实现,网关把每个请求都当作直连;路径未规范化就路由;关闭服务时长连接(SSE)与浏览器预连接拖慢关闭;前端端口被占用时网关会把流量转发给别的程序。

决策​

  • 新增 internal/platform/realip:只有连接对端在 trusted_proxies(IP 或 CIDR)内时才采信 X-Forwarded-For/-Proto/-Host;客户端 IP 取 X-Forwarded-For 中最右侧的非可信地址(最左侧是客户端自己声称的,可伪造)。默认不信任任何代理。网关据此重写发往前端的转发头,M1 的限流与审计也用它取客户端 IP。可热加载。
  • 网关路由前按 path.Clean 规范化(保留结尾斜杠),不一致则 308 跳转。
  • 关闭顺序:Shutdown 开始时关闭发布订阅(所有 SSE 流随之结束),并关闭尚未发出第一个请求的连接(net/http 否则会把它们当作活跃连接等 5 秒)。
  • 启动前端前检查端口;被占用(或配置为 0)时改用操作系统分配的空闲端口。
  • 前端子进程的生命周期绑定到 skinloom:Windows 用作业对象(KILL_ON_JOB_CLOSE),Linux 用 Pdeathsig;输出管道使用 WaitDelay,子孙进程占用管道不再阻塞崩溃检测。

影响​

  • 部署在 Nginx / CDN 后面时必须配置 trusted_proxies,否则前端看到的协议是 http、客户端 IP 是代理地址(安全的默认值)。文档的部署章节已说明。
  • macOS 暂无与作业对象等价的机制:主进程被强制结束时前端可能残留,但下次启动会自动换用空闲端口。