From 9cbffbb727bb9ced2e8b03d35129cf29be6bb458 Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Thu, 23 Jul 2026 01:01:19 +0800 Subject: [PATCH 01/21] =?UTF-8?q?docs(agent):=20=E7=A7=81=E6=9C=89?= =?UTF-8?q?=E7=9B=AE=E7=9A=84=E5=9C=B0=20ACL=20=E8=AE=BE=E8=AE=A1=E6=96=B9?= =?UTF-8?q?=E6=A1=88=E4=B8=8E=E5=AE=9E=E7=8E=B0=E8=AE=A1=E5=88=92?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- docs/index.html | 10 + docs/private-dest-acl-design.html | 243 ++++ docs/private-dest-acl-plan.html | 1119 +++++++++++++++ .../plans/2026-07-23-private-dest-acl.md | 1227 +++++++++++++++++ todo/todo.html | 141 +- todo/todo.json | 60 +- 6 files changed, 2789 insertions(+), 11 deletions(-) create mode 100644 docs/private-dest-acl-design.html create mode 100644 docs/private-dest-acl-plan.html create mode 100644 docs/superpowers/plans/2026-07-23-private-dest-acl.md diff --git a/docs/index.html b/docs/index.html index d310d48..1387ef4 100644 --- a/docs/index.html +++ b/docs/index.html @@ -44,6 +44,11 @@

设计方案 / Specs

+ +
私有目的地访问控制（节点侧 ACL）HTML
+
pangolin 出口 IP 曾等价于「只有我」，多用户后退化成「所有 pangolin 用户」——家庭内网服务（brain/nas/git/win.51yanmei.com）因此对全体用户敞开。在节点 sing-box 加一道按 dp_uuid 的闸：节点本地 acl.json（照 warp.json 骨架）→ 每个目的地渲染「放行白名单 + 兜底拒绝」一对规则，与 WARP 规则合并而非覆写。控制面/DB/proto/客户端/管理后台一律不动，改动收敛在 internal/agentd/。关键点：失效方向必须 fail-closed（与 WARP 的 fail-open 先例相反）、白名单须同时含设备级与账户级 dp_uuid（否则 /sub 订阅链接把自己锁在外面）、生效走 agent SIGHUP 以免重启踢掉全部在线用户。含四态渲染矩阵、规则顺序三条硬约束、名单维护 runbook、验收清单。
+
docs/private-dest-acl-design.html
+
CI/CD 全流程（tag 触发编译/发版/部署）HTML
#30。参考 jiu 的 scripts/ci + .gitea/workflows：tag 触发（site-v*/server-v*/client-v*）→ 编译 → 测试 → Gitea release → 部署。runner 混合（nas=官网+服务端容器化 / mac=Android+macOS / windows=Windows）。服务端部署固化 F3/F4「备份→migrate→换二进制→重启→健康检查+回滚」；官网部署 pangolin.yanmeiai.com；客户端 apk/dmg/exe 挂 release 喂官网下载链接。密钥作用域：Apple/token 账户级、部署 key/Android keystore 仓库级。范围 A~F（排除 iOS/#26/#25）。
@@ -86,6 +91,11 @@

实现计划 / Plans

+ +
私有目的地 ACL（节点侧）HTML
+
阅读版；执行真相源 docs/superpowers/plans/2026-07-23-private-dest-acl.md（含 checkbox）。设计见 docs/private-dest-acl-design.html。6 个 TDD 任务：①ACL 配置类型 + fail-closed 的 active()（空白名单=拒绝所有人，非「未启用」）→ ②rules() 产出「全部放行→全部拒绝」规则对，两侧目的地条件逐字相同 → ③buildRoute 合并 ACL 与 WARP（四态矩阵；现状 cfg["route"] 是整块覆盖，直接赋值会干掉 WARP）→ ④渲染时读 ACL + 内存/磁盘双层 last-good 兜底（fail-closed 须跨重启成立）→ ⑤SIGHUP 触发热重渲染（重启 agent 会冷启 sing-box 踢掉全部在线用户）→ ⑥配置样例与 runbook。改动收敛在 internal/agentd/ + cmd/agent，零 migration/零 proto/零客户端改动。
+
docs/private-dest-acl-plan.html · 真相源 docs/superpowers/plans/2026-07-23-private-dest-acl.md
+
前端设计系统治理重构（ds-flow 全端）HTML
阅读版；执行真相源 docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md（含 checkbox）。用 ds-flow 把 Flutter 五端 + 官网 + 用户中心收口到「设计单源·代码镜像·静态闸拦漂移·golden/fidelity 双级像素验收兜底」。非从零 bootstrap（已约 65% 达标）：补原型三件套（atoms.css/icons.js/index.html 登记页）+ Web 共享原子层去重（各自实现+同源闸）+ 硬编码色/fidelity 闸 + 启用 pre-commit。6 阶段：CLAUDE.md → 原型单源 → Web token 同源 → Web 原子对齐 → Flutter golden 补齐 → 闸挂满。主题保持 light/dark。
diff --git a/docs/private-dest-acl-design.html b/docs/private-dest-acl-design.html new file mode 100644 index 0000000..0e9e974 --- /dev/null +++ b/docs/private-dest-acl-design.html @@ -0,0 +1,243 @@ + + + + + +私有目的地访问控制（设计 · 节点侧 ACL） + + + +
+ ← 文档索引 +

私有目的地访问控制（设计 · 节点侧 ACL）

+

只有指定 dp_uuid 才能经 pangolin 出口访问家庭内网服务 · 2026-07-23

+ +
+

pangolin 出口 IP（103.119.13.48）是家庭内网服务在 ali 侧的唯一准入凭据——brain/nas/git/win.51yanmei.com 全靠「来自这个 IP」放行。单用户时它等价于「只有我」；现在 pangolin 有 5 个账号，它退化成了「所有 pangolin 用户」。本设计在节点 sing-box 上补一道按 dp_uuid 的闸，把语义拉回「只有我」。

+
+ +

1. 范围

+

只做「私有服务白名单」一件事。不做通用租户黑白名单、不做上网管控、不做管理后台、不要求实时生效。这些在评审中被显式砍掉——它们的复杂度大半来自「多策略 × 多组 × 实时下发」，而本需求三个都不需要。

+ +

问题的真实边界

+

经 pangolin 出口能摸到的家里服务，各自本来就有鉴权，唯一裸奔的是 brain：

+ + + + + + + +
服务入口自带鉴权
git.51yanmei.comali 443 → GiteaGitea 登录 有
nas.51yanmei.com:5001frp → DSM账号 + 2FA + 自动封锁 有
nas/win SSH (10022/10023)frp密钥登录 有
win.51yanmei.com:3389frp → RDPNLA + 密码 有
brain.51yanmei.comali 443 → 静态站无
+

所以本设计提供的是网络层前置闸（别人连登录页都摸不到），而不是唯一防线。

+ +

2. 关键决策

+ + + + + + + + + +
维度选择理由
执行点节点 sing-box route.rules控制面不在数据路径上；sing-box 无外部授权钩子（实测 external_controller/auth_request/external_acl/authenticator/webhook/http_provider/external_rule_provider 七个字段名全部 unknown field）。客户端执行会被用户自行修改，且 /sub/{token} 路径天然绕过。
名单来源节点本地 acl.json照 warp.json 现成骨架。控制面/DB/proto/客户端/管理后台一律不动，改动收敛在 internal/agentd/ 一个包。
主体粒度dp_uuid 列表dp_uuid 每设备一个、懒生成、从不轮换（RotateCredential 协议在但控制面无调用方），写死后基本一劳永逸。当前我的账号名下仅 1 台设备有 dp_uuid。
目的地表达域名 + IP:端口 两类brain/git 与公开的 jiu/travel/sudoku 共用 ali 的 443，只能靠 SNI 区分；DSM/RDP/SSH 用独立端口，直接 IP+端口匹配。
sniff复用现有WARP 已在节点启用，线上 route 块本来就是 [{"action":"sniff"},{...warp}]——域名匹配零额外成本。
失效方向fail-closed与 WARP 相反。见 §5，这是本设计唯一容易写错的地方。
生效方式agent SIGHUP 触发重渲染不要求延时，但重启 agent 会让 sing-box 走冷启动、踢掉全部在线用户（见 §6），故加一个轻量信号处理。
+ +

3. 现状事实（设计所依赖的）

+ + +

4. 设计

+ +

4.1 配置文件 /etc/pangolin-agent/acl.json

+
{
+  "enabled": true,
+  "allow_dp_uuids": [
+    "<我的设备级 dp_uuid>",
+    "<我的账户级 dp_uuid（/sub 用）>"
+  ],
+  "targets": [
+    { "domain":  ["brain.51yanmei.com", "git.51yanmei.com"] },
+    { "ip_cidr": ["182.92.213.171/32"], "port": [5001, 3389, 10022, 10023] }
+  ]
+}
+

targets 每项是一个「目的地形状」，字段直接对应 sing-box route rule 的匹配字段（同一项内多字段是 AND，字段内多值是 OR）。刻意不做自研 DSL——形状即 sing-box 语义，减少一层翻译和一类 bug。

+ +

4.2 渲染出的 route 块

+

每个 target 产出一对规则：先放行白名单、再兜底拒绝。顺序即优先级，首条命中即返回。

+
"route": {
+  "rules": [
+    {"action": "sniff"},
+
+    {"user": ["<我的uuid…>"], "domain": ["brain.51yanmei.com","git.51yanmei.com"],
+     "outbound": "direct"},
+    {"user": ["<我的uuid…>"], "ip_cidr": ["182.92.213.171/32"],
+     "port": [5001,3389,10022,10023], "outbound": "direct"},
+
+    {"domain": ["brain.51yanmei.com","git.51yanmei.com"], "action": "reject"},
+    {"ip_cidr": ["182.92.213.171/32"], "port": [5001,3389,10022,10023],
+     "action": "reject"},
+
+    {"domain_suffix": ["reddit.com","redd.it",…], "outbound": "warp"}
+  ],
+  "final": "direct"
+}
+

已用本机 sing-box 1.13.13 sing-box check 验证形状合法（exit 0）。

+ +
+

规则顺序的三条硬约束

+
    +
  1. {"action":"sniff"} 必须最先且只出现一次——域名匹配依赖它取 TLS SNI。合并时若 WARP 已产出 sniff，不得重复追加。
    2. +
  2. 全部 ACL 规则（放行 + 拒绝）排在 WARP 规则之前。当前两者目的地不重叠（reddit vs 我的域名），但被拒绝的目的地永远不该有机会被路由到 warp 出口。
    3. +
  3. 放行必须排在拒绝之前，且两者目的地条件逐字相同。任何不对称都会造成「我自己也被拒」或「有人漏网」。
    4. +
+
+ +

4.3 与 WARP 的合并

+

把 render.go 里 cfg["route"] = warp.warpRoute() 的直接赋值，改为由一个 buildRoute(acl, warp) 统一产出：

+ + + + + + +
ACLWARProute 块
关关不产出（与现有配置逐字节一致，保持向后兼容）
关开现状不变：sniff + warp 规则
开关sniff + ACL 规则，final:"direct"
开开sniff + ACL 规则 + warp 规则，final:"direct"；endpoints 照旧由 WARP 注入
+ +

5. 失效语义 最易写错

+
+

WARP 的先例是 fail-open，绝不能照抄。singbox.go:321-324 加载失败即 warp = nil 放弃分流；warp.go:47-58 的 active() 任一字段缺失即返回 false，注释写着「宁可不分流(全直连)」。对分流这是对的，对访问控制方向正好反了——同样的写法会让一次手抖的编辑把私有服务对全体 pangolin 用户敞开，而且是静默的。

+

本设计的规则：

+
    +
  • 解析失败 / 文件读不出 → 保留上一次成功加载的 ACL（agent 内存中持有 last-good），不清空规则，打 ERROR 日志。
    • +
  • last-good 必须落盘：每次成功加载后把规范化结果写入 <StateDir>/acl.last-good.json（照 state.json 的持久化套路）。否则 agent 一重启，内存里的 last-good 就没了，fail-closed 只在进程生命周期内成立——而进程重启恰恰是最可能撞上坏配置的时刻。
    • +
  • agent 冷启动：先读 acl.json；失败则回退 acl.last-good.json；两者都失败才不产出 ACL 规则，同时打 ERROR 并告警。注意 这最后一档的实际后果是 fail-open（私有服务对全体 pangolin 用户敞开）——之所以只能如此，是因为白名单与目的地清单同在一个文件，文件全丢时连「该拒绝哪些目的地」都无从得知，无法凭空拒起。这也是为什么 last-good 落盘是必需项而非优化项。
    • +
  • allow_dp_uuids 为空数组 → 仍产出拒绝规则，即「谁都不许进」。空名单的语义是「没有人」，不是「所有人」。
    • +
  • 关闭 ACL 只有一条合法途径：显式写 "enabled": false。删文件不算（走 last-good 分支）。
    • +
  • agent 长期离线 → 节点保留旧配置，被移除的 uuid 在 agent 恢复前仍可进入。这是可接受的（不要求延时），但要在 runbook 里写明：撤销某人的访问后，须确认 agent 已重新渲染。
    • +
+
+ +

6. 生效方式

+

编辑 acl.json 本身不会触发渲染——markDirty() 只在凭证变更时被调用。可选做法与代价：

+ + + + + +
做法代价
systemctl restart pangolin-agent会踢人 新进程内 s.started=false，首次渲染走 Restart() 即 systemctl restart sing-box，全部在线用户瞬断
等下一次凭证变更顺带生效时机不可控，可能几小时不生效
给 agent 加 SIGHUP 处理 → markDirty() 采用约 10 行；走 sing-box SIGHUP 热重载，不断线；systemctl reload pangolin-agent 即可
+ +

7. 代码改动清单

+ + + + + + + + +
文件改动
internal/agentd/acl.go 新增ACLConfig 结构、LoadACLConfig、active()（fail-closed 语义）、aclRules() 产出规则对。镜像 warp.go 骨架。
internal/agentd/render.gorenderSingboxConfig 增 acl 入参；抽出 buildRoute(acl, warp) 取代 cfg["route"] = warp.warpRoute()（§4.3 四态表）
internal/agentd/singbox.goRenderConfig 每次重读 acl.json（紧邻现有 warp 重读）；持有 last-good ACL 字段，成功加载后落盘 acl.last-good.json，冷启动按 acl.json → last-good → 无 顺序回退
internal/agentd/config.go新增 ACLConfigPath，默认 <StateDir>/acl.json
internal/agentd/agent.go 或 cmd/agentSIGHUP → markDirty()
internal/agentd/acl_test.go 新增见 §9
+

不动：控制面、数据库（零 migration）、proto、客户端、管理后台、CI。改动全部收敛在 internal/agentd/。

+ +

8. 名单维护 Runbook

+

新增/更换设备后，重新生成白名单（UNION 那一半是账户级 dp_uuid，供 /sub 订阅链接用，别漏）：

+
sqlite3 /var/lib/pangolin/pangolin.db \
+  "SELECT d.dp_uuid FROM devices d JOIN users u ON u.id = d.user_id
+    WHERE u.email = '<我的邮箱>' AND d.dp_uuid IS NOT NULL
+   UNION
+   SELECT dp_uuid FROM users WHERE email = '<我的邮箱>';"
+
+# 填进 acl.json 的 allow_dp_uuids 后
+systemctl reload pangolin-agent          # 不断线
+journalctl -u pangolin-agent -n 20       # 确认已重渲染、无 ACL ERROR
+

设备的 dp_uuid 是首次 connect 时懒生成的：新设备装好后要先连一次，才查得到 dp_uuid。

+ +

9. 测试与验收

+

单元测试（acl_test.go，表驱动，镜像 warp_test.go）

+ +

上线验收

+
    +
  1. 我的设备：brain 首页 200、DSM 5001 可登录、ssh nas-r 通
    2. +
  2. 另一个账号的设备：以上全部被拒（连接被 reject，非超时）
    3. +
  3. 公开站不受影响：jiu / travel / sudoku / pay 在两个账号下均正常
    4. +
  4. WARP 未被破坏：reddit 仍走 warp 出口
    5. +
  5. 把 acl.json 改坏 → 规则仍在、日志有 ERROR（fail-closed 实证）
    6. +
  6. systemctl reload pangolin-agent 期间在线用户不掉线
    7. +
+ +

10. 刻意不做（YAGNI）

+ + +

11. 演进路径

+

若将来真要做多租户策略，渲染层可原样保留，只把名单来源换掉：给 Credential（internal/pb/agentv1/types.go + agentd/singbox.go 的 Cred）加一个 PrivateAccess bool。该字段同时走增量推送与 Register 全量快照两条通道，天然免疫「重连被 ApplyConfig(snap,true) 整表替换」的问题。届时 acl.json 退化为只保留 targets，allow_dp_uuids 由控制面下发。

+ +

12. 已知残留

+ + +

相关：~/code/brain/docs/remote-access-brain-domain.html（brain 外网入口与出口 IP 白名单）· baize 台账 ~/code/baize/data/{hosts,domains}.yaml

+
+ + diff --git a/docs/private-dest-acl-plan.html b/docs/private-dest-acl-plan.html new file mode 100644 index 0000000..390a184 --- /dev/null +++ b/docs/private-dest-acl-plan.html @@ -0,0 +1,1119 @@ + + + + + +私有目的地 ACL · 实现计划（阅读版） + + + +
+← 文档索引 + +

私有目的地访问控制（节点侧 ACL）Implementation Plan

+

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

+

Goal: 在节点 sing-box 上加一道按 dp_uuid 的闸，使家庭内网服务（brain/nas/git/win.51yanmei.com）只对白名单凭证开放，而不是对所有 pangolin 用户开放。

+

Architecture: 节点本地 acl.json（照 warp.json 骨架）声明「白名单 dp_uuid + 私有目的地清单」；agent 每次渲染 sing-box 配置时读取，为每个目的地产出一对 route 规则——先放行白名单、再兜底拒绝。ACL 规则与 WARP 规则由新的 buildRoute() 合并进同一个 route 块（现状是 WARP 整块覆盖 cfg["route"]，直接赋值会把对方干掉）。控制面、数据库、proto、客户端、管理后台一律不动。

+

Tech Stack: Go 1.2x，标准库；sing-box 1.13.13 配置语义；测试为同包 *_test.go + t.TempDir()，go test ./internal/agentd/...。

+

Global Constraints

+ +
+

Task 1: ACL 配置类型、加载与 fail-closed 的 active()

+

Files:

+ +

Interfaces:

+ +
[ ]Step 1: 写失败测试
+

创建 server/internal/agentd/acl_test.go：

+
package agentd
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// writeACL 把 acl.json 写到指定路径。
+func writeACL(t *testing.T, path, body string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(body), 0o600); err != nil {
+		t.Fatal(err)
+	}
+}
+
+const validACL = `{
+  "enabled": true,
+  "allow_dp_uuids": ["uuid-me-1", "uuid-me-sub"],
+  "targets": [
+    { "domain": ["brain.51yanmei.com", "git.51yanmei.com"] },
+    { "ip_cidr": ["182.92.213.171/32"], "port": [5001, 3389, 10022, 10023] }
+  ]
+}`
+
+func TestLoadACLConfig(t *testing.T) {
+	dir := t.TempDir()
+
+	t.Run("文件不存在返回 nil,nil(未配置,不是错误)", func(t *testing.T) {
+		ac, err := LoadACLConfig(filepath.Join(dir, "missing.json"))
+		if err != nil {
+			t.Fatalf("want nil error, got %v", err)
+		}
+		if ac != nil {
+			t.Fatalf("want nil config, got %+v", ac)
+		}
+	})
+
+	t.Run("坏 JSON 返回 error(绝不静默降级)", func(t *testing.T) {
+		p := filepath.Join(dir, "bad.json")
+		writeACL(t, p, `{"enabled": true,`)
+		if _, err := LoadACLConfig(p); err == nil {
+			t.Fatal("want error for malformed JSON, got nil")
+		}
+	})
+
+	t.Run("合法配置解析出全部字段", func(t *testing.T) {
+		p := filepath.Join(dir, "acl.json")
+		writeACL(t, p, validACL)
+		ac, err := LoadACLConfig(p)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if !ac.Enabled {
+			t.Error("Enabled = false, want true")
+		}
+		if len(ac.AllowDpUUIDs) != 2 {
+			t.Errorf("AllowDpUUIDs len = %d, want 2", len(ac.AllowDpUUIDs))
+		}
+		if len(ac.Targets) != 2 {
+			t.Fatalf("Targets len = %d, want 2", len(ac.Targets))
+		}
+		if len(ac.Targets[0].Domain) != 2 {
+			t.Errorf("Targets[0].Domain len = %d, want 2", len(ac.Targets[0].Domain))
+		}
+		if len(ac.Targets[1].Port) != 4 {
+			t.Errorf("Targets[1].Port len = %d, want 4", len(ac.Targets[1].Port))
+		}
+	})
+}
+
+// active() 的语义与 WARP 相反:空白名单不等于「关闭」,而等于「谁都不许进」。
+func TestACLActive_FailClosed(t *testing.T) {
+	cases := []struct {
+		name string
+		ac   *ACLConfig
+		want bool
+	}{
+		{"nil 配置 → 未启用", nil, false},
+		{"enabled=false → 未启用(唯一的合法关闭途径)", &ACLConfig{
+			Enabled:      false,
+			AllowDpUUIDs: []string{"u"},
+			Targets:      []ACLTarget{{Domain: []string{"a.com"}}},
+		}, false},
+		{"无 target → 未启用(无从拒起)", &ACLConfig{
+			Enabled:      true,
+			AllowDpUUIDs: []string{"u"},
+		}, false},
+		{"target 全为空条件 → 未启用", &ACLConfig{
+			Enabled: true,
+			Targets: []ACLTarget{{}},
+		}, false},
+		{"白名单为空但有 target → 仍启用(拒绝所有人)", &ACLConfig{
+			Enabled:      true,
+			AllowDpUUIDs: nil,
+			Targets:      []ACLTarget{{Domain: []string{"a.com"}}},
+		}, true},
+		{"完整配置 → 启用", &ACLConfig{
+			Enabled:      true,
+			AllowDpUUIDs: []string{"u"},
+			Targets:      []ACLTarget{{IPCIDR: []string{"1.2.3.4/32"}, Port: []int{443}}},
+		}, true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := tc.ac.active(); got != tc.want {
+				t.Errorf("active() = %v, want %v", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestACLCleanHelpers(t *testing.T) {
+	ac := &ACLConfig{
+		Enabled:      true,
+		AllowDpUUIDs: []string{" uuid-a ", "", "uuid-b"},
+		Targets: []ACLTarget{
+			{Domain: []string{" BRAIN.51yanmei.com ", ""}},
+			{},
+			{IPCIDR: []string{"1.2.3.4/32"}},
+		},
+	}
+	uuids := ac.cleanUUIDs()
+	if len(uuids) != 2 || uuids[0] != "uuid-a" || uuids[1] != "uuid-b" {
+		t.Errorf("cleanUUIDs() = %v, want [uuid-a uuid-b]", uuids)
+	}
+	targets := ac.cleanTargets()
+	if len(targets) != 2 {
+		t.Fatalf("cleanTargets() len = %d, want 2 (空 target 应被丢弃)", len(targets))
+	}
+	if targets[0].Domain[0] != "brain.51yanmei.com" {
+		t.Errorf("域名未规范化为小写去空白: %q", targets[0].Domain[0])
+	}
+}
+
+func TestACLTargetMatchFields(t *testing.T) {
+	tgt := ACLTarget{
+		Domain: []string{"a.com"},
+		IPCIDR: []string{"1.2.3.4/32"},
+		Port:   []int{443, 5001},
+	}
+	m := tgt.matchFields()
+	if _, ok := m["domain"]; !ok {
+		t.Error("缺 domain 字段")
+	}
+	if _, ok := m["ip_cidr"]; !ok {
+		t.Error("缺 ip_cidr 字段")
+	}
+	if _, ok := m["port"]; !ok {
+		t.Error("缺 port 字段")
+	}
+	if _, ok := m["domain_suffix"]; ok {
+		t.Error("空的 domain_suffix 不应出现在输出里")
+	}
+	// matchFields 必须每次返回新 map,否则放行/拒绝两条规则会共享同一对象,
+	// 给其中一条加 "user"/"action" 会污染另一条。
+	m2 := tgt.matchFields()
+	m2["user"] = []string{"x"}
+	if _, ok := m["user"]; ok {
+		t.Error("matchFields 返回了共享 map,放行与拒绝规则会互相污染")
+	}
+}
+
+func TestConfigACLPaths(t *testing.T) {
+	c := Config{StateDir: "/etc/pangolin-agent"}.withDefaults()
+	if want := "/etc/pangolin-agent/acl.json"; c.ACLConfigPath != want {
+		t.Errorf("ACLConfigPath = %q, want %q", c.ACLConfigPath, want)
+	}
+	if want := "/etc/pangolin-agent/acl.last-good.json"; c.ACLLastGoodPath() != want {
+		t.Errorf("ACLLastGoodPath() = %q, want %q", c.ACLLastGoodPath(), want)
+	}
+}
+
[ ]Step 2: 跑测试确认失败
+
cd server && go test ./internal/agentd/ -run 'ACL' -v
+

Expected: 编译失败，undefined: LoadACLConfig / undefined: ACLConfig / c.ACLConfigPath undefined。

+
[ ]Step 3: 写实现
+

创建 server/internal/agentd/acl.go：

+
package agentd
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+)
+
+// ACLTarget 描述一组「私有目的地」的匹配条件。字段名与取值直接对应 sing-box
+// route rule 的同名字段:同一项内多字段是 AND,字段内多值是 OR。刻意不做自研 DSL
+// —— 形状即 sing-box 语义,少一层翻译就少一类 bug。
+//
+// 典型两类:
+//   - 与公开站共用 443 的私有 vhost(brain/git) → 用 domain,依赖 sniff 取 SNI
+//   - 独占端口的服务(DSM 5001 / RDP 3389 / SSH 10022-10023) → 用 ip_cidr + port
+type ACLTarget struct {
+	Domain       []string `json:"domain,omitempty"`
+	DomainSuffix []string `json:"domain_suffix,omitempty"`
+	IPCIDR       []string `json:"ip_cidr,omitempty"`
+	Port         []int    `json:"port,omitempty"`
+}
+
+// ACLConfig 是节点本地的私有目的地访问控制表(默认 <StateDir>/acl.json)。
+// 只有 AllowDpUUIDs 里的凭证能访问 Targets 描述的目的地,其余一律 reject。
+//
+// 与 WarpConfig 的关键区别是失效方向:WARP 读不出来就不分流(fail-open)是安全的,
+// ACL 读不出来就不拦截等于把私有服务对全体用户敞开。故本类型的 active() 语义为
+// fail-closed —— 空白名单意味着「没有人」,不是「所有人」。
+type ACLConfig struct {
+	Enabled      bool        `json:"enabled"`
+	AllowDpUUIDs []string    `json:"allow_dp_uuids"`
+	Targets      []ACLTarget `json:"targets"`
+}
+
+// LoadACLConfig 读取并解析 acl.json。文件不存在 → (nil, nil)(未配置该功能,
+// 不是错误)。解析失败返回 error,由调用方决定回退到 last-good 还是告警。
+func LoadACLConfig(path string) (*ACLConfig, error) {
+	data, err := os.ReadFile(path)
+	if os.IsNotExist(err) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("agentd: read acl config %q: %w", path, err)
+	}
+	var ac ACLConfig
+	if err := json.Unmarshal(data, &ac); err != nil {
+		return nil, fmt.Errorf("agentd: parse acl config %q: %w", path, err)
+	}
+	return &ac, nil
+}
+
+// empty 报告该 target 是否没有任何匹配条件(没有条件的规则会匹配一切,危险)。
+func (t ACLTarget) empty() bool {
+	return len(t.Domain) == 0 && len(t.DomainSuffix) == 0 &&
+		len(t.IPCIDR) == 0 && len(t.Port) == 0
+}
+
+// matchFields 把 target 转成 sing-box route rule 的匹配字段。
+// 每次调用返回全新 map —— 放行与拒绝两条规则各自在其上追加 user/outbound/action,
+// 共享同一对象会互相污染。
+func (t ACLTarget) matchFields() map[string]any {
+	m := make(map[string]any, 4)
+	if len(t.Domain) > 0 {
+		m["domain"] = t.Domain
+	}
+	if len(t.DomainSuffix) > 0 {
+		m["domain_suffix"] = t.DomainSuffix
+	}
+	if len(t.IPCIDR) > 0 {
+		m["ip_cidr"] = t.IPCIDR
+	}
+	if len(t.Port) > 0 {
+		m["port"] = t.Port
+	}
+	return m
+}
+
+// active 报告本 ACL 是否应真正注入规则。
+//
+// 注意与 WarpConfig.active() 的语义差别:此处 AllowDpUUIDs 为空**不影响**返回值。
+// 空白名单是一个合法且有意义的状态 ——「谁都不许访问这些目的地」。把它当作未启用
+// 会造成 fail-open。唯一的关闭途径是显式 "enabled": false。
+func (ac *ACLConfig) active() bool {
+	if ac == nil || !ac.Enabled {
+		return false
+	}
+	return len(ac.cleanTargets()) > 0
+}
+
+// cleanUUIDs 去空白/空项后返回白名单。
+func (ac *ACLConfig) cleanUUIDs() []string {
+	if ac == nil {
+		return nil
+	}
+	out := make([]string, 0, len(ac.AllowDpUUIDs))
+	for _, u := range ac.AllowDpUUIDs {
+		if u = strings.TrimSpace(u); u != "" {
+			out = append(out, u)
+		}
+	}
+	return out
+}
+
+// cleanTargets 规范化域名(小写去空白)并丢弃无任何条件的 target。
+func (ac *ACLConfig) cleanTargets() []ACLTarget {
+	if ac == nil {
+		return nil
+	}
+	out := make([]ACLTarget, 0, len(ac.Targets))
+	for _, t := range ac.Targets {
+		c := ACLTarget{
+			Domain:       cleanHosts(t.Domain),
+			DomainSuffix: cleanHosts(t.DomainSuffix),
+			IPCIDR:       cleanStrings(t.IPCIDR),
+			Port:         t.Port,
+		}
+		if !c.empty() {
+			out = append(out, c)
+		}
+	}
+	return out
+}
+
+func cleanHosts(in []string) []string {
+	out := make([]string, 0, len(in))
+	for _, s := range in {
+		if s = strings.TrimSpace(strings.ToLower(s)); s != "" {
+			out = append(out, s)
+		}
+	}
+	return out
+}
+
+func cleanStrings(in []string) []string {
+	out := make([]string, 0, len(in))
+	for _, s := range in {
+		if s = strings.TrimSpace(s); s != "" {
+			out = append(out, s)
+		}
+	}
+	return out
+}
+

修改 server/internal/agentd/config.go：

+

① 包注释订正（原文声称 agent 保有零目的地数据，ACL 打破了这条，必须如实记录）。把第 7–10 行的 no-state invariant 段落改为：

+
// No-state invariant (doc/04 §2, doc/06 §3): the agent persists ONLY the
+// credential table (dp_uuid + expires_at) to disk. It keeps zero user identities
+// and writes no access logs. A seized node leaks only opaque dp_uuids, never
+// accounts.
+//
+// 例外(私有目的地 ACL):节点本地 acl.json 含一份 dp_uuid 白名单与目的地清单,
+// 由运营手工维护、不经控制面。它确实让节点知道「这几个 dp_uuid 享有私有访问权」
+// 以及那几个私有域名/端口 —— 这是知情接受的不变式弱化,范围仅限该文件与渲染出的
+// route 规则,不涉及账户身份,也不产生任何访问日志。设计见
+// docs/private-dest-acl-design.html §12。
+

② 在 WarpConfigPath 字段之后新增：

+
	// ACLConfigPath 指向节点本地的私有目的地访问控制表(默认 <StateDir>/acl.json)。
+	// 文件不存在 = 该功能未配置。渲染时读取,SIGHUP agent 即可生效。
+	ACLConfigPath string
+

③ 在 withDefaults() 里 WarpConfigPath 分支之后新增：

+
	if c.ACLConfigPath == "" {
+		c.ACLConfigPath = filepath.Join(c.StateDir, "acl.json")
+	}
+

④ 在文件末尾路径方法区新增：

+
// ACLLastGoodPath 是最近一次成功加载的 ACL 快照,供 agent 冷启动时在 acl.json
+// 损坏的情况下兜底(fail-closed 跨重启成立的前提)。
+func (c Config) ACLLastGoodPath() string { return filepath.Join(c.StateDir, "acl.last-good.json") }
+
[ ]Step 4: 跑测试确认通过
+
cd server && go test ./internal/agentd/ -run 'ACL|ConfigACLPaths' -v
+

Expected: PASS，全部子测试通过。

+
[ ]Step 5: 全包回归 + 提交
+
cd server && go build ./... && go test ./internal/agentd/...
+git add server/internal/agentd/acl.go server/internal/agentd/acl_test.go server/internal/agentd/config.go
+git commit -m "feat(agent): 私有目的地 ACL 配置类型与 fail-closed 加载语义"
+
+

Task 2: 由 ACL 产出 route 规则对（放行 + 兜底拒绝）

+

Files:

+ +

Interfaces:

+ +
[ ]Step 1: 写失败测试
+

追加到 server/internal/agentd/acl_test.go：

+
// rules() 必须产出「先全部放行、再全部拒绝」,且同一 target 两侧目的地条件逐字相同。
+func TestACLRules_AllowThenDeny(t *testing.T) {
+	ac := &ACLConfig{
+		Enabled:      true,
+		AllowDpUUIDs: []string{"uuid-me"},
+		Targets: []ACLTarget{
+			{Domain: []string{"brain.51yanmei.com"}},
+			{IPCIDR: []string{"182.92.213.171/32"}, Port: []int{5001}},
+		},
+	}
+	rules := ac.rules()
+	if len(rules) != 4 {
+		t.Fatalf("规则数 = %d, want 4 (2 target × 放行+拒绝)", len(rules))
+	}
+
+	// 前两条是放行:带 user + outbound,不带 action
+	for i := 0; i < 2; i++ {
+		r := rules[i].(map[string]any)
+		if _, ok := r["user"]; !ok {
+			t.Errorf("rules[%d] 放行规则缺 user", i)
+		}
+		if r["outbound"] != directOutboundTag {
+			t.Errorf("rules[%d] outbound = %v, want %q", i, r["outbound"], directOutboundTag)
+		}
+		if _, ok := r["action"]; ok {
+			t.Errorf("rules[%d] 放行规则不应带 action", i)
+		}
+	}
+	// 后两条是拒绝:带 action=reject,不带 user(对所有人生效)
+	for i := 2; i < 4; i++ {
+		r := rules[i].(map[string]any)
+		if r["action"] != "reject" {
+			t.Errorf("rules[%d] action = %v, want reject", i, r["action"])
+		}
+		if _, ok := r["user"]; ok {
+			t.Errorf("rules[%d] 拒绝规则不应带 user,否则会漏掉名单外的人", i)
+		}
+	}
+
+	// 对称性:target[0] 的放行(rules[0])与拒绝(rules[2])目的地条件必须逐字相同
+	allow0 := rules[0].(map[string]any)
+	deny0 := rules[2].(map[string]any)
+	if fmt.Sprint(allow0["domain"]) != fmt.Sprint(deny0["domain"]) {
+		t.Errorf("target0 放行/拒绝的 domain 不一致: %v vs %v", allow0["domain"], deny0["domain"])
+	}
+	allow1 := rules[1].(map[string]any)
+	deny1 := rules[3].(map[string]any)
+	if fmt.Sprint(allow1["ip_cidr"]) != fmt.Sprint(deny1["ip_cidr"]) ||
+		fmt.Sprint(allow1["port"]) != fmt.Sprint(deny1["port"]) {
+		t.Error("target1 放行/拒绝的 ip_cidr/port 不一致")
+	}
+}
+
+// 空白名单 → 不产出放行规则,但拒绝规则照出(fail-closed 的核心断言)。
+func TestACLRules_EmptyAllowlistStillDenies(t *testing.T) {
+	ac := &ACLConfig{
+		Enabled:      true,
+		AllowDpUUIDs: nil,
+		Targets:      []ACLTarget{{Domain: []string{"brain.51yanmei.com"}}},
+	}
+	rules := ac.rules()
+	if len(rules) != 1 {
+		t.Fatalf("规则数 = %d, want 1 (仅拒绝)", len(rules))
+	}
+	r := rules[0].(map[string]any)
+	if r["action"] != "reject" {
+		t.Errorf("action = %v, want reject", r["action"])
+	}
+}
+
+// 未 active(含 nil / enabled=false)→ 无规则。
+func TestACLRules_InactiveYieldsNil(t *testing.T) {
+	var nilACL *ACLConfig
+	if got := nilACL.rules(); got != nil {
+		t.Errorf("nil ACL rules() = %v, want nil", got)
+	}
+	off := &ACLConfig{Enabled: false, Targets: []ACLTarget{{Domain: []string{"a.com"}}}}
+	if got := off.rules(); got != nil {
+		t.Errorf("enabled=false rules() = %v, want nil", got)
+	}
+}
+

在 acl_test.go 的 import 块加入 "fmt"。

+
[ ]Step 2: 跑测试确认失败
+
cd server && go test ./internal/agentd/ -run 'ACLRules' -v
+

Expected: 编译失败，ac.rules undefined (type *ACLConfig has no field or method rules)。

+
[ ]Step 3: 写实现
+

在 server/internal/agentd/acl.go 末尾追加：

+
// rules 产出 ACL 的 sing-box route 规则:每个 target 一对 —— 先放行白名单、再兜底拒绝。
+//
+// 顺序是安全性的一部分,不可重排:
+//  1. 全部放行规则排在全部拒绝规则之前。不能按 target 交错(放行A/拒绝A/放行B/拒绝B),
+//     因为 target 之间可能重叠,交错会让 B 的成员被 A 的拒绝规则先命中。
+//  2. 拒绝规则不带 user 维度 —— 它要对「白名单之外的所有人」生效。
+//  3. 同一 target 的放行与拒绝,目的地条件由同一个 matchFields() 生成,保证逐字相同。
+//     任何不对称都会造成「我自己也被拒」或「有人漏网」。
+//
+// 白名单为空时只产出拒绝规则(谁都不许进),这是 fail-closed 的核心:空名单的语义是
+// 「没有人」而非「所有人」。
+func (ac *ACLConfig) rules() []any {
+	if !ac.active() {
+		return nil
+	}
+	uuids := ac.cleanUUIDs()
+	targets := ac.cleanTargets()
+
+	out := make([]any, 0, len(targets)*2)
+	if len(uuids) > 0 {
+		for _, t := range targets {
+			r := t.matchFields()
+			r["user"] = uuids
+			r["outbound"] = directOutboundTag
+			out = append(out, r)
+		}
+	}
+	for _, t := range targets {
+		r := t.matchFields()
+		r["action"] = "reject"
+		out = append(out, r)
+	}
+	return out
+}
+
[ ]Step 4: 跑测试确认通过
+
cd server && go test ./internal/agentd/ -run 'ACL' -v
+

Expected: PASS。

+
[ ]Step 5: 提交
+
cd server && go build ./... && go test ./internal/agentd/...
+git add server/internal/agentd/acl.go server/internal/agentd/acl_test.go
+git commit -m "feat(agent): ACL 渲染放行/拒绝规则对,空白名单仍拒绝"
+
+

Task 3: buildRoute 合并 ACL 与 WARP，接入渲染

+

Files:

+ +

Interfaces:

+ +
[ ]Step 1: 写失败测试
+

追加到 server/internal/agentd/acl_test.go：

+
// buildRoute 四态矩阵:ACL×WARP 开关的四种组合。
+func TestBuildRoute_Matrix(t *testing.T) {
+	acl := &ACLConfig{
+		Enabled:      true,
+		AllowDpUUIDs: []string{"uuid-me"},
+		Targets:      []ACLTarget{{Domain: []string{"brain.51yanmei.com"}}},
+	}
+	warp := &WarpConfig{
+		Enabled: true, PrivateKey: "k", PeerPublicKey: "pk",
+		Endpoint: "162.159.192.1:2408", Address: []string{"172.16.0.2/32"},
+		Domains: []string{"reddit.com"},
+	}
+
+	t.Run("都关 → 不产出 route(向后兼容)", func(t *testing.T) {
+		if got := buildRoute(nil, nil); got != nil {
+			t.Errorf("buildRoute(nil,nil) = %v, want nil", got)
+		}
+	})
+
+	t.Run("仅 WARP → sniff + warp 规则(与改动前逐字节一致)", func(t *testing.T) {
+		r := buildRoute(nil, warp)
+		rules := r["rules"].([]any)
+		if len(rules) != 2 {
+			t.Fatalf("规则数 = %d, want 2", len(rules))
+		}
+		if rules[0].(map[string]any)["action"] != "sniff" {
+			t.Error("首条不是 sniff")
+		}
+		if rules[1].(map[string]any)["outbound"] != warpOutboundTag {
+			t.Error("次条不是 warp 分流")
+		}
+		if r["final"] != directOutboundTag {
+			t.Errorf("final = %v, want %q", r["final"], directOutboundTag)
+		}
+	})
+
+	t.Run("仅 ACL → sniff + 放行 + 拒绝", func(t *testing.T) {
+		r := buildRoute(acl, nil)
+		rules := r["rules"].([]any)
+		if len(rules) != 3 {
+			t.Fatalf("规则数 = %d, want 3", len(rules))
+		}
+		if rules[0].(map[string]any)["action"] != "sniff" {
+			t.Error("首条不是 sniff")
+		}
+		if _, ok := rules[1].(map[string]any)["user"]; !ok {
+			t.Error("第二条不是放行规则")
+		}
+		if rules[2].(map[string]any)["action"] != "reject" {
+			t.Error("第三条不是拒绝规则")
+		}
+	})
+
+	t.Run("都开 → sniff + ACL(放行,拒绝) + warp,且 sniff 只出现一次", func(t *testing.T) {
+		r := buildRoute(acl, warp)
+		rules := r["rules"].([]any)
+		if len(rules) != 4 {
+			t.Fatalf("规则数 = %d, want 4", len(rules))
+		}
+		sniffs := 0
+		for _, x := range rules {
+			if x.(map[string]any)["action"] == "sniff" {
+				sniffs++
+			}
+		}
+		if sniffs != 1 {
+			t.Errorf("sniff 出现 %d 次, want 1", sniffs)
+		}
+		if rules[0].(map[string]any)["action"] != "sniff" {
+			t.Error("sniff 必须最先")
+		}
+		// ACL 全部规则必须排在 warp 之前:被拒绝的目的地不该有机会走 warp 出口
+		if rules[3].(map[string]any)["outbound"] != warpOutboundTag {
+			t.Error("warp 规则必须排在最后")
+		}
+		if rules[2].(map[string]any)["action"] != "reject" {
+			t.Error("ACL 拒绝规则必须排在 warp 之前")
+		}
+	})
+}
+
[ ]Step 2: 跑测试确认失败
+
cd server && go test ./internal/agentd/ -run 'BuildRoute' -v
+

Expected: 编译失败，undefined: buildRoute。

+
[ ]Step 3: 写实现
+

① 在 server/internal/agentd/render.go 中，把第 30 行签名与第 50–55 行的 route 注入替换为：

+
func renderSingboxConfig(creds []Cred, reality *agentv1.RealityInbound, hy2 *agentv1.Hy2Inbound, deriveKey string, warp *WarpConfig, acl *ACLConfig) ([]byte, error) {
+
	// WARP 分流(#29)只贡献 endpoints;route 块由 buildRoute 统一产出,因为它现在要
+	// 同时容纳 ACL 规则 —— 原先 cfg["route"] = warp.warpRoute() 是整块覆盖,直接赋值
+	// 会把对方的规则干掉。
+	if warp.active() {
+		cfg["endpoints"] = []any{warp.warpEndpoint()}
+	}
+	if route := buildRoute(acl, warp); route != nil {
+		cfg["route"] = route
+	}
+

② 在 render.go 的 statsUsers 之前插入：

+
// buildRoute 合并私有目的地 ACL 与 WARP 分流,产出单一 route 块。
+// 两者都未激活时返回 nil —— 不产出 route 字段,与旧配置逐字节一致(向后兼容)。
+//
+// 规则顺序是安全语义的一部分:
+//  1. {"action":"sniff"} 唯一且最先。域名匹配依赖它取 TLS SNI(客户端多半发的是
+//     已解析 IP),WARP 与 ACL 都需要,故在此统一产出一次,不由各自重复追加。
+//  2. ACL 规则(放行在前、拒绝在后)整体排在 WARP 之前:被 ACL 拒绝的目的地永远
+//     不该还有机会被路由到 warp 出口。
+//  3. final 恒为 direct。
+func buildRoute(acl *ACLConfig, warp *WarpConfig) map[string]any {
+	aclRules := acl.rules()
+	warpActive := warp.active()
+	if len(aclRules) == 0 && !warpActive {
+		return nil
+	}
+
+	rules := make([]any, 0, len(aclRules)+2)
+	rules = append(rules, map[string]any{"action": "sniff"})
+	rules = append(rules, aclRules...)
+	if warpActive {
+		rules = append(rules, map[string]any{
+			"domain_suffix": warp.cleanDomains(),
+			"outbound":      warpOutboundTag,
+		})
+	}
+	return map[string]any{"rules": rules, "final": directOutboundTag}
+}
+

③ 删除 server/internal/agentd/warp.go 第 111–121 行的 warpRoute() 方法及其上方注释块（唯一调用方已被 buildRoute 取代；grep -rn "warpRoute()" internal/agentd/ 应无剩余命中）。

+

④ 订正 render.go 第 14 行的隐私不变式注释。原文：

+
// Only the opaque dp_uuid is ever written; no account identity touches the node.
+

改为：

+
// Only the opaque dp_uuid is ever written; no account identity touches the node.
+//
+// 例外(私有目的地 ACL):若节点配置了 acl.json,渲染出的 route 规则会含一份享有私有
+// 访问权的 dp_uuid 白名单与对应的私有域名/端口。它仍不含任何账户身份(email/user_id),
+// 但确实让节点知道「这几个 dp_uuid 属于同一组权限」—— 知情接受的不变式弱化,
+// 设计与权衡见 docs/private-dest-acl-design.html §12。
+
+⑤ 修改 `server/internal/agentd/singbox.go` 第 326 行，补一个 nil 实参（Task 4 会替换成真实 ACL）：
+
+

return renderSingboxConfig(creds, reality, hy2, s.cfg.DeriveKey, warp, nil)

+

+- [ ] **Step 4: 跑测试确认通过**
+
+

cd server && go test ./internal/agentd/ -run 'BuildRoute|Warp|Render' -v

+

+Expected: PASS。特别确认既有的 `TestRender_NoWarp_NoRouteSection` 与 `TestRender_Warp_InjectsEndpointAndRoute` 仍绿——这两条守着向后兼容。
+
+- [ ] **Step 5: 提交**
+
+

cd server && go build ./... && go test ./internal/agentd/...

+

git add server/internal/agentd/render.go server/internal/agentd/warp.go server/internal/agentd/singbox.go server/internal/agentd/acl_test.go

+

git commit -m "refactor(agent): route 块改由 buildRoute 统一产出,合并 ACL 与 WARP"

+

+---
+
+### Task 4: 渲染时读取 ACL，last-good 内存 + 落盘兜底
+
+**Files:**
+- Modify: `server/internal/agentd/singbox.go:49-74`（`SingBox` 增 `lastGoodACL` 字段）、`:308-327`（`RenderConfig` 读 ACL）
+- Modify: `server/internal/agentd/acl.go`（新增 `persistACL`）
+- Modify: `server/internal/agentd/acl_test.go`（追加 last-good 测试）
+
+**Interfaces:**
+- Consumes: Task 1 的 `LoadACLConfig` / `Config.ACLConfigPath` / `Config.ACLLastGoodPath()`；Task 3 的 `renderSingboxConfig` 六参签名；既有包内函数 `atomicWrite(path string, data []byte, perm os.FileMode) error`
+- Produces: `func (s *SingBox) loadACL() *ACLConfig`；`func persistACL(path string, ac *ACLConfig) error`
+
+- [ ] **Step 1: 写失败测试**
+
+追加到 `server/internal/agentd/acl_test.go`：
+
+

// 成功加载后必须把快照落盘,否则 agent 一重启 fail-closed 就失效。

+

func TestACL_PersistsLastGoodOnLoad(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)

+

}

+

if _, err := os.Stat(cfg.ACLLastGoodPath()); err != nil {

+

t.Fatalf("last-good 未落盘: %v", err)

+

}

+

}

+

// acl.json 被改坏 → 规则不能消失(内存 last-good 兜底)。

+

func TestACL_BrokenFileKeepsInMemoryLastGood(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,) // 手抖写坏

+

data, err := sb.RenderConfig()

+

if err != nil {

+

t.Fatal(err)

+

}

+

if !strings.Contains(string(data), "reject") {

+

t.Fatal("acl.json 坏掉后拒绝规则消失了 —— 这是 fail-open,私有服务已敞开")

+

}

+

}

+

// 新 agent 实例(模拟进程重启)+ 坏 acl.json → 磁盘 last-good 兜底,规则仍在。

+

func TestACL_ColdStartFallsBackToDiskLastGood(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)

+

}

