fix(agent): 限流状态损坏时拒绝覆盖并发布 v1.3.9

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.3.9] - 2026-09-28
+
+### 修复
+
+- **限流状态损坏时拒绝覆盖**：`readLimitState` 原来忽略 JSON 解析错误并返回空 map，保存任一规则时可能把其他域名的限流配置清空。现在文件不存在仍视为空状态，读取失败、空文件或 JSON 损坏则返回错误，`applyLimitState` / `clearLimitState` 会保留原文件与现有 Nginx zone，不再覆盖
+
+### 变更
+
+- 版本号提升到 1.3.9；`web/package.json` 与 `web/package-lock.json` 同步对齐
+- `AgentVersion` 0.12.8 → **0.12.9**，内嵌 amd64 / arm64 二进制已重编；VPS 上需点一次「升级 Agent」才会生效
+
+### 测试
+
+- `internal/agent`：新增限流状态文件缺失、正常解析、空文件、截断 JSON、null 内容与失败后原文件不变的测试
+
 ## [v1.3.8] - 2026-09-28
 
 ### 新增

VERSION

@@ -1 +1 @@
-1.3.8
+1.3.9

docs/README.md

@@ -1,14 +1,14 @@
 # Fonu 文档索引
 
 > 维护约定：新增方案 / 审查文档时在下方登记；方案落地后在「状态」列标注实施结果，并给已被推翻的描述加时效说明。
-> 最近更新：2026-09-28（v1.3.8）
+> 最近更新：2026-09-28（v1.3.9）
 
 ## 方案与设计（本目录）
 
 | 文件 | 主题 | 状态 |
 | --- | --- | --- |
 | `project-analysis-2026-09-27.md` | 全项目详细分析（v1.2.19）：架构、模块、数据、API、前端、链路、风险与改进路线 | 当前版本快照 |
-| `improvement-roadmap-2026-09-27.md` | P0-P3 改进路线实施方案：逐项改法、测试、验收、依赖、发布与回滚 | P0-1、P0-3 已完成，其余待实施 |
+| `improvement-roadmap-2026-09-27.md` | P0-P3 改进路线实施方案：逐项改法、测试、验收、依赖、发布与回滚 | P0-1、P0-3、P0-4 已完成，其余待实施 |
 | `system-upgrade.md` | Docker Compose 一键升级：sidecar 架构、首次部署、安全边界、回滚、故障排查与验证页 | 已实施（v1.3.8） |
 | `project-audit-2026-09-24.md` | 全项目审查：P0/P1/P2 分级，含精确行号与逐条修法 | **进行中**——P0 已随 v1.2.7 完成，P1 实施中 |
 | `frp-server-list-merge-plan.md` | FRP 服务端列表并入「公网服务端」页（方案 A，四步） | 步 1/2 已完成（v1.2.6）；步 3 文案收尾、步 4 死样式清理未做 |

docs/improvement-roadmap-2026-09-27.md

