frpsctl 0.2.3__tar.gz → 0.2.4__tar.gz

{frpsctl-0.2.3 → frpsctl-0.2.4}/.github/workflows/ci.yml

@@ -112,6 +112,15 @@ jobs:
               with urllib.request.urlopen(req, timeout=10) as resp:
                   return json.load(resp)
 
+          def post(path, body):
+              req = urllib.request.Request(
+                  base + path, method="POST",
+                  data=json.dumps(body).encode(),
+                  headers={"Content-Type": "application/json", "Cookie": cookie, "X-CSRF-Token": csrf},
+              )
+              with urllib.request.urlopen(req, timeout=10) as resp:
+                  return json.load(resp)
+
           status = call("/api/status")
           assert status["state"] == "STOPPED", status
           assert call("/api/session")["csrf"] == csrf
@@ -122,9 +131,18 @@ jobs:
           # 端到端冒烟里的 config set 会留下快照：history 必须真的读得到
           # （只断言"是列表"的话，空列表也能骗过这层守卫）。
           assert any(str(e.get("action", "")).startswith("set ") for e in history["entries"]), history
+          # 回滚前的"看差异"：先经 API 改一个键（实例未运行 → 只写不重启），
+          # 再断言差里真的出现它。
+          preview = post("/api/config/preview", {"changes": [["maxPortsPerClient", "35"]]})
+          applied = post("/api/config/apply", {"preview_id": preview["preview_id"]})
+          assert applied["applied"] is True, applied
+          diff = call("/api/config/history/1/diff")
+          assert "maxPortsPerClient" in diff["diff"], diff
+          favicon = urllib.request.urlopen(base + "/favicon.ico", timeout=10)
+          assert favicon.status == 204
           html = urllib.request.urlopen(base + "/", timeout=10).read().decode("utf-8")
           assert "frpsctl 管理台" in html
-          print("web 冒烟通过：login / session / status / config / history / 静态页")
+          print("web 冒烟通过：login / session / status / config / history / diff / favicon / 静态页")
           EOF
           kill "$WEB_PID"
           wait "$WEB_PID" 2>/dev/null || true

{frpsctl-0.2.3 → frpsctl-0.2.4}/CHANGELOG.md

@@ -3,6 +3,67 @@
 格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.2.4] - 2026-09-17
+
+Web 管理台的体验迭代：把后端已有的能力全部交付到界面，并给单文件前端补上
+自动化守卫。修复 5 条真实缺陷（含一条"白屏而 CI 全绿"的测试盲区）。
+
+### 修复
+
+- **前端在 CI 里几乎零防护**：所有测试与冒烟都只走 HTTP、不执行 JS——一处
+  语法错误会让整站白屏而 CI 全绿。新增 `tests/test_web_frontend.py`：逐
+  `<script>` 块 `node --check`（无 node 时 skip）+ 静态纪律守卫（禁 innerHTML
+  家族、禁外部资源引用、CSS 变量双向对齐、亮色主题必须覆盖全部颜色变量）。
+- **配置页切换视图会丢失未保存的修改**：每次切回配置页都重新拉取并清空草稿。
+  现在已加载过就不重载，"重新加载（丢弃修改）"是显式动作（有未保存修改时
+  二次确认）。
+- **日志面板永远自动滚底**：`logScroll` 恒为 true，用户向上翻日志会被 5 秒
+  刷新拽回底部。现在按真实滚动位置维护"跟随/暂停"（显示在标题栏，回到底部
+  自动恢复）。
+- **清理离线记录后不刷新列表**：用户看到条目还在，以为操作没生效。
+- **认证会话表无上限**：持有口令的调用方反复登录可持续推高内存——与失败
+  来源表同类的"输入驱动的表必须有界"，现在上限 32（驱逐最早到期者）。
+- 发布前回归 review 追加修复：**`plan_change_many` 把字符串当列表逐字符迭代**
+  （`unsets="ab"` 会静默删掉 `a` 与 `b` 两个键；对抗性实测复现，现为用法错误，
+  输入归一化单点化在 core 并覆盖 `changes`/`unsets` 两种形状）；`snapshot_diff`
+  与 `rollback_to` 的 `steps < 1` 曾被 `max(0, steps-1)` 静默归一成"一步"
+  （core 入口补防御，与 CLI 的 min=1 同一条纪律）；代理柱状图的柱宽 clamp
+  （防御"负宽度静默不渲染"）。
+
+### 新增
+
+- **回滚前"查看差异"**：新接口 `GET /api/config/history/{steps}/diff`（打码，
+  与 CLI `config diff --steps` 共用 core 的 `snapshot_diff`）——回滚从盲操作
+  变为可预览；历史表每行都有"查看差异"按钮。
+- **Web 配置删除键**：配置表单每行"删除"按钮 → 与修改合并成一次事务
+  （`plan_change_many` + `apply_sets(unsets=…)`：一份快照、一次重启）；
+  "删除不存在的键"照旧是配置错误。
+- **Web 配置新增键**：此前只能改已有键，新增必须回到 CLI；现在表单底部可
+  添加任意键（预览/校验/危险组合拦截与 CLI 同一套）。
+- **单代理流量曲线**：点击代理行展开该代理的 7 天曲线（数据源与 CLI
+  `traffic <name>` 相同）。
+- **操作进行中状态**：启动/重启/停止/回滚/应用期间按钮禁用、状态徽章显示
+  "操作中…"（启动最长等 10 秒，此前完全无反馈）；轮询与手动刷新不会叠加。
+- **状态面板补齐**：state.json 损坏红色横幅（含处置指引）、0.70.x 版本告警、
+  L3 插件告警（`plugin_warning` 此前没有下发）、systemd unit 行、流量超 50
+  个代理时"已截断"提示（CLI 有、Web 曾静默）。
+- **双主题**：`prefers-color-scheme` 自动 + 手动切换（本地持久化）；图表
+  颜色改由 CSS 变量控制，切换即时生效。
+- 界面打磨：diff 语法高亮（+绿/−红）、图表 hover 数值与合计、实时速率文本、
+  表格数字右对齐与状态 tag、错误 toast 常驻（手动关闭）、日志"跟随/暂停"、
+  内嵌 favicon（`/favicon.ico` 收尾返回 204）、窄屏"菜单"折叠。
+
+### 工程
+
+- `snapshot_diff` 下沉 core（CLI `config diff` 与 Web 差异接口的唯一实现）；
+  `plan_change_many` 统一混合变更；快照动作文案 `set many:` → `edit many:`。
+- 设计文档 §18.2 的 API 表补上 `/api/session`、`/api/config/history`、
+  `/api/config/history/{steps}/diff`（长期 drift），并把"API 表 ↔ 路由"
+  双向核对加入 `tests/test_docs.py`。
+- 新增 35 条测试（510 → 545；非契约 515），覆盖率 85%；前端单文件 650 → 984 行。
+  其中前端守卫含 **JS 对 id 的引用与 HTML 定义的双向核对**——`node --check`
+  抓不到的"id 拼错 = 白屏"由此变成 CI 断言。
+
 ## [0.2.3] - 2026-09-17
 
 全量通读后的根治性迭代：Web 参数边界、systemd 交叉状态、限速来源模型、分层