+

writeACL(t, cfg.ACLConfigPath, not json at all)

+

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,私有服务已敞开")

+

}

+

}

+

// 从未配置过(无 acl.json 也无 last-good)→ 不产出 route,且不误报。

+

func TestACL_NeverConfiguredYieldsNoRoute(t *testing.T) {

+

cfg := testConfig(t)

+

sb := NewSingBox(cfg, nil)

+

sb.ApplyConfig(sampleSnapshot(&agentv1.Credential{DpUUID: "aaaa", Protocol: agentv1.ProtocolBoth}), true)

+

data, err := sb.RenderConfig()

+

if err != nil {

+

t.Fatal(err)

+

}

+

var m map[string]any

+

if err := json.Unmarshal(data, &m); err != nil {

+

t.Fatal(err)

+

}

+

if _, ok := m["route"]; ok {

+

t.Error("未配置 ACL 也未启用 WARP,不应产出 route 块")

+

}

+

}

+

+在 `acl_test.go` 的 import 块补齐 `"encoding/json"`、`"strings"`，以及 `agentv1 "github.com/wangjia/pangolin/server/internal/pb/agentv1"`。
+
+- [ ] **Step 2: 跑测试确认失败**
+
+

cd server && go test ./internal/agentd/ -run 'TestACL_' -v

+

+Expected: `TestACL_PersistsLastGoodOnLoad` 失败（last-good 未落盘），`TestACL_BrokenFile...` / `TestACL_ColdStart...` 失败（渲染结果里没有 reject，因为 Task 3 传的是 nil）。
+
+- [ ] **Step 3: 写实现**
+
+① 在 `server/internal/agentd/acl.go` 末尾追加：
+
+

// persistACL 把成功加载的 ACL 快照原子写到 path,供 agent 冷启动兜底。

+

func persistACL(path string, ac *ACLConfig) error {

+

data, err := json.MarshalIndent(ac, "", " ")

+

if err != nil {

+

return fmt.Errorf("agentd: marshal acl snapshot: %w", err)

+

}

+

return atomicWrite(path, data, 0o600)

+

}

+

+② 在 `server/internal/agentd/singbox.go` 的 `SingBox` 结构体中，`configVersion int64` 之后新增字段：
+
+

// lastGoodACL 是最近一次成功加载的私有目的地 ACL。acl.json 读坏时回退到它,

+

// 而不是像 WARP 那样降级为「不启用」—— 对访问控制,降级即敞开。

+

lastGoodACL *ACLConfig

+

+③ 在 `server/internal/agentd/singbox.go` 的 `RenderConfig` 中，把 WARP 加载之后的部分替换为：
+
+

// WARP 分流配置每次渲染读一次:编辑 warp.json 后任一渲染(或 agent 重启)即生效(#29)。

+

// 读失败(坏 JSON)仅记日志、按未启用处理,绝不因坏配置产出无法启动的 sing-box 配置。

+

warp, err := LoadWarpConfig(s.cfg.WarpConfigPath)

+

if err != nil {

+

logf("[warp] load %s failed, WARP routing disabled: %v", s.cfg.WarpConfigPath, err)

+

warp = nil

+

}

+

return renderSingboxConfig(creds, reality, hy2, s.cfg.DeriveKey, warp, s.loadACL())

+

}

+

// loadACL 读取私有目的地 ACL,并维护 last-good 兜底。

+

//

+

// 语义刻意与 WARP 相反:WARP 读失败静默降级为「不分流」是安全的,ACL 读失败若也

+

// 降级为「不启用」,等于把私有服务对全体 pangolin 用户敞开,而且是静默的。故:

+

// - 成功 → 更新内存 last-good 并落盘,供本进程后续与下次冷启动使用

+

// - 失败/文件消失 → 回退内存 last-good,再回退磁盘 last-good,规则不消失

+

// - 两级 last-good 都没有 → 只能不产出规则(白名单与目的地清单同在一个文件,

+

// 文件全丢时连「该拒绝哪些目的地」都无从得知),此时必须大声告警

+

func (s *SingBox) loadACL() *ACLConfig {

+

acl, err := LoadACLConfig(s.cfg.ACLConfigPath)

+

switch {

+

case err == nil && acl != nil:

+

s.mu.Lock()

+

s.lastGoodACL = acl

+

s.mu.Unlock()

+

if perr := persistACL(s.cfg.ACLLastGoodPath(), acl); perr != nil {

+

logf("[acl] persist last-good to %s failed: %v", s.cfg.ACLLastGoodPath(), perr)

+

}

+

return acl

+

case err != nil:

+

logf("[acl] ERROR load %s failed: %v", s.cfg.ACLConfigPath, err)

+

}

+

s.mu.Lock()

+

lg := s.lastGoodACL

+

s.mu.Unlock()

+

if lg != nil {

+

logf("[acl] falling back to in-memory last-good ACL")

+

return lg

+

}

+

disk, derr := LoadACLConfig(s.cfg.ACLLastGoodPath())

+

if derr == nil && disk != nil {

+

logf("[acl] 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 {

+

logf("[acl] ALERT acl.json is broken and no last-good snapshot exists — "+

+

"private destinations are UNPROTECTED (path=%s)", s.cfg.ACLConfigPath)

+

}

+

return nil

+

}

+

+- [ ] **Step 4: 跑测试确认通过**
+
+

cd server && go test ./internal/agentd/ -run 'TestACL_' -v

+

+Expected: PASS，四条全绿。
+
+- [ ] **Step 5: 提交**
+
+

cd server && go build ./... && go test ./internal/agentd/...

+

git add server/internal/agentd/acl.go server/internal/agentd/singbox.go server/internal/agentd/acl_test.go

+

git commit -m "feat(agent): 渲染时读取 ACL,内存+磁盘 last-good 保证 fail-closed 跨重启"

+

+---
+
+### Task 5: SIGHUP 触发重渲染（避免重启踢掉全部在线用户）
+
+**Files:**
+- Modify: `server/internal/agentd/singbox.go`（新增导出的 `Refresh()`）
+- Modify: `server/cmd/agent/main.go:44-45`（注册 SIGHUP 处理）
+- Modify: `server/internal/agentd/acl_test.go`（追加 `Refresh` 测试）
+
+**Interfaces:**
+- Consumes: 既有 `(*SingBox).markDirty()`（未导出）、`(*Agent).SingBox() *SingBox`（`agent.go:83`，已导出）
+- Produces: `func (s *SingBox) Refresh()` —— 外部触发一次重渲染
+
+**为什么不用 `systemctl restart pangolin-agent`：** 新进程内 `s.started == false`（`singbox.go:64-67`），首次渲染会走 `restarter.Restart()` 即 `systemctl restart sing-box`，**全部在线用户瞬断**。SIGHUP 走的是既有的 debounce → `writeAndRestart` → `Reload()`（SIGHUP 热重载）路径，不断线。
+
+- [ ] **Step 1: 写失败测试**
+
+追加到 `server/internal/agentd/acl_test.go`：
+
+

// Refresh() 必须能触发一次重渲染(经 debounce 循环),用于「编辑 acl.json 后

+

// systemctl reload pangolin-agent」而不必重启 agent(重启会冷启 sing-box 踢人)。

+

func TestSingBoxRefresh_TriggersRender(t *testing.T) {

+

cfg := testConfig(t)

+

writeACL(t, cfg.ACLConfigPath, validACL)

+

fr := &fakeRestarter{}

+

sb := NewSingBox(cfg, fr)

+

sb.ApplyConfig(sampleSnapshot(&agentv1.Credential{DpUUID: "aaaa", Protocol: agentv1.ProtocolBoth}), true)

+

ctx, cancel := context.WithCancel(context.Background())

+

defer cancel()

+

go sb.Run(ctx)

+

// 等首次渲染落地(ApplyConfig 已 markDirty)

+

eventually(t, 2*time.Second, func() bool {

+

_, err := os.Stat(cfg.SingboxConfigPath)

+

return err == nil

+

}, "首次渲染写出配置")

+

// 断言 reloadCount 而非 count:首次渲染已冷启动过(started=true),此后的重渲染

+

// 一律走 Reload(SIGHUP 热重载),Restart 计数不会再增加。断言错计数器会假失败。

+

before := fr.reloadCount()

+

sb.Refresh()

+

eventually(t, 2*time.Second, func() bool { return fr.reloadCount() > before }, "Refresh 触发了热重载")

+

}

+

+在 `acl_test.go` 的 import 块补齐 `"context"` 与 `"time"`。
+
+> 复用 `singbox_test.go:17-47` 既有的 `fakeRestarter`（`count()` 返回 Restart 次数、`reloadCount()` 返回 Reload 次数）与 `integration_test.go:248` 的 `eventually(t *testing.T, timeout time.Duration, fn func() bool, msg string)`。
+
+- [ ] **Step 2: 跑测试确认失败**
+
+

cd server && go test ./internal/agentd/ -run 'Refresh' -v

+

+Expected: 编译失败，`sb.Refresh undefined`。
+
+- [ ] **Step 3: 写实现**
+
+① 在 `server/internal/agentd/singbox.go` 的 `markDirty` 之后追加：
+
+

// Refresh 请求一次重渲染。供 agent 收到 SIGHUP 时调用,使编辑节点本地配置文件

+

// (acl.json / warp.json)后无需重启进程即可生效 —— 重启 agent 会让 sing-box 走

+

// 冷启动(Restart),把全部在线用户踢下线。

+

func (s *SingBox) Refresh() { s.markDirty() }

+

+② 修改 `server/cmd/agent/main.go`，把第 44–45 行替换为：
+
+

ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)

+

defer stop()

+

// SIGHUP 重读节点本地配置(acl.json / warp.json)并重渲染。走 sing-box 的 SIGHUP

+

// 热重载路径,在线用户不掉线;重启 agent 则会冷启 sing-box,把所有人踢下线。

+

hup := make(chan os.Signal, 1)

+

signal.Notify(hup, syscall.SIGHUP)

+

defer signal.Stop(hup)

+

go func() {

+

for {

+

select {

+

case <-ctx.Done():

+

return

+

case <-hup:

+

log.Printf("[pangolin-agent] SIGHUP: re-reading node-local config (acl.json/warp.json)")

+

agent.SingBox().Refresh()

+

}

+

}

+

}()

+

+`os` 与 `log` 已在该文件 import 中（`os` 见 `env()` 用到的 `os.LookupEnv`）；若 `go build` 报缺失，按提示补齐。
+
+- [ ] **Step 4: 跑测试确认通过**
+
+

cd server && go build ./... && go test ./internal/agentd/ -run 'Refresh' -v

+

+Expected: PASS。
+
+- [ ] **Step 5: 提交**
+
+

cd server && go build ./... && go test ./internal/agentd/...

+

git add server/internal/agentd/singbox.go server/internal/agentd/acl_test.go server/cmd/agent/main.go

+

git commit -m "feat(agent): SIGHUP 重读节点本地配置并热重渲染,不踢在线用户"

+

+---
+
+### Task 6: 节点配置样例与运维文档
+
+**Files:**
+- Create: `deploy/single-node/acl.json.example`
+- Modify: `docs/private-dest-acl-design.html`（把 §8 runbook 里的占位符换成指向样例文件）
+
+**Interfaces:**
+- Consumes: Task 1 定义的 `ACLConfig` JSON 形状
+- Produces: 可直接复制到 `/etc/pangolin-agent/acl.json` 的样例
+
+- [ ] **Step 1: 写样例文件**
+
+创建 `deploy/single-node/acl.json.example`：
+
+

{

+

"_comment": "私有目的地访问控制。复制到 /etc/pangolin-agent/acl.json 并填入自己的 dp_uuid。改完执行 systemctl reload pangolin-agent（不要 restart，restart 会冷启 sing-box 踢掉全部在线用户）。",

+

"enabled": true,

+

"allow_dp_uuids": [

+

"TODO-设备级-dp-uuid",

+

"TODO-账户级-dp-uuid-供-sub-订阅链接用"

+

],

+

"targets": [

+

{

+

"_comment": "与公开站共用 ali:443 的私有 vhost，只能靠 SNI 区分",

+

"domain": ["brain.51yanmei.com", "git.51yanmei.com"]

+

},

+

{

+

"_comment": "独占端口的服务：DSM 5001 / RDP 3389 / NAS SSH 10022 / Win SSH 10023",

+

"ip_cidr": ["182.92.213.171/32"],

+

"port": [5001, 3389, 10022, 10023]

+

}

+

]

+

}

+

+> `_comment` 字段会被 `encoding/json` 忽略（`ACLConfig` 无对应字段且未启用 `DisallowUnknownFields`），可安全保留作自文档。样例里的 `TODO-` 值是**样例文件**的占位，不是计划的占位——真实 uuid 属 PII 级标识，不入 git，由运维按 Step 2 的 SQL 现取现填。
+
+- [ ] **Step 2: 验证样例能被解析且渲染出预期规则**
+
+

cd server && cat > /tmp/acl_example_check.go <<'EOF'

+

package main

+

import (

+

"fmt"

+

"os"

+

"github.com/wangjia/pangolin/server/internal/agentd"

+

)

+

func main() {

+

ac, err := agentd.LoadACLConfig(os.Args[1])

+

if err != nil {

+

fmt.Println("FAIL:", err)

+

os.Exit(1)

+

}

+

fmt.Printf("OK enabled=%v uuids=%d targets=%d\n", ac.Enabled, len(ac.AllowDpUUIDs), len(ac.Targets))

+

}

+

EOF

+

go run /tmp/acl_example_check.go ../deploy/single-node/acl.json.example && rm /tmp/acl_example_check.go

+

+Expected: `OK enabled=true uuids=2 targets=2`
+
+- [ ] **Step 3: 更新设计文档的 runbook 指向**
+
+在 `docs/private-dest-acl-design.html` 的 §8 首段（`<h2>8. 名单维护 Runbook</h2>` 之后的第一个 `<p>`）末尾追加一句：
+
+

样例文件见 <code>deploy/single-node/acl.json.example</code>，复制到 <code>/etc/pangolin-agent/acl.json</code> 后按下方 SQL 填入 uuid。

+

+- [ ] **Step 4: 提交**
+
+

cd server && go build ./... && go test ./internal/agentd/...

+

git add deploy/single-node/acl.json.example docs/private-dest-acl-design.html

+

git commit -m "docs(agent): 私有目的地 ACL 配置样例与 runbook 指向"

+

