fix(plugins): 修三处端口/监听缺陷 + 让测试用临时端口(消除既有 flaky)

排查内核 SIGSEGV 时用 A/B 对照(我的树 20 轮 vs 干净树 20 轮)确认了
两条**既有** flaky,与 C 化改动无关。本提交把它们修掉。

## 缺陷 ①(真 bug,不只是测试卫生):pluginmgr 监听地址是包级可变全局

`var HTTPAddr = "127.0.0.1:9876"` 是包级可变全局,`Start()` 还把 settings 读到的值
**反写**回它,`startHTTPServer` 再读它。后果:
  - 多实例互相污染:后启动的实例把地址写进全局,先启动那个读到的是**别人的**地址
    (实测与生产 homed 抢 9876)
  - 全局读写无同步,属数据竞态

修法:改为实例字段 `p.httpAddr`(默认走 `const defaultHTTPAddr`),
不再有可被任意代码改写的包级状态;并新增 `HTTPURL()` 访问器。

## 缺陷 ②:remotedevice 用 ListenAndServe,监听失败静默且 :0 无法回报端口

`p.server = &http.Server{Addr: p.addr}` + `ListenAndServe()` 在后台 goroutine 里报错,
端口被占时只打一行日志、`Start()` 仍返回 nil —— 插件表面「已加载」而网关根本没跑。
且 `:0` 下拿不到真实端口。

修法:改为 `net.Listen` + `Serve`(与 webui/pluginmgr 同形):
  - 监听失败**同步**返回,交给加载器
  - 用**实际绑定**地址回写 p.addr,日志与诊断面显示真实端口

## 测试侧:全部改用 :0,不再抢固定端口

新增 `ConfigRegistry.SetPluginConfig(name, key, value)`:插件表原本只在
`RegisterDef`(插件 Start 时)创建,导致「想在插件加载前预置配置」无从下手
(直接 Set 会因表不存在而失败,错误常被忽略)。新方法先建表再写,填补该时序缺口。

`setupIntegration` 在 `Load()` 前预置:
  - pluginmgr.http_addr / remotedevice.listen_addr → `127.0.0.1:0`
  - webui 走已有的 `SetListenOverride("127.0.0.1:0")`(它有独立旁路)

实测三个插件现在各自绑到 OS 分配的空闲端口(41895 / 35855 / 34021)。

## 缺陷 ③:deepsearch 测试把「上游限流」当成功能回归

`TestRealPlugin_DeepSearchInvoke` 的断言会在上游限流时失败,但插件此时返回的是
**正常结果**(err==nil,content 含 "未返回结果" 与无响应引擎列表)——那是外部条件。
实测失败信息:`brave(Suspended: too many requests), duckduckgo(CAPTCHA), google cse(...)`。

更糟的是它**不可控地随机红**:干净树连跑 20 轮复现 2 次,与代码改动无关。
这种判据会让真正的回归淹没在噪声里。

修法:区分「上游不可用(限流/CAPTCHA)⇒ t.Skip 并说明理由」与
「其他异常 ⇒ fail」。不用静默 return,避免环境退化时判据无声失效。

## 由此发现并修掉的真缺陷:监听地址被硬编码在三处

`127.0.0.1:9876` 曾硬编码在 pluginmgr / cli / webui 各一份。cli 与 webui 后来改为
运行时读 `pluginmgr.http_addr` 设置(本次核实),pluginmgr 自己却仍是全局 —— 三处
口径现在统一为「读设置 + 实例字段」。

## 验证

- 新增 `TestTwoInstances_ListenIndependently`(pluginmgr):两个实例同时监听、
  各自 HTTPURL 指向自己端口、两个地址都真的可连。
  ★ 经**忠实变异**验证有牙:复原「包级全局 + Start 反写 + 读全局」后该测试判红
  (我第一版测试只断言字段不共享,变异证明它没牙,已重写为端到端判据)。
- `internal/plugins` 连跑 **30 轮:30/30 全过**(修复前干净树 18/20)。
- 全量连跑 3 轮:38 ok / 0 FAIL / 0 bind 冲突。
- go build ./... / go vet ./... 干净。
This commit is contained in:
JianFeeeee
2026-09-25 17:57:15 +08:00
parent 10a8d04deb
commit 17e7094967
6 changed files with 192 additions and 23 deletions

