From 8e24a157e1cc63fcc0043ac13313260267acf074 Mon Sep 17 00:00:00 2001
From: wangjia <809946525@qq.com>
Date: Thu, 23 Jul 2026 07:39:30 +0800
Subject: [PATCH] =?UTF-8?q?fix(agent):=20last-good=20=E5=8F=8C=E5=A4=B1?=
 =?UTF-8?q?=E8=B4=A5=E5=BF=85=E9=A1=BB=E5=91=8A=E8=AD=A6=20+=20=E9=99=8D?=
 =?UTF-8?q?=E7=BA=A7=E6=97=A5=E5=BF=97=E5=88=86=E7=BA=A7=20+=20derr=20?=
 =?UTF-8?q?=E8=90=BD=E6=97=A5=E5=BF=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

loadACL 终点此前有两个问题:(1) 读磁盘 last-good 的 derr 从不落日志;(2) ALERT
只在 err != nil 时触发,但 acl.json 单纯缺失(LoadACLConfig 按设计返回 nil,nil,
不是 error)时 err 恰好是 nil——于是 acl.json 缺失 + 磁盘 last-good 同时损坏这种
"gate 实质消失"的最糟场景,反而完全没有日志。

修复:
- derr 非 nil 时打 ERROR。
- ALERT 判断改用文件是否曾经存在(os.Stat)而非 err 是否非 nil:acl.json 与
  last-good 均 not-exist → 判定"从未配置过该功能",安静返回;否则(其一存在但
  读取/解析失败)→ ALERT。
- 两条降级 fallback 日志补 WARN 级别标签,配合 ERROR/ALERT 可用
  journalctl | grep -E 'ERROR|WARN|ALERT' 一并抓到。

TDD:acl_test.go 新增三条——双失败必须 ALERT(RED)、从未配置不误报(基线即绿,
防止告警刷屏回归)、降级日志缺 WARN 标签(RED)。全部现绿。

复现细节:双失败场景没有采用"把 acl.json 和 last-good 都整个删除"来复现——那种
状态在文件系统层面与"这台节点从没配置过 ACL"完全无法区分(两次 os.Stat 皆
not-exist),任何仅凭当前文件状态判断的实现都做不出区分,要区分需要额外的持久
标记,超出本 finding 范围。改用"acl.json 缺失 + 磁盘 last-good 存在但损坏"复现,
这是一个可被 os.Stat 命中的信号,也更贴近 §5 描述的真实故障。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 server/internal/agentd/acl_test.go | 95 ++++++++++++++++++++++++++++++
 server/internal/agentd/singbox.go  | 18 +++++-
 2 files changed, 110 insertions(+), 3 deletions(-)

diff --git a/server/internal/agentd/acl_test.go b/server/internal/agentd/acl_test.go
index a920b10..3753ed1 100644
--- a/server/internal/agentd/acl_test.go
+++ b/server/internal/agentd/acl_test.go
@@ -5,6 +5,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"log"
 	"os"
 	"path/filepath"
 	"strings"
@@ -14,6 +15,20 @@ import (
 	agentv1 "github.com/wangjia/pangolin/server/internal/pb/agentv1"
 )
 
+// captureLog 把标准库 log 包(logf 的底层输出)重定向到一个 buffer,测试结束
+// (t.Cleanup)后自动还原到原输出。agentd 包内没有自己的 logger 抽象——logf 直接
+// 调 log.Printf——但标准库 log 本身就是一个可重定向的现成缝隙,不需要为了可测试性
+// 另外引入 logger 接口。包内测试从不并发跑(无 t.Parallel),重定向全局 log 输出
+// 是安全的。
+func captureLog(t *testing.T) *bytes.Buffer {
+	t.Helper()
+	var buf bytes.Buffer
+	orig := log.Writer()
+	log.SetOutput(&buf)
+	t.Cleanup(func() { log.SetOutput(orig) })
+	return &buf
+}
+
 // writeACL 把 acl.json 写到指定路径。
 func writeACL(t *testing.T, path, body string) {
 	t.Helper()
@@ -604,3 +619,83 @@ func TestACL_EnabledWithEmptyAllowlistStillPersistsAndDenies(t *testing.T) {
 		t.Fatalf("空白名单(但有效 target)的配置应被当作合法 active 配置持久化为 last-good: %v", err)
 	}
 }