+---
+
+## 上线验收（人工，非代码任务）
+
+代码合并后在 pangolin1 上执行。**先备份现网 sing-box 配置**：`sudo cp /etc/sing-box/config.json /etc/sing-box/config.json.bak-$(date +%F)`（此处 `$(...)` 在服务器交互 shell 中手动执行，不经 agent）。
+
+1. 取白名单 uuid（`UNION` 那一半是账户级 dp_uuid，供 `/sub` 订阅链接用，**漏了会把自己锁在外面**）：
+   ```sql
+   sqlite3 /var/lib/pangolin/pangolin.db \
+     "SELECT d.dp_uuid FROM devices d JOIN users u ON u.id = d.user_id
+       WHERE u.email = '<我的邮箱>' AND d.dp_uuid IS NOT NULL
+      UNION
+      SELECT dp_uuid FROM users WHERE email = '<我的邮箱>';"
+   ```
+2. 写 `/etc/pangolin-agent/acl.json`（权限 `0600`，属主 `pangolin`），`systemctl reload pangolin-agent`。
+3. `journalctl -u pangolin-agent -n 30` 确认已重渲染、无 `[acl] ERROR` / `[acl] ALERT`。
+4. `sudo python3 -c "import json;print(json.load(open('/etc/sing-box/config.json'))['route'])"` 确认规则顺序为 sniff → 放行 → 拒绝 → warp。
+5. **我的设备**：brain 首页 200、DSM 5001 可登录、`ssh nas-r` 通。
+6. **另一账号的设备**：以上全部被拒（连接被 reject，不是超时）。
+7. **公开站不受影响**：jiu / travel / sudoku / pay 在两个账号下均正常。
+8. **WARP 未被破坏**：reddit 仍走 warp 出口。
+9. **fail-closed 实证**：把 `acl.json` 改坏 → `systemctl reload pangolin-agent` → 规则仍在、日志有 ERROR；恢复文件。
+10. **不断线实证**：reload 期间另一台设备保持连接不掉。
+
+## 不在本计划范围内
+
+- 给 brain 加 mTLS / basic auth 作纵深防御（与本计划正交，约一小时，另开）
+- 补 `assertNoIdentityFields` 对渲染配置的覆盖（既有缺口，本计划不扩大也不修复）
+- 控制面下发 ACL（演进路径见设计文档 §11，届时渲染层可原样保留）
+
+
+ + diff --git a/docs/superpowers/plans/2026-07-23-private-dest-acl.md b/docs/superpowers/plans/2026-07-23-private-dest-acl.md new file mode 100644 index 0000000..5aec700 --- /dev/null +++ b/docs/superpowers/plans/2026-07-23-private-dest-acl.md @@ -0,0 +1,1227 @@ +# 私有目的地访问控制（节点侧 ACL）Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 在节点 sing-box 上加一道按 dp_uuid 的闸，使家庭内网服务（brain/nas/git/win.51yanmei.com）只对白名单凭证开放，而不是对所有 pangolin 用户开放。 + +**Architecture:** 节点本地 `acl.json`（照 `warp.json` 骨架）声明「白名单 dp_uuid + 私有目的地清单」；agent 每次渲染 sing-box 配置时读取，为每个目的地产出一对 route 规则——先放行白名单、再兜底拒绝。ACL 规则与 WARP 规则由新的 `buildRoute()` 合并进同一个 route 块（现状是 WARP 整块覆盖 `cfg["route"]`，直接赋值会把对方干掉）。控制面、数据库、proto、客户端、管理后台一律不动。 + +**Tech Stack:** Go 1.2x，标准库；sing-box 1.13.13 配置语义；测试为同包 `*_test.go` + `t.TempDir()`，`go test ./internal/agentd/...`。 + +## Global Constraints + +- 设计真相源：`docs/private-dest-acl-design.html`。本计划的任何取舍以该文档为准。 +- **改动收敛在 `server/internal/agentd/` + `server/cmd/agent/main.go`**。不得新增 migration、不得改 proto、不得改控制面（`internal/httpapi`、`internal/nodes`）、不得改客户端。 +- **失效方向必须 fail-closed**，与 `warp.go` 的 fail-open 先例相反。具体：读失败保留 last-good；`allow_dp_uuids: []` 仍产出拒绝规则；仅 `"enabled": false` 能关闭。 +- **route 规则顺序硬约束**：`{"action":"sniff"}` 唯一且最先 → ACL 放行 → ACL 拒绝 → WARP 分流。 +- **放行与拒绝的目的地条件必须逐字相同**，且全部放行规则排在全部拒绝规则之前（目的地可能重叠，交错会漏）。 +- 向后兼容：ACL 与 WARP 均未启用时，渲染结果必须与改动前**逐字节一致**（现有测试 `TestRender_NoWarp_NoRouteSection` 守这条）。 +- 每个 Task 结束必须 `cd server && go build ./... && go test ./internal/agentd/...` 全绿再提交。 +- Commit message 前缀用 `feat(agent):` / `test(agent):` / `refactor(agent):`。 + +--- + +### Task 1: ACL 配置类型、加载与 fail-closed 的 active() + +**Files:** +- Create: `server/internal/agentd/acl.go` +- Create: `server/internal/agentd/acl_test.go` +- Modify: `server/internal/agentd/config.go`（新增 `ACLConfigPath` 字段、`withDefaults` 分支、`ACLLastGoodPath()`，并订正包注释） + +**Interfaces:** +- Produces: `type ACLTarget struct{ Domain, DomainSuffix, IPCIDR []string; Port []int }`；`type ACLConfig struct{ Enabled bool; AllowDpUUIDs []string; Targets []ACLTarget }`；`func LoadACLConfig(path string) (*ACLConfig, error)`；`func (ac *ACLConfig) active() bool`；`func (ac *ACLConfig) cleanUUIDs() []string`；`func (ac *ACLConfig) cleanTargets() []ACLTarget`；`func (t ACLTarget) empty() bool`；`func (t ACLTarget) matchFields() map[string]any`；`func (c Config) ACLLastGoodPath() string` +- Consumes: 无（本任务是叶子） + +- [ ] **Step 1: 写失败测试** + +创建 `server/internal/agentd/acl_test.go`： + +```go +package agentd + +import ( + "os" + "path/filepath" + "testing" +) + +// writeACL 把 acl.json 写到指定路径。 +func writeACL(t *testing.T, path, body string) { + t.Helper() + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, []byte(body), 0o600); err != nil { + t.Fatal(err) + } +} + +const validACL = `{ + "enabled": true, + "allow_dp_uuids": ["uuid-me-1", "uuid-me-sub"], + "targets": [ + { "domain": ["brain.51yanmei.com", "git.51yanmei.com"] }, + { "ip_cidr": ["182.92.213.171/32"], "port": [5001, 3389, 10022, 10023] } + ] +}` + +func TestLoadACLConfig(t *testing.T) { + dir := t.TempDir() + + t.Run("文件不存在返回 nil,nil(未配置,不是错误)", func(t *testing.T) { + ac, err := LoadACLConfig(filepath.Join(dir, "missing.json")) + if err != nil { + t.Fatalf("want nil error, got %v", err) + } + if ac != nil { + t.Fatalf("want nil config, got %+v", ac) + } + }) + + t.Run("坏 JSON 返回 error(绝不静默降级)", func(t *testing.T) { + p := filepath.Join(dir, "bad.json") + writeACL(t, p, `{"enabled": true,`) + if _, err := LoadACLConfig(p); err == nil { + t.Fatal("want error for malformed JSON, got nil") + } + }) + + t.Run("合法配置解析出全部字段", func(t *testing.T) { + p := filepath.Join(dir, "acl.json") + writeACL(t, p, validACL) + ac, err := LoadACLConfig(p) + if err != nil { + t.Fatal(err) + } + if !ac.Enabled { + t.Error("Enabled = false, want true") + } + if len(ac.AllowDpUUIDs) != 2 { + t.Errorf("AllowDpUUIDs len = %d, want 2", len(ac.AllowDpUUIDs)) + } + if len(ac.Targets) != 2 { + t.Fatalf("Targets len = %d, want 2", len(ac.Targets)) + } + if len(ac.Targets[0].Domain) != 2 { + t.Errorf("Targets[0].Domain len = %d, want 2", len(ac.Targets[0].Domain)) + } + if len(ac.Targets[1].Port) != 4 { + t.Errorf("Targets[1].Port len = %d, want 4", len(ac.Targets[1].Port)) + } + }) +} + +// active() 的语义与 WARP 相反:空白名单不等于「关闭」,而等于「谁都不许进」。 +func TestACLActive_FailClosed(t *testing.T) { + cases := []struct { + name string + ac *ACLConfig + want bool + }{ + {"nil 配置 → 未启用", nil, false}, + {"enabled=false → 未启用(唯一的合法关闭途径)", &ACLConfig{ + Enabled: false, + AllowDpUUIDs: []string{"u"}, + Targets: []ACLTarget{{Domain: []string{"a.com"}}}, + }, false}, + {"无 target → 未启用(无从拒起)", &ACLConfig{ + Enabled: true, + AllowDpUUIDs: []string{"u"}, + }, false}, + {"target 全为空条件 → 未启用", &ACLConfig{ + Enabled: true, + Targets: []ACLTarget{{}}, + }, false}, + {"白名单为空但有 target → 仍启用(拒绝所有人)", &ACLConfig{ + Enabled: true, + AllowDpUUIDs: nil, + Targets: []ACLTarget{{Domain: []string{"a.com"}}}, + }, true}, + {"完整配置 → 启用", &ACLConfig{ + Enabled: true, + AllowDpUUIDs: []string{"u"}, + Targets: []ACLTarget{{IPCIDR: []string{"1.2.3.4/32"}, Port: []int{443}}}, + }, true}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + if got := tc.ac.active(); got != tc.want { + t.Errorf("active() = %v, want %v", got, tc.want) + } + }) + } +} + +func TestACLCleanHelpers(t *testing.T) { + ac := &ACLConfig{ + Enabled: true, + AllowDpUUIDs: []string{" uuid-a ", "", "uuid-b"}, + Targets: []ACLTarget{ + {Domain: []string{" BRAIN.51yanmei.com ", ""}}, + {}, + {IPCIDR: []string{"1.2.3.4/32"}}, + }, + } + uuids := ac.cleanUUIDs() + if len(uuids) != 2 || uuids[0] != "uuid-a" || uuids[1] != "uuid-b" { + t.Errorf("cleanUUIDs() = %v, want [uuid-a uuid-b]", uuids) + } + targets := ac.cleanTargets() + if len(targets) != 2 { + t.Fatalf("cleanTargets() len = %d, want 2 (空 target 应被丢弃)", len(targets)) + } + if targets[0].Domain[0] != "brain.51yanmei.com" { + t.Errorf("域名未规范化为小写去空白: %q", targets[0].Domain[0]) + } +} + +func TestACLTargetMatchFields(t *testing.T) { + tgt := ACLTarget{ + Domain: []string{"a.com"}, + IPCIDR: []string{"1.2.3.4/32"}, + Port: []int{443, 5001}, + } + m := tgt.matchFields() + if _, ok := m["domain"]; !ok { + t.Error("缺 domain 字段") + } + if _, ok := m["ip_cidr"]; !ok { + t.Error("缺 ip_cidr 字段") + } + if _, ok := m["port"]; !ok { + t.Error("缺 port 字段") + } + if _, ok := m["domain_suffix"]; ok { + t.Error("空的 domain_suffix 不应出现在输出里") + } + // matchFields 必须每次返回新 map,否则放行/拒绝两条规则会共享同一对象, + // 给其中一条加 "user"/"action" 会污染另一条。 + m2 := tgt.matchFields() + m2["user"] = []string{"x"} + if _, ok := m["user"]; ok { + t.Error("matchFields 返回了共享 map,放行与拒绝规则会互相污染") + } +} + +func TestConfigACLPaths(t *testing.T) { + c := Config{StateDir: "/etc/pangolin-agent"}.withDefaults() + if want := "/etc/pangolin-agent/acl.json"; c.ACLConfigPath != want { + t.Errorf("ACLConfigPath = %q, want %q", c.ACLConfigPath, want) + } + if want := "/etc/pangolin-agent/acl.last-good.json"; c.ACLLastGoodPath() != want { + t.Errorf("ACLLastGoodPath() = %q, want %q", c.ACLLastGoodPath(), want) + } +} +``` + +- [ ] **Step 2: 跑测试确认失败** + +```bash +cd server && go test ./internal/agentd/ -run 'ACL' -v +``` + +Expected: 编译失败，`undefined: LoadACLConfig` / `undefined: ACLConfig` / `c.ACLConfigPath undefined`。 + +- [ ] **Step 3: 写实现** + +创建 `server/internal/agentd/acl.go`： + +```go +package agentd + +import ( + "encoding/json" + "fmt" + "os" + "strings" +) + +// ACLTarget 描述一组「私有目的地」的匹配条件。字段名与取值直接对应 sing-box +// route rule 的同名字段:同一项内多字段是 AND,字段内多值是 OR。刻意不做自研 DSL +// —— 形状即 sing-box 语义,少一层翻译就少一类 bug。 +// +// 典型两类: +// - 与公开站共用 443 的私有 vhost(brain/git) → 用 domain,依赖 sniff 取 SNI +// - 独占端口的服务(DSM 5001 / RDP 3389 / SSH 10022-10023) → 用 ip_cidr + port +type ACLTarget struct { + Domain []string `json:"domain,omitempty"` + DomainSuffix []string `json:"domain_suffix,omitempty"` + IPCIDR []string `json:"ip_cidr,omitempty"` + Port []int `json:"port,omitempty"` +} + +// ACLConfig 是节点本地的私有目的地访问控制表(默认 /acl.json)。 +// 只有 AllowDpUUIDs 里的凭证能访问 Targets 描述的目的地,其余一律 reject。 +// +// 与 WarpConfig 的关键区别是失效方向:WARP 读不出来就不分流(fail-open)是安全的, +// ACL 读不出来就不拦截等于把私有服务对全体用户敞开。故本类型的 active() 语义为 +// fail-closed —— 空白名单意味着「没有人」,不是「所有人」。 +type ACLConfig struct { + Enabled bool `json:"enabled"` + AllowDpUUIDs []string `json:"allow_dp_uuids"` + Targets []ACLTarget `json:"targets"` +} + +// LoadACLConfig 读取并解析 acl.json。文件不存在 → (nil, nil)(未配置该功能, +// 不是错误)。解析失败返回 error,由调用方决定回退到 last-good 还是告警。 +func LoadACLConfig(path string) (*ACLConfig, error) { + data, err := os.ReadFile(path) + if os.IsNotExist(err) { + return nil, nil + } + if err != nil { + return nil, fmt.Errorf("agentd: read acl config %q: %w", path, err) + } + var ac ACLConfig + if err := json.Unmarshal(data, &ac); err != nil { + return nil, fmt.Errorf("agentd: parse acl config %q: %w", path, err) + } + return &ac, nil +} + +// empty 报告该 target 是否没有任何匹配条件(没有条件的规则会匹配一切,危险)。 +func (t ACLTarget) empty() bool { + return len(t.Domain) == 0 && len(t.DomainSuffix) == 0 && + len(t.IPCIDR) == 0 && len(t.Port) == 0 +} + +// matchFields 把 target 转成 sing-box route rule 的匹配字段。 +// 每次调用返回全新 map —— 放行与拒绝两条规则各自在其上追加 user/outbound/action, +// 共享同一对象会互相污染。 +func (t ACLTarget) matchFields() map[string]any { + m := make(map[string]any, 4) + if len(t.Domain) > 0 { + m["domain"] = t.Domain + } + if len(t.DomainSuffix) > 0 { + m["domain_suffix"] = t.DomainSuffix + } + if len(t.IPCIDR) > 0 { + m["ip_cidr"] = t.IPCIDR + } + if len(t.Port) > 0 { + m["port"] = t.Port + } + return m +} + +// active 报告本 ACL 是否应真正注入规则。 +// +// 注意与 WarpConfig.active() 的语义差别:此处 AllowDpUUIDs 为空**不影响**返回值。 +// 空白名单是一个合法且有意义的状态 ——「谁都不许访问这些目的地」。把它当作未启用 +// 会造成 fail-open。唯一的关闭途径是显式 "enabled": false。 +func (ac *ACLConfig) active() bool { + if ac == nil || !ac.Enabled { + return false + } + return len(ac.cleanTargets()) > 0 +} + +// cleanUUIDs 去空白/空项后返回白名单。 +func (ac *ACLConfig) cleanUUIDs() []string { + if ac == nil { + return nil + } + out := make([]string, 0, len(ac.AllowDpUUIDs)) + for _, u := range ac.AllowDpUUIDs { + if u = strings.TrimSpace(u); u != "" { + out = append(out, u) + } + } + return out +} + +// cleanTargets 规范化域名(小写去空白)并丢弃无任何条件的 target。 +func (ac *ACLConfig) cleanTargets() []ACLTarget { + if ac == nil { + return nil + } + out := make([]ACLTarget, 0, len(ac.Targets)) + for _, t := range ac.Targets { + c := ACLTarget{ + Domain: cleanHosts(t.Domain), + DomainSuffix: cleanHosts(t.DomainSuffix), + IPCIDR: cleanStrings(t.IPCIDR), + Port: t.Port, + } + if !c.empty() { + out = append(out, c) + } + } + return out +} + +func cleanHosts(in []string) []string { + out := make([]string, 0, len(in)) + for _, s := range in { + if s = strings.TrimSpace(strings.ToLower(s)); s != "" { + out = append(out, s) + } + } + return out +} + +func cleanStrings(in []string) []string { + out := make([]string, 0, len(in)) + for _, s := range in { + if s = strings.TrimSpace(s); s != "" { + out = append(out, s) + } + } + return out +} +``` + +修改 `server/internal/agentd/config.go`： + +① 包注释订正（原文声称 agent 保有零目的地数据，ACL 打破了这条，必须如实记录）。把第 7–10 行的 no-state invariant 段落改为： + +```go +// No-state invariant (doc/04 §2, doc/06 §3): the agent persists ONLY the +// credential table (dp_uuid + expires_at) to disk. It keeps zero user identities +// and writes no access logs. A seized node leaks only opaque dp_uuids, never +// accounts. +// +// 例外(私有目的地 ACL):节点本地 acl.json 含一份 dp_uuid 白名单与目的地清单, +// 由运营手工维护、不经控制面。它确实让节点知道「这几个 dp_uuid 享有私有访问权」 +// 以及那几个私有域名/端口 —— 这是知情接受的不变式弱化,范围仅限该文件与渲染出的 +// route 规则,不涉及账户身份,也不产生任何访问日志。设计见 +// docs/private-dest-acl-design.html §12。 +``` + +② 在 `WarpConfigPath` 字段之后新增： + +```go + // ACLConfigPath 指向节点本地的私有目的地访问控制表(默认 /acl.json)。 + // 文件不存在 = 该功能未配置。渲染时读取,SIGHUP agent 即可生效。 + ACLConfigPath string +``` + +③ 在 `withDefaults()` 里 `WarpConfigPath` 分支之后新增： + +```go + if c.ACLConfigPath == "" { + c.ACLConfigPath = filepath.Join(c.StateDir, "acl.json") + } +``` + +④ 在文件末尾路径方法区新增： + +```go +// ACLLastGoodPath 是最近一次成功加载的 ACL 快照,供 agent 冷启动时在 acl.json +// 损坏的情况下兜底(fail-closed 跨重启成立的前提)。 +func (c Config) ACLLastGoodPath() string { return filepath.Join(c.StateDir, "acl.last-good.json") } +``` + +- [ ] **Step 4: 跑测试确认通过** + +```bash +cd server && go test ./internal/agentd/ -run 'ACL|ConfigACLPaths' -v +``` + +Expected: PASS，全部子测试通过。 + +- [ ] **Step 5: 全包回归 + 提交** + +```bash +cd server && go build ./... && go test ./internal/agentd/... +git add server/internal/agentd/acl.go server/internal/agentd/acl_test.go server/internal/agentd/config.go +git commit -m "feat(agent): 私有目的地 ACL 配置类型与 fail-closed 加载语义" +``` + +--- + +### Task 2: 由 ACL 产出 route 规则对（放行 + 兜底拒绝） + +**Files:** +- Modify: `server/internal/agentd/acl.go`（新增 `rules()`） +- Modify: `server/internal/agentd/acl_test.go`（追加测试） + +**Interfaces:** +- Consumes: Task 1 的 `ACLConfig.active()` / `cleanUUIDs()` / `cleanTargets()` / `ACLTarget.matchFields()` +- Produces: `func (ac *ACLConfig) rules() []any` —— 返回按「全部放行规则 → 全部拒绝规则」排序的 sing-box route 规则切片；未 active 时返回 nil + +- [ ] **Step 1: 写失败测试** + +追加到 `server/internal/agentd/acl_test.go`： + +```go +// rules() 必须产出「先全部放行、再全部拒绝」,且同一 target 两侧目的地条件逐字相同。 +func TestACLRules_AllowThenDeny(t *testing.T) { + ac := &ACLConfig{ + Enabled: true, + AllowDpUUIDs: []string{"uuid-me"}, + Targets: []ACLTarget{ + {Domain: []string{"brain.51yanmei.com"}}, + {IPCIDR: []string{"182.92.213.171/32"}, Port: []int{5001}}, + }, + } + rules := ac.rules() + if len(rules) != 4 { + t.Fatalf("规则数 = %d, want 4 (2 target × 放行+拒绝)", len(rules)) + } + + // 前两条是放行:带 user + outbound,不带 action + for i := 0; i < 2; i++ { + r := rules[i].(map[string]any) + if _, ok := r["user"]; !ok { + t.Errorf("rules[%d] 放行规则缺 user", i) + } + if r["outbound"] != directOutboundTag { + t.Errorf("rules[%d] outbound = %v, want %q", i, r["outbound"], directOutboundTag) + } + if _, ok := r["action"]; ok { + t.Errorf("rules[%d] 放行规则不应带 action", i) + } + } + // 后两条是拒绝:带 action=reject,不带 user(对所有人生效) + for i := 2; i < 4; i++ { + r := rules[i].(map[string]any) + if r["action"] != "reject" { + t.Errorf("rules[%d] action = %v, want reject", i, r["action"]) + } + if _, ok := r["user"]; ok { + t.Errorf("rules[%d] 拒绝规则不应带 user,否则会漏掉名单外的人", i) + } + } + + // 对称性:target[0] 的放行(rules[0])与拒绝(rules[2])目的地条件必须逐字相同 + allow0 := rules[0].(map[string]any) + deny0 := rules[2].(map[string]any) + if fmt.Sprint(allow0["domain"]) != fmt.Sprint(deny0["domain"]) { + t.Errorf("target0 放行/拒绝的 domain 不一致: %v vs %v", allow0["domain"], deny0["domain"]) + } + allow1 := rules[1].(map[string]any) + deny1 := rules[3].(map[string]any) + if fmt.Sprint(allow1["ip_cidr"]) != fmt.Sprint(deny1["ip_cidr"]) || + fmt.Sprint(allow1["port"]) != fmt.Sprint(deny1["port"]) { + t.Error("target1 放行/拒绝的 ip_cidr/port 不一致") + } +} + +// 空白名单 → 不产出放行规则,但拒绝规则照出(fail-closed 的核心断言)。 +func TestACLRules_EmptyAllowlistStillDenies(t *testing.T) { + ac := &ACLConfig{ + Enabled: true, + AllowDpUUIDs: nil, + Targets: []ACLTarget{{Domain: []string{"brain.51yanmei.com"}}}, + } + rules := ac.rules() + if len(rules) != 1 { + t.Fatalf("规则数 = %d, want 1 (仅拒绝)", len(rules)) + } + r := rules[0].(map[string]any) + if r["action"] != "reject" { + t.Errorf("action = %v, want reject", r["action"]) + } +} + +// 未 active(含 nil / enabled=false)→ 无规则。 +func TestACLRules_InactiveYieldsNil(t *testing.T) { + var nilACL *ACLConfig + if got := nilACL.rules(); got != nil { + t.Errorf("nil ACL rules() = %v, want nil", got) + } + off := &ACLConfig{Enabled: false, Targets: []ACLTarget{{Domain: []string{"a.com"}}}} + if got := off.rules(); got != nil { + t.Errorf("enabled=false rules() = %v, want nil", got) + } +} +``` + +在 `acl_test.go` 的 import 块加入 `"fmt"`。 + +- [ ] **Step 2: 跑测试确认失败** + +```bash +cd server && go test ./internal/agentd/ -run 'ACLRules' -v +``` + +Expected: 编译失败，`ac.rules undefined (type *ACLConfig has no field or method rules)`。 + +- [ ] **Step 3: 写实现** + +在 `server/internal/agentd/acl.go` 末尾追加： + +```go +// rules 产出 ACL 的 sing-box route 规则:每个 target 一对 —— 先放行白名单、再兜底拒绝。 +// +// 顺序是安全性的一部分,不可重排: +// 1. 全部放行规则排在全部拒绝规则之前。不能按 target 交错(放行A/拒绝A/放行B/拒绝B), +// 因为 target 之间可能重叠,交错会让 B 的成员被 A 的拒绝规则先命中。 +// 2. 拒绝规则不带 user 维度 —— 它要对「白名单之外的所有人」生效。 +// 3. 同一 target 的放行与拒绝,目的地条件由同一个 matchFields() 生成,保证逐字相同。 +// 任何不对称都会造成「我自己也被拒」或「有人漏网」。 +// +// 白名单为空时只产出拒绝规则(谁都不许进),这是 fail-closed 的核心:空名单的语义是 +// 「没有人」而非「所有人」。 +func (ac *ACLConfig) rules() []any { + if !ac.active() { + return nil + } + uuids := ac.cleanUUIDs() + targets := ac.cleanTargets() + + out := make([]any, 0, len(targets)*2) + if len(uuids) > 0 { + for _, t := range targets { + r := t.matchFields() + r["user"] = uuids + r["outbound"] = directOutboundTag + out = append(out, r) + } + } + for _, t := range targets { + r := t.matchFields() + r["action"] = "reject" + out = append(out, r) + } + return out +} +``` + +- [ ] **Step 4: 跑测试确认通过** + +```bash +cd server && go test ./internal/agentd/ -run 'ACL' -v +``` + +Expected: PASS。 + +- [ ] **Step 5: 提交** + +```bash +cd server && go build ./... && go test ./internal/agentd/... +git add server/internal/agentd/acl.go server/internal/agentd/acl_test.go +git commit -m "feat(agent): ACL 渲染放行/拒绝规则对,空白名单仍拒绝" +``` + +--- + +### Task 3: buildRoute 合并 ACL 与 WARP，接入渲染 + +**Files:** +- Modify: `server/internal/agentd/render.go`（`:30-58` `renderSingboxConfig` 增参、替换 `cfg["route"]` 赋值、新增 `buildRoute`；`:14` 隐私不变式注释订正） +- Modify: `server/internal/agentd/warp.go:113-121`（删除 `warpRoute()`，其唯一调用方被 `buildRoute` 取代） +- Modify: `server/internal/agentd/singbox.go:326`（`renderSingboxConfig` 调用处补 `nil` 实参，本任务先传 nil，Task 4 换成真实 ACL） +- Modify: `server/internal/agentd/acl_test.go`（追加四态矩阵测试） + +**Interfaces:** +- Consumes: Task 2 的 `(*ACLConfig).rules()`；既有 `(*WarpConfig).active()` / `cleanDomains()` / `warpEndpoint()` +- Produces: `func buildRoute(acl *ACLConfig, warp *WarpConfig) map[string]any`（两者皆未激活时返回 nil）；`renderSingboxConfig` 新签名 `func renderSingboxConfig(creds []Cred, reality *agentv1.RealityInbound, hy2 *agentv1.Hy2Inbound, deriveKey string, warp *WarpConfig, acl *ACLConfig) ([]byte, error)` + +- [ ] **Step 1: 写失败测试** + +追加到 `server/internal/agentd/acl_test.go`： + +```go +// buildRoute 四态矩阵:ACL×WARP 开关的四种组合。 +func TestBuildRoute_Matrix(t *testing.T) { + acl := &ACLConfig{ + Enabled: true, + AllowDpUUIDs: []string{"uuid-me"}, + Targets: []ACLTarget{{Domain: []string{"brain.51yanmei.com"}}}, + } + warp := &WarpConfig{ + Enabled: true, PrivateKey: "k", PeerPublicKey: "pk", + Endpoint: "162.159.192.1:2408", Address: []string{"172.16.0.2/32"}, + Domains: []string{"reddit.com"}, + } + + t.Run("都关 → 不产出 route(向后兼容)", func(t *testing.T) { + if got := buildRoute(nil, nil); got != nil { + t.Errorf("buildRoute(nil,nil) = %v, want nil", got) + } + }) + + t.Run("仅 WARP → sniff + warp 规则(与改动前逐字节一致)", func(t *testing.T) { + r := buildRoute(nil, warp) + rules := r["rules"].([]any) + if len(rules) != 2 { + t.Fatalf("规则数 = %d, want 2", len(rules)) + } + if rules[0].(map[string]any)["action"] != "sniff" { + t.Error("首条不是 sniff") + } + if rules[1].(map[string]any)["outbound"] != warpOutboundTag { + t.Error("次条不是 warp 分流") + } + if r["final"] != directOutboundTag { + t.Errorf("final = %v, want %q", r["final"], directOutboundTag) + } + }) + + t.Run("仅 ACL → sniff + 放行 + 拒绝", func(t *testing.T) { + r := buildRoute(acl, nil) + rules := r["rules"].([]any) + if len(rules) != 3 { + t.Fatalf("规则数 = %d, want 3", len(rules)) + } + if rules[0].(map[string]any)["action"] != "sniff" { + t.Error("首条不是 sniff") + } + if _, ok := rules[1].(map[string]any)["user"]; !ok { + t.Error("第二条不是放行规则") + } + if rules[2].(map[string]any)["action"] != "reject" { + t.Error("第三条不是拒绝规则") + } + }) + + t.Run("都开 → sniff + ACL(放行,拒绝) + warp,且 sniff 只出现一次", func(t *testing.T) { + r := buildRoute(acl, warp) + rules := r["rules"].([]any) + if len(rules) != 4 { + t.Fatalf("规则数 = %d, want 4", len(rules)) + } + sniffs := 0 + for _, x := range rules { + if x.(map[string]any)["action"] == "sniff" { + sniffs++ + } + } + if sniffs != 1 { + t.Errorf("sniff 出现 %d 次, want 1", sniffs) + } + if rules[0].(map[string]any)["action"] != "sniff" { + t.Error("sniff 必须最先") + } + // ACL 全部规则必须排在 warp 之前:被拒绝的目的地不该有机会走 warp 出口 + if rules[3].(map[string]any)["outbound"] != warpOutboundTag { + t.Error("warp 规则必须排在最后") + } + if rules[2].(map[string]any)["action"] != "reject" { + t.Error("ACL 拒绝规则必须排在 warp 之前") + } + }) +} +``` + +- [ ] **Step 2: 跑测试确认失败** + +```bash +cd server && go test ./internal/agentd/ -run 'BuildRoute' -v +``` + +Expected: 编译失败，`undefined: buildRoute`。 + +- [ ] **Step 3: 写实现** + +① 在 `server/internal/agentd/render.go` 中，把第 30 行签名与第 50–55 行的 route 注入替换为： + +```go +func renderSingboxConfig(creds []Cred, reality *agentv1.RealityInbound, hy2 *agentv1.Hy2Inbound, deriveKey string, warp *WarpConfig, acl *ACLConfig) ([]byte, error) { +``` + +```go + // WARP 分流(#29)只贡献 endpoints;route 块由 buildRoute 统一产出,因为它现在要 + // 同时容纳 ACL 规则 —— 原先 cfg["route"] = warp.warpRoute() 是整块覆盖,直接赋值 + // 会把对方的规则干掉。 + if warp.active() { + cfg["endpoints"] = []any{warp.warpEndpoint()} + } + if route := buildRoute(acl, warp); route != nil { + cfg["route"] = route + } +``` + +② 在 `render.go` 的 `statsUsers` 之前插入： + +```go +// buildRoute 合并私有目的地 ACL 与 WARP 分流,产出单一 route 块。 +// 两者都未激活时返回 nil —— 不产出 route 字段,与旧配置逐字节一致(向后兼容)。 +// +// 规则顺序是安全语义的一部分: +// 1. {"action":"sniff"} 唯一且最先。域名匹配依赖它取 TLS SNI(客户端多半发的是 +// 已解析 IP),WARP 与 ACL 都需要,故在此统一产出一次,不由各自重复追加。 +// 2. ACL 规则(放行在前、拒绝在后)整体排在 WARP 之前:被 ACL 拒绝的目的地永远 +// 不该还有机会被路由到 warp 出口。 +// 3. final 恒为 direct。 +func buildRoute(acl *ACLConfig, warp *WarpConfig) map[string]any { + aclRules := acl.rules() + warpActive := warp.active() + if len(aclRules) == 0 && !warpActive { + return nil + } + + rules := make([]any, 0, len(aclRules)+2) + rules = append(rules, map[string]any{"action": "sniff"}) + rules = append(rules, aclRules...) + if warpActive { + rules = append(rules, map[string]any{ + "domain_suffix": warp.cleanDomains(), + "outbound": warpOutboundTag, + }) + } + return map[string]any{"rules": rules, "final": directOutboundTag} +} +``` + +③ 删除 `server/internal/agentd/warp.go` 第 111–121 行的 `warpRoute()` 方法及其上方注释块（唯一调用方已被 `buildRoute` 取代；`grep -rn "warpRoute()" internal/agentd/` 应无剩余命中）。 + +④ 订正 `render.go` 第 14 行的隐私不变式注释。原文： + +```go +// Only the opaque dp_uuid is ever written; no account identity touches the node. +``` + +改为： + +```go +// Only the opaque dp_uuid is ever written; no account identity touches the node. +// +// 例外(私有目的地 ACL):若节点配置了 acl.json,渲染出的 route 规则会含一份享有私有 +// 访问权的 dp_uuid 白名单与对应的私有域名/端口。它仍不含任何账户身份(email/user_id), +// 但确实让节点知道「这几个 dp_uuid 属于同一组权限」—— 知情接受的不变式弱化, +// 设计与权衡见 docs/private-dest-acl-design.html §12。 + +⑤ 修改 `server/internal/agentd/singbox.go` 第 326 行，补一个 nil 实参（Task 4 会替换成真实 ACL）： + +```go + return renderSingboxConfig(creds, reality, hy2, s.cfg.DeriveKey, warp, nil) +``` + +- [ ] **Step 4: 跑测试确认通过** + +```bash +cd server && go test ./internal/agentd/ -run 'BuildRoute|Warp|Render' -v +``` + +Expected: PASS。特别确认既有的 `TestRender_NoWarp_NoRouteSection` 与 `TestRender_Warp_InjectsEndpointAndRoute` 仍绿——这两条守着向后兼容。 + +- [ ] **Step 5: 提交** + +```bash +cd server && go build ./... && go test ./internal/agentd/... +git add server/internal/agentd/render.go server/internal/agentd/warp.go server/internal/agentd/singbox.go server/internal/agentd/acl_test.go +git commit -m "refactor(agent): route 块改由 buildRoute 统一产出,合并 ACL 与 WARP" +``` + +--- + +### Task 4: 渲染时读取 ACL，last-good 内存 + 落盘兜底 + +**Files:** +- Modify: `server/internal/agentd/singbox.go:49-74`（`SingBox` 增 `lastGoodACL` 字段）、`:308-327`（`RenderConfig` 读 ACL） +- Modify: `server/internal/agentd/acl.go`（新增 `persistACL`） +- Modify: `server/internal/agentd/acl_test.go`（追加 last-good 测试） + +**Interfaces:** +- Consumes: Task 1 的 `LoadACLConfig` / `Config.ACLConfigPath` / `Config.ACLLastGoodPath()`；Task 3 的 `renderSingboxConfig` 六参签名；既有包内函数 `atomicWrite(path string, data []byte, perm os.FileMode) error` +- Produces: `func (s *SingBox) loadACL() *ACLConfig`；`func persistACL(path string, ac *ACLConfig) error` + +- [ ] **Step 1: 写失败测试** + +追加到 `server/internal/agentd/acl_test.go`： + +```go +// 成功加载后必须把快照落盘,否则 agent 一重启 fail-closed 就失效。 +func TestACL_PersistsLastGoodOnLoad(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) + } + if _, err := os.Stat(cfg.ACLLastGoodPath()); err != nil { + t.Fatalf("last-good 未落盘: %v", err) + } +} + +// acl.json 被改坏 → 规则不能消失(内存 last-good 兜底)。 +func TestACL_BrokenFileKeepsInMemoryLastGood(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,`) // 手抖写坏 + data, err := sb.RenderConfig() + if err != nil { + t.Fatal(err) + } + if !strings.Contains(string(data), "reject") { + t.Fatal("acl.json 坏掉后拒绝规则消失了 —— 这是 fail-open,私有服务已敞开") + } +} + +// 新 agent 实例(模拟进程重启)+ 坏 acl.json → 磁盘 last-good 兜底,规则仍在。 +func TestACL_ColdStartFallsBackToDiskLastGood(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) + } + + writeACL(t, cfg.ACLConfigPath, `not json at all`) + 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,私有服务已敞开") + } +} + +// 从未配置过(无 acl.json 也无 last-good)→ 不产出 route,且不误报。 +func TestACL_NeverConfiguredYieldsNoRoute(t *testing.T) { + cfg := testConfig(t) + sb := NewSingBox(cfg, nil) + sb.ApplyConfig(sampleSnapshot(&agentv1.Credential{DpUUID: "aaaa", Protocol: agentv1.ProtocolBoth}), true) + data, err := sb.RenderConfig() + if err != nil { + t.Fatal(err) + } + var m map[string]any + if err := json.Unmarshal(data, &m); err != nil { + t.Fatal(err) + } + if _, ok := m["route"]; ok { + t.Error("未配置 ACL 也未启用 WARP,不应产出 route 块") + } +} +``` + +在 `acl_test.go` 的 import 块补齐 `"encoding/json"`、`"strings"`，以及 `agentv1 "github.com/wangjia/pangolin/server/internal/pb/agentv1"`。 + +- [ ] **Step 2: 跑测试确认失败** + +```bash +cd server && go test ./internal/agentd/ -run 'TestACL_' -v +``` + +Expected: `TestACL_PersistsLastGoodOnLoad` 失败（last-good 未落盘），`TestACL_BrokenFile...` / `TestACL_ColdStart...` 失败（渲染结果里没有 reject，因为 Task 3 传的是 nil）。 + +- [ ] **Step 3: 写实现** + +① 在 `server/internal/agentd/acl.go` 末尾追加： + +```go +// persistACL 把成功加载的 ACL 快照原子写到 path,供 agent 冷启动兜底。 +func persistACL(path string, ac *ACLConfig) error { + data, err := json.MarshalIndent(ac, "", " ") + if err != nil { + return fmt.Errorf("agentd: marshal acl snapshot: %w", err) + } + return atomicWrite(path, data, 0o600) +} +``` + +② 在 `server/internal/agentd/singbox.go` 的 `SingBox` 结构体中，`configVersion int64` 之后新增字段： + +```go + // lastGoodACL 是最近一次成功加载的私有目的地 ACL。acl.json 读坏时回退到它, + // 而不是像 WARP 那样降级为「不启用」—— 对访问控制,降级即敞开。 + lastGoodACL *ACLConfig +``` + +③ 在 `server/internal/agentd/singbox.go` 的 `RenderConfig` 中，把 WARP 加载之后的部分替换为： + +```go + // WARP 分流配置每次渲染读一次:编辑 warp.json 后任一渲染(或 agent 重启)即生效(#29)。 + // 读失败(坏 JSON)仅记日志、按未启用处理,绝不因坏配置产出无法启动的 sing-box 配置。 + warp, err := LoadWarpConfig(s.cfg.WarpConfigPath) + if err != nil { + logf("[warp] load %s failed, WARP routing disabled: %v", s.cfg.WarpConfigPath, err) + warp = nil + } + return renderSingboxConfig(creds, reality, hy2, s.cfg.DeriveKey, warp, s.loadACL()) +} + +// loadACL 读取私有目的地 ACL,并维护 last-good 兜底。 +// +// 语义刻意与 WARP 相反:WARP 读失败静默降级为「不分流」是安全的,ACL 读失败若也 +// 降级为「不启用」,等于把私有服务对全体 pangolin 用户敞开,而且是静默的。故: +// - 成功 → 更新内存 last-good 并落盘,供本进程后续与下次冷启动使用 +// - 失败/文件消失 → 回退内存 last-good,再回退磁盘 last-good,规则不消失 +// - 两级 last-good 都没有 → 只能不产出规则(白名单与目的地清单同在一个文件, +// 文件全丢时连「该拒绝哪些目的地」都无从得知),此时必须大声告警 +func (s *SingBox) loadACL() *ACLConfig { + acl, err := LoadACLConfig(s.cfg.ACLConfigPath) + switch { + case err == nil && acl != nil: + s.mu.Lock() + s.lastGoodACL = acl + s.mu.Unlock() + if perr := persistACL(s.cfg.ACLLastGoodPath(), acl); perr != nil { + logf("[acl] persist last-good to %s failed: %v", s.cfg.ACLLastGoodPath(), perr) + } + return acl + case err != nil: + logf("[acl] ERROR load %s failed: %v", s.cfg.ACLConfigPath, err) + } + + s.mu.Lock() + lg := s.lastGoodACL + s.mu.Unlock() + if lg != nil { + logf("[acl] falling back to in-memory last-good ACL") + return lg + } + + disk, derr := LoadACLConfig(s.cfg.ACLLastGoodPath()) + if derr == nil && disk != nil { + logf("[acl] 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 { + logf("[acl] ALERT acl.json is broken and no last-good snapshot exists — "+ + "private destinations are UNPROTECTED (path=%s)", s.cfg.ACLConfigPath) + } + return nil +} +``` + +- [ ] **Step 4: 跑测试确认通过** + +```bash +cd server && go test ./internal/agentd/ -run 'TestACL_' -v +``` + +Expected: PASS，四条全绿。 + +- [ ] **Step 5: 提交** + +```bash +cd server && go build ./... && go test ./internal/agentd/... +git add server/internal/agentd/acl.go server/internal/agentd/singbox.go server/internal/agentd/acl_test.go +git commit -m "feat(agent): 渲染时读取 ACL,内存+磁盘 last-good 保证 fail-closed 跨重启" +``` + +--- + +### Task 5: SIGHUP 触发重渲染（避免重启踢掉全部在线用户） + +**Files:** +- Modify: `server/internal/agentd/singbox.go`（新增导出的 `Refresh()`） +- Modify: `server/cmd/agent/main.go:44-45`（注册 SIGHUP 处理） +- Modify: `server/internal/agentd/acl_test.go`（追加 `Refresh` 测试） + +**Interfaces:** +- Consumes: 既有 `(*SingBox).markDirty()`（未导出）、`(*Agent).SingBox() *SingBox`（`agent.go:83`，已导出） +- Produces: `func (s *SingBox) Refresh()` —— 外部触发一次重渲染 + +**为什么不用 `systemctl restart pangolin-agent`：** 新进程内 `s.started == false`（`singbox.go:64-67`），首次渲染会走 `restarter.Restart()` 即 `systemctl restart sing-box`，**全部在线用户瞬断**。SIGHUP 走的是既有的 debounce → `writeAndRestart` → `Reload()`（SIGHUP 热重载）路径，不断线。 + +- [ ] **Step 1: 写失败测试** + +追加到 `server/internal/agentd/acl_test.go`： + +```go +// Refresh() 必须能触发一次重渲染(经 debounce 循环),用于「编辑 acl.json 后 +// systemctl reload pangolin-agent」而不必重启 agent(重启会冷启 sing-box 踢人)。 +func TestSingBoxRefresh_TriggersRender(t *testing.T) { + cfg := testConfig(t) + writeACL(t, cfg.ACLConfigPath, validACL) + fr := &fakeRestarter{} + sb := NewSingBox(cfg, fr) + sb.ApplyConfig(sampleSnapshot(&agentv1.Credential{DpUUID: "aaaa", Protocol: agentv1.ProtocolBoth}), true) + + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + go sb.Run(ctx) + + // 等首次渲染落地(ApplyConfig 已 markDirty) + eventually(t, 2*time.Second, func() bool { + _, err := os.Stat(cfg.SingboxConfigPath) + return err == nil + }, "首次渲染写出配置") + + // 断言 reloadCount 而非 count:首次渲染已冷启动过(started=true),此后的重渲染 + // 一律走 Reload(SIGHUP 热重载),Restart 计数不会再增加。断言错计数器会假失败。 + before := fr.reloadCount() + sb.Refresh() + eventually(t, 2*time.Second, func() bool { return fr.reloadCount() > before }, "Refresh 触发了热重载") +} +``` + +在 `acl_test.go` 的 import 块补齐 `"context"` 与 `"time"`。 + +> 复用 `singbox_test.go:17-47` 既有的 `fakeRestarter`（`count()` 返回 Restart 次数、`reloadCount()` 返回 Reload 次数）与 `integration_test.go:248` 的 `eventually(t *testing.T, timeout time.Duration, fn func() bool, msg string)`。 + +- [ ] **Step 2: 跑测试确认失败** + +```bash +cd server && go test ./internal/agentd/ -run 'Refresh' -v +``` + +Expected: 编译失败，`sb.Refresh undefined`。 + +- [ ] **Step 3: 写实现** + +① 在 `server/internal/agentd/singbox.go` 的 `markDirty` 之后追加： + +```go +// Refresh 请求一次重渲染。供 agent 收到 SIGHUP 时调用,使编辑节点本地配置文件 +// (acl.json / warp.json)后无需重启进程即可生效 —— 重启 agent 会让 sing-box 走 +// 冷启动(Restart),把全部在线用户踢下线。 +func (s *SingBox) Refresh() { s.markDirty() } +``` + +② 修改 `server/cmd/agent/main.go`，把第 44–45 行替换为： + +```go + ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM) + defer stop() + + // SIGHUP 重读节点本地配置(acl.json / warp.json)并重渲染。走 sing-box 的 SIGHUP + // 热重载路径,在线用户不掉线;重启 agent 则会冷启 sing-box,把所有人踢下线。 + hup := make(chan os.Signal, 1) + signal.Notify(hup, syscall.SIGHUP) + defer signal.Stop(hup) + go func() { + for { + select { + case <-ctx.Done(): + return + case <-hup: + log.Printf("[pangolin-agent] SIGHUP: re-reading node-local config (acl.json/warp.json)") + agent.SingBox().Refresh() + } + } + }() +``` + +`os` 与 `log` 已在该文件 import 中（`os` 见 `env()` 用到的 `os.LookupEnv`）；若 `go build` 报缺失，按提示补齐。 + +- [ ] **Step 4: 跑测试确认通过** + +```bash +cd server && go build ./... && go test ./internal/agentd/ -run 'Refresh' -v +``` + +Expected: PASS。 + +- [ ] **Step 5: 提交** + +```bash +cd server && go build ./... && go test ./internal/agentd/... +git add server/internal/agentd/singbox.go server/internal/agentd/acl_test.go server/cmd/agent/main.go +git commit -m "feat(agent): SIGHUP 重读节点本地配置并热重渲染,不踢在线用户" +``` + +--- + +### Task 6: 节点配置样例与运维文档 + +**Files:** +- Create: `deploy/single-node/acl.json.example` +- Modify: `docs/private-dest-acl-design.html`（把 §8 runbook 里的占位符换成指向样例文件） + +**Interfaces:** +- Consumes: Task 1 定义的 `ACLConfig` JSON 形状 +- Produces: 可直接复制到 `/etc/pangolin-agent/acl.json` 的样例 + +- [ ] **Step 1: 写样例文件** + +创建 `deploy/single-node/acl.json.example`： + +```json +{ + "_comment": "私有目的地访问控制。复制到 /etc/pangolin-agent/acl.json 并填入自己的 dp_uuid。改完执行 systemctl reload pangolin-agent（不要 restart，restart 会冷启 sing-box 踢掉全部在线用户）。", + "enabled": true, + "allow_dp_uuids": [ + "TODO-设备级-dp-uuid", + "TODO-账户级-dp-uuid-供-sub-订阅链接用" + ], + "targets": [ + { + "_comment": "与公开站共用 ali:443 的私有 vhost，只能靠 SNI 区分", + "domain": ["brain.51yanmei.com", "git.51yanmei.com"] + }, + { + "_comment": "独占端口的服务：DSM 5001 / RDP 3389 / NAS SSH 10022 / Win SSH 10023", + "ip_cidr": ["182.92.213.171/32"], + "port": [5001, 3389, 10022, 10023] + } + ] +} +``` + +> `_comment` 字段会被 `encoding/json` 忽略（`ACLConfig` 无对应字段且未启用 `DisallowUnknownFields`），可安全保留作自文档。样例里的 `TODO-` 值是**样例文件**的占位，不是计划的占位——真实 uuid 属 PII 级标识，不入 git，由运维按 Step 2 的 SQL 现取现填。 + +- [ ] **Step 2: 验证样例能被解析且渲染出预期规则** + +```bash +cd server && cat > /tmp/acl_example_check.go <<'EOF' +package main + +import ( + "fmt" + "os" + + "github.com/wangjia/pangolin/server/internal/agentd" +) + +func main() { + ac, err := agentd.LoadACLConfig(os.Args[1]) + if err != nil { + fmt.Println("FAIL:", err) + os.Exit(1) + } + fmt.Printf("OK enabled=%v uuids=%d targets=%d\n", ac.Enabled, len(ac.AllowDpUUIDs), len(ac.Targets)) +} +EOF +go run /tmp/acl_example_check.go ../deploy/single-node/acl.json.example && rm /tmp/acl_example_check.go +``` + +Expected: `OK enabled=true uuids=2 targets=2` + +- [ ] **Step 3: 更新设计文档的 runbook 指向** + +在 `docs/private-dest-acl-design.html` 的 §8 首段（`