@@ -384,6 +384,8 @@ if token == "" || !secureEqual(token, s.cfg.Token) {
 
 ## 3.4 P0-4：限流状态解析失败时拒绝覆盖原状态
 
+> 实施状态：2026-09-28 已完成。
+
 ### 3.4.1 现状
 
 `internal/agent/server.go` 的 `readLimitState`：
@@ -443,6 +445,15 @@ func (s *Server) clearLimitState(domain string) error
 - 错误能显示在“应用配置”或路由保存响应中。
 - `nginx -t` 仍以真实生成结果为准。
 
+### 3.4.6 实施记录
+
+- `readLimitState` 改为返回 `(map[string]routeLimit, error)`，新增可测试的 `readLimitStateFile`。
+- 文件不存在返回空状态；读取失败、空文件、`null` 或 JSON 损坏返回错误。
+- `applyLimitState` / `clearLimitState` 传播错误并保留原文件，不再用空状态覆盖。
+- 新增 `internal/agent/limits_test.go`，覆盖缺失、正常、空文件、截断 JSON、null 和原文件不变。
+- `AgentVersion` 提升到 `0.12.9`，双架构内嵌二进制已重编。
+- 验证通过：`go test ./internal/agent -count=1`、`go test ./... -count=1`、`go vet ./...`、`npm test`。
+
 ---
 
 ## 3.5 P0-5：明确 Agent 默认监听策略

docs/system-upgrade.md

@@ -234,16 +234,16 @@ FONU_VERSION=<旧版本> docker compose up -d --no-deps --force-recreate fonu
 
 ## 10. 在线升级验证
 
-示例页面用于验证升级结果。v1.3.8 的验证流程：
+示例页面用于验证升级结果。v1.3.9 的验证流程：
 
 1. 确认当前线上实例为 v1.3.0，且 `fonu-updater` sidecar 已运行。
-2. 确认远端 `main` 分支的 `VERSION` 为 `1.3.8`。
+2. 确认远端 `main` 分支的 `VERSION` 为 `1.3.9`。
 3. 在侧栏看到「一键升级」后点击并确认。
 4. 等待升级弹窗显示成功，页面自动刷新。
 5. 打开侧栏「示例页面」，确认：
    - 页面路由为 `/example`；
-   - 页面显示的版本为 `1.3.8`；
+   - 页面显示的版本为 `1.3.9`；
-   - 页面显示验证标识 `v1.3.8-example-page`；
+   - 页面显示验证标识 `v1.3.9-example-page`；
    - 页面显示独立的「本次升级验证」区块；
    - 「升级验证」显示为「通过」。
 

internal/agent/limits_test.go

@@ -0,0 +1,65 @@
+package agent
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestReadLimitStateFile(t *testing.T) {
+	dir := t.TempDir()
+
+	missing, err := readLimitStateFile(filepath.Join(dir, "missing.json"))
+	if err != nil {
+		t.Fatalf("文件不存在应返回空状态: %v", err)
+	}
+	if len(missing) != 0 {
+		t.Fatalf("文件不存在应返回空 map，实际 %#v", missing)
+	}
+
+	validPath := filepath.Join(dir, "valid.json")
+	valid := []byte(`{"a.example.com":{"rate":10,"burst":20,"conn":5}}`)
+	if err := os.WriteFile(validPath, valid, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	state, err := readLimitStateFile(validPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := state["a.example.com"]
+	if got.Rate != 10 || got.Burst != 20 || got.Conn != 5 {
+		t.Fatalf("解析结果不正确: %#v", got)
+	}
+
+	brokenPath := filepath.Join(dir, "broken.json")
+	broken := []byte(`{"a.example.com":`)
+	if err := os.WriteFile(brokenPath, broken, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := readLimitStateFile(brokenPath); err == nil {
+		t.Fatal("损坏 JSON 应返回错误")
+	}
+	after, err := os.ReadFile(brokenPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(after) != string(broken) {
+		t.Fatalf("读取失败不应修改原文件: %q", after)
+	}
+
+	emptyPath := filepath.Join(dir, "empty.json")
+	if err := os.WriteFile(emptyPath, nil, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := readLimitStateFile(emptyPath); err == nil {
+		t.Fatal("空文件应返回错误")
+	}
+
+	nullPath := filepath.Join(dir, "null.json")
+	if err := os.WriteFile(nullPath, []byte("null\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := readLimitStateFile(nullPath); err == nil {
+		t.Fatal("null 内容应返回错误")
+	}
+}

internal/agent/server.go

@@ -50,7 +50,8 @@ import (
 // 0.12.7：vhost 目录探测不再要求被加载文件带 .conf 后缀（Debian 的 sites-enabled/default 不带），
 // 并在失败信息里带上最后一次的具体原因与常见的显式指定目录。
 // 0.12.8：Agent Bearer Token 改为常量时间比较，避免认证路径上的长度/内容时序泄漏。
-const AgentVersion = "0.12.8"
+// 0.12.9：限流状态文件损坏时拒绝覆盖，避免保存单条规则时清空其他域名的限流配置。
+const AgentVersion = "0.12.9"
 
 // Config 是 fonu-agent 的运行配置。agent 只在 VPS 本地管理自己的 Nginx 片段、证书和 frps 配置。
 type Config struct {
@@ -1520,14 +1521,29 @@ type routeLimit struct {
 	Conn  int `json:"conn,omitempty"`
 }
 
-func readLimitState() map[string]routeLimit {
+func readLimitState() (map[string]routeLimit, error) {
+	return readLimitStateFile(limitsStatePath())
+}
+
+func readLimitStateFile(path string) (map[string]routeLimit, error) {
 	state := map[string]routeLimit{}
-	data, err := os.ReadFile(limitsStatePath())
+	data, err := os.ReadFile(path)
-	if err != nil {
+	if errors.Is(err, os.ErrNotExist) {
-		return state
+		return state, nil
 	}
-	_ = json.Unmarshal(data, &state)
+	if err != nil {
-	return state
+		return nil, err
+	}
+	if strings.TrimSpace(string(data)) == "" {
+		return nil, fmt.Errorf("限流状态文件为空: %s", path)
+	}
+	if err := json.Unmarshal(data, &state); err != nil {
+		return nil, fmt.Errorf("解析限流状态失败: %w", err)
+	}
+	if state == nil {
+		return nil, fmt.Errorf("限流状态文件内容为空对象: %s", path)
+	}
+	return state, nil
 }
 
 // writeLimitState 落盘限流参数并重生成 zone 定义文件；无限流时删除该文件。
@@ -1568,7 +1584,10 @@ func (s *Server) writeLimitState(state map[string]routeLimit) error {
 
 // applyLimitState 记录本次路由的限流参数并刷新 zone 文件（必须在写 vhost 之前完成）。
 func (s *Server) applyLimitState(req routeRequest) error {
-	state := readLimitState()
+	state, err := readLimitState()
+	if err != nil {
+		return fmt.Errorf("读取限流状态失败，已保留原文件: %w", err)
+	}
 	if req.RateLimitRate > 0 || req.ConnLimitMax > 0 {
 		state[req.Domain] = routeLimit{Rate: req.RateLimitRate, Burst: req.RateLimitBurst, Conn: req.ConnLimitMax}
 	} else {
@@ -1579,7 +1598,10 @@ func (s *Server) applyLimitState(req routeRequest) error {
 
 // clearLimitState 删除该域名的限流参数并刷新 zone 文件。
 func (s *Server) clearLimitState(domain string) error {
-	state := readLimitState()
+	state, err := readLimitState()
+	if err != nil {
+		return fmt.Errorf("读取限流状态失败，已保留原文件: %w", err)
+	}
 	if _, ok := state[domain]; !ok {
 		return nil
 	}

web/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "fonu-web",
-  "version": "1.3.8",
+  "version": "1.3.9",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "fonu-web",
-      "version": "1.3.8",
+      "version": "1.3.9",
       "dependencies": {
         "@codemirror/commands": "^6.11.1",
         "@codemirror/lang-javascript": "^6.2.5",

web/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fonu-web",
   "private": true,
-  "version": "1.3.8",
+  "version": "1.3.9",
   "packageManager": "npm@10.9.4",
   "type": "module",
   "scripts": {

web/src/views/ExampleView.vue

@@ -8,7 +8,7 @@
     </template>
   </PageHeader>
 
-  <n-alert type="success" :bordered="false" class="example-alert" title="v1.3.8 示例页面验证标识已生效">
+  <n-alert type="success" :bordered="false" class="example-alert" title="v1.3.9 示例页面验证标识已生效">
     当前页面由 v{{ version }} 提供，验证标识为 <span class="mono">{{ verificationMarker }}</span>。
     如果你是在升级后首次看到这行内容，说明前端构建、镜像重建和服务重启均已成功。
   </n-alert>
@@ -19,7 +19,7 @@
       <strong class="example-proof__value">{{ verificationRound }}</strong>
     </div>
     <div class="example-proof__hint">
-      看到这个新区块，说明前端资源已经从旧版本切换到 v1.3.8。
+      看到这个新区块，说明前端资源已经从旧版本切换到 v1.3.9。
     </div>
   </div>
 
@@ -33,16 +33,16 @@
     <StatCard label="本次验证标识" :value="verificationMarker" sub="用于区分升级前后的前端资源" tone="blue" value-small>
       <template #icon><n-icon :component="FlashOutline" /></template>
     </StatCard>
-    <StatCard label="页面状态" value="已更新" sub="v1.3.8 前端资源已加载" tone="teal">
+    <StatCard label="页面状态" value="已更新" sub="v1.3.9 前端资源已加载" tone="teal">
       <template #icon><n-icon :component="CheckmarkCircleOutline" /></template>
     </StatCard>
   </div>
 
   <FonuCard title="本次示例页变化" subtitle="用于确认升级后的页面内容确实发生变化">
     <ul class="example-changes">
-      <li>页面版本提示更新为 v1.3.8。</li>
+      <li>页面版本提示更新为 v1.3.9。</li>
-      <li>「本次升级验证」区块和页面状态同步更新为 v1.3.8。</li>
+      <li>「本次升级验证」区块和页面状态同步更新为 v1.3.9。</li>
-      <li>验证标识更新为 <span class="mono">v1.3.8-example-page</span>。</li>
+      <li>验证标识更新为 <span class="mono">v1.3.9-example-page</span>。</li>
     </ul>
   </FonuCard>
 
@@ -87,8 +87,8 @@ const message = useMessage()
 const version = ref(__APP_VERSION__)
 const checkedAt = ref('')
 const refreshing = ref(false)
-const verificationRound = 'v1.3.8'
+const verificationRound = 'v1.3.9'
-const verificationMarker = 'v1.3.8-example-page'
+const verificationMarker = 'v1.3.9-example-page'
 
 async function refreshVersion() {
   refreshing.value = true