{frpsctl-0.2.3 → frpsctl-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: frpsctl
-Version: 0.2.3
+Version: 0.2.4
 Summary: 把 frp 服务端（frps）包装成命令行工具：配置翻译器 + 进程保镖 + 状态聚合器
 Project-URL: Homepage, https://github.com/ThzxxArt/frpsctl
 Project-URL: Repository, https://github.com/ThzxxArt/frpsctl
@@ -792,12 +792,15 @@ Web 管理台：http://127.0.0.1:8787/
 Ctrl-C 停止。
 ```
 
-打开浏览器即可——单文件前端（暗色主题），零外部资源（不加载任何 CDN）：
+打开浏览器即可——单文件前端（明暗双主题，跟随系统并可手动切换），零外部资源（不加载任何 CDN）：
 
 | 页面 | 内容 |
 |------|------|
-| 仪表盘 | 实例状态 / 三层健康 / 客户端与代理列表 / 近 7 天流量柱状图 / 会话内实时流量曲线 / 日志（5 秒自动刷新） |
-| 配置 | 逐字段表单（敏感值不回显，留空表示不改）→ 预览打码 diff → 确认应用（一次事务、一次重启）→ 一键回滚 |
+| 仪表盘 | 实例状态 / 三层健康 / 客户端与代理列表 / 近 7 天流量柱状图（悬停看数值，点代理行展开单代理曲线）/ 会话内实时流量曲线 / 日志（5 秒自动刷新，向上翻自动暂停跟随）。操作进行中有"操作中…"状态，清理离线记录后列表即时刷新 |
+| 配置 | 逐字段表单（敏感值以打码形式提示"已设置"，留空表示不改；可**删除**任意键回落默认值、也可**新增**键）→ 预览打码 diff（+绿/−红）→ 确认应用（一次事务、一次重启）→ 历史回滚（**先看差异再回滚**） |
+
+状态异常不会藏在角落：state.json 损坏、0.70.x 缺安全修复、插件不可达（客户端
+将无法登录）、流量超 50 个代理被截断——都会在页面顶部横幅或图表下方明确写出。
 
 **安全设计**（比 frp 自带 dashboard 更严——它正是本项目安全决策的来源）：
 
@@ -819,9 +822,10 @@ sudo frpsctl web service uninstall
 > `web service install` 同样需要 `frpsctl` 位于系统路径（不能被 `ProtectHome`
 > 挡住）——与插件服务的部署要求一致。
 
-配置页里还有**历史与回滚**：列出最近 10 份快照（时间 / 动作 / 步数），可回滚到
-任意一份（接口 `GET /api/config/history` 只读快照的元数据，**不下发配置原文**
-——快照是含 token 与口令的完整副本）。
+配置页里还有**历史与回滚**：列出最近 10 份快照（时间 / 动作 / 步数），每行可
+先"查看差异"再决定是否回滚到那一份（差异接口 `GET /api/config/history/{steps}/diff`
+与 `config diff --steps` 共用同一实现，同样打码；列表接口只读快照元数据，
+**不下发配置原文**——快照是含 token 与口令的完整副本）。
 
 生成的口令随时可以取回（权限过宽时会告警）：
 
@@ -1222,17 +1226,19 @@ FRPSCTL_TRACEBACK=1 frpsctl status
 
 ```bash
 uv venv && uv pip install -e ".[dev]"
-.venv/bin/pytest                       # 全部 510 条（契约层缺二进制时自动 skip）
-.venv/bin/pytest -m "not contract"     # 快速回归（480 条）
+.venv/bin/pytest                       # 全部 545 条（契约层缺二进制时自动 skip）
+.venv/bin/pytest -m "not contract"     # 快速回归（515 条）
 .venv/bin/pytest --cov=frpsctl         # 覆盖率（CI 门禁 80%，当前 85%）
 .venv/bin/ruff check src/ tests/       # 静态分析
 ```
 
 CI（Linux，Python 3.11/3.12/3.13/3.14）还包含：ruff、覆盖率门禁、真 frp 0.71.0
 契约层、**真 frp 0.70.0 下界契约矩阵**、无二进制降级路径、端到端冒烟与
-Web 管理台冒烟、**文档一致性守卫**（README/设计文档 vs 代码的三向核对）。
+Web 管理台冒烟（含配置差异接口）、**前端静态守卫**（逐 `<script>` 块
+`node --check` + 禁 innerHTML/外部资源）、**文档一致性守卫**（README/设计文档/
+API 表 vs 代码的交叉核对）。
 
-### 测试分六层
+### 测试分七层
 
 | 层 | 文件 | 目标 |
 |----|------|------|
@@ -1242,6 +1248,7 @@ Web 管理台冒烟、**文档一致性守卫**（README/设计文档 vs 代码
 | 契约 | `tests/test_facts.py` | **设计文档事实基线的自动化守卫**（需真 frps） |
 | 故障注入 | `tests/test_faults.py` | 注入系统调用失败，验证异常路径的五项不变量 |
 | 插件 | `tests/test_plugin.py` | 协议报文、裁决、审计、配额；含真 frpc 端到端契约 |
+| 前端与文档 | `tests/test_web_frontend.py`、`tests/test_docs.py` | 单文件前端的静态守卫（`node --check`、禁 innerHTML/外部资源、CSS 变量对齐）与 README / 设计文档 / API 表的双向一致性 |
 
 让契约层跑起来（需要真实二进制）：
 

{frpsctl-0.2.3 → frpsctl-0.2.4}/README.md

@@ -769,12 +769,15 @@ Web 管理台：http://127.0.0.1:8787/
 Ctrl-C 停止。
 ```
 
-打开浏览器即可——单文件前端（暗色主题），零外部资源（不加载任何 CDN）：
+打开浏览器即可——单文件前端（明暗双主题，跟随系统并可手动切换），零外部资源（不加载任何 CDN）：
 
 | 页面 | 内容 |
 |------|------|
-| 仪表盘 | 实例状态 / 三层健康 / 客户端与代理列表 / 近 7 天流量柱状图 / 会话内实时流量曲线 / 日志（5 秒自动刷新） |
-| 配置 | 逐字段表单（敏感值不回显，留空表示不改）→ 预览打码 diff → 确认应用（一次事务、一次重启）→ 一键回滚 |
+| 仪表盘 | 实例状态 / 三层健康 / 客户端与代理列表 / 近 7 天流量柱状图（悬停看数值，点代理行展开单代理曲线）/ 会话内实时流量曲线 / 日志（5 秒自动刷新，向上翻自动暂停跟随）。操作进行中有"操作中…"状态，清理离线记录后列表即时刷新 |
+| 配置 | 逐字段表单（敏感值以打码形式提示"已设置"，留空表示不改；可**删除**任意键回落默认值、也可**新增**键）→ 预览打码 diff（+绿/−红）→ 确认应用（一次事务、一次重启）→ 历史回滚（**先看差异再回滚**） |
+
+状态异常不会藏在角落：state.json 损坏、0.70.x 缺安全修复、插件不可达（客户端
+将无法登录）、流量超 50 个代理被截断——都会在页面顶部横幅或图表下方明确写出。
 
 **安全设计**（比 frp 自带 dashboard 更严——它正是本项目安全决策的来源）：
 
@@ -796,9 +799,10 @@ sudo frpsctl web service uninstall
 > `web service install` 同样需要 `frpsctl` 位于系统路径（不能被 `ProtectHome`
 > 挡住）——与插件服务的部署要求一致。
 
-配置页里还有**历史与回滚**：列出最近 10 份快照（时间 / 动作 / 步数），可回滚到
-任意一份（接口 `GET /api/config/history` 只读快照的元数据，**不下发配置原文**
-——快照是含 token 与口令的完整副本）。
+配置页里还有**历史与回滚**：列出最近 10 份快照（时间 / 动作 / 步数），每行可
+先"查看差异"再决定是否回滚到那一份（差异接口 `GET /api/config/history/{steps}/diff`
+与 `config diff --steps` 共用同一实现，同样打码；列表接口只读快照元数据，
+**不下发配置原文**——快照是含 token 与口令的完整副本）。
 
 生成的口令随时可以取回（权限过宽时会告警）：
 
@@ -1199,17 +1203,19 @@ FRPSCTL_TRACEBACK=1 frpsctl status
 
 ```bash
 uv venv && uv pip install -e ".[dev]"
-.venv/bin/pytest                       # 全部 510 条（契约层缺二进制时自动 skip）
-.venv/bin/pytest -m "not contract"     # 快速回归（480 条）
+.venv/bin/pytest                       # 全部 545 条（契约层缺二进制时自动 skip）
+.venv/bin/pytest -m "not contract"     # 快速回归（515 条）
 .venv/bin/pytest --cov=frpsctl         # 覆盖率（CI 门禁 80%，当前 85%）
 .venv/bin/ruff check src/ tests/       # 静态分析
 ```
 
 CI（Linux，Python 3.11/3.12/3.13/3.14）还包含：ruff、覆盖率门禁、真 frp 0.71.0
 契约层、**真 frp 0.70.0 下界契约矩阵**、无二进制降级路径、端到端冒烟与
-Web 管理台冒烟、**文档一致性守卫**（README/设计文档 vs 代码的三向核对）。
+Web 管理台冒烟（含配置差异接口）、**前端静态守卫**（逐 `<script>` 块
+`node --check` + 禁 innerHTML/外部资源）、**文档一致性守卫**（README/设计文档/
+API 表 vs 代码的交叉核对）。
 
-### 测试分六层
+### 测试分七层
 
 | 层 | 文件 | 目标 |
 |----|------|------|
@@ -1219,6 +1225,7 @@ Web 管理台冒烟、**文档一致性守卫**（README/设计文档 vs 代码
 | 契约 | `tests/test_facts.py` | **设计文档事实基线的自动化守卫**（需真 frps） |
 | 故障注入 | `tests/test_faults.py` | 注入系统调用失败，验证异常路径的五项不变量 |
 | 插件 | `tests/test_plugin.py` | 协议报文、裁决、审计、配额；含真 frpc 端到端契约 |
+| 前端与文档 | `tests/test_web_frontend.py`、`tests/test_docs.py` | 单文件前端的静态守卫（`node --check`、禁 innerHTML/外部资源、CSS 变量对齐）与 README / 设计文档 / API 表的双向一致性 |
 
 让契约层跑起来（需要真实二进制）：
 

{frpsctl-0.2.3 → frpsctl-0.2.4}/frpsctl-/350/256/276/350/256/241/346/226/271/346/241/210.md

@@ -2476,13 +2476,17 @@ frpsctl web serve（独立进程，默认只绑 127.0.0.1）
 | 方法 | 路径 | 说明 |
 |------|------|------|
 | POST | `/api/login` `/api/logout` | 口令登录（下发会话 Cookie + CSRF）/ 登出；**login 是唯一免认证入口** |
-| GET | `/api/status` | 进程状态 + 三层健康 + dashboard 统计（统计不可得为 null） |
-| GET | `/api/clients` `/api/proxies` `/api/traffic` | v2 数据（自动翻页；traffic 为 7 天日粒度） |
+| GET | `/api/session` | 会话状态：归还 CSRF（刷新页面后内存丢失 → 用它恢复，否则所有变更都 403） |
+| GET | `/api/status` | 进程状态 + 三层健康（含 L3 告警文本）+ dashboard 统计（统计不可得为 null） |
+| GET | `/api/clients` `/api/proxies` `/api/traffic` | v2 数据（自动翻页；traffic 为 7 天日粒度，超 50 个代理时带 `truncated` / `total`） |
 | GET | `/api/config` | 配置树（**打码值 + masked 标记**，原文永不下发） |
+| GET | `/api/config/history` | 快照列表（只读 meta.json，**不读快照里的配置原文**） |
+| GET | `/api/config/history/{steps}/diff` | 某快照 vs 当前配置的**打码 diff**（回滚前的"看差异"；与 `config diff --steps` 同一实现） |
 | GET | `/api/logs?lines=` | 日志尾部（≤2000 行，路径解析复用 `core/logs`） |
-| POST | `/api/config/preview` | 多键变更 → 锁内取快照 + 打码 diff，登记 `preview_id`（TTL 10 分钟） |
-| POST | `/api/config/apply` | 按 `preview_id` 应用；**CAS**：预览后文件被改 → 400 拒绝而不是覆盖 |
-| POST | `/api/actions/{start,stop,restart,rollback,prune}` | 与 CLI 同一套 core 入口 |
+| GET | `/favicon.ico` | 204（页面内嵌 data URI 图标；这条是给旧工具收尾的） |
+| POST | `/api/config/preview` | 多键变更（`changes`）+ 删除键（`unsets`）→ 锁内取快照 + 打码 diff，登记 `preview_id`（TTL 10 分钟） |
+| POST | `/api/config/apply` | 按 `preview_id` 应用（含删除）；**CAS**：预览后文件被改 → 400 拒绝而不是覆盖 |
+| POST | `/api/actions/{start,stop,restart,rollback,prune}` | 与 CLI 同一套 core 入口（数值参数做范围校验，越界/布尔一律 400） |
 
 错误映射：`FrpsctlError.exit_code` → HTTP（用法/配置 400、未运行/冲突 409、
 权限 403、dashboard 不可达/健康未过 502）——响应只含 `message` 与 `hint`，
@@ -2500,9 +2504,11 @@ frp 的教训（user/password 双空 = 完全不鉴权，§3.3）是本项目全
 | 会话劫持 | 256 位随机 token；Cookie `HttpOnly` + `SameSite=Strict`；TTL 8h（内存态） |
 | CSRF | 一切变更请求要求 `X-CSRF-Token`（登录下发，仅存浏览器内存） |
 | 口令爆破 | 来源级失败限速（60s/5 次）；冷却与错口令**响应完全一致** |
+| 反代部署下的爆破误伤 | `--trusted-proxy`（默认**关**）：开启后按 `X-Forwarded-For` **最后一跳**限速；不开启时该头完全不被读取——伪造它既不能绕开限速、也不能制造新来源 |
 | 时序侧信道 | `hmac.compare_digest` |
+| 内存放大（失败来源 / 会话表） | 两张输入驱动的表都**有上限**：失败来源 1024（驱逐最早失败者）、会话 32（驱逐最早到期者） |
 | 配置泄露 | 界面/API 只出打码值；欲看明文用 CLI `--reveal` |
-| 前端供应链 | 单文件、零外部资源；CSP `default-src 'none'` + `connect-src 'self'` |
+| 前端供应链 | 单文件、零外部资源；CSP `default-src 'none'` + `connect-src 'self'`；`tests/test_web_frontend.py` 静态守卫（禁 innerHTML 家族、禁外部引用、JS 语法 `node --check`） |
 
 ### 18.4 systemd 托管
 
@@ -2536,6 +2542,9 @@ Web 端到端测试（真 frps + frpc）第一次调用"下线代理"就暴露
 | HTTPS | 不做：默认回环明文即可；远程访问建议反向代理终结 TLS（文档已说明） |
 | 配置的"全文编辑器" | 不做：表单式逐键编辑 + 预览 diff 更安全（原文不回传浏览器） |
 | 强制下线在线代理 | 做不到：frp 没有该 API（§18.6）；停掉对端 frpc 是唯一途径 |
+| 前端行为测试（DOM 级） | 不做**测试框架**：引入 jsdom/构建链会破坏"单文件零依赖"这个安全资产。语法与静态纪律由 `tests/test_web_frontend.py` 守卫（`node --check` + 禁 innerHTML/外部资源 + CSS 变量对齐），行为正确性由 HTTP 层全路由测试 + 真机冒烟覆盖；已知残余风险是"UI 逻辑分支只有人工点得到" |
+| CSP 去 `'unsafe-inline'`（nonce 化） | 暂不做：单文件内联脚本需要服务端渲染时注入 nonce，收益是纵深防御（当前无任何注入点），成本是前端从"静态文件直发"变成"每请求改写"。已记账，等有真实动机再动 |
+| 配置表单的结构化数组编辑器 | 暂不做：`allowPorts` 这类数组目前按 JSON 文本编辑（有 `parse_scalar` 兜底与预览 diff 兜底）；等实际使用中确认痛点再设计 |
 
 ### 18.8 发布前回归 review（第八轮）
 
@@ -2669,6 +2678,93 @@ JS 经 `node --check` 语法验证通过。
 
 ---
 
+## 20. 第七轮全量迭代（v0.2.4：Web 体验与前端守卫）
+
+本轮聚焦 Web 管理台的优化与增强、易用性、可用性、美观性。方法仍是**完整通读
+全部源码、测试与文档（无截断）后逐条核对**——这一轮暴露出一个此前从未被
+正视的断层：
+
+> **后端能力已经齐了，前端没有把它们全部用出来；而前端本身在 CI 里几乎零防护。**
+
+证据都在代码里（不是推测）：`index.html` 的 `logScroll` 恒为 true（日志永远
+自动滚底）、API 已下发打码值而前端丢弃、`state_corrupted` / `version_hint` /
+`plugin_warning` 三个后端字段前端从未使用、traffic 超 50 代理静默截断（CLI
+会告警）、`history` 接口长期不进 §18.2 API 表；而全部测试与冒烟只走 HTTP——
+**一处 JS 语法错误会让整站白屏而 CI 全绿**。
+
+### 20.1 修复（5 条，含一条测试盲区）
+
+| # | 问题 | 根因 | 根治方式 |
+|---|------|------|---------|
+| 1 | 前端无任何自动化保护 | 测试与冒烟都只走 HTTP，从不执行 JS | `tests/test_web_frontend.py`：逐 `<script>` 块 `node --check` + 静态纪律守卫（禁 innerHTML 家族 / 禁外部资源 / CSS 变量双向对齐 / 亮色主题覆盖检查） |
+| 2 | 配置页切换视图丢草稿 | 每次切回都 `loadConfig()` 清空 dirty | `configLoaded` 标志：已加载不重载；"重新加载（丢弃修改）"是显式动作且二次确认 |
+| 3 | 日志永远自动滚底 | `logScroll` 定义后从未被改写，条件恒真 | 真实滚动监听维护"跟随/暂停"状态并显示在标题栏；滚到底部自动恢复 |
+| 4 | 清理离线记录后不刷新 | `pruneOffline` 成功路径没有后续刷新 | 成功后 `refreshLists()` |
+| 5 | 会话表无上限 | 惰性清理只处理过期；持有口令者可反复登录 | `MAX_SESSIONS = 32`，驱逐最早到期者（与失败来源表同一护栏纪律） |
+
+### 20.2 新增（把后端已有能力交付到界面）
+
+| 能力 | 落点 |
+|------|------|
+| 回滚前"查看差异" | `snapshot_diff` 下沉 core（CLI `config diff` 与 `GET /api/config/history/{steps}/diff` 唯一实现）；历史表逐行"查看差异"，回滚从盲操作变为可预览 |
+| Web 删除键 | `plan_change_many` + `apply_sets(unsets=…)`：改与删合成**一次事务**（一份快照、一次重启）；同键冲突是用法错误 |
+| Web 新增键 | 配置表单底部添加任意键（预览/校验/危险组合拦截与 CLI 同一套）——此前新增必须回 CLI |
+| 单代理流量曲线 | 点击代理行展开该代理 7 天曲线（数据与 CLI `traffic <name>` 同源） |
+| 操作进行中状态 | start/stop/restart/回滚/应用期间按钮禁用 + 状态徽章"操作中…"；in-flight 守卫防轮询叠加（start 最长 10 秒，此前零反馈） |
+| 状态面板补齐 | 损坏横幅（含处置指引）、版本告警、L3 插件告警（`plugin_warning` 此前未下发）、systemd 行、流量截断提示 |
+| 双主题 | `prefers-color-scheme` 自动 + 手动切换（localStorage）；未手动选择时跟随系统实时变化；图表颜色改由 CSS 变量控制 |
+| 界面打磨 | diff 语法高亮、图表 hover 数值与合计、实时速率文本、表格数字右对齐、状态 tag、错误 toast 常驻、内嵌 favicon（`/favicon.ico` → 204）、窄屏菜单折叠 |
+
+### 20.3 工程
+
+- 设计文档 §18.2 补上 `/api/session`、`/api/config/history`、
+  `/api/config/history/{steps}/diff`（长期 drift），并新增
+  `tests/test_docs.py::TestApiDocConsistency`——**API 表 ↔ 路由双向核对**，
+  与命令表守卫同一条纪律；
+- 快照动作文案 `set many:` → `edit many:`（混合变更语义更准确，快照记账同步）；
+- §18.7 边界新增三项明确记账：不做 DOM 级前端测试框架（残余风险如实标注）、
+  CSP nonce 化暂缓的理由、结构化数组编辑器暂缓的理由。
+
+### 20.4 统计与边界（明确记账）
+
+统计：修复 **7 条**（实施期 5 条 + 发布前 review 2 条）、新增 8 项能力、
+新增 **35 条**测试（510 → 545；非契约 515），覆盖率 85%，前端单文件
+650 → 984 行。
+
+| 项 | 说明 |
+|----|------|
+| UI 逻辑分支的人工覆盖 | 语法/纪律已自动化，但"点击某按钮后 DOM 变化"仍只有人工点得到——不引入 jsdom 是刻意的（见 §18.7） |
+| `allowPorts` 等数组仍按 JSON 文本编辑 | `parse_scalar` 与预览 diff 兜底；结构化编辑器等真实痛点 |
+| 前端单文件会继续变大（本轮 650 → 984 行） | 拆分需要构建链，与"零外部资源"冲突；在行数带来实际维护痛点前不拆 |
+
+### 20.5 发布前回归 review
+
+方法同历次（§17.10 / §17.11 / §19.4）：**全部 diff 逐行审查 + 对抗性实测 +
+测试基建复查**。对抗面集中在两处新代码——core 的混合变更入口与 984 行的
+单文件前端。
+
+发现并修复 **2 条真实缺陷**：
+
+| # | 问题 | 复现 | 修复 |
+|---|------|------|------|
+| 1 | `plan_change_many` 把字符串当列表**逐字符迭代**：`unsets="ab"` 静默删掉 `a` 与 `b` 两个键（与 `policy._strict_list` 同型的经典陷阱）；`changes="bindPort"` 则在解包处抛裸 `ValueError` | 对抗性实测复现（"删掉的键: ('a','b')"） | 输入归一化单点化到 `plan_change_many`（`_normalize_pairs` / `_normalize_keys`）：字符串 / 字典 / 生成器一律用法错误；`apply_sets` 改为直接透传原始参数——"字符串当列表"没有第二个藏身处 |
+| 2 | `snapshot_diff` / `rollback_to` 的 `steps < 1` 被 `max(0, steps-1)` **静默归一**成"一步"——参数笔误变成另一个动作（v0.2.3 修过 CLI 侧，core 侧一直敞着） | 代码审查 + 边界实测 | 两个 core 入口都加 `steps >= 1` 防御（与 CLI 的 `min=1` 同一条纪律），各自新增回归用例 |
+
+另有三条**加固**（非缺陷，但成本极低而静默失败风险真实）：
+
+- **JS id 交叉守卫**进 `test_web_frontend.py`：`$("id")` 引用 ↔ HTML 定义
+  **双向核对**（当前 47/47 完全一致）——`node --check` 抓不到"id 拼错 =
+  运行时 null = 白屏"，这条守卫把该盲区关掉；
+- **柱状图柱宽 clamp**（`Math.max(1.5, …)`）：点数异常变多时负宽度会静默不渲染；
+- **前端脚本真实执行烟测**（一次性，node + 最小 DOM stub）：主脚本顶层与
+  boot 异步路径完整执行无异常、`humanBytes` / `humanDuration` 的 7 组取值
+  逐一对齐——覆盖语法检查抓不到的未定义变量 / TDZ 类错误。
+
+残余风险如实记账：DOM 级行为（点击后的界面变化）仍只能人工验证（§18.7 的
+不做项），而 id 缺失这类"用户可见的白屏风险"已被自动化覆盖。
+
+---
+
 ## 附录 A：frps 配置键速查表
 
 > 全部取自 `v0.71.0` 源码；「默认值」栏是 `Complete()` 之后的**生效值**。合法取值来自校验器。

{frpsctl-0.2.3 → frpsctl-0.2.4}/src/frpsctl/__init__.py

@@ -11,4 +11,4 @@ __all__ = ["__version__"]
 
 #: 版本号唯一来源：pyproject.toml 通过 hatchling 从这里读取（tool.hatch.version）。
 #: 发布新版本时只改这里，然后打 `v<version>` tag——release workflow 会校验两者一致。
-__version__ = "0.2.3"
+__version__ = "0.2.4"

{frpsctl-0.2.3 → frpsctl-0.2.4}/src/frpsctl/cli/__init__.py

@@ -29,7 +29,13 @@ from ..core.instance import list_instances
 from ..core.lifecycle import Lifecycle, StartReport, State
 from ..core.lock import instance_lock
 from ..core.systemd import DEFAULT_SERVICE_USER, PluginService, Systemd, WebService
-from ..core.transaction import apply_edit, apply_set, apply_unset, rollback_to
+from ..core.transaction import (
+    apply_edit,
+    apply_set,
+    apply_unset,
+    rollback_to,
+    snapshot_diff,
+)
 from ..core.version import RECKONED_VERSION
 from ..plugin.policy import PluginPolicy
 from ..plugin.server import PluginServer, ServerSettings
@@ -1290,28 +1296,15 @@ def config_diff(
 ) -> None:
     """当前配置 vs 历史快照（unified diff）。"""
     app_ctx = _ctx(ctx).with_json(json_output)
-    inst = app_ctx.instance
-    # 锁内读两份文本：锁外读时"选中的快照"与"当前文本"可能来自不同时刻，
-    # 展示的差异与真实状态不符（并发 config set 正在推进历史的窗口）。
-    with instance_lock(inst.lock):
-        entries = inst.history_entries()
-        if not entries:
-            raise ConfigError("没有配置快照", hint="快照在每次 config set / edit 时自动创建")
-        index = max(0, steps - 1)
-        if index >= len(entries):
-            raise ConfigError(f"只找到 {len(entries)} 份快照")
-        snapshot = entries[index] / "frps.toml"
-        if not snapshot.exists():
-            raise ConfigError(f"快照不完整：{snapshot}")
-        snapshot_text = snapshot.read_text("utf-8")
-        current_text = cfg.read_config_text(inst.config)
-    diff = cfg.diff_texts(snapshot_text, current_text, "frps.toml")
+    # 快照选择与读取在 core 的 snapshot_diff 里（锁内完成）——与 Web 的
+    # "查看差异"共用同一份实现与边界错误。
+    result = snapshot_diff(app_ctx.instance, steps=steps)
     if app_ctx.json:
-        ui.emit_json({"snapshot": str(snapshot.parent), "diff": cfg.mask_diff(diff)})
+        ui.emit_json({"snapshot": str(result.snapshot), "diff": cfg.mask_diff(result.diff)})
     else:
-        ui.emit(cfg.mask_diff(diff).rstrip() or "(无差异)")
+        ui.emit(cfg.mask_diff(result.diff).rstrip() or "(无差异)")
         ui.emit("")
-        ui.emit(f"# 快照：{snapshot.parent.name}")
+        ui.emit(f"# 快照：{result.snapshot.name}")
 
 
 @config_app.command("rollback")

{frpsctl-0.2.3 → frpsctl-0.2.4}/src/frpsctl/core/config.py

@@ -53,6 +53,7 @@ __all__ = [
     "flatten_tree",
     "plan_set",
     "plan_set_many",
+    "plan_change_many",
     "plan_unset",
     "parse_scalar",
     "reject_template_syntax",
@@ -562,8 +563,12 @@ class ChangePlan:
 class MultiChangePlan:
     """多键变更的内存补丁结果（Web 配置表单用）。
 
-    `first before/after` 是逐键的旧值与新值（`dict`，键为点分路径）——
-    供调用方展示"改了哪些键"；`is_noop` 在所有键都未变时为真。
+    `before/after` 是逐键的旧值与新值（`dict`，键为点分路径）——供调用方展示
+    "改了哪些键"；被删除的键 `after` 为 `None` 且出现在 `deletes` 里。
+    `is_noop` 在所有键都未变时为真。
+
+    ⚠️ `dumps` 只调用**一次**：set 与 unset 作用在同一个文档上，因此一次变更
+    只产生一份快照、一次重启——把删除做成"先删再 set"两次调用会破坏这个性质。
     """
 
     changes: tuple[tuple[str, str], ...]
@@ -571,6 +576,8 @@ class MultiChangePlan:
     after: dict[str, Any]
     text: str
     diff: str
+    #: 被删除的键（`config unset` 语义：回落 frp 默认值）。
+    deletes: tuple[str, ...] = ()
 
     @property
     def is_noop(self) -> bool:
@@ -625,13 +632,82 @@ def plan_set(path: Path, dotted: str, raw: str) -> ChangePlan:
 def plan_set_many(path: Path, changes: Any) -> MultiChangePlan:
     """对**多个键**做一次内存补丁（Web 配置表单：一次提交 → 一次重启）。
 
-    与 `plan_set` 同一套校验与定点赋值；所有键作用在**同一个文档**上，
-    因此一次 dumps 就是合并结果。同一键重复出现时后者覆盖前者。
+    是 `plan_change_many` 的纯 set 形态（保留为独立入口，语义更直白）。
+    """
+    return plan_change_many(path, changes, ())
+
+
+def _delete_one(doc: Any, dotted: str) -> Any:
+    """对文档就地删除一个键；返回被删的值（键不存在抛 `ConfigKeyMissing`）。
+
+    与 `plan_unset` 同一条语义：键不存在是配置错误(3)，而不是静默 noop——
+    拼错键名的"成功删除"会让人以为清掉了某个设置（ADR-7：不猜测）。
+    """
+    parts = _validate_dotted(dotted)
+    node: Any = doc
+    for part in parts[:-1]:
+        if not isinstance(node, dict) or part not in node:
+            raise ConfigKeyMissing(dotted)
+        node = node[part]
+    if not isinstance(node, dict) or parts[-1] not in node:
+        raise ConfigKeyMissing(dotted)
+    before = node[parts[-1]]
+    del node[parts[-1]]
+    return before
+
+
+def _normalize_pairs(raw: Any) -> list[tuple[str, str]]:
+    """把 `changes` 归一化成 `(key, value)` 列表；形状错误抛用法错误。
+
+    **拒绝字符串**：`for key, value in "ab"` 会解包失败（裸 ValueError），
+    而 `for key in "ab"` 这类形态在别处会**逐字符迭代**——"看似能跑"的输入
+    必须在边界变成明确报错（与 `plugin/policy.py` 的 `_strict_list` 同一条纪律）。
     """
-    items: list[tuple[str, str]] = [(str(k), str(v)) for k, v in changes]
+    if isinstance(raw, (str, bytes)) or not isinstance(raw, (list, tuple)):
+        raise UsageError(f"changes 必须是 (键, 值) 的数组，实际是 {type(raw).__name__}")
+    out: list[tuple[str, str]] = []
+    for item in raw:
+        if isinstance(item, (list, tuple)) and len(item) == 2:
+            out.append((str(item[0]), str(item[1])))
+        else:
+            raise UsageError(f"无法识别的变更条目：{item!r}（应为 (key, value)）")
+    return out
+
+
+def _normalize_keys(raw: Any) -> list[str]:
+    """把 `unsets` 归一化成键名列表；**字符串会被逐字符迭代，必须拒绝**。"""
+    if isinstance(raw, (str, bytes)) or not isinstance(raw, (list, tuple)):
+        raise UsageError(f"unsets 必须是键名数组，实际是 {type(raw).__name__}")
+    return [str(item) for item in raw]
+
+
+def plan_change_many(
+    path: Path,
+    changes: Any,
+    unsets: Any = (),
+) -> MultiChangePlan:
+    """对多个键做一次**混合**内存补丁：赋值（set）与删除（unset）在同一个文档上。
+
+    为什么要混合形态而不是两个入口相加：删除与赋值作用于**同一份文档**，
+    一次 `dumps` 就是合并结果——Web 的"改两个键 + 删一个键"因此只产生一份
+    快照、一次重启（§9 的事务语义）；分成两次调用会重启两次，中间那次还可能
+    因为"只删了口令"撞上危险组合检查而被拒绝。
+
+    同一键同时出现在 set 与 unset 里是用法错误：两边的意图互相矛盾，静默取
+    其一都会让人以为变更生效了。
+
+    输入在**这里**统一归一化与防御（`apply_sets` 直接透传原始参数）：
+    所有入口共用一套形状检查，"传字符串当列表"这类静默错误没有藏身处。
+    """
+    items = _normalize_pairs(changes)
+    delete_keys = _normalize_keys(unsets)
+    conflict = {key for key, _ in items} & set(delete_keys)
+    if conflict:
+        raise UsageError(f"同一个键不能同时赋值与删除：{', '.join(sorted(conflict))}")
     original = path.read_text("utf-8")
-    if not items:
+    if not items and not delete_keys:
         return MultiChangePlan(changes=(), before={}, after={}, text=original, diff="")
+
     doc = load_config(path)
     before: dict[str, Any] = {}
     after: dict[str, Any] = {}
@@ -639,6 +715,9 @@ def plan_set_many(path: Path, changes: Any) -> MultiChangePlan:
         old, new = _set_one(doc, dotted, raw)
         before[dotted] = old
         after[dotted] = new
+    for dotted in delete_keys:
+        before[dotted] = _delete_one(doc, dotted)
+        after[dotted] = None
     text = tomlkit.dumps(doc)
     return MultiChangePlan(
         changes=tuple(items),
@@ -646,6 +725,7 @@ def plan_set_many(path: Path, changes: Any) -> MultiChangePlan:
         after=after,
         text=text,
         diff=diff_texts(original, text, path.name),
+        deletes=tuple(delete_keys),
     )
 
 
@@ -660,16 +740,7 @@ def plan_unset(path: Path, dotted: str) -> ChangePlan:
     对不存在的键报错同一条原则（ADR-7：不猜测）。
     """
     doc = load_config(path)
-    parts = _validate_dotted(dotted)
-    node: Any = doc
-    for part in parts[:-1]:
-        if not isinstance(node, dict) or part not in node:
-            raise ConfigKeyMissing(dotted)
-        node = node[part]
-    if not isinstance(node, dict) or parts[-1] not in node:
-        raise ConfigKeyMissing(dotted)
-    before = node[parts[-1]]
-    del node[parts[-1]]
+    before = _delete_one(doc, dotted)
     text = tomlkit.dumps(doc)
     return ChangePlan(
         dotted=dotted,