8. 名单维护 Runbook

` 之后的第一个 `

`）末尾追加一句： + +```html +样例文件见 deploy/single-node/acl.json.example，复制到 /etc/pangolin-agent/acl.json 后按下方 SQL 填入 uuid。 +``` + +- [ ] **Step 4: 提交** + +```bash +cd server && go build ./... && go test ./internal/agentd/... +git add deploy/single-node/acl.json.example docs/private-dest-acl-design.html +git commit -m "docs(agent): 私有目的地 ACL 配置样例与 runbook 指向" +``` + +--- + +## 上线验收（人工，非代码任务） + +代码合并后在 pangolin1 上执行。**先备份现网 sing-box 配置**：`sudo cp /etc/sing-box/config.json /etc/sing-box/config.json.bak-$(date +%F)`（此处 `$(...)` 在服务器交互 shell 中手动执行，不经 agent）。 + +1. 取白名单 uuid（`UNION` 那一半是账户级 dp_uuid，供 `/sub` 订阅链接用，**漏了会把自己锁在外面**）： + ```sql + sqlite3 /var/lib/pangolin/pangolin.db \ + "SELECT d.dp_uuid FROM devices d JOIN users u ON u.id = d.user_id + WHERE u.email = '<我的邮箱>' AND d.dp_uuid IS NOT NULL + UNION + SELECT dp_uuid FROM users WHERE email = '<我的邮箱>';" + ``` +2. 写 `/etc/pangolin-agent/acl.json`（权限 `0600`，属主 `pangolin`），`systemctl reload pangolin-agent`。 +3. `journalctl -u pangolin-agent -n 30` 确认已重渲染、无 `[acl] ERROR` / `[acl] ALERT`。 +4. `sudo python3 -c "import json;print(json.load(open('/etc/sing-box/config.json'))['route'])"` 确认规则顺序为 sniff → 放行 → 拒绝 → warp。 +5. **我的设备**：brain 首页 200、DSM 5001 可登录、`ssh nas-r` 通。 +6. **另一账号的设备**：以上全部被拒（连接被 reject，不是超时）。 +7. **公开站不受影响**：jiu / travel / sudoku / pay 在两个账号下均正常。 +8. **WARP 未被破坏**：reddit 仍走 warp 出口。 +9. **fail-closed 实证**：把 `acl.json` 改坏 → `systemctl reload pangolin-agent` → 规则仍在、日志有 ERROR；恢复文件。 +10. **不断线实证**：reload 期间另一台设备保持连接不掉。 + +## 不在本计划范围内 + +- 给 brain 加 mTLS / basic auth 作纵深防御（与本计划正交，约一小时，另开） +- 补 `assertNoIdentityFields` 对渲染配置的覆盖（既有缺口，本计划不扩大也不修复） +- 控制面下发 ACL（演进路径见设计文档 §11，届时渲染层可原样保留） diff --git a/todo/todo.html b/todo/todo.html index 9b710a2..cc8ebdd 100644 --- a/todo/todo.html +++ b/todo/todo.html @@ -327,12 +327,12 @@ header .header-meta{color:var(--fg-soft)}

feature+windows — 项目 TODO

-
生成于 2026-07-08 · 真相源 todo/todo.json
+
生成于 2026-07-23 · 真相源 todo/todo.json
-
18全部
-
8待开始
-
0开发中
-
2待验收
+
22全部
+
9待开始
+
1开发中
+
4待验收
8已验收
@@ -376,7 +376,7 @@ header .header-meta{color:var(--fg-soft)}
- 📋 待开始 8 + 📋 待开始 9 ▴ 收起
@@ -599,6 +599,37 @@ header .header-meta{color:var(--fg-soft)}
+
  • +
    + #21 + 邀请/任务奖励明细列表 — GET /v1/invite/events(读 audit_log:action/target/days/时间)+ App 邀请页明细区(逐行:日期·事件·+N天)+ 六语;审计数据已齐(audit_log target 现带对方id),纯展示层活 +
    + 待开始 + 重要 + + + +
    +
    + + + + +
    +
    +
    + 🤖 agent + 🕐 2026-07-13 + +
    +
    +
    • +
  • - 🔨 开发中 0 + 🔨 开发中 1 ▴ 收起
      -

      暂无条目

      + +
    • +
      + #23 + 私有目的地 ACL（节点侧）：只有白名单 dp_uuid 能经 pangolin 出口访问 brain/nas/git/win.51yanmei.com。节点本地 acl.json + agent 渲染放行/拒绝规则对，fail-closed，SIGHUP 热生效。设计 docs/private-dest-acl-design.html，计划 docs/superpowers/plans/2026-07-23-private-dest-acl.md +
      + 开发中 + 重要 + + + +
      +
      + + + + +
      +
      +
      + 🤖 agent + 🕐 2026-07-23 + +
      +
      +
    - 🔍 待验收 2 + 🔍 待验收 4 ▴ 收起
    @@ -714,6 +775,68 @@ header .header-meta{color:var(--fg-soft)} 🤖 agent 🕐 2026-07-07 +
    +
    +
    • + +
  • +
    + #20 + Tablet(iPad)补通知入口 — tablet_shell 顶栏接铃铛 + content() 加 NavView.notifications 真屏(现平板铃铛/通知不可达,桌面/手机正常) +
    + 待验收 + 重要 + + + +
    +
    + + + + +
    +
    +
    + 🤖 agent + 🕐 2026-07-12 + +
    +
    +
    • + +
  • +
    + #22 + 客户端私有服务域名分流(BuildClientConfig): nas/git/win.yanmeiai.com 本地DNS+resolve+私网直连+强制走隧道,smartRoute 可重开 +
    + 待验收 + 重要 + + + +
    +
    + + + + +
    +
    +
    + 🤖 agent + 🕐 2026-07-16 +
    • diff --git a/todo/todo.json b/todo/todo.json index a7cd675..fad570d 100644 --- a/todo/todo.json +++ b/todo/todo.json @@ -1,9 +1,9 @@ { "meta": { "title": "feature+windows — 项目 TODO", - "updated_at": "2026-07-07T17:45:18.036Z" + "updated_at": "2026-07-22T16:59:57.735Z" }, - "seq": 19, + "seq": 23, "items": [ { "id": 1, @@ -317,6 +317,62 @@ "proposed_at": "2026-07-07T15:41:36.536Z", "approved_at": "2026-07-07T15:54:54.386Z" } + }, + { + "id": 20, + "title": "Tablet(iPad)补通知入口 — tablet_shell 顶栏接铃铛 + content() 加 NavView.notifications 真屏(现平板铃铛/通知不可达,桌面/手机正常)", + "desc": null, + "level": "mid", + "tier": null, + "tags": [], + "owner": "agent", + "status": "done", + "created_at": "2026-07-12T10:48:49.013Z", + "done": false, + "completed_at": "2026-07-13T02:20:58.685Z", + "version": "site-v0.0.13" + }, + { + "id": 21, + "title": "邀请/任务奖励明细列表 — GET /v1/invite/events(读 audit_log:action/target/days/时间)+ App 邀请页明细区(逐行:日期·事件·+N天)+ 六语;审计数据已齐(audit_log target 现带对方id),纯展示层活", + "desc": null, + "level": "mid", + "tier": null, + "tags": [], + "owner": "agent", + "status": "open", + "created_at": "2026-07-13T04:29:47.253Z", + "done": false, + "completed_at": null, + "version": null + }, + { + "id": 22, + "title": "客户端私有服务域名分流(BuildClientConfig): nas/git/win.yanmeiai.com 本地DNS+resolve+私网直连+强制走隧道,smartRoute 可重开", + "desc": null, + "level": "mid", + "tier": null, + "tags": [], + "owner": "agent", + "status": "done", + "created_at": "2026-07-15T21:40:35.427Z", + "done": false, + "completed_at": null, + "version": null + }, + { + "id": 23, + "title": "私有目的地 ACL（节点侧）：只有白名单 dp_uuid 能经 pangolin 出口访问 brain/nas/git/win.51yanmei.com。节点本地 acl.json + agent 渲染放行/拒绝规则对，fail-closed，SIGHUP 热生效。设计 docs/private-dest-acl-design.html，计划 docs/superpowers/plans/2026-07-23-private-dest-acl.md", + "desc": null, + "level": "mid", + "tier": null, + "tags": [], + "owner": "agent", + "status": "doing", + "created_at": "2026-07-22T16:59:41.945Z", + "done": false, + "completed_at": null, + "version": null } ] } From b71f6038ae008a157046f45aadce98f3780ca8b9 Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Thu, 23 Jul 2026 01:02:37 +0800 Subject: [PATCH 02/21] =?UTF-8?q?chore:=20gitignore=20superpowers=20?= =?UTF-8?q?=E6=89=A7=E8=A1=8C=E6=9A=82=E5=AD=98=E7=9B=AE=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 3306398..3fad797 100644 --- a/.gitignore +++ b/.gitignore @@ -90,3 +90,6 @@ client/windows/installer/Output/ /server/cover.out /server/coverage.txt /client/coverage/ + +# superpowers 执行进度暂存(本地,不入库) +.superpowers/ From e4d014ba992be3bee7c342e91422f893e2c25214 Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Thu, 23 Jul 2026 01:07:15 +0800 Subject: [PATCH 03/21] =?UTF-8?q?feat(agent):=20=E7=A7=81=E6=9C=89?= =?UTF-8?q?=E7=9B=AE=E7=9A=84=E5=9C=B0=20ACL=20=E9=85=8D=E7=BD=AE=E7=B1=BB?= =?UTF-8?q?=E5=9E=8B=E4=B8=8E=20fail-closed=20=E5=8A=A0=E8=BD=BD=E8=AF=AD?= =?UTF-8?q?=E4=B9=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- server/internal/agentd/acl.go | 143 +++++++++++++++++++++++ server/internal/agentd/acl_test.go | 175 +++++++++++++++++++++++++++++ server/internal/agentd/config.go | 23 +++- 3 files changed, 338 insertions(+), 3 deletions(-) create mode 100644 server/internal/agentd/acl.go create mode 100644 server/internal/agentd/acl_test.go diff --git a/server/internal/agentd/acl.go b/server/internal/agentd/acl.go new file mode 100644 index 0000000..ee8f336 --- /dev/null +++ b/server/internal/agentd/acl.go @@ -0,0 +1,143 @@ +package agentd + +import ( + "encoding/json" + "fmt" + "os" + "strings" +) + +// ACLTarget 描述一组「私有目的地」的匹配条件。字段名与取值直接对应 sing-box +// route rule 的同名字段:同一项内多字段是 AND,字段内多值是 OR。刻意不做自研 DSL +// —— 形状即 sing-box 语义,少一层翻译就少一类 bug。 +// +// 典型两类: +// - 与公开站共用 443 的私有 vhost(brain/git) → 用 domain,依赖 sniff 取 SNI +// - 独占端口的服务(DSM 5001 / RDP 3389 / SSH 10022-10023) → 用 ip_cidr + port +type ACLTarget struct { + Domain []string `json:"domain,omitempty"` + DomainSuffix []string `json:"domain_suffix,omitempty"` + IPCIDR []string `json:"ip_cidr,omitempty"` + Port []int `json:"port,omitempty"` +} + +// ACLConfig 是节点本地的私有目的地访问控制表(默认 /acl.json)。 +// 只有 AllowDpUUIDs 里的凭证能访问 Targets 描述的目的地,其余一律 reject。 +// +// 与 WarpConfig 的关键区别是失效方向:WARP 读不出来就不分流(fail-open)是安全的, +// ACL 读不出来就不拦截等于把私有服务对全体用户敞开。故本类型的 active() 语义为 +// fail-closed —— 空白名单意味着「没有人」,不是「所有人」。 +type ACLConfig struct { + Enabled bool `json:"enabled"` + AllowDpUUIDs []string `json:"allow_dp_uuids"` + Targets []ACLTarget `json:"targets"` +} + +// LoadACLConfig 读取并解析 acl.json。文件不存在 → (nil, nil)(未配置该功能, +// 不是错误)。解析失败返回 error,由调用方决定回退到 last-good 还是告警。 +func LoadACLConfig(path string) (*ACLConfig, error) { + data, err := os.ReadFile(path) + if os.IsNotExist(err) { + return nil, nil + } + if err != nil { + return nil, fmt.Errorf("agentd: read acl config %q: %w", path, err) + } + var ac ACLConfig + if err := json.Unmarshal(data, &ac); err != nil { + return nil, fmt.Errorf("agentd: parse acl config %q: %w", path, err) + } + return &ac, nil +} + +// empty 报告该 target 是否没有任何匹配条件(没有条件的规则会匹配一切,危险)。 +func (t ACLTarget) empty() bool { + return len(t.Domain) == 0 && len(t.DomainSuffix) == 0 && + len(t.IPCIDR) == 0 && len(t.Port) == 0 +} + +// matchFields 把 target 转成 sing-box route rule 的匹配字段。 +// 每次调用返回全新 map —— 放行与拒绝两条规则各自在其上追加 user/outbound/action, +// 共享同一对象会互相污染。 +func (t ACLTarget) matchFields() map[string]any { + m := make(map[string]any, 4) + if len(t.Domain) > 0 { + m["domain"] = t.Domain + } + if len(t.DomainSuffix) > 0 { + m["domain_suffix"] = t.DomainSuffix + } + if len(t.IPCIDR) > 0 { + m["ip_cidr"] = t.IPCIDR + } + if len(t.Port) > 0 { + m["port"] = t.Port + } + return m +} + +// active 报告本 ACL 是否应真正注入规则。 +// +// 注意与 WarpConfig.active() 的语义差别:此处 AllowDpUUIDs 为空**不影响**返回值。 +// 空白名单是一个合法且有意义的状态 ——「谁都不许访问这些目的地」。把它当作未启用 +// 会造成 fail-open。唯一的关闭途径是显式 "enabled": false。 +func (ac *ACLConfig) active() bool { + if ac == nil || !ac.Enabled { + return false + } + return len(ac.cleanTargets()) > 0 +} + +// cleanUUIDs 去空白/空项后返回白名单。 +func (ac *ACLConfig) cleanUUIDs() []string { + if ac == nil { + return nil + } + out := make([]string, 0, len(ac.AllowDpUUIDs)) + for _, u := range ac.AllowDpUUIDs { + if u = strings.TrimSpace(u); u != "" { + out = append(out, u) + } + } + return out +} + +// cleanTargets 规范化域名(小写去空白)并丢弃无任何条件的 target。 +func (ac *ACLConfig) cleanTargets() []ACLTarget { + if ac == nil { + return nil + } + out := make([]ACLTarget, 0, len(ac.Targets)) + for _, t := range ac.Targets { + c := ACLTarget{ + Domain: cleanHosts(t.Domain), + DomainSuffix: cleanHosts(t.DomainSuffix), + IPCIDR: cleanStrings(t.IPCIDR), + Port: t.Port, + } + if !c.empty() { + out = append(out, c) + } + } + return out +} + +func cleanHosts(in []string) []string { + out := make([]string, 0, len(in)) + for _, s := range in { + if s = strings.TrimSpace(strings.ToLower(s)); s != "" { + out = append(out, s) + } + } + return out +} + +func cleanStrings(in []string) []string { + out := make([]string, 0, len(in)) + for _, s := range in { + if s = strings.TrimSpace(s); s != "" { + out = append(out, s) + } + } + return out +} diff --git a/server/internal/agentd/acl_test.go b/server/internal/agentd/acl_test.go new file mode 100644 index 0000000..b0bdee2 --- /dev/null +++ b/server/internal/agentd/acl_test.go @@ -0,0 +1,175 @@ +package agentd + +import ( + "os" + "path/filepath" + "testing" +) + +// writeACL 把 acl.json 写到指定路径。 +func writeACL(t *testing.T, path, body string) { + t.Helper() + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, []byte(body), 0o600); err != nil { + t.Fatal(err) + } +} + +const validACL = `{ + "enabled": true, + "allow_dp_uuids": ["uuid-me-1", "uuid-me-sub"], + "targets": [ + { "domain": ["brain.51yanmei.com", "git.51yanmei.com"] }, + { "ip_cidr": ["182.92.213.171/32"], "port": [5001, 3389, 10022, 10023] } + ] +}` + +func TestLoadACLConfig(t *testing.T) { + dir := t.TempDir() + + t.Run("文件不存在返回 nil,nil(未配置,不是错误)", func(t *testing.T) { + ac, err := LoadACLConfig(filepath.Join(dir, "missing.json")) + if err != nil { + t.Fatalf("want nil error, got %v", err) + } + if ac != nil { + t.Fatalf("want nil config, got %+v", ac) + } + }) + + t.Run("坏 JSON 返回 error(绝不静默降级)", func(t *testing.T) { + p := filepath.Join(dir, "bad.json") + writeACL(t, p, `{"enabled": true,`) + if _, err := LoadACLConfig(p); err == nil { + t.Fatal("want error for malformed JSON, got nil") + } + }) + + t.Run("合法配置解析出全部字段", func(t *testing.T) { + p := filepath.Join(dir, "acl.json") + writeACL(t, p, validACL) + ac, err := LoadACLConfig(p) + if err != nil { + t.Fatal(err) + } + if !ac.Enabled { + t.Error("Enabled = false, want true") + } + if len(ac.AllowDpUUIDs) != 2 { + t.Errorf("AllowDpUUIDs len = %d, want 2", len(ac.AllowDpUUIDs)) + } + if len(ac.Targets) != 2 { + t.Fatalf("Targets len = %d, want 2", len(ac.Targets)) + } + if len(ac.Targets[0].Domain) != 2 { + t.Errorf("Targets[0].Domain len = %d, want 2", len(ac.Targets[0].Domain)) + } + if len(ac.Targets[1].Port) != 4 { + t.Errorf("Targets[1].Port len = %d, want 4", len(ac.Targets[1].Port)) + } + }) +} + +// active() 的语义与 WARP 相反:空白名单不等于「关闭」,而等于「谁都不许进」。 +func TestACLActive_FailClosed(t *testing.T) { + cases := []struct { + name string + ac *ACLConfig + want bool + }{ + {"nil 配置 → 未启用", nil, false}, + {"enabled=false → 未启用(唯一的合法关闭途径)", &ACLConfig{ + Enabled: false, + AllowDpUUIDs: []string{"u"}, + Targets: []ACLTarget{{Domain: []string{"a.com"}}}, + }, false}, + {"无 target → 未启用(无从拒起)", &ACLConfig{ + Enabled: true, + AllowDpUUIDs: []string{"u"}, + }, false}, + {"target 全为空条件 → 未启用", &ACLConfig{ + Enabled: true, + Targets: []ACLTarget{{}}, + }, false}, + {"白名单为空但有 target → 仍启用(拒绝所有人)", &ACLConfig{ + Enabled: true, + AllowDpUUIDs: nil, + Targets: []ACLTarget{{Domain: []string{"a.com"}}}, + }, true}, + {"完整配置 → 启用", &ACLConfig{ + Enabled: true, + AllowDpUUIDs: []string{"u"}, + Targets: []ACLTarget{{IPCIDR: []string{"1.2.3.4/32"}, Port: []int{443}}}, + }, true}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + if got := tc.ac.active(); got != tc.want { + t.Errorf("active() = %v, want %v", got, tc.want) + } + }) + } +} + +func TestACLCleanHelpers(t *testing.T) { + ac := &ACLConfig{ + Enabled: true, + AllowDpUUIDs: []string{" uuid-a ", "", "uuid-b"}, + Targets: []ACLTarget{ + {Domain: []string{" BRAIN.51yanmei.com ", ""}}, + {}, + {IPCIDR: []string{"1.2.3.4/32"}}, + }, + } + uuids := ac.cleanUUIDs() + if len(uuids) != 2 || uuids[0] != "uuid-a" || uuids[1] != "uuid-b" { + t.Errorf("cleanUUIDs() = %v, want [uuid-a uuid-b]", uuids) + } + targets := ac.cleanTargets() + if len(targets) != 2 { + t.Fatalf("cleanTargets() len = %d, want 2 (空 target 应被丢弃)", len(targets)) + } + if targets[0].Domain[0] != "brain.51yanmei.com" { + t.Errorf("域名未规范化为小写去空白: %q", targets[0].Domain[0]) + } +} + +func TestACLTargetMatchFields(t *testing.T) { + tgt := ACLTarget{ + Domain: []string{"a.com"}, + IPCIDR: []string{"1.2.3.4/32"}, + Port: []int{443, 5001}, + } + m := tgt.matchFields() + if _, ok := m["domain"]; !ok { + t.Error("缺 domain 字段") + } + if _, ok := m["ip_cidr"]; !ok { + t.Error("缺 ip_cidr 字段") + } + if _, ok := m["port"]; !ok { + t.Error("缺 port 字段") + } + if _, ok := m["domain_suffix"]; ok { + t.Error("空的 domain_suffix 不应出现在输出里") + } + // matchFields 必须每次返回新 map,否则放行/拒绝两条规则会共享同一对象, + // 给其中一条加 "user"/"action" 会污染另一条。 + m2 := tgt.matchFields() + m2["user"] = []string{"x"} + if _, ok := m["user"]; ok { + t.Error("matchFields 返回了共享 map,放行与拒绝规则会互相污染") + } +} + +func TestConfigACLPaths(t *testing.T) { + c := Config{StateDir: "/etc/pangolin-agent"}.withDefaults() + if want := "/etc/pangolin-agent/acl.json"; c.ACLConfigPath != want { + t.Errorf("ACLConfigPath = %q, want %q", c.ACLConfigPath, want) + } + if want := "/etc/pangolin-agent/acl.last-good.json"; c.ACLLastGoodPath() != want { + t.Errorf("ACLLastGoodPath() = %q, want %q", c.ACLLastGoodPath(), want) + } +} diff --git a/server/internal/agentd/config.go b/server/internal/agentd/config.go index 6d455f1..b75bca8 100644 --- a/server/internal/agentd/config.go +++ b/server/internal/agentd/config.go @@ -5,9 +5,15 @@ // command feed by managing the local sing-box user table. // // No-state invariant (doc/04 §2, doc/06 §3): the agent persists ONLY the -// credential table (dp_uuid + expires_at) to disk. It keeps zero user identities, -// zero destination/DNS data and writes no access logs. A seized node leaks only -// opaque dp_uuids, never accounts. +// credential table (dp_uuid + expires_at) to disk. It keeps zero user identities +// and writes no access logs. A seized node leaks only opaque dp_uuids, never +// accounts. +// +// 例外(私有目的地 ACL):节点本地 acl.json 含一份 dp_uuid 白名单与目的地清单, +// 由运营手工维护、不经控制面。它确实让节点知道「这几个 dp_uuid 享有私有访问权」 +// 以及那几个私有域名/端口 —— 这是知情接受的不变式弱化,范围仅限该文件与渲染出的 +// route 规则,不涉及账户身份,也不产生任何访问日志。设计见 +// docs/private-dest-acl-design.html §12。 package agentd import ( @@ -58,6 +64,10 @@ type Config struct { // 文件不存在 = WARP 未启用。渲染时读取,支持编辑后重启 agent 生效(#29)。 WarpConfigPath string + // ACLConfigPath 指向节点本地的私有目的地访问控制表(默认 /acl.json)。 + // 文件不存在 = 该功能未配置。渲染时读取,SIGHUP agent 即可生效。 + ACLConfigPath string + // DeriveKey keys the Hy2 password derivation (see DeriveHy2Password). DeriveKey string @@ -86,6 +96,9 @@ func (c Config) withDefaults() Config { if c.WarpConfigPath == "" { c.WarpConfigPath = filepath.Join(c.StateDir, "warp.json") } + if c.ACLConfigPath == "" { + c.ACLConfigPath = filepath.Join(c.StateDir, "acl.json") + } if c.HeartbeatInterval == 0 { c.HeartbeatInterval = DefaultHeartbeatInterval } @@ -118,3 +131,7 @@ func (c Config) KeyPath() string { return filepath.Join(c.StateDir, "node.key" func (c Config) CertPath() string { return filepath.Join(c.StateDir, "node.crt") } func (c Config) CAPath() string { return filepath.Join(c.StateDir, "ca.crt") } func (c Config) StatePath() string { return filepath.Join(c.StateDir, "state.json") } + +// ACLLastGoodPath 是最近一次成功加载的 ACL 快照,供 agent 冷启动时在 acl.json +// 损坏的情况下兜底(fail-closed 跨重启成立的前提)。 +func (c Config) ACLLastGoodPath() string { return filepath.Join(c.StateDir, "acl.last-good.json") } From 6df7c9de44f0a64a279daf09dac04c5ee94da034 Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Thu, 23 Jul 2026 01:12:06 +0800 Subject: [PATCH 04/21] =?UTF-8?q?docs(agent):=20=E4=BF=AE=E5=A4=8D?= =?UTF-8?q?=E8=AE=A1=E5=88=92=E6=9C=AA=E9=97=AD=E5=90=88=E4=BB=A3=E7=A0=81?= =?UTF-8?q?=E5=9D=97=20+=20Task=206=20=E6=94=B9=E7=94=A8=E5=B8=B8=E9=A9=BB?= =?UTF-8?q?=E6=B5=8B=E8=AF=95=E6=A0=A1=E9=AA=8C=E6=A0=B7=E4=BE=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 未闭合的 ```go 让 Task 4-6 的标题落进代码块，task-brief 无法提取； Task 6 原用 go run 校验样例文件，该文件在 module 外无法解析 import， 改为常驻测试 TestACLExampleFileStaysValid，并断言样例 uuid 为占位符 以防真实 dp_uuid 入库。 Co-Authored-By: Claude Opus 4.8 --- docs/private-dest-acl-plan.html | 731 +++++++++--------- .../plans/2026-07-23-private-dest-acl.md | 59 +- 2 files changed, 387 insertions(+), 403 deletions(-) diff --git a/docs/private-dest-acl-plan.html b/docs/private-dest-acl-plan.html index 390a184..b4f020e 100644 --- a/docs/private-dest-acl-plan.html +++ b/docs/private-dest-acl-plan.html @@ -718,402 +718,369 @@ func buildRoute(acl *ACLConfig, warp *WarpConfig) map[string]any { // 例外(私有目的地 ACL):若节点配置了 acl.json,渲染出的 route 规则会含一份享有私有 // 访问权的 dp_uuid 白名单与对应的私有域名/端口。它仍不含任何账户身份(email/user_id), // 但确实让节点知道「这几个 dp_uuid 属于同一组权限」—— 知情接受的不变式弱化, -// 设计与权衡见 docs/private-dest-acl-design.html §12。 +// 设计与权衡见 docs/private-dest-acl-design.html §12。 +

    ⑤ 修改 server/internal/agentd/singbox.go 第 326 行，补一个 nil 实参（Task 4 会替换成真实 ACL）：

    +
    	return renderSingboxConfig(creds, reality, hy2, s.cfg.DeriveKey, warp, nil)
    +
    [ ]Step 4: 跑测试确认通过
    +
    cd server && go test ./internal/agentd/ -run 'BuildRoute|Warp|Render' -v
    +

    Expected: PASS。特别确认既有的 TestRender_NoWarp_NoRouteSection 与 TestRender_Warp_InjectsEndpointAndRoute 仍绿——这两条守着向后兼容。

    +
    [ ]Step 5: 提交
    +
    cd server && go build ./... && go test ./internal/agentd/...
+git add server/internal/agentd/render.go server/internal/agentd/warp.go server/internal/agentd/singbox.go server/internal/agentd/acl_test.go
+git commit -m "refactor(agent): route 块改由 buildRoute 统一产出,合并 ACL 与 WARP"
    +
    +

    Task 4: 渲染时读取 ACL，last-good 内存 + 落盘兜底

    +

    Files:

    +
      +
    • Modify: server/internal/agentd/singbox.go:49-74（SingBox 增 lastGoodACL 字段）、:308-327（RenderConfig 读 ACL）
      • +
    • Modify: server/internal/agentd/acl.go（新增 persistACL）
      • +
    • Modify: server/internal/agentd/acl_test.go（追加 last-good 测试）
      • +
    +

    Interfaces:

    +
      +
    • Consumes: Task 1 的 LoadACLConfig / Config.ACLConfigPath / Config.ACLLastGoodPath()；Task 3 的 renderSingboxConfig 六参签名；既有包内函数 atomicWrite(path string, data []byte, perm os.FileMode) error
      • +
    • Produces: func (s *SingBox) loadACL() *ACLConfig；func persistACL(path string, ac *ACLConfig) error
      • +
    +
    [ ]Step 1: 写失败测试
    +

    追加到 server/internal/agentd/acl_test.go：

    +
    // 成功加载后必须把快照落盘,否则 agent 一重启 fail-closed 就失效。
+func TestACL_PersistsLastGoodOnLoad(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)
 
-⑤ 修改 `server/internal/agentd/singbox.go` 第 326 行，补一个 nil 实参（Task 4 会替换成真实 ACL）：
-
    -

    return renderSingboxConfig(creds, reality, hy2, s.cfg.DeriveKey, warp, nil)

    -
    
-- [ ] **Step 4: 跑测试确认通过**
-
    -

    cd server && go test ./internal/agentd/ -run 'BuildRoute|Warp|Render' -v

    -
    
-Expected: PASS。特别确认既有的 `TestRender_NoWarp_NoRouteSection` 与 `TestRender_Warp_InjectsEndpointAndRoute` 仍绿——这两条守着向后兼容。
+	if _, err := sb.RenderConfig(); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(cfg.ACLLastGoodPath()); err != nil {
+		t.Fatalf("last-good 未落盘: %v", err)
+	}
+}
 
-- [ ] **Step 5: 提交**
-
    -

    cd server && go build ./... && go test ./internal/agentd/...

    -

    git add server/internal/agentd/render.go server/internal/agentd/warp.go server/internal/agentd/singbox.go server/internal/agentd/acl_test.go

    -

    git commit -m "refactor(agent): route 块改由 buildRoute 统一产出,合并 ACL 与 WARP"

    -
    
----
+// acl.json 被改坏 → 规则不能消失(内存 last-good 兜底)。
+func TestACL_BrokenFileKeepsInMemoryLastGood(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)
+	}
 
