架构决策记录
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
- server 不再存储、不再推断自己的对外地址:删除设置页「访问入口」卡片与
access设置(GET/PUT /api/v1/settings/access)、server.yaml的public_url键与--public-url/GPUWORKS_PUBLIC_URL、按请求Host/X-Forwarded-Host推断地址的逻辑(resolvePublicURL等)、推断失败时的本机出口网卡兜底,以及服务网络拨号的显式源地址配置serving_source。 - 地址由拿到它的一方给出,而不是 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; - 服务网络拨号不再绑定源地址,交给本机路由表按目标选择出口网卡。
- UI 里凡是要给出 server 地址的地方(添加节点、云厂商安装、API Key 页接入示例、Playground「查看代码」)一律用浏览器当前的
- 保留「监听地址」,但只表示这一件事: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按文件配置兜底:反代场景下这个值几乎总是配置时的内网地址,一旦换网段或迁移就必须记得手改,与「本机出口网卡兜底」犯的是同一类错误,只是换了一个配置入口。
Related
这篇文档有帮助吗?