+
+// ─── I2: last-good 双失败必须大声告警,读盘错误不能被吞掉 ─────────────────────
+
+// acl.json 缺失 + 磁盘 last-good 损坏(存在但解析不了,模拟卷挂载异常/写坏)→
+// 两级兜底都失败,gate 实质消失,必须在 loadACL 的终点打 ALERT——这正是设计 §5
+// "两者都失败才不产出 ACL 规则,同时打 ERROR 并告警" 要求的那一档。
+//
+// 注:没有采用"把两个文件都整个删掉"来复现,因为那种状态在文件系统层面与
+// "这台节点从没配置过 ACL"完全无法区分(两次 os.Stat 都是 not-exist),任何仅凭
+// 现有文件状态判断的实现都做不出区分;若真要区分,需要额外的持久化标记,超出本
+// finding 的范围。"last-good 文件存在但损坏"则是一个可观察、可被 os.Stat 命中
+// 的信号,且更贴近 §5 描述的真实故障("last-good 损坏"),故以此复现。
+func TestACL_BothLastGoodFailuresAlert(t *testing.T) {
+	cfg := testConfig(t)
+	writeACL(t, cfg.ACLConfigPath, validACL)
+	sb1 := NewSingBox(cfg, nil)
+	sb1.ApplyConfig(sampleSnapshot(&agentv1.Credential{DpUUID: "aaaa", Protocol: agentv1.ProtocolBoth}), true)
+	if _, err := sb1.RenderConfig(); err != nil {
+		t.Fatal(err) // acl.last-good.json 现已落盘
+	}
+
+	if err := os.Remove(cfg.ACLConfigPath); err != nil {
+		t.Fatalf("failed to remove acl.json: %v", err)
+	}
+	writeACL(t, cfg.ACLLastGoodPath(), `{"enabled": true,`) // 磁盘 last-good 也损坏
+
+	buf := captureLog(t)
+	sb2 := NewSingBox(cfg, nil) // 全新实例,内存 last-good 为空(模拟进程重启)
+	sb2.ApplyConfig(sampleSnapshot(&agentv1.Credential{DpUUID: "aaaa", Protocol: agentv1.ProtocolBoth}), true)
+	data, err := sb2.RenderConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(data), "reject") {
+		t.Fatal("两级 last-good 都失败,不应该还能产出规则(此断言只是确认前提)")
+	}
+	logged := buf.String()
+	if !strings.Contains(logged, "ALERT") {
+		t.Fatalf("两级 last-good 都失败(acl.json 缺失 + 磁盘 last-good 损坏)必须打 ALERT,实际日志:\n%s", logged)
+	}
+	if !strings.Contains(logged, "ERROR reading last-good") {
+		t.Fatalf("读磁盘 last-good 失败的 derr 必须落日志,实际日志:\n%s", logged)
+	}
+}
+
+// 从未配置过 ACL(acl.json 和 last-good 都从来没存在过)→ 终点应保持安静,不误报
+// ALERT。这条守着"没用这个功能的节点不该被日志刷屏"。
+func TestACL_NeverConfiguredNoAlert(t *testing.T) {
+	cfg := testConfig(t)
+	buf := captureLog(t)
+	sb := NewSingBox(cfg, nil)
+	sb.ApplyConfig(sampleSnapshot(&agentv1.Credential{DpUUID: "aaaa", Protocol: agentv1.ProtocolBoth}), true)
+	if _, err := sb.RenderConfig(); err != nil {
+		t.Fatal(err)
+	}
+	if logged := buf.String(); strings.Contains(logged, "ALERT") {
+		t.Fatalf("从未配置过 ACL 的节点不该收到 ALERT(会造成告警刷屏),实际日志:\n%s", logged)
+	}
+}
+
+// 降级路径(内存/磁盘 last-good 兜底成功)的日志必须带 WARN 级别标签,便于
+// journalctl | grep -E 'ERROR|WARN|ALERT' 抓到"已恢复但曾经降级"的状态。
+func TestACL_FallbackLogsCarryWarnLevel(t *testing.T) {
+	cfg := testConfig(t)
+	writeACL(t, cfg.ACLConfigPath, validACL)
+	sb := NewSingBox(cfg, nil)
+	sb.ApplyConfig(sampleSnapshot(&agentv1.Credential{DpUUID: "aaaa", Protocol: agentv1.ProtocolBoth}), true)
+	if _, err := sb.RenderConfig(); err != nil {
+		t.Fatal(err)
+	}
+
+	writeACL(t, cfg.ACLConfigPath, `{"enabled": true,`) // 手抖写坏,触发内存 last-good 兜底
+	buf := captureLog(t)
+	if _, err := sb.RenderConfig(); err != nil {
+		t.Fatal(err)
+	}
+	if logged := buf.String(); !strings.Contains(logged, "WARN falling back to in-memory") {
+		t.Fatalf("内存 last-good 兜底日志缺 WARN 级别标签,实际日志:\n%s", logged)
+	}
+}
diff --git a/server/internal/agentd/singbox.go b/server/internal/agentd/singbox.go
index 961bceb..73930b7 100644
--- a/server/internal/agentd/singbox.go
+++ b/server/internal/agentd/singbox.go
@@ -371,20 +371,32 @@ func (s *SingBox) loadACL() *ACLConfig {
 	lg := s.lastGoodACL
 	s.mu.Unlock()
 	if lg != nil {
-		logf("[acl] falling back to in-memory last-good ACL")
+		logf("[acl] WARN falling back to in-memory last-good ACL")
 		return lg
 	}
 
 	disk, derr := LoadACLConfig(s.cfg.ACLLastGoodPath())
+	if derr != nil {
+		logf("[acl] ERROR reading last-good %s: %v", s.cfg.ACLLastGoodPath(), derr)
+	}
 	if derr == nil && disk != nil {
-		logf("[acl] falling back to on-disk last-good %s", s.cfg.ACLLastGoodPath())
+		logf("[acl] WARN falling back to on-disk last-good %s", s.cfg.ACLLastGoodPath())
 		s.mu.Lock()
 		s.lastGoodACL = disk
 		s.mu.Unlock()
 		return disk
 	}
 
-	if err != nil {
+	// 两级 last-good 都没有可用配置。区分两种终态:
+	//   - 这台节点从未配置过 ACL(acl.json 与 last-good 均从未存在过)→ 安静返回,
+	//     不刷屏告警。
+	//   - 除此之外的任何情况(acl.json 存在但损坏/last-good 存在但损坏等)→ 私有
+	//     服务的访问闸实质已消失,必须大声告警(§5 "两者都失败才不产出 ACL 规则,
+	//     同时打 ERROR 并告警")。
+	_, aclStatErr := os.Stat(s.cfg.ACLConfigPath)
+	_, lgStatErr := os.Stat(s.cfg.ACLLastGoodPath())
+	neverConfigured := os.IsNotExist(aclStatErr) && os.IsNotExist(lgStatErr)
+	if !neverConfigured {
 		logf("[acl] ALERT acl.json is broken and no last-good snapshot exists — "+
 			"private destinations are UNPROTECTED (path=%s)", s.cfg.ACLConfigPath)
 	}