-### Task 4: 渲染时读取 ACL，last-good 内存 + 落盘兜底
+	writeACL(t, cfg.ACLConfigPath, `{"enabled": true,`) // 手抖写坏
+	data, err := sb.RenderConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(data), "reject") {
+		t.Fatal("acl.json 坏掉后拒绝规则消失了 —— 这是 fail-open,私有服务已敞开")
+	}
+}
 
-**Files:**
-- Modify: `server/internal/agentd/singbox.go:49-74`（`SingBox` 增 `lastGoodACL` 字段）、`:308-327`（`RenderConfig` 读 ACL）
-- Modify: `server/internal/agentd/acl.go`（新增 `persistACL`）
-- Modify: `server/internal/agentd/acl_test.go`（追加 last-good 测试）
+// 新 agent 实例(模拟进程重启)+ 坏 acl.json → 磁盘 last-good 兜底,规则仍在。
+func TestACL_ColdStartFallsBackToDiskLastGood(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)
+	}
 
-**Interfaces:**
-- Consumes: Task 1 的 `LoadACLConfig` / `Config.ACLConfigPath` / `Config.ACLLastGoodPath()`；Task 3 的 `renderSingboxConfig` 六参签名；既有包内函数 `atomicWrite(path string, data []byte, perm os.FileMode) error`
-- Produces: `func (s *SingBox) loadACL() *ACLConfig`；`func persistACL(path string, ac *ACLConfig) error`
+	writeACL(t, cfg.ACLConfigPath, `not json at all`)
+	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,私有服务已敞开")
+	}
+}
 
-- [ ] **Step 1: 写失败测试**
+// 从未配置过(无 acl.json 也无 last-good)→ 不产出 route,且不误报。
+func TestACL_NeverConfiguredYieldsNoRoute(t *testing.T) {
+	cfg := testConfig(t)
+	sb := NewSingBox(cfg, nil)
+	sb.ApplyConfig(sampleSnapshot(&agentv1.Credential{DpUUID: "aaaa", Protocol: agentv1.ProtocolBoth}), true)
+	data, err := sb.RenderConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m map[string]any
+	if err := json.Unmarshal(data, &m); err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := m["route"]; ok {
+		t.Error("未配置 ACL 也未启用 WARP,不应产出 route 块")
+	}
+}
    +

    在 acl_test.go 的 import 块补齐 "encoding/json"、"strings"，以及 agentv1 "github.com/wangjia/pangolin/server/internal/pb/agentv1"。

    +
    [ ]Step 2: 跑测试确认失败
    +
    cd server && go test ./internal/agentd/ -run 'TestACL_' -v
    +

    Expected: TestACL_PersistsLastGoodOnLoad 失败（last-good 未落盘），TestACL_BrokenFile... / TestACL_ColdStart... 失败（渲染结果里没有 reject，因为 Task 3 传的是 nil）。

    +
    [ ]Step 3: 写实现
    +

    ① 在 server/internal/agentd/acl.go 末尾追加：

    +
    // persistACL 把成功加载的 ACL 快照原子写到 path,供 agent 冷启动兜底。
+func persistACL(path string, ac *ACLConfig) error {
+	data, err := json.MarshalIndent(ac, "", "  ")
+	if err != nil {
+		return fmt.Errorf("agentd: marshal acl snapshot: %w", err)
+	}
+	return atomicWrite(path, data, 0o600)
+}
    +

    ② 在 server/internal/agentd/singbox.go 的 SingBox 结构体中，configVersion int64 之后新增字段：

    +
    	// lastGoodACL 是最近一次成功加载的私有目的地 ACL。acl.json 读坏时回退到它,
+	// 而不是像 WARP 那样降级为「不启用」—— 对访问控制,降级即敞开。
+	lastGoodACL *ACLConfig
    +

    ③ 在 server/internal/agentd/singbox.go 的 RenderConfig 中，把 WARP 加载之后的部分替换为：

    +
    	// WARP 分流配置每次渲染读一次:编辑 warp.json 后任一渲染(或 agent 重启)即生效(#29)。
+	// 读失败(坏 JSON)仅记日志、按未启用处理,绝不因坏配置产出无法启动的 sing-box 配置。
+	warp, err := LoadWarpConfig(s.cfg.WarpConfigPath)
+	if err != nil {
+		logf("[warp] load %s failed, WARP routing disabled: %v", s.cfg.WarpConfigPath, err)
+		warp = nil
+	}
+	return renderSingboxConfig(creds, reality, hy2, s.cfg.DeriveKey, warp, s.loadACL())
+}
 
-追加到 `server/internal/agentd/acl_test.go`：
-
    -

    // 成功加载后必须把快照落盘,否则 agent 一重启 fail-closed 就失效。

    -

    func TestACL_PersistsLastGoodOnLoad(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)

    -

    }

    -

    if _, err := os.Stat(cfg.ACLLastGoodPath()); err != nil {

    -

    t.Fatalf("last-good 未落盘: %v", err)

    -

    }

    -

    }

    -

    // acl.json 被改坏 → 规则不能消失(内存 last-good 兜底)。

    -

    func TestACL_BrokenFileKeepsInMemoryLastGood(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,) // 手抖写坏

    -

    data, err := sb.RenderConfig()

    -

    if err != nil {

    -

    t.Fatal(err)

    -

    }

    -

    if !strings.Contains(string(data), "reject") {

    -

    t.Fatal("acl.json 坏掉后拒绝规则消失了 —— 这是 fail-open,私有服务已敞开")

    -

    }

    -

    }

    -

    // 新 agent 实例(模拟进程重启)+ 坏 acl.json → 磁盘 last-good 兜底,规则仍在。

    -

    func TestACL_ColdStartFallsBackToDiskLastGood(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)

    -

    }

    -

    writeACL(t, cfg.ACLConfigPath, not json at all)

    -

    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,私有服务已敞开")

    -

    }

    -

    }

    -

    // 从未配置过(无 acl.json 也无 last-good)→ 不产出 route,且不误报。

    -

    func TestACL_NeverConfiguredYieldsNoRoute(t *testing.T) {

    -

    cfg := testConfig(t)

    -

    sb := NewSingBox(cfg, nil)

    -

    sb.ApplyConfig(sampleSnapshot(&agentv1.Credential{DpUUID: "aaaa", Protocol: agentv1.ProtocolBoth}), true)

    -

    data, err := sb.RenderConfig()

    -

    if err != nil {

    -

    t.Fatal(err)

    -

    }

    -

    var m map[string]any

    -

    if err := json.Unmarshal(data, &m); err != nil {

    -

    t.Fatal(err)

    -

    }

    -

    if _, ok := m["route"]; ok {

    -

    t.Error("未配置 ACL 也未启用 WARP,不应产出 route 块")

    -

    }

    -

    }

    -
    
-在 `acl_test.go` 的 import 块补齐 `"encoding/json"`、`"strings"`，以及 `agentv1 "github.com/wangjia/pangolin/server/internal/pb/agentv1"`。
+// loadACL 读取私有目的地 ACL,并维护 last-good 兜底。
+//
+// 语义刻意与 WARP 相反:WARP 读失败静默降级为「不分流」是安全的,ACL 读失败若也
+// 降级为「不启用」,等于把私有服务对全体 pangolin 用户敞开,而且是静默的。故:
+//   - 成功  → 更新内存 last-good 并落盘,供本进程后续与下次冷启动使用
+//   - 失败/文件消失 → 回退内存 last-good,再回退磁盘 last-good,规则不消失
+//   - 两级 last-good 都没有 → 只能不产出规则(白名单与目的地清单同在一个文件,
+//     文件全丢时连「该拒绝哪些目的地」都无从得知),此时必须大声告警
+func (s *SingBox) loadACL() *ACLConfig {
+	acl, err := LoadACLConfig(s.cfg.ACLConfigPath)
+	switch {
+	case err == nil && acl != nil:
+		s.mu.Lock()
+		s.lastGoodACL = acl
+		s.mu.Unlock()
+		if perr := persistACL(s.cfg.ACLLastGoodPath(), acl); perr != nil {
+			logf("[acl] persist last-good to %s failed: %v", s.cfg.ACLLastGoodPath(), perr)
+		}
+		return acl
+	case err != nil:
+		logf("[acl] ERROR load %s failed: %v", s.cfg.ACLConfigPath, err)
+	}
 
-- [ ] **Step 2: 跑测试确认失败**
-
    -

    cd server && go test ./internal/agentd/ -run 'TestACL_' -v

    -
    
-Expected: `TestACL_PersistsLastGoodOnLoad` 失败（last-good 未落盘），`TestACL_BrokenFile...` / `TestACL_ColdStart...` 失败（渲染结果里没有 reject，因为 Task 3 传的是 nil）。
+	s.mu.Lock()
+	lg := s.lastGoodACL
+	s.mu.Unlock()
+	if lg != nil {
+		logf("[acl] falling back to in-memory last-good ACL")
+		return lg
+	}
 
-- [ ] **Step 3: 写实现**
+	disk, derr := LoadACLConfig(s.cfg.ACLLastGoodPath())
+	if derr == nil && disk != nil {
+		logf("[acl] falling back to on-disk last-good %s", s.cfg.ACLLastGoodPath())
+		s.mu.Lock()
+		s.lastGoodACL = disk
+		s.mu.Unlock()
+		return disk
+	}
 
-① 在 `server/internal/agentd/acl.go` 末尾追加：
-
    -

    // persistACL 把成功加载的 ACL 快照原子写到 path,供 agent 冷启动兜底。

    -

    func persistACL(path string, ac *ACLConfig) error {

    -

    data, err := json.MarshalIndent(ac, "", " ")

    -

    if err != nil {

    -

    return fmt.Errorf("agentd: marshal acl snapshot: %w", err)

    -

    }

    -

    return atomicWrite(path, data, 0o600)

    -

    }

    -
    
-② 在 `server/internal/agentd/singbox.go` 的 `SingBox` 结构体中，`configVersion int64` 之后新增字段：
-
    -

    // lastGoodACL 是最近一次成功加载的私有目的地 ACL。acl.json 读坏时回退到它,

    -

    // 而不是像 WARP 那样降级为「不启用」—— 对访问控制,降级即敞开。

    -

    lastGoodACL *ACLConfig

    -
    
-③ 在 `server/internal/agentd/singbox.go` 的 `RenderConfig` 中，把 WARP 加载之后的部分替换为：
-
    -

    // WARP 分流配置每次渲染读一次:编辑 warp.json 后任一渲染(或 agent 重启)即生效(#29)。

    -

    // 读失败(坏 JSON)仅记日志、按未启用处理,绝不因坏配置产出无法启动的 sing-box 配置。

    -

    warp, err := LoadWarpConfig(s.cfg.WarpConfigPath)

    -

    if err != nil {

    -

    logf("[warp] load %s failed, WARP routing disabled: %v", s.cfg.WarpConfigPath, err)

    -

    warp = nil

    -

    }

    -

    return renderSingboxConfig(creds, reality, hy2, s.cfg.DeriveKey, warp, s.loadACL())

    -

    }

    -

    // loadACL 读取私有目的地 ACL,并维护 last-good 兜底。

    -

    //

    -

    // 语义刻意与 WARP 相反:WARP 读失败静默降级为「不分流」是安全的,ACL 读失败若也

    -

    // 降级为「不启用」,等于把私有服务对全体 pangolin 用户敞开,而且是静默的。故:

    -

    // - 成功 → 更新内存 last-good 并落盘,供本进程后续与下次冷启动使用

    -

    // - 失败/文件消失 → 回退内存 last-good,再回退磁盘 last-good,规则不消失

    -

    // - 两级 last-good 都没有 → 只能不产出规则(白名单与目的地清单同在一个文件,

    -

    // 文件全丢时连「该拒绝哪些目的地」都无从得知),此时必须大声告警

    -

    func (s *SingBox) loadACL() *ACLConfig {

    -

    acl, err := LoadACLConfig(s.cfg.ACLConfigPath)

    -

    switch {

    -

    case err == nil && acl != nil:

    -

    s.mu.Lock()

    -

    s.lastGoodACL = acl

    -

    s.mu.Unlock()

    -

    if perr := persistACL(s.cfg.ACLLastGoodPath(), acl); perr != nil {

    -

    logf("[acl] persist last-good to %s failed: %v", s.cfg.ACLLastGoodPath(), perr)

    -

    }

    -

    return acl

    -

    case err != nil:

    -

    logf("[acl] ERROR load %s failed: %v", s.cfg.ACLConfigPath, err)

    -

    }

    -

    s.mu.Lock()

    -

    lg := s.lastGoodACL

    -

    s.mu.Unlock()

    -

    if lg != nil {

    -

    logf("[acl] falling back to in-memory last-good ACL")

    -

    return lg

    -

    }

    -

    disk, derr := LoadACLConfig(s.cfg.ACLLastGoodPath())

    -

    if derr == nil && disk != nil {

    -

    logf("[acl] 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 {

    -

    logf("[acl] ALERT acl.json is broken and no last-good snapshot exists — "+

    -

    "private destinations are UNPROTECTED (path=%s)", s.cfg.ACLConfigPath)

    -

    }

    -

    return nil

    -

    }

    -
    
-- [ ] **Step 4: 跑测试确认通过**
-
    -

    cd server && go test ./internal/agentd/ -run 'TestACL_' -v

    -
    
-Expected: PASS，四条全绿。
+	if err != nil {
+		logf("[acl] ALERT acl.json is broken and no last-good snapshot exists — "+
+			"private destinations are UNPROTECTED (path=%s)", s.cfg.ACLConfigPath)
+	}
+	return nil
+}
    +
    [ ]Step 4: 跑测试确认通过
    +
    cd server && go test ./internal/agentd/ -run 'TestACL_' -v
    +

    Expected: PASS，四条全绿。

    +
    [ ]Step 5: 提交
    +
    cd server && go build ./... && go test ./internal/agentd/...
+git add server/internal/agentd/acl.go server/internal/agentd/singbox.go server/internal/agentd/acl_test.go
+git commit -m "feat(agent): 渲染时读取 ACL,内存+磁盘 last-good 保证 fail-closed 跨重启"
    +
    +

    Task 5: SIGHUP 触发重渲染（避免重启踢掉全部在线用户）

    +

    Files:

    +
      +
    • Modify: server/internal/agentd/singbox.go（新增导出的 Refresh()）
      • +
    • Modify: server/cmd/agent/main.go:44-45（注册 SIGHUP 处理）
      • +
    • Modify: server/internal/agentd/acl_test.go（追加 Refresh 测试）
      • +
    +

    Interfaces:

    +
      +
    • Consumes: 既有 (*SingBox).markDirty()（未导出）、(*Agent).SingBox() *SingBox（agent.go:83，已导出）
      • +
    • Produces: func (s *SingBox) Refresh() —— 外部触发一次重渲染
      • +
    +

    为什么不用 systemctl restart pangolin-agent： 新进程内 s.started == false（singbox.go:64-67），首次渲染会走 restarter.Restart() 即 systemctl restart sing-box，全部在线用户瞬断。SIGHUP 走的是既有的 debounce → writeAndRestart → Reload()（SIGHUP 热重载）路径，不断线。

    +
    [ ]Step 1: 写失败测试
    +

    追加到 server/internal/agentd/acl_test.go：

    +
    // Refresh() 必须能触发一次重渲染(经 debounce 循环),用于「编辑 acl.json 后
+// systemctl reload pangolin-agent」而不必重启 agent(重启会冷启 sing-box 踢人)。
+func TestSingBoxRefresh_TriggersRender(t *testing.T) {
+	cfg := testConfig(t)
+	writeACL(t, cfg.ACLConfigPath, validACL)
+	fr := &fakeRestarter{}
+	sb := NewSingBox(cfg, fr)
+	sb.ApplyConfig(sampleSnapshot(&agentv1.Credential{DpUUID: "aaaa", Protocol: agentv1.ProtocolBoth}), true)
 
-- [ ] **Step 5: 提交**
-
    -

    cd server && go build ./... && go test ./internal/agentd/...

    -

    git add server/internal/agentd/acl.go server/internal/agentd/singbox.go server/internal/agentd/acl_test.go

    -

    git commit -m "feat(agent): 渲染时读取 ACL,内存+磁盘 last-good 保证 fail-closed 跨重启"

    -
    
----
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go sb.Run(ctx)
 
-### Task 5: SIGHUP 触发重渲染（避免重启踢掉全部在线用户）
+	// 等首次渲染落地(ApplyConfig 已 markDirty)
+	eventually(t, 2*time.Second, func() bool {
+		_, err := os.Stat(cfg.SingboxConfigPath)
+		return err == nil
+	}, "首次渲染写出配置")
 
-**Files:**
-- Modify: `server/internal/agentd/singbox.go`（新增导出的 `Refresh()`）
-- Modify: `server/cmd/agent/main.go:44-45`（注册 SIGHUP 处理）
-- Modify: `server/internal/agentd/acl_test.go`（追加 `Refresh` 测试）
+	// 断言 reloadCount 而非 count:首次渲染已冷启动过(started=true),此后的重渲染
+	// 一律走 Reload(SIGHUP 热重载),Restart 计数不会再增加。断言错计数器会假失败。
+	before := fr.reloadCount()
+	sb.Refresh()
+	eventually(t, 2*time.Second, func() bool { return fr.reloadCount() > before }, "Refresh 触发了热重载")
+}
    +

    在 acl_test.go 的 import 块补齐 "context" 与 "time"。

    +

    复用 singbox_test.go:17-47 既有的 fakeRestarter（count() 返回 Restart 次数、reloadCount() 返回 Reload 次数）与 integration_test.go:248 的 eventually(t *testing.T, timeout time.Duration, fn func() bool, msg string)。

    +
    [ ]Step 2: 跑测试确认失败
    +
    cd server && go test ./internal/agentd/ -run 'Refresh' -v
    +

    Expected: 编译失败，sb.Refresh undefined。

    +
    [ ]Step 3: 写实现
    +

    ① 在 server/internal/agentd/singbox.go 的 markDirty 之后追加：

    +
    // Refresh 请求一次重渲染。供 agent 收到 SIGHUP 时调用,使编辑节点本地配置文件
+// (acl.json / warp.json)后无需重启进程即可生效 —— 重启 agent 会让 sing-box 走
+// 冷启动(Restart),把全部在线用户踢下线。
+func (s *SingBox) Refresh() { s.markDirty() }
    +

    ② 修改 server/cmd/agent/main.go，把第 44–45 行替换为：

    +
    	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
 
-**Interfaces:**
-- Consumes: 既有 `(*SingBox).markDirty()`（未导出）、`(*Agent).SingBox() *SingBox`（`agent.go:83`，已导出）
-- Produces: `func (s *SingBox) Refresh()` —— 外部触发一次重渲染
-
-**为什么不用 `systemctl restart pangolin-agent`：** 新进程内 `s.started == false`（`singbox.go:64-67`），首次渲染会走 `restarter.Restart()` 即 `systemctl restart sing-box`，**全部在线用户瞬断**。SIGHUP 走的是既有的 debounce → `writeAndRestart` → `Reload()`（SIGHUP 热重载）路径，不断线。
-
-- [ ] **Step 1: 写失败测试**
-
-追加到 `server/internal/agentd/acl_test.go`：
-
    -

    // Refresh() 必须能触发一次重渲染(经 debounce 循环),用于「编辑 acl.json 后

    -

    // systemctl reload pangolin-agent」而不必重启 agent(重启会冷启 sing-box 踢人)。

    -

    func TestSingBoxRefresh_TriggersRender(t *testing.T) {

    -

    cfg := testConfig(t)

    -

    writeACL(t, cfg.ACLConfigPath, validACL)

    -

    fr := &fakeRestarter{}

    -

    sb := NewSingBox(cfg, fr)

    -

    sb.ApplyConfig(sampleSnapshot(&agentv1.Credential{DpUUID: "aaaa", Protocol: agentv1.ProtocolBoth}), true)

    -

    ctx, cancel := context.WithCancel(context.Background())

    -

    defer cancel()

    -

    go sb.Run(ctx)

    -

    // 等首次渲染落地(ApplyConfig 已 markDirty)

    -

    eventually(t, 2*time.Second, func() bool {

    -

    _, err := os.Stat(cfg.SingboxConfigPath)

    -

    return err == nil

    -

    }, "首次渲染写出配置")

    -

    // 断言 reloadCount 而非 count:首次渲染已冷启动过(started=true),此后的重渲染

    -

    // 一律走 Reload(SIGHUP 热重载),Restart 计数不会再增加。断言错计数器会假失败。

    -

    before := fr.reloadCount()

    -

    sb.Refresh()

    -

    eventually(t, 2*time.Second, func() bool { return fr.reloadCount() > before }, "Refresh 触发了热重载")

    -

    }

    -
    
-在 `acl_test.go` 的 import 块补齐 `"context"` 与 `"time"`。
-
-> 复用 `singbox_test.go:17-47` 既有的 `fakeRestarter`（`count()` 返回 Restart 次数、`reloadCount()` 返回 Reload 次数）与 `integration_test.go:248` 的 `eventually(t *testing.T, timeout time.Duration, fn func() bool, msg string)`。
-
-- [ ] **Step 2: 跑测试确认失败**
-
    -

    cd server && go test ./internal/agentd/ -run 'Refresh' -v

    -
    
-Expected: 编译失败，`sb.Refresh undefined`。
-
-- [ ] **Step 3: 写实现**
-
-① 在 `server/internal/agentd/singbox.go` 的 `markDirty` 之后追加：
-
    -

    // Refresh 请求一次重渲染。供 agent 收到 SIGHUP 时调用,使编辑节点本地配置文件

    -

    // (acl.json / warp.json)后无需重启进程即可生效 —— 重启 agent 会让 sing-box 走

    -

    // 冷启动(Restart),把全部在线用户踢下线。

    -

    func (s *SingBox) Refresh() { s.markDirty() }

    -
    
-② 修改 `server/cmd/agent/main.go`，把第 44–45 行替换为：
-
    -

    ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)

    -

    defer stop()

    -

    // SIGHUP 重读节点本地配置(acl.json / warp.json)并重渲染。走 sing-box 的 SIGHUP

    -

    // 热重载路径,在线用户不掉线;重启 agent 则会冷启 sing-box,把所有人踢下线。

    -

    hup := make(chan os.Signal, 1)

    -

    signal.Notify(hup, syscall.SIGHUP)

    -

    defer signal.Stop(hup)

    -

    go func() {

    -

    for {

    -

    select {

    -

    case <-ctx.Done():

    -

    return

    -

    case <-hup:

    -

    log.Printf("[pangolin-agent] SIGHUP: re-reading node-local config (acl.json/warp.json)")

    -

    agent.SingBox().Refresh()

    -

    }

    -

    }

    -

    }()

    -
    
-`os` 与 `log` 已在该文件 import 中（`os` 见 `env()` 用到的 `os.LookupEnv`）；若 `go build` 报缺失，按提示补齐。
-
-- [ ] **Step 4: 跑测试确认通过**
-
    -

    cd server && go build ./... && go test ./internal/agentd/ -run 'Refresh' -v

    -
    
-Expected: PASS。
-
-- [ ] **Step 5: 提交**
-
    -

    cd server && go build ./... && go test ./internal/agentd/...

    -

    git add server/internal/agentd/singbox.go server/internal/agentd/acl_test.go server/cmd/agent/main.go

    -

    git commit -m "feat(agent): SIGHUP 重读节点本地配置并热重渲染,不踢在线用户"

    -
    
----
-
-### Task 6: 节点配置样例与运维文档
-
-**Files:**
-- Create: `deploy/single-node/acl.json.example`
-- Modify: `docs/private-dest-acl-design.html`（把 §8 runbook 里的占位符换成指向样例文件）
-
-**Interfaces:**
-- Consumes: Task 1 定义的 `ACLConfig` JSON 形状
-- Produces: 可直接复制到 `/etc/pangolin-agent/acl.json` 的样例
-
-- [ ] **Step 1: 写样例文件**
-
-创建 `deploy/single-node/acl.json.example`：
-
    -

    {

    -

    "_comment": "私有目的地访问控制。复制到 /etc/pangolin-agent/acl.json 并填入自己的 dp_uuid。改完执行 systemctl reload pangolin-agent（不要 restart，restart 会冷启 sing-box 踢掉全部在线用户）。",

    -

    "enabled": true,

    -

    "allow_dp_uuids": [

    -

    "TODO-设备级-dp-uuid",

    -

    "TODO-账户级-dp-uuid-供-sub-订阅链接用"

    -

    ],

    -

    "targets": [

    -

    {

    -

    "_comment": "与公开站共用 ali:443 的私有 vhost，只能靠 SNI 区分",

    -

    "domain": ["brain.51yanmei.com", "git.51yanmei.com"]

    -

    },

    -

    {

    -

    "_comment": "独占端口的服务：DSM 5001 / RDP 3389 / NAS SSH 10022 / Win SSH 10023",

    -

    "ip_cidr": ["182.92.213.171/32"],

    -

    "port": [5001, 3389, 10022, 10023]

    -

    }

    -

    ]

    -

    }

    -
    
-> `_comment` 字段会被 `encoding/json` 忽略（`ACLConfig` 无对应字段且未启用 `DisallowUnknownFields`），可安全保留作自文档。样例里的 `TODO-` 值是**样例文件**的占位，不是计划的占位——真实 uuid 属 PII 级标识，不入 git，由运维按 Step 2 的 SQL 现取现填。
-
-- [ ] **Step 2: 验证样例能被解析且渲染出预期规则**
-
    -

    cd server && cat > /tmp/acl_example_check.go <<'EOF'

    -

    package main

    -

    import (

    -

    "fmt"

    -

    "os"

    -

    "github.com/wangjia/pangolin/server/internal/agentd"

    -

    )

    -

    func main() {

    -

    ac, err := agentd.LoadACLConfig(os.Args[1])

    -

    if err != nil {

    -

    fmt.Println("FAIL:", err)

    -

    os.Exit(1)

    -

    }

    -

    fmt.Printf("OK enabled=%v uuids=%d targets=%d\n", ac.Enabled, len(ac.AllowDpUUIDs), len(ac.Targets))

    -

    }

    -

    EOF

    -

    go run /tmp/acl_example_check.go ../deploy/single-node/acl.json.example && rm /tmp/acl_example_check.go

    -
    
-Expected: `OK enabled=true uuids=2 targets=2`
-
-- [ ] **Step 3: 更新设计文档的 runbook 指向**
-
-在 `docs/private-dest-acl-design.html` 的 §8 首段（`<h2>8. 名单维护 Runbook</h2>` 之后的第一个 `<p>`）末尾追加一句：
-
    -

    样例文件见 <code>deploy/single-node/acl.json.example</code>，复制到 <code>/etc/pangolin-agent/acl.json</code> 后按下方 SQL 填入 uuid。

    -
    
-- [ ] **Step 4: 提交**
-
    -

    cd server && go build ./... && go test ./internal/agentd/...

    -

    git add deploy/single-node/acl.json.example docs/private-dest-acl-design.html

    -

    git commit -m "docs(agent): 私有目的地 ACL 配置样例与 runbook 指向"

    -
    
----
-
-## 上线验收（人工，非代码任务）
-
-代码合并后在 pangolin1 上执行。**先备份现网 sing-box 配置**：`sudo cp /etc/sing-box/config.json /etc/sing-box/config.json.bak-$(date +%F)`（此处 `$(...)` 在服务器交互 shell 中手动执行，不经 agent）。
-
-1. 取白名单 uuid（`UNION` 那一半是账户级 dp_uuid，供 `/sub` 订阅链接用，**漏了会把自己锁在外面**）：
-   ```sql
-   sqlite3 /var/lib/pangolin/pangolin.db \
-     "SELECT d.dp_uuid FROM devices d JOIN users u ON u.id = d.user_id
-       WHERE u.email = '<我的邮箱>' AND d.dp_uuid IS NOT NULL
-      UNION
-      SELECT dp_uuid FROM users WHERE email = '<我的邮箱>';"
-   ```
-2. 写 `/etc/pangolin-agent/acl.json`（权限 `0600`，属主 `pangolin`），`systemctl reload pangolin-agent`。
-3. `journalctl -u pangolin-agent -n 30` 确认已重渲染、无 `[acl] ERROR` / `[acl] ALERT`。
-4. `sudo python3 -c "import json;print(json.load(open('/etc/sing-box/config.json'))['route'])"` 确认规则顺序为 sniff → 放行 → 拒绝 → warp。
-5. **我的设备**：brain 首页 200、DSM 5001 可登录、`ssh nas-r` 通。
-6. **另一账号的设备**：以上全部被拒（连接被 reject，不是超时）。
-7. **公开站不受影响**：jiu / travel / sudoku / pay 在两个账号下均正常。
-8. **WARP 未被破坏**：reddit 仍走 warp 出口。
-9. **fail-closed 实证**：把 `acl.json` 改坏 → `systemctl reload pangolin-agent` → 规则仍在、日志有 ERROR；恢复文件。
-10. **不断线实证**：reload 期间另一台设备保持连接不掉。
-
-## 不在本计划范围内
-
-- 给 brain 加 mTLS / basic auth 作纵深防御（与本计划正交，约一小时，另开）
-- 补 `assertNoIdentityFields` 对渲染配置的覆盖（既有缺口，本计划不扩大也不修复）
-- 控制面下发 ACL（演进路径见设计文档 §11，届时渲染层可原样保留）
-
    + // SIGHUP 重读节点本地配置(acl.json / warp.json)并重渲染。走 sing-box 的 SIGHUP + // 热重载路径,在线用户不掉线;重启 agent 则会冷启 sing-box,把所有人踢下线。 + hup := make(chan os.Signal, 1) + signal.Notify(hup, syscall.SIGHUP) + defer signal.Stop(hup) + go func() { + for { + select { + case <-ctx.Done(): + return + case <-hup: + log.Printf("[pangolin-agent] SIGHUP: re-reading node-local config (acl.json/warp.json)") + agent.SingBox().Refresh() + } + } + }() +

    os 与 log 已在该文件 import 中（os 见 env() 用到的 os.LookupEnv）；若 go build 报缺失，按提示补齐。

    +
    [ ]Step 4: 跑测试确认通过
    +
    cd server && go build ./... && go test ./internal/agentd/ -run 'Refresh' -v
    +

    Expected: PASS。

    +
    [ ]Step 5: 提交
    +
    cd server && go build ./... && go test ./internal/agentd/...
+git add server/internal/agentd/singbox.go server/internal/agentd/acl_test.go server/cmd/agent/main.go
+git commit -m "feat(agent): SIGHUP 重读节点本地配置并热重渲染,不踢在线用户"
    +
    +

    Task 6: 节点配置样例与运维文档

    +

    Files:

    +
      +
    • Create: deploy/single-node/acl.json.example
      • +
    • Modify: server/internal/agentd/acl_test.go（追加样例文件常驻校验测试）
      • +
    • Modify: docs/private-dest-acl-design.html（把 §8 runbook 里的占位符换成指向样例文件）
      • +
    +

    Interfaces:

    +
      +
    • Consumes: Task 1 定义的 ACLConfig JSON 形状
      • +
    • Produces: 可直接复制到 /etc/pangolin-agent/acl.json 的样例
      • +
    +
    [ ]Step 1: 写样例文件
    +

    创建 deploy/single-node/acl.json.example：

    +
    {
+  "_comment": "私有目的地访问控制。复制到 /etc/pangolin-agent/acl.json 并填入自己的 dp_uuid。改完执行 systemctl reload pangolin-agent（不要 restart，restart 会冷启 sing-box 踢掉全部在线用户）。",
+  "enabled": true,
+  "allow_dp_uuids": [
+    "TODO-设备级-dp-uuid",
+    "TODO-账户级-dp-uuid-供-sub-订阅链接用"
+  ],
+  "targets": [
+    {
+      "_comment": "与公开站共用 ali:443 的私有 vhost，只能靠 SNI 区分",
+      "domain": ["brain.51yanmei.com", "git.51yanmei.com"]
+    },
+    {
+      "_comment": "独占端口的服务：DSM 5001 / RDP 3389 / NAS SSH 10022 / Win SSH 10023",
+      "ip_cidr": ["182.92.213.171/32"],
+      "port": [5001, 3389, 10022, 10023]
+    }
+  ]
+}
    +

    _comment 字段会被 encoding/json 忽略（ACLConfig 无对应字段且未启用 DisallowUnknownFields），可安全保留作自文档。样例里的 TODO- 值是样例文件的占位，不是计划的占位——真实 uuid 属 PII 级标识，不入 git，由运维按 Step 2 的 SQL 现取现填。

    +
    [ ]Step 2: 加一条测试，锁死「样例文件永远可解析」
    +

    样例文件会随需求漂移（改了 target 形状却忘了同步样例），靠人工 go run 检查一次没有约束力。改为一条常驻测试。追加到 server/internal/agentd/acl_test.go：

    +
    // 样例文件必须始终可被解析且产出预期规则,防止改了 ACLTarget 形状却忘了同步样例。
+func TestACLExampleFileStaysValid(t *testing.T) {
+	path := filepath.Join("..", "..", "..", "deploy", "single-node", "acl.json.example")
+	ac, err := LoadACLConfig(path)
+	if err != nil {
+		t.Fatalf("样例文件解析失败 %s: %v", path, err)
+	}
+	if ac == nil {
+		t.Fatalf("样例文件不存在: %s", path)
+	}
+	if !ac.active() {
+		t.Error("样例文件应当是一份 active 的 ACL")
+	}
+	if len(ac.Targets) != 2 {
+		t.Errorf("样例 targets = %d, want 2", len(ac.Targets))
+	}
+	// 样例里的 uuid 是占位符,不该是真实 uuid(真实 uuid 属标识信息,不入 git)
+	for _, u := range ac.AllowDpUUIDs {
+		if !strings.HasPrefix(u, "TODO-") {
+			t.Errorf("样例文件混入了非占位 uuid %q —— 真实 dp_uuid 不得入 git", u)
+		}
+	}
+}
    +

    跑：

    +
    cd server && go test ./internal/agentd/ -run 'ExampleFileStaysValid' -v
    +

    Expected: PASS。

    +

    注：_comment 字段会被 encoding/json 忽略（ACLConfig 无对应字段且未启用 DisallowUnknownFields），故样例里的自文档注释不影响解析——这条测试同时守着这个前提。

    +
    [ ]Step 3: 更新设计文档的 runbook 指向
    +

    在 docs/private-dest-acl-design.html 的 §8 首段（<h2>8. 名单维护 Runbook</h2> 之后的第一个 <p>）末尾追加一句：

    +
    样例文件见 <code>deploy/single-node/acl.json.example</code>，复制到 <code>/etc/pangolin-agent/acl.json</code> 后按下方 SQL 填入 uuid。
    +
    [ ]Step 4: 提交
    +
    cd server && go build ./... && go test ./internal/agentd/...
