mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-10-06 07:28:11 +00:00
feat(clients): 设备桥自动链接改用服务端发现 + 路径挂载(无 DNS 依赖)
配套 webui 反代改造:网关现在可由 HomeAgent 反代出去,客户端不能再靠
「门户地址同 host 拼 /api/v1/device/ws」猜地址——基域名与子域标签都是
**服务端配置**,客户端无从得知。
## 服务端:/api/v1/device/gateway 发现端点
客户端问「网关在哪」是唯一不会漂移的做法:子域标签可改(插件声明)、
基域名可改(webui.base_domain)、实例可换形态,客户端都不用跟着改。
⚠️ **不返回设备令牌**:本端点用门户凭证鉴权,而设备令牌能执行设备命令;
把令牌塞进来等于「门户只读凭证 → 设备执行权」的越权。令牌仍由客户端
自配。已有判据钉住「不得泄漏凭证字段」。
## ★ 实测发现:*.localhost 只有浏览器能解析
这是本轮最重要的发现,直接决定了设计:
| 环境 | devices.localhost 解析 |
|---|---|
| 浏览器 | ✓(RFC 6761 内置) |
| curl | ✓(内置特例) |
| getent / Go / Node | ✗(系统 nsswitch 是 files,dns,无 nss-myhostname) |
设备客户端(waiter / GUI 主进程 / 嵌入式固件)用的正是系统解析器。
实测 waiter 报「lookup devices.localhost on 192.168.2.1:53」。
因此**两处**设计变更:
1. 发现端点同时返回两种形态,并标 preferred:
- url(子域)—— 浏览器用
- url_portal(门户同源,同一 host、同一端口,走路径挂载)—— 非浏览器用,
无任何 DNS 依赖
2. SDK 的 ProxyDecl 新增 **Path**(路径挂载前缀):让同一服务同时挂到
门户自身 host 的路径下。remotedevice 声明 Path="/api/v1/device",
设备客户端因此能沿用**它已硬编码的路径**,不需要知道反代存在。
路径挂载语义:请求路径**原样保留**(不剥前缀),上游按真实路径注册即可。
边界卡在路径分隔符上(/api/v1/device 不匹配 /api/v1/devicefoo)。
## 客户端
- **waiter**:新增 discoverGateway(),仅在用户配了门户地址时尝试,失败回退
自配地址(老版本 HomeAgent 无该端点)。抽出 normalizeGateway() 纯函数,
显式钉住「已带子域/完整端点的地址不得被改写」。
- **GUI**:renderer 新增 loadDiscoveredGateway(),renderDeviceChannel 优先用
发现值、回退旧口径。顺带修掉此前插入函数时 anchor 不匹配导致调用点
找不到定义的问题。
- **鸿蒙**:discoverGateway() + resolveGatewayUrl(),优先 url_portal。
- 三者都**优先 url_portal**(system resolver 的现实约束)。
## 遗留路由鉴权修正
`/api/v1/device/` 的旧路径反代原被 requireAPI 包裹 —— 但其调用方是设备
(带设备令牌而非门户凭证),套上门户鉴权会把它们全挡在 401(**真实实测**:
waiter 经此路径升级握手 401)。去掉这层包装,鉴权交给上游 remotedevice
自己的 requireToken,安全性不降级。
## 判据
webui +6 条、waiter +7 条。
★ 其中一条是**真实回归**:/api/v1/device/gateway 曾被 Path="/api/v1/device"
的路径挂载接走(那服务 auth=none),于是发现请求被转给上游、回 401,
客户端再也发现不到网关。修法是发现端点先于路径挂载判定,并补判据
(走完整生产链,同时确认同前缀的真实设备路径仍归反代)。
## 真实验收(隔离实例,命名 netns + 独立 data + 18080)
真 waiter 客户端 + 真 remotedevice 网关:
device gateway discovered: ws://127.0.0.1:18080/api/v1/device/ws
device bridge active: waiter-mainserver authorized=true
hello_ack / bind_ack 均经反代往返成功
说明:`bind_ack device=<nil>` 与在线列表为空的现象,**直连 9890 绕开反代
完全一致复现**,属 remotedevice 与 waiter 之间既有的握手细节,与本次
反代改造无关(反代侧职责已证:连接建立 + 双向帧往返都通)。
This commit is contained in:
27
third_party/homeagent-sdk/sdk/proxy.go
vendored
27
third_party/homeagent-sdk/sdk/proxy.go
vendored
@ -57,6 +57,22 @@ type ProxyDecl struct {
|
||||
// 而不是静默降级成普通请求(后者表现为前端一直重连、排查困难)。
|
||||
WebSocket bool `json:"websocket,omitempty"`
|
||||
|
||||
// Path 是可选的**路径挂载前缀**(如 "/api/v1/device")。
|
||||
//
|
||||
// 为什么 Host 子域之外还需要它:子域形态依赖 DNS 解析,而 *.localhost
|
||||
// 只有浏览器内置该特例(RFC 6761)—— 普通进程(设备客户端、固件、
|
||||
// CLI)走系统解析器,实测解析不到,会以「no such host」失败。
|
||||
// 路径形态挂在门户自身 host 下,**无任何 DNS 依赖**,是给非浏览器
|
||||
// 客户端用的。
|
||||
//
|
||||
// 语义:请求路径**原样保留**(不做前缀剥除)——声明者按上游真实路径填写,
|
||||
// 例如上游注册 /api/v1/device/ws,就声明 Path="/api/v1/device"。
|
||||
// 这样设备客户端可以直接使用它已硬编码的路径,不需要知道反代的存在。
|
||||
//
|
||||
// 留空 = 只提供子域形态(插件自带 UI 的常见情形:UI 与它自己的 API
|
||||
// 同源,走子域天然正确)。
|
||||
Path string `json:"path,omitempty"`
|
||||
|
||||
// Auth 决定这条反代由谁保护,取值见 ProxyAuthNone / ProxyAuthHomeAgent。
|
||||
// 空串等价于 ProxyAuthHomeAgent(默认安全)。
|
||||
//
|
||||
@ -163,6 +179,17 @@ func ValidateProxyDecl(d ProxyDecl) string {
|
||||
if d.Host != "" && !ValidProxyHostLabel(d.Host) {
|
||||
return "host 不是合法的子域名标签(只允许小写字母/数字/连字符,且不以连字符开头结尾): " + d.Host
|
||||
}
|
||||
if p := strings.TrimSpace(d.Path); p != "" {
|
||||
if !strings.HasPrefix(p, "/") {
|
||||
return "path 必须以 / 开头: " + d.Path
|
||||
}
|
||||
if strings.HasSuffix(p, "/") {
|
||||
return "path 不应以 / 结尾(它是前缀,不是目录): " + d.Path
|
||||
}
|
||||
if strings.Contains(p, "..") || strings.ContainsAny(p, " \t\r\n\x00?#") {
|
||||
return "path 含非法字符: " + d.Path
|
||||
}
|
||||
}
|
||||
// Target 的 host:port 部分必须可解析;路径前缀允许保留。
|
||||
//
|
||||
// 规则(刻意从严,因为地址写错是最常见的声明错误,而错误的反代会把
|
||||
|
||||
Reference in New Issue
Block a user