跳转到正文

ADR 0025: server 不管理自己的对外地址

本文目录

Status: Accepted Date: 2026-09-27

Context

server 的对外地址(用户浏览器访问控制台的地址、装 agent 的安装命令里 --server 指向的地址、推理网关接入示例里的地址)曾经有好几个互相冲突的来源:设置页「访问入口」(access 设置,落库)、server.yaml 的 public_url / --public-url、按请求 Host / X-Forwarded-Host 推断(ADR 0012)、以及推断失败时按本机出口网卡兜底。反代改写或不改写 Host、TrustedProxies 有没有配、access 设置是否覆盖 public_url,四个来源叠加后行为很难预测;已经出过反代场景推断成内网地址、节点永远连不上的事故(见 ADR 0012 原文)。

根子问题是 server 没有可靠的办法知道「别人是怎么连到我的」:同一个 server 可能同时经域名、反代、NAT 端口转发和局域网直连被不同的人访问,这些地址互不相同,server 自己存一个或猜一个都注定在某些路径上是错的。

服务网络那一侧也有类似的问题:serving_source 要求用户显式声明网关连节点服务网络时用的本机源地址,但这本质上是路由表已经能决定的事,多一个配置项只是多一个配错的地方。

Decision

  1. server 不再存储、不再推断自己的对外地址:删除设置页「访问入口」卡片与 access 设置(GET/PUT /api/v1/settings/access)、server.yaml 的 public_url 键与 --public-url / GPUWORKS_PUBLIC_URL、按请求 Host/X-Forwarded-Host 推断地址的逻辑(resolvePublicURL 等)、推断失败时的本机出口网卡兜底,以及服务网络拨号的显式源地址配置 serving_source。
  2. 地址由拿到它的一方给出,而不是 server 算出来:
    • UI 里凡是要给出 server 地址的地方(添加节点、云厂商安装、API Key 页接入示例、Playground「查看代码」)一律用浏览器当前的 window.location.origin 预填,用户可以改成域名或反代地址;
    • API 侧(创建节点、SSH 纳管、云厂商安装)把这个地址作为必填字段 server_url 收进来,不再有任何隐式来源;缺失或不是不含账号/查询/片段的绝对 http(s) 地址直接 400,不做静默兜底;
    • /install.sh 本身不内置任何地址,只认安装命令里显式传的 --server;
    • server 自己发起的请求(评测的「从 server 发起」)用回环地址 http://127.0.0.1:<控制台端口>,因为这类请求就是 server 连自己,不存在「别人怎么连过来」的问题;没有绑定控制台端口时返回 503;
    • 服务网络拨号不再绑定源地址,交给本机路由表按目标选择出口网卡。
  3. 保留「监听地址」,但只表示这一件事:server 在本机绑定了哪些 IP:端口(加上常驻的 127.0.0.1)。谁用什么地址连过来——域名、反代、NAT 转发——完全是别人的选择,不影响也不依赖监听地址的值。

Consequences

  • API 调用方(UI、脚本、第三方集成)现在必须自己知道并传入正确的 server_url;不再有「不配置也能工作」的兜底路径,换来的是这个地址永远等于调用方实际打算用的那个地址,不会被 server 的猜测覆盖或搞错。
  • 装好的 agent 只认安装命令里烤进去的地址:改节点接入监听地址、换反代/域名后,已装节点不会自动跟着变,需要维护对应的转发或重装。
  • 旧的 server.yaml 里如果还带着 public_url / serving_source 键,启动时会被拒绝(未知配置键),需要手工删除后再启动。
  • ADR 0012 描述的三级解析(显式配置 > 请求 Host 推断 > 本机出口 IP 兜底)不再是当前行为,标记为被本 ADR 取代,原文保留供追溯。

Alternatives Considered

  • 保留三级解析,只是把「访问入口」和 public_url 合并成一处:不解决根子问题——请求 Host 在反代改写、SSH 端口转发、容器 NAT 等场景下依然可能既不是「浏览器看到的地址」也不是「agent 应该连的地址」,合并只是少一处配置,出错的方式不变。
  • server 探测多个候选地址后择优:没有可靠信号判断哪个候选对发起请求的这个人是可达的;不可达的地址被选中时,失败只会在节点安装之后才暴露,比现在的「必须显式给」更难定位。
  • 只删设置页「访问入口」,保留 public_url 按文件配置兜底:反代场景下这个值几乎总是配置时的内网地址,一旦换网段或迁移就必须记得手改,与「本机出口网卡兜底」犯的是同一类错误,只是换了一个配置入口。
  • ADR 0012(被本 ADR 取代):PublicURL 三级解析的原始决策与历次更新
  • ADR 0030:节点网络对象,服务网络角色的定义
  • 配置节点网络:监听地址与「别人怎么连过来」的操作说明
  • artifacts/archive/2026-09-27-server-address-cleanup/plan.md:本次改动的计划与验收记录

这篇文档有帮助吗?