+git add deploy/single-node/acl.json.example server/internal/agentd/acl_test.go docs/private-dest-acl-design.html
+git commit -m "docs(agent): 私有目的地 ACL 配置样例与常驻校验测试"
    +

    git add 只列具体路径，切勿 git add -A：仓库里有未跟踪的 pangolin-release.jks（Android 签名密钥）与若干无关的本地改动，误提交会泄露密钥。

    +
    +

    上线验收（人工，非代码任务）

    +

    代码合并后在 pangolin1 上执行。先备份现网 sing-box 配置：sudo cp /etc/sing-box/config.json /etc/sing-box/config.json.bak-$(date +%F)（此处 $(...) 在服务器交互 shell 中手动执行，不经 agent）。

    +
      +
    1. 取白名单 uuid（UNION 那一半是账户级 dp_uuid，供 /sub 订阅链接用，漏了会把自己锁在外面）：
      2. +
    +

    ```sql

    +

    sqlite3 /var/lib/pangolin/pangolin.db \

    +

    "SELECT d.dp_uuid FROM devices d JOIN users u ON u.id = d.user_id

    +

    WHERE u.email = '<我的邮箱>' AND d.dp_uuid IS NOT NULL

    +

    UNION

    +

    SELECT dp_uuid FROM users WHERE email = '<我的邮箱>';"

    +

    ```

    +
      +
    1. 写 /etc/pangolin-agent/acl.json（权限 0600，属主 pangolin），systemctl reload pangolin-agent。
      2. +
    2. journalctl -u pangolin-agent -n 30 确认已重渲染、无 [acl] ERROR / [acl] ALERT。
      3. +
    3. sudo python3 -c "import json;print(json.load(open('/etc/sing-box/config.json'))['route'])" 确认规则顺序为 sniff → 放行 → 拒绝 → warp。
      4. +
    4. 我的设备：brain 首页 200、DSM 5001 可登录、ssh nas-r 通。
      5. +
    5. 另一账号的设备：以上全部被拒（连接被 reject，不是超时）。
      6. +
    6. 公开站不受影响：jiu / travel / sudoku / pay 在两个账号下均正常。
      7. +
    7. WARP 未被破坏：reddit 仍走 warp 出口。
      8. +
    8. fail-closed 实证：把 acl.json 改坏 → systemctl reload pangolin-agent → 规则仍在、日志有 ERROR；恢复文件。
      9. +
    9. 不断线实证：reload 期间另一台设备保持连接不掉。
      10. +
    +

    不在本计划范围内

    +
      +
    • 给 brain 加 mTLS / basic auth 作纵深防御（与本计划正交，约一小时，另开）
      • +
    • 补 assertNoIdentityFields 对渲染配置的覆盖（既有缺口，本计划不扩大也不修复）
      • +
    • 控制面下发 ACL（演进路径见设计文档 §11，届时渲染层可原样保留）
      • +
    diff --git a/docs/superpowers/plans/2026-07-23-private-dest-acl.md b/docs/superpowers/plans/2026-07-23-private-dest-acl.md index 5aec700..eee0c4e 100644 --- a/docs/superpowers/plans/2026-07-23-private-dest-acl.md +++ b/docs/superpowers/plans/2026-07-23-private-dest-acl.md @@ -774,6 +774,7 @@ func buildRoute(acl *ACLConfig, warp *WarpConfig) map[string]any { // 访问权的 dp_uuid 白名单与对应的私有域名/端口。它仍不含任何账户身份(email/user_id), // 但确实让节点知道「这几个 dp_uuid 属于同一组权限」—— 知情接受的不变式弱化, // 设计与权衡见 docs/private-dest-acl-design.html §12。 +``` ⑤ 修改 `server/internal/agentd/singbox.go` 第 326 行，补一个 nil 实参（Task 4 会替换成真实 ACL）： @@ -1119,6 +1120,7 @@ git commit -m "feat(agent): SIGHUP 重读节点本地配置并热重渲染,不 **Files:** - Create: `deploy/single-node/acl.json.example` +- Modify: `server/internal/agentd/acl_test.go`（追加样例文件常驻校验测试） - Modify: `docs/private-dest-acl-design.html`（把 §8 runbook 里的占位符换成指向样例文件） **Interfaces:** @@ -1153,32 +1155,45 @@ git commit -m "feat(agent): SIGHUP 重读节点本地配置并热重渲染,不 > `_comment` 字段会被 `encoding/json` 忽略（`ACLConfig` 无对应字段且未启用 `DisallowUnknownFields`），可安全保留作自文档。样例里的 `TODO-` 值是**样例文件**的占位，不是计划的占位——真实 uuid 属 PII 级标识，不入 git，由运维按 Step 2 的 SQL 现取现填。 -- [ ] **Step 2: 验证样例能被解析且渲染出预期规则** +- [ ] **Step 2: 加一条测试，锁死「样例文件永远可解析」** -```bash -cd server && cat > /tmp/acl_example_check.go <<'EOF' -package main +样例文件会随需求漂移（改了 target 形状却忘了同步样例），靠人工 `go run` 检查一次没有约束力。改为一条常驻测试。追加到 `server/internal/agentd/acl_test.go`： -import ( - "fmt" - "os" - - "github.com/wangjia/pangolin/server/internal/agentd" -) - -func main() { - ac, err := agentd.LoadACLConfig(os.Args[1]) +```go +// 样例文件必须始终可被解析且产出预期规则,防止改了 ACLTarget 形状却忘了同步样例。 +func TestACLExampleFileStaysValid(t *testing.T) { + path := filepath.Join("..", "..", "..", "deploy", "single-node", "acl.json.example") + ac, err := LoadACLConfig(path) if err != nil { - fmt.Println("FAIL:", err) - os.Exit(1) + t.Fatalf("样例文件解析失败 %s: %v", path, err) + } + if ac == nil { + t.Fatalf("样例文件不存在: %s", path) + } + if !ac.active() { + t.Error("样例文件应当是一份 active 的 ACL") + } + if len(ac.Targets) != 2 { + t.Errorf("样例 targets = %d, want 2", len(ac.Targets)) + } + // 样例里的 uuid 是占位符,不该是真实 uuid(真实 uuid 属标识信息,不入 git) + for _, u := range ac.AllowDpUUIDs { + if !strings.HasPrefix(u, "TODO-") { + t.Errorf("样例文件混入了非占位 uuid %q —— 真实 dp_uuid 不得入 git", u) + } } - fmt.Printf("OK enabled=%v uuids=%d targets=%d\n", ac.Enabled, len(ac.AllowDpUUIDs), len(ac.Targets)) } -EOF -go run /tmp/acl_example_check.go ../deploy/single-node/acl.json.example && rm /tmp/acl_example_check.go ``` -Expected: `OK enabled=true uuids=2 targets=2` +跑： + +```bash +cd server && go test ./internal/agentd/ -run 'ExampleFileStaysValid' -v +``` + +Expected: PASS。 + +> 注：`_comment` 字段会被 `encoding/json` 忽略（`ACLConfig` 无对应字段且未启用 `DisallowUnknownFields`），故样例里的自文档注释不影响解析——这条测试同时守着这个前提。 - [ ] **Step 3: 更新设计文档的 runbook 指向** @@ -1192,10 +1207,12 @@ Expected: `OK enabled=true uuids=2 targets=2` ```bash cd server && go build ./... && go test ./internal/agentd/... -git add deploy/single-node/acl.json.example docs/private-dest-acl-design.html -git commit -m "docs(agent): 私有目的地 ACL 配置样例与 runbook 指向" +git add deploy/single-node/acl.json.example server/internal/agentd/acl_test.go docs/private-dest-acl-design.html +git commit -m "docs(agent): 私有目的地 ACL 配置样例与常驻校验测试" ``` +> `git add` 只列具体路径，**切勿 `git add -A`**：仓库里有未跟踪的 `pangolin-release.jks`（Android 签名密钥）与若干无关的本地改动，误提交会泄露密钥。 + --- ## 上线验收（人工，非代码任务） From d4156b81e24acbd30e3e2c6f7dce3d77c2441d17 Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Thu, 23 Jul 2026 01:32:43 +0800 Subject: [PATCH 05/21] =?UTF-8?q?refactor(agent):=20cleanDomains=20?= =?UTF-8?q?=E5=A7=94=E6=89=98=20cleanHosts,=E6=B6=88=E9=99=A4=E5=90=8C?= =?UTF-8?q?=E5=8C=85=E9=87=8D=E5=A4=8D=E9=80=BB=E8=BE=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- server/internal/agentd/warp.go | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/server/internal/agentd/warp.go b/server/internal/agentd/warp.go index acb40ee..1aed2fa 100644 --- a/server/internal/agentd/warp.go +++ b/server/internal/agentd/warp.go @@ -6,7 +6,6 @@ import ( "net" "os" "strconv" - "strings" ) // WarpConfig 描述节点上「部分域名走 Cloudflare WARP 干净出口」的分流配置(#29)。 @@ -66,15 +65,9 @@ func (wc *WarpConfig) mtu() int { } // cleanDomains 去空白/空项后返回域名清单(用于 domain_suffix)。 +// 与 ACL 的目的地域名规范化共用 cleanHosts,避免两处逻辑漂移。 func (wc *WarpConfig) cleanDomains() []string { - out := make([]string, 0, len(wc.Domains)) - for _, d := range wc.Domains { - d = strings.TrimSpace(strings.ToLower(d)) - if d != "" { - out = append(out, d) - } - } - return out + return cleanHosts(wc.Domains) } // endpointHostPort 拆 Endpoint 为 host + port(active() 已校验可拆)。 From 597d6ab68b5e3b32e8c585d77c8663422d12dd27 Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Thu, 23 Jul 2026 01:40:11 +0800 Subject: [PATCH 06/21] =?UTF-8?q?feat(agent):=20ACL=20=E6=B8=B2=E6=9F=93?= =?UTF-8?q?=E6=94=BE=E8=A1=8C/=E6=8B=92=E7=BB=9D=E8=A7=84=E5=88=99?= =?UTF-8?q?=E5=AF=B9,=E7=A9=BA=E7=99=BD=E5=90=8D=E5=8D=95=E4=BB=8D?= =?UTF-8?q?=E6=8B=92=E7=BB=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- server/internal/agentd/acl.go | 35 +++++++++++++ server/internal/agentd/acl_test.go | 83 ++++++++++++++++++++++++++++++ 2 files changed, 118 insertions(+) diff --git a/server/internal/agentd/acl.go b/server/internal/agentd/acl.go index ee8f336..354b0e0 100644 --- a/server/internal/agentd/acl.go +++ b/server/internal/agentd/acl.go @@ -141,3 +141,38 @@ func cleanStrings(in []string) []string { } return out } + +// rules 产出 ACL 的 sing-box route 规则:每个 target 一对 —— 先放行白名单、再兜底拒绝。 +// +// 顺序是安全性的一部分,不可重排: +// 1. 全部放行规则排在全部拒绝规则之前。不能按 target 交错(放行A/拒绝A/放行B/拒绝B), +// 因为 target 之间可能重叠,交错会让 B 的成员被 A 的拒绝规则先命中。 +// 2. 拒绝规则不带 user 维度 —— 它要对「白名单之外的所有人」生效。 +// 3. 同一 target 的放行与拒绝,目的地条件由同一个 matchFields() 生成,保证逐字相同。 +// 任何不对称都会造成「我自己也被拒」或「有人漏网」。 +// +// 白名单为空时只产出拒绝规则(谁都不许进),这是 fail-closed 的核心:空名单的语义是 +// 「没有人」而非「所有人」。 +func (ac *ACLConfig) rules() []any { + if !ac.active() { + return nil + } + uuids := ac.cleanUUIDs() + targets := ac.cleanTargets() + + out := make([]any, 0, len(targets)*2) + if len(uuids) > 0 { + for _, t := range targets { + r := t.matchFields() + r["user"] = uuids + r["outbound"] = directOutboundTag + out = append(out, r) + } + } + for _, t := range targets { + r := t.matchFields() + r["action"] = "reject" + out = append(out, r) + } + return out +} diff --git a/server/internal/agentd/acl_test.go b/server/internal/agentd/acl_test.go index b0bdee2..53e0fed 100644 --- a/server/internal/agentd/acl_test.go +++ b/server/internal/agentd/acl_test.go @@ -1,6 +1,7 @@ package agentd import ( + "fmt" "os" "path/filepath" "testing" @@ -173,3 +174,85 @@ func TestConfigACLPaths(t *testing.T) { t.Errorf("ACLLastGoodPath() = %q, want %q", c.ACLLastGoodPath(), want) } } + +// rules() 必须产出「先全部放行、再全部拒绝」,且同一 target 两侧目的地条件逐字相同。 +func TestACLRules_AllowThenDeny(t *testing.T) { + ac := &ACLConfig{ + Enabled: true, + AllowDpUUIDs: []string{"uuid-me"}, + Targets: []ACLTarget{ + {Domain: []string{"brain.51yanmei.com"}}, + {IPCIDR: []string{"182.92.213.171/32"}, Port: []int{5001}}, + }, + } + rules := ac.rules() + if len(rules) != 4 { + t.Fatalf("规则数 = %d, want 4 (2 target × 放行+拒绝)", len(rules)) + } + + // 前两条是放行:带 user + outbound,不带 action + for i := 0; i < 2; i++ { + r := rules[i].(map[string]any) + if _, ok := r["user"]; !ok { + t.Errorf("rules[%d] 放行规则缺 user", i) + } + if r["outbound"] != directOutboundTag { + t.Errorf("rules[%d] outbound = %v, want %q", i, r["outbound"], directOutboundTag) + } + if _, ok := r["action"]; ok { + t.Errorf("rules[%d] 放行规则不应带 action", i) + } + } + // 后两条是拒绝:带 action=reject,不带 user(对所有人生效) + for i := 2; i < 4; i++ { + r := rules[i].(map[string]any) + if r["action"] != "reject" { + t.Errorf("rules[%d] action = %v, want reject", i, r["action"]) + } + if _, ok := r["user"]; ok { + t.Errorf("rules[%d] 拒绝规则不应带 user,否则会漏掉名单外的人", i) + } + } + + // 对称性:target[0] 的放行(rules[0])与拒绝(rules[2])目的地条件必须逐字相同 + allow0 := rules[0].(map[string]any) + deny0 := rules[2].(map[string]any) + if fmt.Sprint(allow0["domain"]) != fmt.Sprint(deny0["domain"]) { + t.Errorf("target0 放行/拒绝的 domain 不一致: %v vs %v", allow0["domain"], deny0["domain"]) + } + allow1 := rules[1].(map[string]any) + deny1 := rules[3].(map[string]any) + if fmt.Sprint(allow1["ip_cidr"]) != fmt.Sprint(deny1["ip_cidr"]) || + fmt.Sprint(allow1["port"]) != fmt.Sprint(deny1["port"]) { + t.Error("target1 放行/拒绝的 ip_cidr/port 不一致") + } +} + +// 空白名单 → 不产出放行规则,但拒绝规则照出(fail-closed 的核心断言)。 +func TestACLRules_EmptyAllowlistStillDenies(t *testing.T) { + ac := &ACLConfig{ + Enabled: true, + AllowDpUUIDs: nil, + Targets: []ACLTarget{{Domain: []string{"brain.51yanmei.com"}}}, + } + rules := ac.rules() + if len(rules) != 1 { + t.Fatalf("规则数 = %d, want 1 (仅拒绝)", len(rules)) + } + r := rules[0].(map[string]any) + if r["action"] != "reject" { + t.Errorf("action = %v, want reject", r["action"]) + } +} + +// 未 active(含 nil / enabled=false)→ 无规则。 +func TestACLRules_InactiveYieldsNil(t *testing.T) { + var nilACL *ACLConfig + if got := nilACL.rules(); got != nil { + t.Errorf("nil ACL rules() = %v, want nil", got) + } + off := &ACLConfig{Enabled: false, Targets: []ACLTarget{{Domain: []string{"a.com"}}}} + if got := off.rules(); got != nil { + t.Errorf("enabled=false rules() = %v, want nil", got) + } +} From 4155fc85426d86b0eea5e5b1f33f22ea04a75869 Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Thu, 23 Jul 2026 01:52:39 +0800 Subject: [PATCH 07/21] =?UTF-8?q?refactor(agent):=20route=20=E5=9D=97?= =?UTF-8?q?=E6=94=B9=E7=94=B1=20buildRoute=20=E7=BB=9F=E4=B8=80=E4=BA=A7?= =?UTF-8?q?=E5=87=BA,=E5=90=88=E5=B9=B6=20ACL=20=E4=B8=8E=20WARP?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- server/internal/agentd/acl_test.go | 81 ++++++++++++++++++++++++++++++ server/internal/agentd/render.go | 44 ++++++++++++++-- server/internal/agentd/singbox.go | 2 +- server/internal/agentd/warp.go | 12 ----- 4 files changed, 122 insertions(+), 17 deletions(-) diff --git a/server/internal/agentd/acl_test.go b/server/internal/agentd/acl_test.go index 53e0fed..b849044 100644 --- a/server/internal/agentd/acl_test.go +++ b/server/internal/agentd/acl_test.go @@ -256,3 +256,84 @@ func TestACLRules_InactiveYieldsNil(t *testing.T) { t.Errorf("enabled=false rules() = %v, want nil", got) } } + +// buildRoute 四态矩阵:ACL×WARP 开关的四种组合。 +func TestBuildRoute_Matrix(t *testing.T) { + acl := &ACLConfig{ + Enabled: true, + AllowDpUUIDs: []string{"uuid-me"}, + Targets: []ACLTarget{{Domain: []string{"brain.51yanmei.com"}}}, + } + warp := &WarpConfig{ + Enabled: true, PrivateKey: "k", PeerPublicKey: "pk", + Endpoint: "162.159.192.1:2408", Address: []string{"172.16.0.2/32"}, + Domains: []string{"reddit.com"}, + } + + t.Run("都关 → 不产出 route(向后兼容)", func(t *testing.T) { + if got := buildRoute(nil, nil); got != nil { + t.Errorf("buildRoute(nil,nil) = %v, want nil", got) + } + }) + + t.Run("仅 WARP → sniff + warp 规则(与改动前逐字节一致)", func(t *testing.T) { + r := buildRoute(nil, warp) + rules := r["rules"].([]any) + if len(rules) != 2 { + t.Fatalf("规则数 = %d, want 2", len(rules)) + } + if rules[0].(map[string]any)["action"] != "sniff" { + t.Error("首条不是 sniff") + } + if rules[1].(map[string]any)["outbound"] != warpOutboundTag { + t.Error("次条不是 warp 分流") + } + if r["final"] != directOutboundTag { + t.Errorf("final = %v, want %q", r["final"], directOutboundTag) + } + }) + + t.Run("仅 ACL → sniff + 放行 + 拒绝", func(t *testing.T) { + r := buildRoute(acl, nil) + rules := r["rules"].([]any) + if len(rules) != 3 { + t.Fatalf("规则数 = %d, want 3", len(rules)) + } + if rules[0].(map[string]any)["action"] != "sniff" { + t.Error("首条不是 sniff") + } + if _, ok := rules[1].(map[string]any)["user"]; !ok { + t.Error("第二条不是放行规则") + } + if rules[2].(map[string]any)["action"] != "reject" { + t.Error("第三条不是拒绝规则") + } + }) + + t.Run("都开 → sniff + ACL(放行,拒绝) + warp,且 sniff 只出现一次", func(t *testing.T) { + r := buildRoute(acl, warp) + rules := r["rules"].([]any) + if len(rules) != 4 { + t.Fatalf("规则数 = %d, want 4", len(rules)) + } + sniffs := 0 + for _, x := range rules { + if x.(map[string]any)["action"] == "sniff" { + sniffs++ + } + } + if sniffs != 1 { + t.Errorf("sniff 出现 %d 次, want 1", sniffs) + } + if rules[0].(map[string]any)["action"] != "sniff" { + t.Error("sniff 必须最先") + } + // ACL 全部规则必须排在 warp 之前:被拒绝的目的地不该有机会走 warp 出口 + if rules[3].(map[string]any)["outbound"] != warpOutboundTag { + t.Error("warp 规则必须排在最后") + } + if rules[2].(map[string]any)["action"] != "reject" { + t.Error("ACL 拒绝规则必须排在 warp 之前") + } + }) +} diff --git a/server/internal/agentd/render.go b/server/internal/agentd/render.go index ef2966d..a5223ff 100644 --- a/server/internal/agentd/render.go +++ b/server/internal/agentd/render.go @@ -13,6 +13,11 @@ import ( // // Only the opaque dp_uuid is ever written; no account identity touches the node. // +// 例外(私有目的地 ACL):若节点配置了 acl.json,渲染出的 route 规则会含一份享有私有 +// 访问权的 dp_uuid 白名单与对应的私有域名/端口。它仍不含任何账户身份(email/user_id), +// 但确实让节点知道「这几个 dp_uuid 属于同一组权限」—— 知情接受的不变式弱化, +// 设计与权衡见 docs/private-dest-acl-design.html §12。 +// // 用量统计走 v2ray_api StatsService(loopback gRPC):节点 sing-box 编入 // with_v2ray_api,stats.users 列出全部 dp_uuid → 每个用户独立的 // user>>>{dp_uuid}>>>traffic>>>uplink|downlink 计数器,agent 按用户精确读取 @@ -27,7 +32,7 @@ const ( warpOutboundTag = "warp" ) -func renderSingboxConfig(creds []Cred, reality *agentv1.RealityInbound, hy2 *agentv1.Hy2Inbound, deriveKey string, warp *WarpConfig) ([]byte, error) { +func renderSingboxConfig(creds []Cred, reality *agentv1.RealityInbound, hy2 *agentv1.Hy2Inbound, deriveKey string, warp *WarpConfig, acl *ACLConfig) ([]byte, error) { cfg := map[string]any{ "log": map[string]any{"level": "warn", "timestamp": true}, "inbounds": buildInbounds(creds, reality, hy2, deriveKey), @@ -47,16 +52,47 @@ func renderSingboxConfig(creds []Cred, reality *agentv1.RealityInbound, hy2 *age }, } - // WARP 分流(#29):命中配置域名的流量走 Cloudflare WARP 干净出口,其余直连。 - // warp 为 nil 或未 active 时完全不加 endpoints/route → 与旧配置逐字节一致(向后兼容)。 + // WARP 分流(#29)只贡献 endpoints;route 块由 buildRoute 统一产出,因为它现在要 + // 同时容纳 ACL 规则 —— 原先 cfg["route"] = warp.warpRoute() 是整块覆盖,直接赋值 + // 会把对方的规则干掉。 if warp.active() { cfg["endpoints"] = []any{warp.warpEndpoint()} - cfg["route"] = warp.warpRoute() + } + if route := buildRoute(acl, warp); route != nil { + cfg["route"] = route } return json.MarshalIndent(cfg, "", " ") } +// buildRoute 合并私有目的地 ACL 与 WARP 分流,产出单一 route 块。 +// 两者都未激活时返回 nil —— 不产出 route 字段,与旧配置逐字节一致(向后兼容)。 +// +// 规则顺序是安全语义的一部分: +// 1. {"action":"sniff"} 唯一且最先。域名匹配依赖它取 TLS SNI(客户端多半发的是 +// 已解析 IP),WARP 与 ACL 都需要,故在此统一产出一次,不由各自重复追加。 +// 2. ACL 规则(放行在前、拒绝在后)整体排在 WARP 之前:被 ACL 拒绝的目的地永远 +// 不该还有机会被路由到 warp 出口。 +// 3. final 恒为 direct。 +func buildRoute(acl *ACLConfig, warp *WarpConfig) map[string]any { + aclRules := acl.rules() + warpActive := warp.active() + if len(aclRules) == 0 && !warpActive { + return nil + } + + rules := make([]any, 0, len(aclRules)+2) + rules = append(rules, map[string]any{"action": "sniff"}) + rules = append(rules, aclRules...) + if warpActive { + rules = append(rules, map[string]any{ + "domain_suffix": warp.cleanDomains(), + "outbound": warpOutboundTag, + }) + } + return map[string]any{"rules": rules, "final": directOutboundTag} +} + // statsUsers 收集所有去重 dp_uuid,供 v2ray_api stats.users 按用户开启流量计数器。 func statsUsers(creds []Cred) []string { seen := make(map[string]struct{}, len(creds)) diff --git a/server/internal/agentd/singbox.go b/server/internal/agentd/singbox.go index 9cbf554..e2c5b67 100644 --- a/server/internal/agentd/singbox.go +++ b/server/internal/agentd/singbox.go @@ -323,7 +323,7 @@ func (s *SingBox) RenderConfig() ([]byte, error) { logf("[warp] load %s failed, WARP routing disabled: %v", s.cfg.WarpConfigPath, err) warp = nil } - return renderSingboxConfig(creds, reality, hy2, s.cfg.DeriveKey, warp) + return renderSingboxConfig(creds, reality, hy2, s.cfg.DeriveKey, warp, nil) } // writeAndRestart renders, writes the config file and restarts sing-box. diff --git a/server/internal/agentd/warp.go b/server/internal/agentd/warp.go index 1aed2fa..d86e97f 100644 --- a/server/internal/agentd/warp.go +++ b/server/internal/agentd/warp.go @@ -100,15 +100,3 @@ func (wc *WarpConfig) warpEndpoint() map[string]any { "peers": []any{peer}, } } - -// warpRoute 构造分流 route:先 sniff 取出 SNI/Host(客户端多半发的是已解析 IP, -// 不 sniff 域名规则无从命中),命中域名后缀走 warp,其余 final=direct。 -func (wc *WarpConfig) warpRoute() map[string]any { - return map[string]any{ - "rules": []any{ - map[string]any{"action": "sniff"}, - map[string]any{"domain_suffix": wc.cleanDomains(), "outbound": warpOutboundTag}, - }, - "final": directOutboundTag, - } -} From 87d5afa703c6ad6bec5a24151c60885892964f0e Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Thu, 23 Jul 2026 02:01:45 +0800 Subject: [PATCH 08/21] =?UTF-8?q?feat(agent):=20=E6=B8=B2=E6=9F=93?= =?UTF-8?q?=E6=97=B6=E8=AF=BB=E5=8F=96=20ACL,=E5=86=85=E5=AD=98+=E7=A3=81?= =?UTF-8?q?=E7=9B=98=20last-good=20=E4=BF=9D=E8=AF=81=20fail-closed=20?= =?UTF-8?q?=E8=B7=A8=E9=87=8D=E5=90=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- server/internal/agentd/acl.go | 9 ++++ server/internal/agentd/acl_test.go | 79 ++++++++++++++++++++++++++++++ server/internal/agentd/singbox.go | 53 +++++++++++++++++++- 3 files changed, 140 insertions(+), 1 deletion(-) diff --git a/server/internal/agentd/acl.go b/server/internal/agentd/acl.go index 354b0e0..d9af0d7 100644 --- a/server/internal/agentd/acl.go +++ b/server/internal/agentd/acl.go @@ -176,3 +176,12 @@ func (ac *ACLConfig) rules() []any { } return out } + +// persistACL 把成功加载的 ACL 快照原子写到 path,供 agent 冷启动兜底。 +func persistACL(path string, ac *ACLConfig) error { + data, err := json.MarshalIndent(ac, "", " ") + if err != nil { + return fmt.Errorf("agentd: marshal acl snapshot: %w", err) + } + return atomicWrite(path, data, 0o600) +} diff --git a/server/internal/agentd/acl_test.go b/server/internal/agentd/acl_test.go index b849044..390f53e 100644 --- a/server/internal/agentd/acl_test.go +++ b/server/internal/agentd/acl_test.go @@ -1,10 +1,14 @@ package agentd import ( + "encoding/json" "fmt" "os" "path/filepath" + "strings" "testing" + + agentv1 "github.com/wangjia/pangolin/server/internal/pb/agentv1" ) // writeACL 把 acl.json 写到指定路径。 @@ -337,3 +341,78 @@ func TestBuildRoute_Matrix(t *testing.T) { } }) } + +// 成功加载后必须把快照落盘,否则 agent 一重启 fail-closed 就失效。 +func TestACL_PersistsLastGoodOnLoad(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) + } + if _, err := os.Stat(cfg.ACLLastGoodPath()); err != nil { + t.Fatalf("last-good 未落盘: %v", err) + } +} + +// acl.json 被改坏 → 规则不能消失(内存 last-good 兜底)。 +func TestACL_BrokenFileKeepsInMemoryLastGood(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,`) // 手抖写坏 + data, err := sb.RenderConfig() + if err != nil { + t.Fatal(err) + } + if !strings.Contains(string(data), "reject") { + t.Fatal("acl.json 坏掉后拒绝规则消失了 —— 这是 fail-open,私有服务已敞开") + } +} + +// 新 agent 实例(模拟进程重启)+ 坏 acl.json → 磁盘 last-good 兜底,规则仍在。 +func TestACL_ColdStartFallsBackToDiskLastGood(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) + } + + writeACL(t, cfg.ACLConfigPath, `not json at all`) + 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,私有服务已敞开") + } +} + +// 从未配置过(无 acl.json 也无 last-good)→ 不产出 route,且不误报。 +func TestACL_NeverConfiguredYieldsNoRoute(t *testing.T) { + cfg := testConfig(t) + sb := NewSingBox(cfg, nil) + sb.ApplyConfig(sampleSnapshot(&agentv1.Credential{DpUUID: "aaaa", Protocol: agentv1.ProtocolBoth}), true) + data, err := sb.RenderConfig() + if err != nil { + t.Fatal(err) + } + var m map[string]any + if err := json.Unmarshal(data, &m); err != nil { + t.Fatal(err) + } + if _, ok := m["route"]; ok { + t.Error("未配置 ACL 也未启用 WARP,不应产出 route 块") + } +} diff --git a/server/internal/agentd/singbox.go b/server/internal/agentd/singbox.go index e2c5b67..dc734ad 100644 --- a/server/internal/agentd/singbox.go +++ b/server/internal/agentd/singbox.go @@ -61,6 +61,10 @@ type SingBox struct { hy2 *agentv1.Hy2Inbound configVersion int64 + // lastGoodACL 是最近一次成功加载的私有目的地 ACL。acl.json 读坏时回退到它, + // 而不是像 WARP 那样降级为「不启用」—— 对访问控制,降级即敞开。 + lastGoodACL *ACLConfig + // started 标记 sing-box 是否已被本 agent 冷启动过:首次走 Restart(冷启动), // 之后配置变更走 Reload(SIGHUP 热重载)。agent 进程重启后复位为 false, // 下次渲染做一次冷启动以确保与渲染配置一致。 @@ -323,7 +327,54 @@ func (s *SingBox) RenderConfig() ([]byte, error) { logf("[warp] load %s failed, WARP routing disabled: %v", s.cfg.WarpConfigPath, err) warp = nil } - return renderSingboxConfig(creds, reality, hy2, s.cfg.DeriveKey, warp, nil) + return renderSingboxConfig(creds, reality, hy2, s.cfg.DeriveKey, warp, s.loadACL()) +} + +// loadACL 读取私有目的地 ACL,并维护 last-good 兜底。 +// +// 语义刻意与 WARP 相反:WARP 读失败静默降级为「不分流」是安全的,ACL 读失败若也 +// 降级为「不启用」,等于把私有服务对全体 pangolin 用户敞开,而且是静默的。故: +// - 成功 → 更新内存 last-good 并落盘,供本进程后续与下次冷启动使用 +// - 失败/文件消失 → 回退内存 last-good,再回退磁盘 last-good,规则不消失 +// - 两级 last-good 都没有 → 只能不产出规则(白名单与目的地清单同在一个文件, +// 文件全丢时连「该拒绝哪些目的地」都无从得知),此时必须大声告警 +func (s *SingBox) loadACL() *ACLConfig { + acl, err := LoadACLConfig(s.cfg.ACLConfigPath) + switch { + case err == nil && acl != nil: + s.mu.Lock() + s.lastGoodACL = acl + s.mu.Unlock() + if perr := persistACL(s.cfg.ACLLastGoodPath(), acl); perr != nil { + logf("[acl] persist last-good to %s failed: %v", s.cfg.ACLLastGoodPath(), perr) + } + return acl + case err != nil: + logf("[acl] ERROR load %s failed: %v", s.cfg.ACLConfigPath, err) + } + + s.mu.Lock() + lg := s.lastGoodACL + s.mu.Unlock() + if lg != nil { + logf("[acl] falling back to in-memory last-good ACL") + return lg + } + + disk, derr := LoadACLConfig(s.cfg.ACLLastGoodPath()) + if derr == nil && disk != nil { + logf("[acl] 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 { + logf("[acl] ALERT acl.json is broken and no last-good snapshot exists — "+ + "private destinations are UNPROTECTED (path=%s)", s.cfg.ACLConfigPath) + } + return nil } // writeAndRestart renders, writes the config file and restarts sing-box. From d216e157c300fb603eac402b8e67573c6cf26e70 Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Thu, 23 Jul 2026 02:09:02 +0800 Subject: [PATCH 09/21] =?UTF-8?q?test(agent):=20=E8=A6=86=E7=9B=96=20acl.j?= =?UTF-8?q?son=20=E8=A2=AB=E5=88=A0=E6=97=B6=E4=BB=8D=E8=B5=B0=20last-good?= =?UTF-8?q?=20=E5=85=9C=E5=BA=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 删文件走的是 LoadACLConfig 返回 (nil,nil) 的分支,与坏 JSON 的 err!=nil 分支不同,此前无回归覆盖。 Co-Authored-By: Claude Opus 4.8 --- server/internal/agentd/acl_test.go | 46 ++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/server/internal/agentd/acl_test.go b/server/internal/agentd/acl_test.go index 390f53e..7100b9a 100644 --- a/server/internal/agentd/acl_test.go +++ b/server/internal/agentd/acl_test.go @@ -416,3 +416,49 @@ func TestACL_NeverConfiguredYieldsNoRoute(t *testing.T) { t.Error("未配置 ACL 也未启用 WARP,不应产出 route 块") } } + +// acl.json 被删除 → 规则不能消失(内存 last-good 兜底)。 +func TestACL_DeletedFileKeepsInMemoryLastGood(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) + } + + if err := os.Remove(cfg.ACLConfigPath); err != nil { + t.Fatalf("failed to remove acl.json: %v", err) + } + data, err := sb.RenderConfig() + if err != nil { + t.Fatal(err) + } + if !strings.Contains(string(data), "reject") { + t.Fatal("acl.json 被删除后拒绝规则消失了 —— 这是 fail-open,私有服务已敞开") + } +} + +// 新 agent 实例(模拟进程重启) + 被删的 acl.json → 磁盘 last-good 兜底,规则仍在。 +func TestACL_ColdStartAfterDeletedFileFallsBackToDisk(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) + } + + if err := os.Remove(cfg.ACLConfigPath); err != nil { + t.Fatalf("failed to remove acl.json: %v", err) + } + 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("冷启动(acl.json 删除)未回退到磁盘 last-good,私有服务已敞开") + } +} From 6f183ff0df83f6705433c7ce76db892a278864b0 Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Thu, 23 Jul 2026 02:15:27 +0800 Subject: [PATCH 10/21] =?UTF-8?q?feat(agent):=20SIGHUP=20=E9=87=8D?= =?UTF-8?q?=E8=AF=BB=E8=8A=82=E7=82=B9=E6=9C=AC=E5=9C=B0=E9=85=8D=E7=BD=AE?= =?UTF-8?q?=E5=B9=B6=E7=83=AD=E9=87=8D=E6=B8=B2=E6=9F=93,=E4=B8=8D?= =?UTF-8?q?=E8=B8=A2=E5=9C=A8=E7=BA=BF=E7=94=A8=E6=88=B7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- server/cmd/agent/main.go | 17 +++++++++++++++++ server/internal/agentd/acl_test.go | 28 ++++++++++++++++++++++++++++ server/internal/agentd/singbox.go | 5 +++++ 3 files changed, 50 insertions(+) diff --git a/server/cmd/agent/main.go b/server/cmd/agent/main.go index 8b24693..db358d7 100644 --- a/server/cmd/agent/main.go +++ b/server/cmd/agent/main.go @@ -44,6 +44,23 @@ func main() { ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM) defer stop() + // SIGHUP 重读节点本地配置(acl.json / warp.json)并重渲染。走 sing-box 的 SIGHUP + // 热重载路径,在线用户不掉线;重启 agent 则会冷启 sing-box,把所有人踢下线。 + hup := make(chan os.Signal, 1) + signal.Notify(hup, syscall.SIGHUP) + defer signal.Stop(hup) + go func() { + for { + select { + case <-ctx.Done(): + return + case <-hup: + log.Printf("[pangolin-agent] SIGHUP: re-reading node-local config (acl.json/warp.json)") + agent.SingBox().Refresh() + } + } + }() + log.Printf("[pangolin-agent] starting (control-plane=%s, version=%s)", cfg.ControlPlaneAddr, cfg.AgentVersion) start := time.Now() if err := agent.Run(ctx); err != nil { diff --git a/server/internal/agentd/acl_test.go b/server/internal/agentd/acl_test.go index 7100b9a..a974848 100644 --- a/server/internal/agentd/acl_test.go +++ b/server/internal/agentd/acl_test.go @@ -1,12 +1,14 @@ package agentd import ( + "context" "encoding/json" "fmt" "os" "path/filepath" "strings" "testing" + "time" agentv1 "github.com/wangjia/pangolin/server/internal/pb/agentv1" ) @@ -439,6 +441,32 @@ func TestACL_DeletedFileKeepsInMemoryLastGood(t *testing.T) { } } +// Refresh() 必须能触发一次重渲染(经 debounce 循环),用于「编辑 acl.json 后 +// systemctl reload pangolin-agent」而不必重启 agent(重启会冷启 sing-box 踢人)。 +func TestSingBoxRefresh_TriggersRender(t *testing.T) { + cfg := testConfig(t) + writeACL(t, cfg.ACLConfigPath, validACL) + fr := &fakeRestarter{} + sb := NewSingBox(cfg, fr) + sb.ApplyConfig(sampleSnapshot(&agentv1.Credential{DpUUID: "aaaa", Protocol: agentv1.ProtocolBoth}), true) + + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + go sb.Run(ctx) + + // 等首次渲染落地(ApplyConfig 已 markDirty) + eventually(t, 2*time.Second, func() bool { + _, err := os.Stat(cfg.SingboxConfigPath) + return err == nil + }, "首次渲染写出配置") + + // 断言 reloadCount 而非 count:首次渲染已冷启动过(started=true),此后的重渲染 + // 一律走 Reload(SIGHUP 热重载),Restart 计数不会再增加。断言错计数器会假失败。 + before := fr.reloadCount() + sb.Refresh() + eventually(t, 2*time.Second, func() bool { return fr.reloadCount() > before }, "Refresh 触发了热重载") +} + // 新 agent 实例(模拟进程重启) + 被删的 acl.json → 磁盘 last-good 兜底,规则仍在。 func TestACL_ColdStartAfterDeletedFileFallsBackToDisk(t *testing.T) { cfg := testConfig(t) diff --git a/server/internal/agentd/singbox.go b/server/internal/agentd/singbox.go index dc734ad..8c185b4 100644 --- a/server/internal/agentd/singbox.go +++ b/server/internal/agentd/singbox.go @@ -446,6 +446,11 @@ func (s *SingBox) markDirty() { } } +// Refresh 请求一次重渲染。供 agent 收到 SIGHUP 时调用,使编辑节点本地配置文件 +// (acl.json / warp.json)后无需重启进程即可生效 —— 重启 agent 会让 sing-box 走 +// 冷启动(Restart),把全部在线用户踢下线。 +func (s *SingBox) Refresh() { s.markDirty() } + // Run drives the debounce loop: it coalesces bursts of changes within // DebounceWindow into a single write+restart. It blocks until ctx is cancelled. func (s *SingBox) Run(ctx context.Context) { From 3324c1d687b36744a2e14a9adb0b2db8f5f3ff97 Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Thu, 23 Jul 2026 02:24:51 +0800 Subject: [PATCH 11/21] =?UTF-8?q?docs(agent):=20=E7=A7=81=E6=9C=89?= =?UTF-8?q?=E7=9B=AE=E7=9A=84=E5=9C=B0=20ACL=20=E9=85=8D=E7=BD=AE=E6=A0=B7?= =?UTF-8?q?=E4=BE=8B=E4=B8=8E=E5=B8=B8=E9=A9=BB=E6=A0=A1=E9=AA=8C=E6=B5=8B?= =?UTF-8?q?=E8=AF=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- deploy/single-node/acl.json.example | 19 +++++++++++++++++++ docs/private-dest-acl-design.html | 2 +- server/internal/agentd/acl_test.go | 24 ++++++++++++++++++++++++ 3 files changed, 44 insertions(+), 1 deletion(-) create mode 100644 deploy/single-node/acl.json.example diff --git a/deploy/single-node/acl.json.example b/deploy/single-node/acl.json.example new file mode 100644 index 0000000..8229bae --- /dev/null +++ b/deploy/single-node/acl.json.example @@ -0,0 +1,19 @@ +{ + "_comment": "私有目的地访问控制。复制到 /etc/pangolin-agent/acl.json 并填入自己的 dp_uuid。改完执行 systemctl reload pangolin-agent（不要 restart，restart 会冷启 sing-box 踢掉全部在线用户）。", + "enabled": true, + "allow_dp_uuids": [ + "TODO-设备级-dp-uuid", + "TODO-账户级-dp-uuid-供-sub-订阅链接用" + ], + "targets": [ + { + "_comment": "与公开站共用 ali:443 的私有 vhost，只能靠 SNI 区分", + "domain": ["brain.51yanmei.com", "git.51yanmei.com"] + }, + { + "_comment": "独占端口的服务：DSM 5001 / RDP 3389 / NAS SSH 10022 / Win SSH 10023", + "ip_cidr": ["182.92.213.171/32"], + "port": [5001, 3389, 10022, 10023] + } + ] +} diff --git a/docs/private-dest-acl-design.html b/docs/private-dest-acl-design.html index 0e9e974..f5d7bc6 100644 --- a/docs/private-dest-acl-design.html +++ b/docs/private-dest-acl-design.html @@ -185,7 +185,7 @@

    不动：控制面、数据库（零 migration）、proto、客户端、管理后台、CI。改动全部收敛在 internal/agentd/。

    8. 名单维护 Runbook

    -

    新增/更换设备后，重新生成白名单（UNION 那一半是账户级 dp_uuid，供 /sub 订阅链接用，别漏）：

    +

    新增/更换设备后，重新生成白名单（UNION 那一半是账户级 dp_uuid，供 /sub 订阅链接用，别漏）。样例文件见 deploy/single-node/acl.json.example，复制到 /etc/pangolin-agent/acl.json 后按下方 SQL 填入 uuid。

    sqlite3 /var/lib/pangolin/pangolin.db \
   "SELECT d.dp_uuid FROM devices d JOIN users u ON u.id = d.user_id
     WHERE u.email = '<我的邮箱>' AND d.dp_uuid IS NOT NULL
diff --git a/server/internal/agentd/acl_test.go b/server/internal/agentd/acl_test.go
index a974848..5ae4159 100644
--- a/server/internal/agentd/acl_test.go
+++ b/server/internal/agentd/acl_test.go
@@ -490,3 +490,27 @@ func TestACL_ColdStartAfterDeletedFileFallsBackToDisk(t *testing.T) {
 		t.Fatal("冷启动(acl.json 删除)未回退到磁盘 last-good,私有服务已敞开")
 	}
 }