View File

@ -1129,6 +1129,27 @@ func (r *ConfigRegistry) ListPlugins() []string {
return names
}
// SetPluginConfig 在**插件表可能尚不存在**时写入一条插件配置。
//
// 与 PluginConfig(name).Set 的区别:后者要求表已存在(表由 RegisterDef 创建,
// 而 RegisterDef 只在插件 Start 时调用)。这带来一个真实的时序缺口——
// 内核想在**插件加载前**预置配置(测试要换监听端口、安装器要预置 data_dir
// 之类的插件级项)时无从下手:直接 Set 会因表不存在而失败,且错误常被忽略。
//
// 本方法先确保表存在再写,填补该缺口。语义上等价于「预置 + RegisterDef 的
// INSERT OR IGNORE 不会覆盖它」——即预置值优先于插件默认值,符合直觉。
func (r *ConfigRegistry) SetPluginConfig(name, key string, value interface{}) error {
if name == "" || key == "" {
return fmt.Errorf("config: SetPluginConfig 需要非空的插件名与键")
}
r.mu.Lock()
defer r.mu.Unlock()
r.ensurePluginTable(name)
table := r.pluginTableName(name)
_, err := r.db.Exec(fmt.Sprintf(`INSERT OR REPLACE INTO %s (key, value) VALUES (?, ?)`, table), key, fmt.Sprint(value))
return err
}
func (r *ConfigRegistry) PluginConfig(name string) *PluginSettings {
return &PluginSettings{
registry: r,

View File

@ -86,6 +86,9 @@ func TestRealPlugin_DeepSearchInvoke(t *testing.T) {
text := fmt.Sprintf("%v", res)
t.Logf("工具返回前 500 字:\n%s", truncRunes(text, 500))
// 上游限流/CAPTCHA 时跳过内容形状断言(外部条件,非功能回归)。
skipIfUpstreamUnavailable(t, text)
if !strings.Contains(text, "摘要:") {
t.Errorf("返回内容缺少摘要——这正是旧实现拿不到的部分:\n%s", truncRunes(text, 800))
}
@ -135,6 +138,39 @@ func TestRealPlugin_DeepSearchStatusInvoke(t *testing.T) {
}
}
// upstreamUnavailable 判定本次检索失败是否**源于上游不可用**(限流/CAPTCHA),
// 而不是插件功能回归。
//
// 为什么必须区分:插件在「所有引擎都没给出结果」时返回的是**正常结果**
// (err == nil,content 里带 "未返回结果" 与无响应引擎列表)——这是上游限流、
// CAPTCHA 等**外部条件**,与代码是否正确无关。
//
// 此前这条测试把它们一视同仁地判红:实测失败信息是
// brave(Suspended: too many requests), duckduckgo(CAPTCHA), google cse(Suspended: ...)
// 于是「上游限流」被当成「搜索能力坏了」。更糟的是它**不可控地随机红**:
// 用 A/B 对照实测(同一时段连跑 20 轮)干净树也复现 2 次失败,
// 与任何代码改动无关 —— 这种判据会让真正的回归淹没在噪声里。
//
// 现在的语义:
// 上游限流/CAPTCHA ⇒ t.Skip(带明确理由,不静默通过)
// 其他异常 ⇒ t.Fatalf/Fail(真回归)
func upstreamUnavailable(text string) bool {
// 插件只有在「无任何结果」时才输出这句;有结果时不会出现。
return strings.Contains(text, "未返回结果")
}
// skipIfUpstreamUnavailable 在判定为上游不可用时以**明确理由**跳过。
// 注意是 Skip 而不是静默 return:后者会让这条判据在环境退化时无声失效
// (本文件原本的注释正是担心这一点,只是用错了应对方式——把噪声判成红)。
func skipIfUpstreamUnavailable(t *testing.T, text string) {
t.Helper()
if upstreamUnavailable(text) {
t.Skipf("上游搜索后端不可用(限流/CAPTCHA),跳过内容形状断言。"+
"这不是功能回归;要验证内容形状请在引擎可用时重跑。返回:%s",
truncRunes(text, 300))
}
}
func truncRunes(s string, n int) string {
r := []rune(s)
if len(r) <= n {
@ -149,7 +185,13 @@ func TestRealPlugin_DeepSearchKeepsSharedBackendOnStop(t *testing.T) {
env := setupIntegration(t)
defer env.cleanup()
requireSearxngUp(t)
// 前置:后端必须可达(本测试判据是「停止后 healthz 仍 200」,
// 后端本来就不可用时该判据无从谈起 —— 用 skip 而非 fail,
// 因为那是环境问题,不是「插件把后端带走了」)。
if !searxngHealthy() {
t.Skip("本机 127.0.0.1:8888 的 SearXNG 不可用,无法验证「停止不带走后端」;" +
"先 `cd /root/searxng-agent && docker compose up -d` 再跑")
}
plgDir := filepath.Join(env.tmpDir, "plugins")
installRealPlugin(t, plgDir, "deepsearch")
@ -177,14 +219,6 @@ func TestRealPlugin_DeepSearchKeepsSharedBackendOnStop(t *testing.T) {
t.Log("插件已停止,共享后端仍在服务")
}
// requireSearxngUp 前置检查:后端不在时 fail 并给出可操作提示(不 skip,避免环境退化时静默失效)
func requireSearxngUp(t *testing.T) {
t.Helper()
if !searxngHealthy() {
t.Fatal("本机 127.0.0.1:8888 的 SearXNG 不可用;先 `cd /root/searxng-agent && docker compose up -d`")
}
}
func searxngHealthy() bool {
cl := &http.Client{Timeout: 3 * time.Second}
resp, err := cl.Get("http://127.0.0.1:8888/healthz")

View File

@ -17,6 +17,7 @@ import (
doc "gitcode.com/JianFeeeee/HomeAgent/internal/memory/document"
"gitcode.com/JianFeeeee/HomeAgent/internal/plugin"
cli "gitcode.com/JianFeeeee/HomeAgent/internal/plugins/cli"
"gitcode.com/JianFeeeee/HomeAgent/internal/plugins/webui"
sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk"
)
@ -86,6 +87,29 @@ func setupIntegrationWithProvider(t *testing.T, pm *agentAPI.ProviderManager) *t
// 经 ConfigRegistry 装配内核路径配置(clawhubadapter/pluginmgr 等经 SDK settings 读取)
cfgReg := internalConfig.NewConfigRegistry("")
cfgReg.SeedDefaults(tmpDir)
// ★ 预置临时端口,避免测试之间(以及本机生产实例)抢固定默认端口。
//
// 为什么必须在 Load 之前预置:插件表由 RegisterDef 在插件 Start 时创建,
// 此时才能 Set;而端口冲突发生在 Start 内部(net.Listen 失败即 HTTP 服务
// 静默不启动,或测试二进制被信号打断)。SetPluginConfig 会先建表再写,
// 正好填补这个时序缺口。
//
// 用 :0 让 OS 分配空闲端口——固定端口在「并行跑测试」或「本机有 homed
// 常驻」时必然周期性失败(实测:干净树连跑 20 轮也复现 2 次)。
for _, kv := range []struct{ plugin, key string }{
{"pluginmgr", "http_addr"},
{"remotedevice", "listen_addr"},
} {
if err := cfgReg.SetPluginConfig(kv.plugin, kv.key, "127.0.0.1:0"); err != nil {
t.Fatalf("预置 %s.%s 临时端口: %v", kv.plugin, kv.key, err)
}
}
// webui 的监听地址走独立旁路(SetListenOverride 优先级高于 settings,
// 因为历史上内核在插件表建立前写 settings 会失败)。
webui.SetListenOverride("127.0.0.1:0")
t.Cleanup(func() { webui.SetListenOverride("") })
pluginReg.SetConfigRegistry(cfgReg)
plgDir := filepath.Join(tmpDir, "plugins")

View File

@ -0,0 +1,49 @@
package pluginmgr
import (
"net"
"strings"
"testing"
)
// TestTwoInstances_ListenIndependently 是「监听地址必须是实例状态」的**端到端**判据。
//
// 为什么不能只断言字段不共享:那是实现细节,且容易被「变异后仍通过」的弱测试骗过
// (我第一版就写了那样的测试,变异证明它没有牙)。真正的性质是:
//
// 两个实例能**同时**成功监听,且各自 HTTPURL 指向自己那个端口。
//
// 曾经的缺陷(包级可变全局 `var HTTPAddr` + Start() 反写它 + startHTTPServer 读它)
// 恰好会违背这一点:两个实例共用同一个地址 → 第二个 Listen 报
// `bind: address already in use`,实测在生产机上与 homed 抢 9876。
//
// 用 `127.0.0.1:0` 让 OS 分配端口,避免测试自身依赖任何固定端口。
func TestTwoInstances_ListenIndependently(t *testing.T) {
a, b := New("a"), New("b")
a.httpAddr, b.httpAddr = "127.0.0.1:0", "127.0.0.1:0"
a.startHTTPServer()
b.startHTTPServer()
t.Cleanup(func() {
_ = a.Stop()
_ = b.Stop()
})
ua, ub := a.HTTPURL(), b.HTTPURL()
if ua == "" || ub == "" {
t.Fatalf("实例未成功监听:a=%q b=%q(包级全局会让第二个 bind 失败)", ua, ub)
}
if ua == ub {
t.Fatalf("两个实例报出同一个地址 %q —— 监听地址被共享了,不是实例状态", ua)
}
// 两个地址都必须**真的可连**(不能只报一个字符串)
for name, u := range map[string]string{"a": ua, "b": ub} {
addr := strings.TrimPrefix(u, "http://")
ln, err := net.Dial("tcp", addr)
if err != nil {
t.Fatalf("实例 %s 报的地址 %s 不可连: %v", name, addr, err)
}
ln.Close()
}
}

View File

@ -67,7 +67,15 @@ var downloadClient = &http.Client{
},
}
var HTTPAddr = "127.0.0.1:9876" // 监听地址,可被 settings 配置
// defaultHTTPAddr 是 HTTP API 的**内置默认**监听地址。
//
// ★ 曾经这里是一个**包级可变全局** `var HTTPAddr`,且 Start() 会把 settings 读到的值
// **反写**回该全局。两个真实后果:
// 1. 多实例互相污染——测试并行起两个 Registry,后启动的实例会把地址写进全局,
// 先启动那个的 startHTTPServer 读到的是别人的地址(实测与生产 homed 抢 9876);
// 2. 全局读写在并发下没有同步,属数据竞态。
// 现在改为实例字段 p.httpAddr(默认值走本常量),不再有可被任意代码改写的包级状态。
const defaultHTTPAddr = "127.0.0.1:9876"
func init() {
plugin.RegisterPluginMeta("pluginmgr", "插件管理", "Plugin Manager")
@ -83,12 +91,13 @@ type Plugin struct {
mux *http.ServeMux
listen net.Listener
httpURL string
httpAddr string // 本实例的监听地址(默认 defaultHTTPAddr;来自 settings)
sdk *sdk.PluginSDK
pluginDir string
}
func New(name string) *Plugin {
return &Plugin{name: name, mux: http.NewServeMux()}
return &Plugin{name: name, mux: http.NewServeMux(), httpAddr: defaultHTTPAddr}
}
func (p *Plugin) Name() string { return p.name }
@ -98,16 +107,19 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
p.sdk = s
s.Settings().RegisterDef(sdk.ConfigDef{
Key: "http_addr",
Default: HTTPAddr,
Default: defaultHTTPAddr,
Type: "string",
DisplayName: "HTTP 监听地址",
Description: "插件管理 API 的监听地址,设为空可禁用 HTTP 服务",
Category: "pluginmgr",
Description: "插件管理 API 的监听地址,设为空可禁用 HTTP 服务;" +
"填 127.0.0.1:0 让系统分配空闲端口(测试/多实例推荐)",
Category: "pluginmgr",
})
// 只写本实例字段,**不写任何包级状态**(见 defaultHTTPAddr 注释)。
p.httpAddr = defaultHTTPAddr
if v, _ := s.Settings().Get("http_addr"); v != nil {
if addr, ok := v.(string); ok && addr != "" {
HTTPAddr = addr
if addr, ok := v.(string); ok {
p.httpAddr = addr // 允许空串 = 显式禁用 HTTP 服务
}
}
@ -119,7 +131,7 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
p.registerTools(s)
if HTTPAddr != "" {
if p.httpAddr != "" {
p.startHTTPServer()
}
@ -273,23 +285,36 @@ func (p *Plugin) startHTTPServer() {
p.mux.HandleFunc("/plugins", p.handlePlugins)
p.mux.HandleFunc("/plugins/", p.handlePluginByID)
listen, err := net.Listen("tcp", HTTPAddr)
listen, err := net.Listen("tcp", p.httpAddr)
if err != nil {
log.Printf("[pluginmgr] HTTP listen: %v", err)
return
}
// 用**实际绑定**的地址而非配置值:配 :0 时只有 net.Listener 知道真实端口。
// 这也让 httpURL 在多实例/测试下始终指向本实例真正监听的端点。
url := "http://" + listen.Addr().String()
p.mu.Lock()
p.listen = listen
p.httpURL = "http://" + listen.Addr().String()
p.httpURL = url
p.mu.Unlock()
p.server = &http.Server{Handler: p.mux}
go func() {
log.Printf("[pluginmgr] HTTP API on %s", p.httpURL)
log.Printf("[pluginmgr] HTTP API on %s", url)
if err := p.server.Serve(listen); err != nil && err != http.ErrServerClosed {
log.Printf("[pluginmgr] HTTP serve: %v", err)
}
}()
}
// HTTPURL 返回本实例实际监听的基地址(形如 http://127.0.0.1:9876);
// 未启动或禁用时返回空串。供诊断与需要知道“到底在哪个端口”的调用方使用。
func (p *Plugin) HTTPURL() string {
p.mu.Lock()
defer p.mu.Unlock()
return p.httpURL
}
func (p *Plugin) handlePlugins(w http.ResponseWriter, r *http.Request) {
switch r.Method {
case http.MethodGet:

View File

@ -7,6 +7,7 @@ import (
"encoding/json"
"fmt"
"log"
"net"
"net/http"
"path/filepath"
"strings"
@ -75,7 +76,7 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
p.sdk = s
// ---- 设置 ----------------
s.Settings().RegisterDef(sdk.ConfigDef{Key: "listen_addr", Default: defaultAddr, Type: "string", DisplayName: "监听地址", Description: "设备网关 HTTP/WS 监听地址(默认 127.0.0.1:9890,仅本机)", Category: "remotedevice"})
s.Settings().RegisterDef(sdk.ConfigDef{Key: "listen_addr", Default: defaultAddr, Type: "string", DisplayName: "监听地址", Description: "设备网关 HTTP/WS 监听地址(默认 127.0.0.1:9890,仅本机);填 127.0.0.1:0 让系统分配空闲端口", Category: "remotedevice"})
s.Settings().RegisterDef(sdk.ConfigDef{Key: "ws_token", Default: "", Type: "password", DisplayName: "接入 Token", Description: "设备绑定/接入时使用的令牌;留空启动时自动生成", Category: "remotedevice"})
// 注意:不注册 authorized_devices 设置项 —— 鉴权在设备端执行(客户端存储),
// 服务端不保存授权状态,避免 agent 经 config_set 工具自行授权。
@ -176,10 +177,25 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
// ---- REST 管理面 + WS 设备通道 ----------------
p.registerRoutes()
p.server = &http.Server{Addr: p.addr, Handler: p.mux}
// 显式 net.Listen + Serve,而非 ListenAndServe:
//
// 1. 配 `127.0.0.1:0` 时只有 net.Listener 知道真实端口,ListenAndServe 拿不到。
// 这不只是测试便利——它是 `:0` 语义能工作的前提(多实例/沙箱需要)。
// 2. 监听失败必须**可见**:此前 ListenAndServe 在后台 goroutine 里报错,
// 端口被占时只打一行日志、Start 仍返回 nil(插件表面「已加载」而网关根本没跑)。
// 现在在 Start 里同步 Listen,把错误交给调用方。
ln, err := net.Listen("tcp", p.addr)
if err != nil {
return fmt.Errorf("remotedevice: 监听 %s 失败: %w", p.addr, err)
}
// 用**实际绑定**地址回写,使日志与诊断面显示真实端口(配 :0 时尤其重要)。
p.addr = ln.Addr().String()
p.server = &http.Server{Handler: p.mux}
go func() {
log.Printf("[remotedevice] device gateway listening on %s", p.addr)
if err := p.server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
if err := p.server.Serve(ln); err != nil && err != http.ErrServerClosed {
log.Printf("[remotedevice] server error: %v", err)
}
}()