+
+// 样例文件必须始终可被解析且产出预期规则,防止改了 ACLTarget 形状却忘了同步样例。
+func TestACLExampleFileStaysValid(t *testing.T) {
+	path := filepath.Join("..", "..", "..", "deploy", "single-node", "acl.json.example")
+	ac, err := LoadACLConfig(path)
+	if err != nil {
+		t.Fatalf("样例文件解析失败 %s: %v", path, err)
+	}
+	if ac == nil {
+		t.Fatalf("样例文件不存在: %s", path)
+	}
+	if !ac.active() {
+		t.Error("样例文件应当是一份 active 的 ACL")
+	}
+	if len(ac.Targets) != 2 {
+		t.Errorf("样例 targets = %d, want 2", len(ac.Targets))
+	}
+	// 样例里的 uuid 是占位符,不该是真实 uuid(真实 uuid 属标识信息,不入 git)
+	for _, u := range ac.AllowDpUUIDs {
+		if !strings.HasPrefix(u, "TODO-") {
+			t.Errorf("样例文件混入了非占位 uuid %q —— 真实 dp_uuid 不得入 git", u)
+		}
+	}
+}

From 1cb494daa6077dc4947e630027b65dcfb41300dc Mon Sep 17 00:00:00 2001
From: wangjia <809946525@qq.com>
Date: Thu, 23 Jul 2026 02:28:49 +0800
Subject: [PATCH 12/21] =?UTF-8?q?docs(agent):=20=E8=AE=A1=E5=88=92?=
 =?UTF-8?q?=E5=9B=9E=E5=A1=AB=20cleanHosts=20=E5=8E=BB=E9=87=8D=E7=9A=84?=
 =?UTF-8?q?=E6=89=A7=E8=A1=8C=E5=90=8E=E4=BF=AE=E8=AE=A2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.8 
---
 docs/private-dest-acl-plan.html                       | 1 +
 docs/superpowers/plans/2026-07-23-private-dest-acl.md | 2 ++
 2 files changed, 3 insertions(+)

diff --git a/docs/private-dest-acl-plan.html b/docs/private-dest-acl-plan.html
index b4f020e..dcbda86 100644
--- a/docs/private-dest-acl-plan.html
+++ b/docs/private-dest-acl-plan.html
@@ -428,6 +428,7 @@ func (c Config) ACLLastGoodPath() string { return filepath.Join(c.StateDir, &quo
 
    cd server && go build ./... && go test ./internal/agentd/...
 git add server/internal/agentd/acl.go server/internal/agentd/acl_test.go server/internal/agentd/config.go
 git commit -m "feat(agent): 私有目的地 ACL 配置类型与 fail-closed 加载语义"
    
+
    执行后修订（2026-07-23，提交 d4156b8）：审查指出上面的 cleanHosts 与 warp.go 既有的 cleanDomains 是同包内逐字重复的逻辑。已按用户裁决改为 cleanDomains 委托 cleanHosts（func (wc *WarpConfig) cleanDomains() []string { return cleanHosts(wc.Domains) }，并移除 warp.go 中变为未使用的 strings import）。若日后照本计划重新实现，请直接采用委托版本，不要写回两份重复实现。
    
 
    
 
    Task 2: 由 ACL 产出 route 规则对（放行 + 兜底拒绝）
    
 
    Files:
    
diff --git a/docs/superpowers/plans/2026-07-23-private-dest-acl.md b/docs/superpowers/plans/2026-07-23-private-dest-acl.md
index eee0c4e..bfe16d7 100644
--- a/docs/superpowers/plans/2026-07-23-private-dest-acl.md
+++ b/docs/superpowers/plans/2026-07-23-private-dest-acl.md
@@ -429,6 +429,8 @@ git add server/internal/agentd/acl.go server/internal/agentd/acl_test.go server/
 git commit -m "feat(agent): 私有目的地 ACL 配置类型与 fail-closed 加载语义"
 ```
 
+> **执行后修订（2026-07-23，提交 `d4156b8`）**：审查指出上面的 `cleanHosts` 与 `warp.go` 既有的 `cleanDomains` 是同包内逐字重复的逻辑。已按用户裁决改为 **`cleanDomains` 委托 `cleanHosts`**（`func (wc *WarpConfig) cleanDomains() []string { return cleanHosts(wc.Domains) }`，并移除 `warp.go` 中变为未使用的 `strings` import）。**若日后照本计划重新实现，请直接采用委托版本，不要写回两份重复实现。**
+
 ---
 
 ### Task 2: 由 ACL 产出 route 规则对（放行 + 兜底拒绝）

From 60ff7cc5862f807560b986c583289fdfb31b3b08 Mon Sep 17 00:00:00 2001
From: wangjia <809946525@qq.com>
Date: Thu, 23 Jul 2026 07:36:11 +0800
Subject: [PATCH 13/21] =?UTF-8?q?fix(agent):=20pangolin-agent.service=20?=
 =?UTF-8?q?=E8=A1=A5=20ExecReload,=E4=BD=BF=20systemctl=20reload=20?=
 =?UTF-8?q?=E8=B5=B0=20SIGHUP=20=E7=83=AD=E9=87=8D=E8=BD=BD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

[Service] 块只有 ExecStart,没有 ExecReload——systemctl reload pangolin-agent
返回「Job type reload is not applicable」,运维只能退回 restart,而 restart 会让
agent 进程内 s.started 复位为 false,首次渲染走冷启动 systemctl restart sing-box,
瞬断全部在线用户。这正是 Task 5 SIGHUP 热重载路径存在的意义所在,却因为 unit 文件
缺一行而完全走不通。

Co-Authored-By: Claude Opus 4.8 
---
 deploy/single-node/systemd/pangolin-agent.service | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/deploy/single-node/systemd/pangolin-agent.service b/deploy/single-node/systemd/pangolin-agent.service
index 5ce9add..f24fe38 100644
--- a/deploy/single-node/systemd/pangolin-agent.service
+++ b/deploy/single-node/systemd/pangolin-agent.service
@@ -12,6 +12,10 @@ StartLimitIntervalSec=0
 Type=simple
 EnvironmentFile=/etc/pangolin-agent/agent.env
 ExecStart=/usr/local/bin/pangolin-agent
+# SIGHUP → agent 重读节点本地配置(acl.json/warp.json)并热重渲染,不冷启动
+# sing-box、不踢在线用户。没有这行,`systemctl reload` 会报「Job type reload is
+# not applicable」,运维只能退回 restart(整进程重启,sing-box 冷启动瞬断全员)。
+ExecReload=/bin/kill -HUP $MAINPID
 # 始终自愈(崩溃/被依赖停后都拉起);RestartSec 做退避。
 Restart=always
 RestartSec=5

From 63f4325e511beaae845e54f5df0356687baaef3b Mon Sep 17 00:00:00 2001
From: wangjia <809946525@qq.com>
Date: Thu, 23 Jul 2026 07:37:47 +0800
Subject: [PATCH 14/21] =?UTF-8?q?fix(agent):=20=E7=A9=BA/=E6=89=8B?=
 =?UTF-8?q?=E6=8A=96=20acl.json=20=E4=B8=8D=E5=BE=97=E9=9D=99=E9=BB=98?=
 =?UTF-8?q?=E5=85=B3=E9=97=B8=E6=88=96=E8=A6=86=E7=9B=96=20last-good?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

loadACL 的成功分支此前无条件把解析出的 ACL 存为内存 last-good 并落盘,不管
它是否真的产出任何规则。encoding/json 忽略未知字段(必须如此,样例文件靠
_comment 自文档)——所以 "targetz"(手抖打错 "targets")或 "targets": [] 都能
解析通过,Targets 变 nil,active() 为 false,规则消失(gate 被静默关闭),且同一次
调用还会拿这份空配置覆盖 acl.last-good.json,销毁唯一的恢复快照。

修复:
- enabled=true 但 cleanTargets() 为空 → 视为加载失败,走 last-good 兜底,
  绝不返回、也绝不持久化这份空配置。
- 只有 active() 为真的配置才更新 last-good;active()=false 只可能是显式
  enabled:false(合法关闭),此时原样返回(不产出规则)但不覆盖磁盘上的
  last-good,保留后续误删/损坏时的恢复能力。
- 白名单为空但 target 有效(拒绝所有人的合法配置)不受影响,仍持久化为
  last-good、仍产出拒绝规则。

TDD:acl_test.go 新增三条 —— 手抖字段名(RED:拒绝规则消失且 last-good 被覆盖)、
显式 enabled:false(RED:last-good 被覆盖)、空白名单但有效 target(基线即绿,
防止修复过度矫正)。三条现全绿。

Co-Authored-By: Claude Opus 4.8 
---
 server/internal/agentd/acl_test.go | 90 ++++++++++++++++++++++++++++++
 server/internal/agentd/singbox.go  | 24 ++++++--
 2 files changed, 109 insertions(+), 5 deletions(-)

diff --git a/server/internal/agentd/acl_test.go b/server/internal/agentd/acl_test.go
index 5ae4159..a920b10 100644
--- a/server/internal/agentd/acl_test.go
+++ b/server/internal/agentd/acl_test.go
@@ -1,6 +1,7 @@
 package agentd
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
 	"fmt"
@@ -514,3 +515,92 @@ func TestACLExampleFileStaysValid(t *testing.T) {
 		}
 	}
 }
+
+// ─── C2: 手抖字段名(如 targets → targetz)不得静默关闸,也不得覆盖 last-good ──────
+
+// 字段名手抖(targetz)→ encoding/json 忽略未知字段,Targets 变 nil,active()=false。
+// 若不做特殊处理,旧代码会把这份"看似合法"的空配置当成新的 last-good 落盘,
+// 把恢复用的快照也一起冲掉。正确行为:当作加载失败处理,回退 last-good,不覆盖磁盘。
+func TestACL_TypoFieldWithEnabledTrue_FallsBackWithoutOverwritingLastGood(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)
+	}
+	before, err := os.ReadFile(cfg.ACLLastGoodPath())
+	if err != nil {
+		t.Fatalf("last-good 未在健康加载后落盘: %v", err)
+	}
+
+	// "targets" 手抖成 "targetz":JSON 仍能解析,但 Targets 字段收不到值。
+	writeACL(t, cfg.ACLConfigPath, `{"enabled":true,"allow_dp_uuids":["x"],"targetz":[{"domain":["a.com"]}]}`)
+	data, err := sb.RenderConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(data), "reject") {
+		t.Fatal("字段名手抖(targetz)后拒绝规则消失了 —— 这是静默关闸,私有服务已敞开")
+	}
+	after, err := os.ReadFile(cfg.ACLLastGoodPath())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Equal(before, after) {
+		t.Fatal("手抖配置覆盖了 acl.last-good.json —— 恢复用的快照被销毁了")
+	}
+}
+
+// 显式 enabled:false 是唯一合法的关闭方式,渲染结果必须真的没有 reject 规则;
+// 但它不该覆盖磁盘上已有的 last-good 快照——否则日后 acl.json 意外损坏/丢失时,
+// 回退到的将是这份"已关闭"的快照而不是最近一次真正 active 的配置。
+func TestACL_ExplicitDisableDoesNotOverwriteLastGood(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)
+	}
+	before, err := os.ReadFile(cfg.ACLLastGoodPath())
+	if err != nil {
+		t.Fatalf("last-good 未在健康加载后落盘: %v", err)
+	}
+
+	writeACL(t, cfg.ACLConfigPath, `{"enabled": false, "allow_dp_uuids": ["x"], "targets": [{"domain":["a.com"]}]}`)
+	data, err := sb.RenderConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(data), "reject") {
+		t.Fatal("enabled=false 应真正关闭 ACL,不应再产出 reject 规则")
+	}
+	after, err := os.ReadFile(cfg.ACLLastGoodPath())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Equal(before, after) {
+		t.Fatal("显式 enabled=false 不该覆盖 last-good 快照,否则日后 acl.json 损坏就回不到真正 active 的配置了")
+	}
+}
+
+// 白名单为空但 target 有效 → 是合法的"拒绝所有人"配置,不是手抖,必须仍被当作
+// last-good 持久化,且仍产出拒绝规则。防止 C2 修复对"零 target"的特判过度矫正到
+// "零白名单"上。
+func TestACL_EnabledWithEmptyAllowlistStillPersistsAndDenies(t *testing.T) {
+	cfg := testConfig(t)
+	writeACL(t, cfg.ACLConfigPath, `{"enabled": true, "allow_dp_uuids": [], "targets": [{"domain": ["brain.51yanmei.com"]}]}`)
+	sb := NewSingBox(cfg, nil)
+	sb.ApplyConfig(sampleSnapshot(&agentv1.Credential{DpUUID: "aaaa", Protocol: agentv1.ProtocolBoth}), true)
+	data, err := sb.RenderConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(data), "reject") {
+		t.Fatal("空白名单+有效 target 应仍产出拒绝规则(拒所有人),不该被当成手抖")
+	}
+	if _, err := os.Stat(cfg.ACLLastGoodPath()); err != nil {
+		t.Fatalf("空白名单(但有效 target)的配置应被当作合法 active 配置持久化为 last-good: %v", err)
+	}
+}
diff --git a/server/internal/agentd/singbox.go b/server/internal/agentd/singbox.go
index 8c185b4..961bceb 100644
--- a/server/internal/agentd/singbox.go
+++ b/server/internal/agentd/singbox.go
@@ -342,11 +342,25 @@ func (s *SingBox) loadACL() *ACLConfig {
 	acl, err := LoadACLConfig(s.cfg.ACLConfigPath)
 	switch {
 	case err == nil && acl != nil:
-		s.mu.Lock()
-		s.lastGoodACL = acl
-		s.mu.Unlock()
-		if perr := persistACL(s.cfg.ACLLastGoodPath(), acl); perr != nil {
-			logf("[acl] persist last-good to %s failed: %v", s.cfg.ACLLastGoodPath(), perr)
+		if acl.Enabled && len(acl.cleanTargets()) == 0 {
+			// enabled 却零 target = 几乎必然是字段名手抖(如 targets 打成 targetz)。
+			// encoding/json 对未知字段静默无视,这份配置"看似合法"但毫无内容——当作
+			// 加载失败,走下面的 last-good 兜底,绝不静默敞开、更不能拿它覆盖兜底快照。
+			logf("[acl] ERROR %s parsed but enabled=true yields zero targets — treating as broken, falling back", s.cfg.ACLConfigPath)
+			break // 落到下方 last-good 兜底(Go 的 switch 内 break 只退出 switch)
+		}
+		if acl.active() {
+			// 只有 active 的配置才配当 last-good:否则一次手抖既关闸又冲掉兜底。
+			s.mu.Lock()
+			s.lastGoodACL = acl
+			s.mu.Unlock()
+			if perr := persistACL(s.cfg.ACLLastGoodPath(), acl); perr != nil {
+				logf("[acl] persist last-good to %s failed: %v", s.cfg.ACLLastGoodPath(), perr)
+			}
+		} else {
+			// active() 为 false 但走到了这里,只可能是显式 enabled:false —— 合法关闭。
+			// 直接返回这份(空规则的)配置,不 persist,保留此前的恢复能力。
+			logf("[acl] gate explicitly disabled (enabled=false)")
 		}
 		return acl
 	case err != nil:

From dbc787ac2e34ffcae91f68b9ba4662b77ee5702b Mon Sep 17 00:00:00 2001
From: wangjia <809946525@qq.com>
Date: Thu, 23 Jul 2026 07:38:16 +0800
Subject: [PATCH 15/21] =?UTF-8?q?docs(agent):=20=E8=AE=BE=E8=AE=A1=20?=
 =?UTF-8?q?=C2=A712=20=E8=A1=A5=20SNI=20=E7=BB=95=E8=BF=87=E6=AE=8B?=
 =?UTF-8?q?=E7=95=99=20+=20brain=20basic=20auth=20=E5=B7=B2=E8=90=BD?=
 =?UTF-8?q?=E5=9C=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.8 
---
 docs/private-dest-acl-design.html | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/private-dest-acl-design.html b/docs/private-dest-acl-design.html
index f5d7bc6..059364c 100644
--- a/docs/private-dest-acl-design.html
+++ b/docs/private-dest-acl-design.html
@@ -234,7 +234,8 @@ journalctl -u pangolin-agent -n 20       # 确认已重渲染、无 ACL ERROR
     
  • 泄露 节点配置里我的几台设备 uuid 会出现在同一条规则中（自我关联），且目的地明文可见。目的地本就在公网 DNS 里，泄露面小；但这确实弱化了 render.go:14 的「节点只见不透明 dp_uuid」不变式，属于知情接受，需在该注释处补一行说明。
    • 
     
  • 缺闸 守红线的 assertNoIdentityFields（agentd/singbox_test.go）只作用于 state.json，从不检查渲染出的 sing-box 配置。本设计不扩大这个缺口，但也没有补上——补闸另开。
    • 
-    
  • 建议 本闸失效时（agent 挂了、配置写错）brain 会重新变成对全体 pangolin 用户可读的裸站。建议另外给 brain 加一层 mTLS 或 basic auth 作纵深防御，约一小时工作量，与本设计正交。
    • 
+    
  • 架构限制 443 vhost 的判定依赖 SNI，可被绕过。对 brain/git，节点侧唯一的区分手段是 sniff 出的 SNI。攻击者（持有效 dp_uuid 的其他 pangolin 用户）向 182.92.213.171:443 发起不带 SNI 的 TLS、握手后用 Host: brain.51yanmei.com 头访问，则不匹配任何 domain 规则、也不匹配 ip_cidr（443 不在端口清单里）→ 落 final:direct → nginx 按 Host 路由放行。这在 sing-box 层无法闭合——不能整封 :443，否则 jiu/travel/sudoku/pay 一起死。因此下面这条 brain 鉴权不是「可选纵深」，而是本闸对 brain 的前置条件。
    • 
+    
  • 已做（2026-07-23） brain 已加 nginx basic auth 作纵深防御：ali 的 /etc/nginx/conf.d/brain.conf 在原有 allow 103.119.13.48; deny all 之上叠加 auth_basic（satisfy 默认 all → 源 IP 白名单 与 口令二者都需满足），口令存 Bitwarden「brain basic auth」，htpasswd 仅存 apr1 哈希（明文不落 ali）。acme 通道（:80）与 robots.txt 免密。这样即便本节点 ACL 闸失效（agent 挂了、配置手抖）或被上面的 SNI 手法绕过，brain——唯一无自带鉴权的私有服务——仍不裸奔。
    • 
   
 
   
    相关：~/code/brain/docs/remote-access-brain-domain.html（brain 外网入口与出口 IP 白名单）· baize 台账 ~/code/baize/data/{hosts,domains}.yaml
    

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 16/21] =?UTF-8?q?fix(agent):=20last-good=20=E5=8F=8C?=
 =?UTF-8?q?=E5=A4=B1=E8=B4=A5=E5=BF=85=E9=A1=BB=E5=91=8A=E8=AD=A6=20+=20?=
 =?UTF-8?q?=E9=99=8D=E7=BA=A7=E6=97=A5=E5=BF=97=E5=88=86=E7=BA=A7=20+=20de?=
 =?UTF-8?q?rr=20=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 
---
 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)
 	}

From f147ffbe9e62d01dbb5c2350a44982d0b7dff3c6 Mon Sep 17 00:00:00 2001
From: wangjia <809946525@qq.com>
Date: Thu, 23 Jul 2026 07:43:18 +0800
Subject: [PATCH 17/21] =?UTF-8?q?fix(agent):=20=E6=A0=A1=E9=AA=8C=20ip=5Fc?=
 =?UTF-8?q?idr/port,=E9=9D=9E=E6=B3=95=E5=8D=B3=E8=B5=B0=20fail-closed;?=
 =?UTF-8?q?=E6=B8=B2=E6=9F=93=E4=BA=A7=E7=89=A9=E5=8A=A0=20sing-box=20chec?=
 =?UTF-8?q?k=20=E5=B8=B8=E9=A9=BB=E6=B5=8B=E8=AF=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

cleanTargets 只做 trim/lower,从不校验取值——port:[70000]、ip_cidr:"not-a-cidr"
这类语法正确但语义非法的值会被顺利渲染进 sing-box 配置。SIGHUP 热重载路径下
sing-box 会自己校验并拒绝这份新配置、保留旧实例继续跑,但 agent 早已把它当
"渲染成功"写盘并记正常日志——于是 /etc/sing-box/config.json 内容看起来正常
(能被 json.load 解析、rules 都在),但线上的 gate 其实完全没生效,而这在
运维层面几乎不可见。

修复:
- LoadACLConfig 解析成功后跑一遍 validate():每个 target 的 ip_cidr 必须能被
  netip.ParsePrefix 解析,每个 port 必须落在 1-65535,否则返回 error——与解析
  失败走同一条路径(fail-closed last-good 兜底),而不是把坏值一路渲染出去。
- 新增 TestRenderedConfig_PassesSingBoxCheck:把渲染结果喂给真实 sing-box 1.13.13
  二进制的 `check` 子命令断言 exit 0,把设计 §9 "产物合法性" 验收项落成常驻测试
  (exec.LookPath 找不到二进制则 t.Skip,不 fail)。本机 sing-box(homebrew 装,
  无 with_v2ray_api tag)会因实验性 v2ray_api 段落报编译期不支持的 FATAL——与本
  测试要验的 ACL/route 语法合法性无关,故只在这条测试内剥离该段落后再校验。

TDD:acl_test.go 新增 TestLoadACLConfig_RejectsInvalidPort / _RejectsInvalidCIDR
(RED:此前返回 nil error)、TestACL_InvalidPortFallsBackToLastGood(RED:非法端口
被渲染进配置)。三条现全绿。

Co-Authored-By: Claude Opus 4.8 
---
 server/internal/agentd/acl.go      |  31 ++++++++
 server/internal/agentd/acl_test.go | 119 +++++++++++++++++++++++++++++
 2 files changed, 150 insertions(+)

diff --git a/server/internal/agentd/acl.go b/server/internal/agentd/acl.go
index d9af0d7..537cbad 100644
--- a/server/internal/agentd/acl.go
+++ b/server/internal/agentd/acl.go
@@ -3,6 +3,7 @@ package agentd
 import (
 	"encoding/json"
 	"fmt"
+	"net/netip"
 	"os"
 	"strings"
 )
@@ -47,9 +48,39 @@ func LoadACLConfig(path string) (*ACLConfig, error) {
 	if err := json.Unmarshal(data, &ac); err != nil {
 		return nil, fmt.Errorf("agentd: parse acl config %q: %w", path, err)
 	}
+	if err := ac.validate(); err != nil {
+		return nil, fmt.Errorf("agentd: acl config %q: %w", path, err)
+	}
 	return &ac, nil
 }
 
+// validate 校验每个 target 的 ip_cidr/port 取值本身是否合法(与 cleanTargets 只做
+// trim/lower、完全不校验取值的定位不同)。一个语法正确但语义非法的值(如
+// port:70000、ip_cidr:"not-a-cidr")会被 encoding/json 顺利接受,一路渲染进
+// sing-box 配置——sing-box 自己在 reload/restart 时会拒绝它并保留旧实例,但那时
+// agent 早已把这份坏配置当"渲染成功"写盘,运维靠 journalctl/看 config.json 内容
+// 完全看不出线上 gate 其实没生效。故必须在加载阶段就把这类值当加载失败处理,
+// 使其走 fail-closed 的 last-good 回退路径,而不是让它成为渲染产物。
+func (ac *ACLConfig) validate() error {
+	for i, t := range ac.Targets {
+		for _, c := range t.IPCIDR {
+			c = strings.TrimSpace(c)
+			if c == "" {
+				continue
+			}
+			if _, err := netip.ParsePrefix(c); err != nil {
+				return fmt.Errorf("target[%d] invalid ip_cidr %q: %w", i, c, err)
+			}
+		}
+		for _, p := range t.Port {
+			if p < 1 || p > 65535 {
+				return fmt.Errorf("target[%d] invalid port %d (must be 1-65535)", i, p)
+			}
+		}
+	}
+	return nil
+}
+
 // empty 报告该 target 是否没有任何匹配条件(没有条件的规则会匹配一切,危险)。
 func (t ACLTarget) empty() bool {
 	return len(t.Domain) == 0 && len(t.DomainSuffix) == 0 &&
diff --git a/server/internal/agentd/acl_test.go b/server/internal/agentd/acl_test.go
index 3753ed1..b4adeb9 100644
--- a/server/internal/agentd/acl_test.go
+++ b/server/internal/agentd/acl_test.go
@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"log"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -699,3 +700,121 @@ func TestACL_FallbackLogsCarryWarnLevel(t *testing.T) {
 		t.Fatalf("内存 last-good 兜底日志缺 WARN 级别标签,实际日志:\n%s", logged)
 	}
 }
+
+// ─── I1: 非法 ip_cidr/port 必须在加载阶段被拒绝,走 fail-closed last-good ──────
+
+// port 超出 1-65535、ip_cidr 不是合法 CIDR,cleanTargets 此前只做 trim/lower,
+// 完全不校验取值——这类配置会被当作"合法"渲染进 sing-box 配置,而 sing-box 自己
+// 会在运行时(reload/restart)拒绝它、保留旧实例,导致"渲染产物落盘看起来正常,
+// 但线上 gate 其实没生效"这种难排查的静默失败。加载阶段直接拒绝,让它走
+// last-good 兜底(与解析失败同一条路径),而不是把坏值一路渲染出去。
+func TestLoadACLConfig_RejectsInvalidPort(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "acl.json")
+	writeACL(t, p, `{
+		"enabled": true,
+		"allow_dp_uuids": ["u"],
+		"targets": [{ "ip_cidr": ["182.92.213.171/32"], "port": [70000] }]
+	}`)
+	if _, err := LoadACLConfig(p); err == nil {
+		t.Fatal("port 70000 超出合法范围(1-65535),LoadACLConfig 应返回 error")
+	}
+}
+
+func TestLoadACLConfig_RejectsInvalidCIDR(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "acl.json")
+	writeACL(t, p, `{
+		"enabled": true,
+		"allow_dp_uuids": ["u"],
+		"targets": [{ "ip_cidr": ["not-a-cidr"], "port": [443] }]
+	}`)
+	if _, err := LoadACLConfig(p); err == nil {
+		t.Fatal("ip_cidr \"not-a-cidr\" 不是合法 CIDR,LoadACLConfig 应返回 error")
+	}
+}
+
+// 非法配置在 loadACL 层面必须走 last-good 兜底(与解析失败同一条路径),而不是
+// 被渲染进 sing-box 配置。
+func TestACL_InvalidPortFallsBackToLastGood(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,
+		"allow_dp_uuids": ["u"],
+		"targets": [{ "ip_cidr": ["182.92.213.171/32"], "port": [70000] }]
+	}`)
+	data, err := sb.RenderConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(data), "70000") {
+		t.Fatal("非法 port 70000 不应该被渲染进 sing-box 配置,应走 last-good 兜底")
+	}
+	if !strings.Contains(string(data), "reject") {
+		t.Fatal("非法配置应走 last-good 兜底,拒绝规则不应消失")
+	}
+}
+
+// 产物合法性:渲染结果喂给真实 sing-box 二进制的 `check` 子命令,必须 exit 0。
+// 这把设计 §9 "产物合法性" 验收项变成一条常驻测试,而不是只在上线前手工跑一次。
+//
+// 刻意不经 SingBox/ApplyConfig 走完整 reality/hy2 inbound(sampleSnapshot 里的
+// PrivateKey/CertPath 都是占位假值,sing-box 会因证书/密钥不合法而拒绝——那是
+// 另一类问题,不是本测试要盯的 ACL route 合法性)。直接调用 renderSingboxConfig,
+// reality/hy2 传 nil,只产出 outbounds + ACL route,聚焦 §9 要验的东西。
+func TestRenderedConfig_PassesSingBoxCheck(t *testing.T) {
+	singboxBin, err := exec.LookPath("sing-box")
+	if err != nil {
+		t.Skip("sing-box not installed, skipping resident config-validity check")
+	}
+
+	ac, err := LoadACLConfig(writeTempACL(t, validACL))
+	if err != nil {
+		t.Fatal(err)
+	}
+	data, err := renderSingboxConfig(nil, nil, nil, "test-derive-key", nil, ac)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// homebrew 装的本机 sing-box 二进制没有编译 with_v2ray_api tag(生产节点上的
+	// 那份是),`v2ray_api` 这段实验性配置在本机会导致 check 因为"功能未编译进来"
+	// 而 FATAL——这与本测试要验的 ACL/route 语法合法性无关,故只为本次校验剥离它。
+	var m map[string]any
+	if err := json.Unmarshal(data, &m); err != nil {
+		t.Fatal(err)
+	}
+	if exp, ok := m["experimental"].(map[string]any); ok {
+		delete(exp, "v2ray_api")
+	}
+	data, err = json.Marshal(m)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	dir := t.TempDir()
+	cfgPath := filepath.Join(dir, "config.json")
+	if err := os.WriteFile(cfgPath, data, 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	out, err := exec.Command(singboxBin, "check", "-c", cfgPath).CombinedOutput()
+	if err != nil {
+		t.Fatalf("sing-box check 未通过(exit != 0): %v\n%s", err, out)
+	}
+}
+
+// writeTempACL 把 body 写到临时目录下的 acl.json 并返回路径。
+func writeTempACL(t *testing.T, body string) string {
+	t.Helper()
+	p := filepath.Join(t.TempDir(), "acl.json")
+	writeACL(t, p, body)
+	return p
+}

From aaa3384e3b1c99c5c5fe1cd964fc7f0579c3fe90 Mon Sep 17 00:00:00 2001
From: wangjia <809946525@qq.com>
Date: Thu, 23 Jul 2026 07:44:58 +0800
Subject: [PATCH 18/21] =?UTF-8?q?feat(agent):=20route=20=E5=8A=A0=20resolv?=
 =?UTF-8?q?e=20action,=E5=A0=B5=E4=BD=8F=20ip=5Fcidr=20=E7=9B=AE=E7=9A=84?=
 =?UTF-8?q?=E5=9C=B0=E7=9A=84=E5=9F=9F=E5=90=8D=E5=BD=A2=E5=BC=8F=E7=BB=95?=
 =?UTF-8?q?=E8=BF=87?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

sing-box route 的 ip_cidr 匹配的是已解析的连接目的地地址;客户端若发的是域名
形式(如 nas.51yanmei.com:5001)而不先解析,ip_cidr + port 的拒绝规则不命中,
请求会绕过 ACL 直接落到 final:direct——DSM/RDP/SSH 因而对任何持有有效 dp_uuid
的 pangolin 用户可达,不受白名单约束。攻击者只需让客户端连接目的地时使用域名
而非 IP 即可绕过。

用户已拍板方案:在 sniff 之后紧跟加一条 {"action":"resolve"},让节点自己解析
目的地,使域名形式收敛到 ip_cidr 规则上(已用本机 sing-box 1.13.13 确认接受
[{"action":"sniff"},{"action":"resolve"},...] 这个形状,TestRenderedConfig_
PassesSingBoxCheck 也覆盖了这条产物)。route 规则顺序变为:
sniff → resolve → ACL 放行 → ACL 拒绝 → WARP。resolve 与 sniff 同条件——只在
产出 route 块时才出现,唯一且紧跟 sniff。

代价(用户已知情接受):节点从此会对连接目的地做 DNS 解析,是对"节点只见不透明
dp_uuid、不知道目的地"这条隐私姿态的一次主动后退,详见设计文档 §12。

TDD:更新 TestBuildRoute_Matrix 的四态断言(规则数 2/3/4 → 3/4/5,新增 resolve
计数/位置断言),新增 TestBuildRoute_ResolvePositionedRightAfterSniff(RED:此前
resolve 不存在)与 TestBuildRoute_NeverConfigured_NoResolve(未配置态不受影响)。
确认既有 TestRender_Warp_InjectsEndpointAndRoute(只断言首条 sniff、末条 warp,
不断言精确条数)未受影响,原样绿。

Co-Authored-By: Claude Opus 4.8 
---
 server/internal/agentd/acl_test.go | 102 +++++++++++++++++++++--------
 server/internal/agentd/render.go   |  14 +++-
 2 files changed, 85 insertions(+), 31 deletions(-)

diff --git a/server/internal/agentd/acl_test.go b/server/internal/agentd/acl_test.go
index b4adeb9..b8e9ffe 100644
--- a/server/internal/agentd/acl_test.go
+++ b/server/internal/agentd/acl_test.go
@@ -299,68 +299,114 @@ func TestBuildRoute_Matrix(t *testing.T) {
 		}
 	})
 
-	t.Run("仅 WARP → sniff + warp 规则(与改动前逐字节一致)", func(t *testing.T) {
+	t.Run("仅 WARP → sniff + resolve + warp 规则", func(t *testing.T) {
 		r := buildRoute(nil, warp)
 		rules := r["rules"].([]any)
-		if len(rules) != 2 {
-			t.Fatalf("规则数 = %d, want 2", len(rules))
-		}
-		if rules[0].(map[string]any)["action"] != "sniff" {
-			t.Error("首条不是 sniff")
-		}
-		if rules[1].(map[string]any)["outbound"] != warpOutboundTag {
-			t.Error("次条不是 warp 分流")
-		}
-		if r["final"] != directOutboundTag {
-			t.Errorf("final = %v, want %q", r["final"], directOutboundTag)
-		}
-	})
-
-	t.Run("仅 ACL → sniff + 放行 + 拒绝", func(t *testing.T) {
-		r := buildRoute(acl, nil)
-		rules := r["rules"].([]any)
 		if len(rules) != 3 {
 			t.Fatalf("规则数 = %d, want 3", len(rules))
 		}
 		if rules[0].(map[string]any)["action"] != "sniff" {
 			t.Error("首条不是 sniff")
 		}
-		if _, ok := rules[1].(map[string]any)["user"]; !ok {
-			t.Error("第二条不是放行规则")
+		if rules[1].(map[string]any)["action"] != "resolve" {
+			t.Error("第二条不是 resolve(域名形式的目的地需要先解析才能命中后续 ip_cidr 规则)")
 		}
-		if rules[2].(map[string]any)["action"] != "reject" {
-			t.Error("第三条不是拒绝规则")
+		if rules[2].(map[string]any)["outbound"] != warpOutboundTag {
+			t.Error("第三条不是 warp 分流")
+		}
+		if r["final"] != directOutboundTag {
+			t.Errorf("final = %v, want %q", r["final"], directOutboundTag)
 		}
 	})
 
-	t.Run("都开 → sniff + ACL(放行,拒绝) + warp,且 sniff 只出现一次", func(t *testing.T) {
-		r := buildRoute(acl, warp)
+	t.Run("仅 ACL → sniff + resolve + 放行 + 拒绝", func(t *testing.T) {
+		r := buildRoute(acl, nil)
 		rules := r["rules"].([]any)
 		if len(rules) != 4 {
 			t.Fatalf("规则数 = %d, want 4", len(rules))
 		}
-		sniffs := 0
+		if rules[0].(map[string]any)["action"] != "sniff" {
+			t.Error("首条不是 sniff")
+		}
+		if rules[1].(map[string]any)["action"] != "resolve" {
+			t.Error("第二条不是 resolve")
+		}
+		if _, ok := rules[2].(map[string]any)["user"]; !ok {
+			t.Error("第三条不是放行规则")
+		}
+		if rules[3].(map[string]any)["action"] != "reject" {
+			t.Error("第四条不是拒绝规则")
+		}
+	})
+
+	t.Run("都开 → sniff + resolve + ACL(放行,拒绝) + warp,且 sniff/resolve 各只出现一次", func(t *testing.T) {
+		r := buildRoute(acl, warp)
+		rules := r["rules"].([]any)
+		if len(rules) != 5 {
+			t.Fatalf("规则数 = %d, want 5", len(rules))
+		}
+		sniffs, resolves := 0, 0
 		for _, x := range rules {
-			if x.(map[string]any)["action"] == "sniff" {
+			switch x.(map[string]any)["action"] {
+			case "sniff":
 				sniffs++
+			case "resolve":
+				resolves++
 			}
 		}
 		if sniffs != 1 {
 			t.Errorf("sniff 出现 %d 次, want 1", sniffs)
 		}
+		if resolves != 1 {
+			t.Errorf("resolve 出现 %d 次, want 1", resolves)
+		}
 		if rules[0].(map[string]any)["action"] != "sniff" {
 			t.Error("sniff 必须最先")
 		}
+		if rules[1].(map[string]any)["action"] != "resolve" {
+			t.Error("resolve 必须紧跟 sniff 之后")
+		}
 		// ACL 全部规则必须排在 warp 之前:被拒绝的目的地不该有机会走 warp 出口
-		if rules[3].(map[string]any)["outbound"] != warpOutboundTag {
+		if rules[4].(map[string]any)["outbound"] != warpOutboundTag {
 			t.Error("warp 规则必须排在最后")
 		}
-		if rules[2].(map[string]any)["action"] != "reject" {
+		if rules[3].(map[string]any)["action"] != "reject" {
 			t.Error("ACL 拒绝规则必须排在 warp 之前")
 		}
 	})
 }
 
+// I3:ip_cidr 目的地能被"域名形式"的请求绕过——ip_cidr 匹配的是已解析的目的地
+// 地址,客户端若发送域名形式(如 nas.51yanmei.com:5001)而不先解析,ip_cidr 规则
+// 不命中,请求穿透到 final:direct。route 块加 {"action":"resolve"} 让节点自己
+// 解析目的地,使域名形式收敛到 ip_cidr 规则上。resolve 必须紧跟 sniff 之后、且
+// 只在产出 route 块时才出现(与 sniff 同条件)。
+func TestBuildRoute_ResolvePositionedRightAfterSniff(t *testing.T) {
+	acl := &ACLConfig{
+		Enabled:      true,
+		AllowDpUUIDs: []string{"uuid-me"},
+		Targets:      []ACLTarget{{IPCIDR: []string{"182.92.213.171/32"}, Port: []int{5001}}},
+	}
+	r := buildRoute(acl, nil)
+	rules := r["rules"].([]any)
+	if len(rules) < 2 {
+		t.Fatalf("规则数 = %d, 至少要有 sniff+resolve", len(rules))
+	}
+	if rules[0].(map[string]any)["action"] != "sniff" {
+		t.Fatal("sniff 必须最先")
+	}
+	if rules[1].(map[string]any)["action"] != "resolve" {
+		t.Fatal("resolve 必须紧跟 sniff 之后")
+	}
+}
+
+// 未配置 ACL 也未启用 WARP → 仍不产出 route 块(resolve 不该单独出现)。
+func TestBuildRoute_NeverConfigured_NoResolve(t *testing.T) {
+	if got := buildRoute(nil, nil); got != nil {
+		t.Errorf("buildRoute(nil,nil) = %v, want nil", got)
+	}
+}
+
 // 成功加载后必须把快照落盘,否则 agent 一重启 fail-closed 就失效。
 func TestACL_PersistsLastGoodOnLoad(t *testing.T) {
 	cfg := testConfig(t)
diff --git a/server/internal/agentd/render.go b/server/internal/agentd/render.go
index a5223ff..452df8a 100644
--- a/server/internal/agentd/render.go
+++ b/server/internal/agentd/render.go
@@ -71,9 +71,16 @@ func renderSingboxConfig(creds []Cred, reality *agentv1.RealityInbound, hy2 *age
 // 规则顺序是安全语义的一部分:
 //  1. {"action":"sniff"} 唯一且最先。域名匹配依赖它取 TLS SNI(客户端多半发的是
 //     已解析 IP),WARP 与 ACL 都需要,故在此统一产出一次,不由各自重复追加。
-//  2. ACL 规则(放行在前、拒绝在后)整体排在 WARP 之前:被 ACL 拒绝的目的地永远
+//  2. {"action":"resolve"} 紧跟 sniff 之后,同样唯一且只在产出 route 块时才出现。
+//     ACL 的 ip_cidr 目的地(DSM/RDP/SSH 等独占端口服务)匹配的是已解析的连接
+//     目的地地址——若客户端发的是域名形式(如 nas.51yanmei.com:5001)而节点不主动
+//     解析,ip_cidr 规则不命中,请求会绕过 ACL 直接落到 final:direct。resolve 让
+//     节点自己解析目的地,使域名形式收敛到 ip_cidr 规则上,堵住这个绕过口子
+//     (I3;这也是唯一一处从"节点不知道目的地"这条不变式主动后退的地方,是知情
+//     接受的取舍,见 docs/private-dest-acl-design.html §12)。
+//  3. ACL 规则(放行在前、拒绝在后)整体排在 WARP 之前:被 ACL 拒绝的目的地永远
 //     不该还有机会被路由到 warp 出口。
-//  3. final 恒为 direct。
+//  4. final 恒为 direct。
 func buildRoute(acl *ACLConfig, warp *WarpConfig) map[string]any {
 	aclRules := acl.rules()
 	warpActive := warp.active()
@@ -81,8 +88,9 @@ func buildRoute(acl *ACLConfig, warp *WarpConfig) map[string]any {
 		return nil
 	}
 
-	rules := make([]any, 0, len(aclRules)+2)
+	rules := make([]any, 0, len(aclRules)+3)
 	rules = append(rules, map[string]any{"action": "sniff"})
+	rules = append(rules, map[string]any{"action": "resolve"})
 	rules = append(rules, aclRules...)
 	if warpActive {
 		rules = append(rules, map[string]any{

From e4b527b2c9ac6f5b6b2aa0a8cb6e313216a17d22 Mon Sep 17 00:00:00 2001
From: wangjia <809946525@qq.com>
Date: Thu, 23 Jul 2026 07:45:38 +0800
Subject: [PATCH 19/21] =?UTF-8?q?docs(agent):=20=E4=B8=8A=E7=BA=BF?=
 =?UTF-8?q?=E9=AA=8C=E6=94=B6=E8=A1=A5=E3=80=8Clive=20=E7=94=9F=E6=95=88?=
 =?UTF-8?q?=E6=A0=B8=E5=AE=9E=E3=80=8D=E4=B8=8E=E3=80=8C=E5=9F=9F=E5=90=8D?=
 =?UTF-8?q?+=E8=A3=B8IP=20=E5=8F=8C=E5=BD=A2=E5=BC=8F=E6=B5=8B=E5=8F=A6?=
 =?UTF-8?q?=E4=B8=80=E8=B4=A6=E5=8F=B7=E8=A2=AB=E6=8B=92=E3=80=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

C1 指出 config.json 内容正常不等于线上生效——SIGHUP 走 sing-box 自身校验,若
新配置被拒,它会保留旧实例继续跑,agent 侧仍记"渲染成功"。第 4 步补
systemctl is-active sing-box + journalctl -u sing-box -n5 | grep -v FATAL。

I3 表明 ip_cidr 目的地存在域名形式绕过口子(已修),第 6 步"另一账号被拒"补充
必须分别用域名和裸 IP 两种目的地表达形式各测一遍,只测一种形式验证不到位。

Co-Authored-By: Claude Opus 4.8 
---
 docs/superpowers/plans/2026-07-23-private-dest-acl.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/docs/superpowers/plans/2026-07-23-private-dest-acl.md b/docs/superpowers/plans/2026-07-23-private-dest-acl.md
index bfe16d7..68df1ef 100644
--- a/docs/superpowers/plans/2026-07-23-private-dest-acl.md
+++ b/docs/superpowers/plans/2026-07-23-private-dest-acl.md
@@ -1231,9 +1231,12 @@ git commit -m "docs(agent): 私有目的地 ACL 配置样例与常驻校验测
    ```
 2. 写 `/etc/pangolin-agent/acl.json`（权限 `0600`，属主 `pangolin`），`systemctl reload pangolin-agent`。
 3. `journalctl -u pangolin-agent -n 30` 确认已重渲染、无 `[acl] ERROR` / `[acl] ALERT`。
-4. `sudo python3 -c "import json;print(json.load(open('/etc/sing-box/config.json'))['route'])"` 确认规则顺序为 sniff → 放行 → 拒绝 → warp。
+4. `sudo python3 -c "import json;print(json.load(open('/etc/sing-box/config.json'))['route'])"` 确认规则顺序为 sniff → resolve → 放行 → 拒绝 → warp（resolve 见 I3：堵住 ip_cidr 目的地的域名形式绕过）。
+   **`config.json` 内容正常不等于线上生效**——SIGHUP 走的是 sing-box 自身校验，若新配置被 sing-box 拒绝，它会保留旧实例继续跑，agent 侧仍记"渲染成功"。reload 后必须额外确认：
+   - `systemctl is-active sing-box` → `active`；
+   - `journalctl -u sing-box -n5 | grep -v FATAL`（有 FATAL 说明 sing-box 拒绝了新配置，旧实例还在跑，config.json 上的内容其实没生效）。
 5. **我的设备**：brain 首页 200、DSM 5001 可登录、`ssh nas-r` 通。
-6. **另一账号的设备**：以上全部被拒（连接被 reject，不是超时）。
+6. **另一账号的设备**：以上全部被拒（连接被 reject，不是超时）。**分别用域名和裸 IP 两种形式各测一遍**（如 `curl https://brain.51yanmei.com` 与 `curl --resolve brain.51yanmei.com:443:103.119.13.48 https://brain.51yanmei.com`；DSM 同理分别用 `nas.51yanmei.com:5001` 与 `182.92.213.171:5001`）——I3 表明目的地表达形式（域名 vs IP）会走到不同的 sing-box 匹配路径，只测一种形式验证不到位。
 7. **公开站不受影响**：jiu / travel / sudoku / pay 在两个账号下均正常。
 8. **WARP 未被破坏**：reddit 仍走 warp 出口。
 9. **fail-closed 实证**：把 `acl.json` 改坏 → `systemctl reload pangolin-agent` → 规则仍在、日志有 ERROR；恢复文件。

From 2abe4d08165e49f9b26faedb08b8290fb64331cb Mon Sep 17 00:00:00 2001
From: wangjia <809946525@qq.com>
Date: Thu, 23 Jul 2026 10:36:02 +0800
Subject: [PATCH 20/21] =?UTF-8?q?fix(agent):=20ACL=20=E6=94=BE=E8=A1=8C?=
 =?UTF-8?q?=E7=94=A8=20auth=5Fuser=20=E8=80=8C=E9=9D=9E=20user(VLESS=20?=
 =?UTF-8?q?=E8=BF=90=E8=A1=8C=E6=97=B6=E5=8F=AA=E8=AE=A4=20auth=5Fuser)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

生产验证发现:sing-box 1.13 的 route rule 里 user 字段对 VLESS/REALITY
入站运行时不匹配(仅 sing-box check 语法通过),导致放行规则永不命中、
白名单用户也被兜底拒绝。本地真 VLESS 连接实测确认 auth_user 生效
(good→通/bad→block),node 端 git 一进一出白名单验证 per-user 生效。

Co-Authored-By: Claude Opus 4.8 
---
 server/internal/agentd/acl.go      |  6 +++++-
 server/internal/agentd/acl_test.go | 18 +++++++++++-------
 2 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/server/internal/agentd/acl.go b/server/internal/agentd/acl.go
index 537cbad..76a174d 100644
--- a/server/internal/agentd/acl.go
+++ b/server/internal/agentd/acl.go
@@ -195,7 +195,11 @@ func (ac *ACLConfig) rules() []any {
 	if len(uuids) > 0 {
 		for _, t := range targets {
 			r := t.matchFields()
-			r["user"] = uuids
+			// auth_user(非 user):sing-box 1.13 的 route rule 里,VLESS/REALITY 入站的
+			// 认证用户要用 auth_user 匹配 inbound user 的 name;user 字段对 VLESS 运行时
+			// 不生效(仅 sing-box check 语法通过),会导致放行规则永不命中、白名单用户也
+			// 被兜底拒绝。已用本地真 VLESS 连接实测确认(good→通, bad→被 block)。
+			r["auth_user"] = uuids
 			r["outbound"] = directOutboundTag
 			out = append(out, r)
 		}
diff --git a/server/internal/agentd/acl_test.go b/server/internal/agentd/acl_test.go
index b8e9ffe..3f91270 100644
--- a/server/internal/agentd/acl_test.go
+++ b/server/internal/agentd/acl_test.go
@@ -213,11 +213,15 @@ func TestACLRules_AllowThenDeny(t *testing.T) {
 		t.Fatalf("规则数 = %d, want 4 (2 target × 放行+拒绝)", len(rules))
 	}
 
-	// 前两条是放行:带 user + outbound,不带 action
+	// 前两条是放行:带 auth_user + outbound,不带 action
+	// (auth_user 而非 user:VLESS 入站运行时只认 auth_user,见 acl.go rules() 注释)
 	for i := 0; i < 2; i++ {
 		r := rules[i].(map[string]any)
-		if _, ok := r["user"]; !ok {
-			t.Errorf("rules[%d] 放行规则缺 user", i)
+		if _, ok := r["auth_user"]; !ok {
+			t.Errorf("rules[%d] 放行规则缺 auth_user", i)
+		}
+		if _, ok := r["user"]; ok {
+			t.Errorf("rules[%d] 放行规则不应带 user(VLESS 不生效),应用 auth_user", i)
 		}
 		if r["outbound"] != directOutboundTag {
 			t.Errorf("rules[%d] outbound = %v, want %q", i, r["outbound"], directOutboundTag)
@@ -226,14 +230,14 @@ func TestACLRules_AllowThenDeny(t *testing.T) {
 			t.Errorf("rules[%d] 放行规则不应带 action", i)
 		}
 	}
-	// 后两条是拒绝:带 action=reject,不带 user(对所有人生效)
+	// 后两条是拒绝:带 action=reject,不带 auth_user(对所有人生效)
 	for i := 2; i < 4; i++ {
 		r := rules[i].(map[string]any)
 		if r["action"] != "reject" {
 			t.Errorf("rules[%d] action = %v, want reject", i, r["action"])
 		}
-		if _, ok := r["user"]; ok {
-			t.Errorf("rules[%d] 拒绝规则不应带 user,否则会漏掉名单外的人", i)
+		if _, ok := r["auth_user"]; ok {
+			t.Errorf("rules[%d] 拒绝规则不应带 auth_user,否则会漏掉名单外的人", i)
 		}
 	}
 
@@ -331,7 +335,7 @@ func TestBuildRoute_Matrix(t *testing.T) {
 		if rules[1].(map[string]any)["action"] != "resolve" {
 			t.Error("第二条不是 resolve")
 		}
-		if _, ok := rules[2].(map[string]any)["user"]; !ok {
+		if _, ok := rules[2].(map[string]any)["auth_user"]; !ok {
 			t.Error("第三条不是放行规则")
 		}
 		if rules[3].(map[string]any)["action"] != "reject" {

From 344dfe9a82f00836b0e49ec2deaeee2aa067da88 Mon Sep 17 00:00:00 2001
From: wangjia <809946525@qq.com>
Date: Fri, 24 Jul 2026 07:39:39 +0800
Subject: [PATCH 21/21] =?UTF-8?q?docs(agent):=20=E8=AE=B0=E5=BD=95=20auth?=
 =?UTF-8?q?=5Fuser=20=E8=A1=80=E6=B3=AA=E6=95=99=E8=AE=AD=20+=20=E5=AE=A2?=
 =?UTF-8?q?=E6=88=B7=E7=AB=AF=E9=9A=A7=E9=81=93=E5=89=8D=E7=BD=AE=20+=20?=
 =?UTF-8?q?=E9=AA=8C=E6=94=B6=E9=A1=BB=E7=9C=9F=E8=BF=9E=E6=8E=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.8 
---
 docs/private-dest-acl-design.html                 | 15 +++++++++++----
 docs/private-dest-acl-plan.html                   | 12 +++++++++---
 .../plans/2026-07-23-private-dest-acl.md          |  2 ++
 3 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/docs/private-dest-acl-design.html b/docs/private-dest-acl-design.html
index 059364c..49069c0 100644
--- a/docs/private-dest-acl-design.html
+++ b/docs/private-dest-acl-design.html
@@ -114,10 +114,11 @@
 
    "route": {
   "rules": [
     {"action": "sniff"},
+    {"action": "resolve"},
 
-    {"user": ["<我的uuid…>"], "domain": ["brain.51yanmei.com","git.51yanmei.com"],
+    {"auth_user": ["<我的uuid…>"], "domain": ["brain.51yanmei.com","git.51yanmei.com"],
      "outbound": "direct"},
-    {"user": ["<我的uuid…>"], "ip_cidr": ["182.92.213.171/32"],
+    {"auth_user": ["<我的uuid…>"], "ip_cidr": ["182.92.213.171/32"],
      "port": [5001,3389,10022,10023], "outbound": "direct"},
 
     {"domain": ["brain.51yanmei.com","git.51yanmei.com"], "action": "reject"},
@@ -128,7 +129,11 @@
   ],
   "final": "direct"
 }
    
-  
    已用本机 sing-box 1.13.13 sing-box check 验证形状合法（exit 0）。
    
+  
    
+    
    血泪教训:VLESS 只认 auth_user,不认 user（2026-07-23 生产验证）
    
+    
    放行规则匹配凭证必须用 auth_user 而非 user。sing-box check 对两者都语法通过,但 user 字段对 VLESS/REALITY 入站运行时根本不匹配——放行规则永不命中,结果连白名单用户也被兜底拒绝(全员进不去)。上线时正是踩了这个:节点端 git 一直 000,把本机 uuid 换着法加进白名单都没用。本地起一对真 VLESS 实例实测才定位:auth_user:["good"] 生效(good 通/bad 被 block),user 不生效。只跑 sing-box check 不足以验收访问控制,必须真连接跑一次。
    
+  
    
+  
    已用本机 sing-box 1.13.13 真 VLESS 连接验证 auth_user 匹配 + resolve 后 ip_cidr/domain 仍匹配;节点端以 git 做「白名单一进一出」验证 per-user 放行/拒绝生效。
    
 
   
    
     
    规则顺序的三条硬约束
    
@@ -206,7 +211,8 @@ journalctl -u pangolin-agent -n 20       # 确认已重渲染、无 ACL ERROR渲染：四态矩阵（ACL×WARP 开关）逐一断言 route 结构
     
  • 顺序：sniff 唯一且最先；放行先于拒绝；ACL 全部先于 WARP
    • 
     
  • 对称性：同一 target 的放行与拒绝规则，目的地条件逐字相同
    • 
-    
  • 产物合法性：渲染结果喂 sing-box check 通过
    • 
+    
  • 产物合法性：渲染结果喂 sing-box check 通过（注意：check 只验语法,不验 auth_user 运行时是否真匹配 VLESS——见 §4.2 血泪教训）
    • 
+    
  • 运行时匹配（不可省）：起真 VLESS 连接实测 auth_user 放行/拒绝生效;或节点端以某个白名单域名做「本机 uuid 一进一出」验证 per-user 生效。仅 sing-box check 绿=未验收。
    • 
   
   
    上线验收
    
   
      
@@ -235,6 +241,7 @@ journalctl -u pangolin-agent -n 20       # 确认已重渲染、无 ACL ERROR泄露 节点配置里我的几台设备 uuid 会出现在同一条规则中（自我关联），且目的地明文可见。目的地本就在公网 DNS 里，泄露面小；但这确实弱化了 render.go:14 的「节点只见不透明 dp_uuid」不变式，属于知情接受，需在该注释处补一行说明。
     
    1. 缺闸 守红线的 assertNoIdentityFields（agentd/singbox_test.go）只作用于 state.json，从不检查渲染出的 sing-box 配置。本设计不扩大这个缺口，但也没有补上——补闸另开。
      2. 
     
    2. 架构限制 443 vhost 的判定依赖 SNI，可被绕过。对 brain/git，节点侧唯一的区分手段是 sniff 出的 SNI。攻击者（持有效 dp_uuid 的其他 pangolin 用户）向 182.92.213.171:443 发起不带 SNI 的 TLS、握手后用 Host: brain.51yanmei.com 头访问，则不匹配任何 domain 规则、也不匹配 ip_cidr（443 不在端口清单里）→ 落 final:direct → nginx 按 Host 路由放行。这在 sing-box 层无法闭合——不能整封 :443，否则 jiu/travel/sudoku/pay 一起死。因此下面这条 brain 鉴权不是「可选纵深」，而是本闸对 brain 的前置条件。
      3. 
+    
    3. 客户端前置 私有域名必须走隧道,否则本闸无从谈起。节点 ACL 只对经隧道进入 sing-box 的流量生效;若客户端把 brain/nas 直连(smartRoute 把国内 IP 分流成直连),则流量根本不到节点、直接打 ali,brain 得 403(nginx deny 非白名单源 IP)、nas 超时。故 brain/nas/git/win.51yanmei.com 必须在控制面 PANGOLIN_PRIVATE_SPLIT_DOMAINS 里(已配),且客户端改动后要重连一次才拿到新分流规则。上线验证时 git 走隧道正常、brain/nas 因客户端未重连仍直连——排查时先确认「域名是否真走了隧道」(curl -v 看连的是不是 pangolin 出口),再判 ACL。
      4. 
     
    4. 已做（2026-07-23） brain 已加 nginx basic auth 作纵深防御：ali 的 /etc/nginx/conf.d/brain.conf 在原有 allow 103.119.13.48; deny all 之上叠加 auth_basic（satisfy 默认 all → 源 IP 白名单 与 口令二者都需满足），口令存 Bitwarden「brain basic auth」，htpasswd 仅存 apr1 哈希（明文不落 ali）。acme 通道（:80）与 robots.txt 免密。这样即便本节点 ACL 闸失效（agent 挂了、配置手抖）或被上面的 SNI 手法绕过，brain——唯一无自带鉴权的私有服务——仍不裸奔。
      5. 
   
 
diff --git a/docs/private-dest-acl-plan.html b/docs/private-dest-acl-plan.html
index dcbda86..d17414e 100644
--- a/docs/private-dest-acl-plan.html
+++ b/docs/private-dest-acl-plan.html
@@ -59,6 +59,7 @@
 
    5. 每个 Task 结束必须 cd server && go build ./... && go test ./internal/agentd/... 全绿再提交。
      6. 
 
    6. Commit message 前缀用 feat(agent): / test(agent): / refactor(agent):。
      7. 
 
+
      执行后修订（2026-07-23，提交 2abe4d0）· 血泪教训：放行规则匹配凭证必须用 auth_user 而非本计划各处写的 user。sing-box check 对两者都语法通过,但 user 字段对 VLESS/REALITY 入站运行时不匹配,导致放行规则永不命中、连白名单用户也被兜底拒绝(全员进不去)。生产上线时踩中,本地起真 VLESS 连接实测才定位。凡本计划(Task 2 rules()、Task 3 测试)出现 r["user"] = uuids 或断言 r["user"] 之处,一律应为 auth_user。 且验收不能只跑 sing-box check——必须真连接跑一次(节点端「白名单 uuid 一进一出」即可)。
      
 
      
 
      Task 1: ACL 配置类型、加载与 fail-closed 的 active()
      
 
      Files:
      
@@ -1068,14 +1069,19 @@ git commit -m "docs(agent): 私有目的地 ACL 配置样例与常驻校验
 
        
 
      1. 写 /etc/pangolin-agent/acl.json（权限 0600，属主 pangolin），systemctl reload pangolin-agent。
        2. 
 
      2. journalctl -u pangolin-agent -n 30 确认已重渲染、无 [acl] ERROR / [acl] ALERT。
        3. 
-
      3. sudo python3 -c "import json;print(json.load(open('/etc/sing-box/config.json'))['route'])" 确认规则顺序为 sniff → 放行 → 拒绝 → warp。
        4. 
+
      4. sudo python3 -c "import json;print(json.load(open('/etc/sing-box/config.json'))['route'])" 确认规则顺序为 sniff → resolve → 放行 → 拒绝 → warp（resolve 见 I3：堵住 ip_cidr 目的地的域名形式绕过）。
        5. 
+
      
+
         config.json 内容正常不等于线上生效——SIGHUP 走的是 sing-box 自身校验，若新配置被 sing-box 拒绝，它会保留旧实例继续跑，agent 侧仍记"渲染成功"。reload 后必须额外确认：
      
+
        
+
      • systemctl is-active sing-box → active；
        • 
+
      • journalctl -u sing-box -n5 | grep -v FATAL（有 FATAL 说明 sing-box 拒绝了新配置，旧实例还在跑，config.json 上的内容其实没生效）。
        • 
 
      • 我的设备：brain 首页 200、DSM 5001 可登录、ssh nas-r 通。
        • 
-
      • 另一账号的设备：以上全部被拒（连接被 reject，不是超时）。
        • 
+
      • 另一账号的设备：以上全部被拒（连接被 reject，不是超时）。分别用域名和裸 IP 两种形式各测一遍（如 curl https://brain.51yanmei.com 与 curl --resolve brain.51yanmei.com:443:103.119.13.48 https://brain.51yanmei.com；DSM 同理分别用 nas.51yanmei.com:5001 与 182.92.213.171:5001）——I3 表明目的地表达形式（域名 vs IP）会走到不同的 sing-box 匹配路径，只测一种形式验证不到位。
        • 
 
      • 公开站不受影响：jiu / travel / sudoku / pay 在两个账号下均正常。
        • 
 
      • WARP 未被破坏：reddit 仍走 warp 出口。
        • 
 
      • fail-closed 实证：把 acl.json 改坏 → systemctl reload pangolin-agent → 规则仍在、日志有 ERROR；恢复文件。
        • 
 
      • 不断线实证：reload 期间另一台设备保持连接不掉。
        • 
-
    
+
 
    不在本计划范围内
    
 
      
 
    • 给 brain 加 mTLS / basic auth 作纵深防御（与本计划正交，约一小时，另开）
      • 
diff --git a/docs/superpowers/plans/2026-07-23-private-dest-acl.md b/docs/superpowers/plans/2026-07-23-private-dest-acl.md
index 68df1ef..1ad617f 100644
--- a/docs/superpowers/plans/2026-07-23-private-dest-acl.md
+++ b/docs/superpowers/plans/2026-07-23-private-dest-acl.md
@@ -19,6 +19,8 @@
 - 每个 Task 结束必须 `cd server && go build ./... && go test ./internal/agentd/...` 全绿再提交。
 - Commit message 前缀用 `feat(agent):` / `test(agent):` / `refactor(agent):`。
 
+> **执行后修订（2026-07-23，提交 `2abe4d0`）· 血泪教训**：放行规则匹配凭证必须用 **`auth_user`** 而非本计划各处写的 `user`。`sing-box check` 对两者都语法通过,但 `user` 字段对 VLESS/REALITY 入站**运行时不匹配**,导致放行规则永不命中、**连白名单用户也被兜底拒绝**(全员进不去)。生产上线时踩中,本地起真 VLESS 连接实测才定位。**凡本计划(Task 2 `rules()`、Task 3 测试)出现 `r["user"] = uuids` 或断言 `r["user"]` 之处,一律应为 `auth_user`。** 且验收不能只跑 `sing-box check`——必须真连接跑一次(节点端「白名单 uuid 一进一出」即可)。
+
 ---
 
 ### Task 1: ACL 配置类型、加载与 fail-closed 的 active()