frpsctl 0.2.2__tar.gz → 0.2.4__tar.gz

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

@@ -18,7 +18,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v4
@@ -112,14 +112,37 @@ 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
           config = call("/api/config")
           assert any(item["key"] == "bindPort" for item in config["entries"]), config
+          history = call("/api/config/history")
+          assert isinstance(history["entries"], list), history
+          # 端到端冒烟里的 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 / 静态页")
+          print("web 冒烟通过：login / session / status / config / history / diff / favicon / 静态页")
           EOF
           kill "$WEB_PID"
           wait "$WEB_PID" 2>/dev/null || true

{frpsctl-0.2.2 → frpsctl-0.2.4}/.github/workflows/release.yml

@@ -51,7 +51,14 @@ jobs:
 
           wheel = next(pathlib.Path("dist").glob("*.whl"))
           names = set(zipfile.ZipFile(wheel).namelist())
-          required = {"frpsctl/py.typed", "frpsctl/cli/__init__.py", "frpsctl/core/lifecycle.py"}
+          required = {
+              "frpsctl/py.typed",
+              "frpsctl/cli/__init__.py",
+              "frpsctl/core/lifecycle.py",
+              "frpsctl/core/diagnostics.py",
+              # 前端是 package data：丢它 = 管理台页面 500，而 CLI 测试全绿
+              "frpsctl/web/static/index.html",
+          }
           missing = required - names
           if missing:
               raise SystemExit(f"wheel 缺少文件：{sorted(missing)}")

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

@@ -3,6 +3,128 @@
 格式参考 [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 交叉状态、限速来源模型、分层
+倒置，以及六项新能力（config unset / traffic / plugin user / web password /
+配置历史回滚 / dry-run 与 stdin 输入通道）。
+
+### 修复
+
+- **Web 动作接口的负参数会立即 SIGKILL**：`/api/actions/stop` 的 `timeout` 走
+  宽松解析，`-1` 让等待循环一次都不执行、直接升级 SIGKILL——与 CLI 侧
+  `stop --timeout -1`（v0.2.0 修复）是同一缺陷的镜像。现在全部动作参数做范围
+  校验（越界 / 非数值 → 400），并有一条测试断言"进程必须仍存活"。
+- **`status` 在 systemd 托管 + 损坏 state.json 时误报 STOPPED**：损坏分支完全
+  不探测 unit，而 systemd 下 state.json 本就不参与判定（direct → systemd 迁移
+  的残留即可触发）。现在 systemd 实例照常报告；非 systemd 仍报"不可判定"。
+  同时给 status 的"永不异常"承诺补上 TOCTOU 收口（损坏检查与读取之间的竞态）。
+- **认证失败限速的来源模型**：来源表加上限（1024，防慢速内存放大）；反代部署
+  下所有请求同源、攻击者 5 次失败即可连带锁住管理员 → 新增
+  `web serve --trusted-proxy`（默认关；开启后按 `X-Forwarded-For` 最后一跳
+  限速，`web service install` 亦可写入 unit）。
+- **`config rollback -1` / `config diff --steps 0` 静默归一**：步数必须 ≥ 1
+  （用法错误 2），参数笔误不再变成另一个动作。
+- 健康 detail 在 L2 与 L3 同时失败时只显示 L3 的信息 → 现在汇总两层，且
+  L2 失败时也会渲染失败原因（控制面是恢复顺序上的第一层）。
+- 发布前回归 review 追加修复：Web 动作参数的**布尔值**（`{"timeout": true}`
+  曾被当作 1.0 秒静默接受）；`plugin user set/remove` 的读-改-写**没有锁**
+  （两个并发调用互相覆盖——与第四轮 `config set` 并发丢失同形态，现与 config
+  写共用实例锁）；**首尾空白**（`parse_scalar` 此前保留未 strip 的原文，现按
+  TOML 裸值语义去空白；纯空白的值一律拒绝）；`--prompt` 在无输入时抛裸
+  `EOFError`（现为用法错误并提示改用 `--stdin`）。
+
+### 新增
+
+- `frpsctl config unset <key>`：删键回落 frp 默认值，与 `config set` 同一事务
+  闭环（校验 → 快照 → 重启 → 失败自动回滚）；键不存在报配置错误(3)。
+- `frpsctl config set --dry-run`：跑完全部真实校验（含 `frps verify` 与危险组合
+  拦截）但零落盘、零快照——CLI 版的"预览"；`config unset` 同样支持。
+- `config set --stdin / --prompt`：敏感值不再必须走 argv（shell 历史与
+  `/proc/<pid>/cmdline`）；三种值来源互斥。
+- `frpsctl traffic [name]`：近 7 天流量历史（无参 = 全部代理逐日汇总；离线
+  代理 404 = 无数据，单代理失败不拖垮整体）。
+- `frpsctl plugin user set|remove|list`：策略的结构化编辑（写入前同
+  `plugin check` 判据复验、0600 原子写、未知键原样保留）。
+- `frpsctl web password show`：读回 `web service install` 生成的口令（权限
+  过宽时向 stderr 告警）。
+- Web 管理台的"历史与回滚"卡片：列出快照（时间 / 动作 / 步数）并可回滚到
+  任意一份；新接口 `GET /api/config/history` 只读 meta.json，不下发快照原文。
+
+### 工程
+
+- **分层倒置根治**：`core/` 不再反向 import `cli/`（此前 8 处
+  `cli.ui.trace` / `mask_secret`）——诊断开关下沉为 `core/diagnostics.py`，
+  打码统一走 `config.mask_value`。
+- 死代码清理（零调用即删）：`lock.held_locks`、`plugin.server.serve` /
+  `wait_ready`、`WebSettings.password`（构造后从未被读，容易误以为生效）。
+- 新增 `tests/test_docs.py`：README 命令 / 环境变量 / 退出码与设计文档命令面的
+  **双向一致性守卫**——文档 drift 从此在 CI 里直接暴露；同步刷新设计文档
+  §1.3 / §5 / §7.2。
+- CI 矩阵加入 Python 3.14；Web 与插件的监听 backlog 设为 64（过载行为可预期）。
+- 新增 75 条测试（435 → 510；非契约 480），覆盖率 82% → **85%**。
+
 ## [0.2.2] - 2026-09-17
 
 Web 管理台（内置界面）与 `kick` 语义修正。

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: frpsctl
-Version: 0.2.2
+Version: 0.2.4
 Summary: 把 frp 服务端（frps）包装成命令行工具：配置翻译器 + 进程保镖 + 状态聚合器
 Project-URL: Homepage, https://github.com/ThzxxArt/frpsctl
 Project-URL: Repository, https://github.com/ThzxxArt/frpsctl
@@ -411,6 +411,21 @@ alice.alice-ssh              alice      tcp     6000   online   0      0 B / 0 B
 $ frpsctl proxies --type http      # 只看某类型
 ```
 
+近 7 天的流量历史（日粒度；数据源与 Web 趋势图相同）：
+
+```console
+$ frpsctl traffic                  # 全部代理逐日汇总
+date                  in         out
+2026-09-16       1.2 MiB     3.4 MiB
+2026-09-17       0.4 MiB     1.1 MiB
+合计             1.6 MiB     4.5 MiB
+
+$ frpsctl traffic alice.alice-ssh  # 单个代理的明细
+```
+
+离线或已删除的代理在数据源上返回 404 = 无数据（不是错误）；单个代理查询失败
+也不拖垮整体。
+
 `prune` 清理离线代理记录；在线代理无法从服务端强制下线（frp 没有该 API，
 见"清理离线记录"一节）。
 
@@ -450,6 +465,10 @@ $ frpsctl config set maxPortsPerClient 30
 
 ```bash
 frpsctl config set bindPort 8000 --no-restart   # 只写不重启（输出会提示"尚未生效"）
+frpsctl config set bindPort 8000 --dry-run      # 只校验并展示 diff，不写入、不重启
+frpsctl config set webServer.password --prompt  # 敏感值隐藏输入（不进 argv / shell 历史）
+frpsctl config set webServer.password --stdin   # 或从管道读：echo -n "$PW" | frpsctl ...
+frpsctl config unset maxPortsPerClient          # 删键回落 frp 默认值（同一事务闭环）
 frpsctl config list                             # 列出全部键（值自动打码）
 frpsctl config list --prefix webServer          # 只看某张表
 frpsctl config list --tree                      # 按表分组缩进展示
@@ -462,6 +481,10 @@ frpsctl config rollback                         # 回滚到上一份
 frpsctl config rollback 3                       # 回滚到 3 份之前
 ```
 
+> `--dry-run` 与 `--no-restart` 的区别：前者**什么都不写**（只校验+预览），
+> 后者已经落盘、只是没有重启；`config unset` 删除不存在的键会报配置错误(3)
+> ——拼错键名的"成功删除"会让人以为清掉了某个设置。
+
 **机密保护**：`config get` 默认打码（`SU***56` 形式，保留首尾便于核对是不是同一个
 值），`--json` 与所有 diff 输出同样打码。要看明文必须 `--reveal`。
 
@@ -606,6 +629,20 @@ frpsctl plugin check     # 离线校验 + 试算典型裁决
 frpsctl plugin serve     # 启动（只允许绑回环）
 ```
 
+策略里的用户可以用命令维护——不必手写 JSON（写入前用与 `plugin check` 相同的
+判据复验，0600 原子写，`_comment` 等自定义字段原样保留）：
+
+```bash
+frpsctl plugin user list                               # 用户与权限摘要（不显示策略级凭据）
+frpsctl plugin user set alice --ports 6000-6010 --max-proxies 5
+frpsctl plugin user set alice --no-random-port         # 只改这一个字段，其余保持
+frpsctl plugin user set bob --names ""                 # 空串 = 删除该字段（不限名称）
+frpsctl plugin user remove alice
+```
+
+> 插件服务在启动时载入策略：改完记得重启它才生效
+> （`systemctl restart frpsctl-plugin@<实例>`）。
+
 `plugin check` 让你在部署前就看到"策略会怎么判"：
 
 ```console
@@ -755,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 更严——它正是本项目安全决策的来源）：
 
@@ -782,6 +822,23 @@ sudo frpsctl web service uninstall
 > `web service install` 同样需要 `frpsctl` 位于系统路径（不能被 `ProtectHome`
 > 挡住）——与插件服务的部署要求一致。
 
+配置页里还有**历史与回滚**：列出最近 10 份快照（时间 / 动作 / 步数），每行可
+先"查看差异"再决定是否回滚到那一份（差异接口 `GET /api/config/history/{steps}/diff`
+与 `config diff --steps` 共用同一实现，同样打码；列表接口只读快照元数据，
+**不下发配置原文**——快照是含 token 与口令的完整副本）。
+
+生成的口令随时可以取回（权限过宽时会告警）：
+
+```bash
+frpsctl web password show
+```
+
+**在反向代理后运行**（`--allow-non-loopback` + Nginx 等）时加 `--trusted-proxy`：
+登录失败限速按 `X-Forwarded-For` 的**最后一跳**区分来源。默认关闭时该头完全
+不被读取；开启的前提是"前面确实有一层会重写该头的可信代理"——否则攻击者的
+失败会与管理员同源，5 次失败就能把管理员锁在冷却之外。
+`web service install --trusted-proxy` 会把该标志写进 unit。
+
 ## 用 systemd 托管
 
 ```bash
@@ -1169,16 +1226,19 @@ FRPSCTL_TRACEBACK=1 frpsctl status
 
 ```bash
 uv venv && uv pip install -e ".[dev]"
-.venv/bin/pytest                       # 全部 435 条（契约层缺二进制时自动 skip）
-.venv/bin/pytest -m "not contract"     # 快速回归（405 条）
-.venv/bin/pytest --cov=frpsctl         # 覆盖率（CI 门禁 80%，当前 83%）
+.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）还包含：ruff、覆盖率门禁、真 frp 0.71.0 契约层、
-**真 frp 0.70.0 下界契约矩阵**、无二进制降级路径、端到端冒烟。
+CI（Linux，Python 3.11/3.12/3.13/3.14）还包含：ruff、覆盖率门禁、真 frp 0.71.0
+契约层、**真 frp 0.70.0 下界契约矩阵**、无二进制降级路径、端到端冒烟与
+Web 管理台冒烟（含配置差异接口）、**前端静态守卫**（逐 `<script>` 块
+`node --check` + 禁 innerHTML/外部资源）、**文档一致性守卫**（README/设计文档/
+API 表 vs 代码的交叉核对）。
 
-### 测试分六层
+### 测试分七层
 
 | 层 | 文件 | 目标 |
 |----|------|------|
@@ -1188,6 +1248,7 @@ CI（Linux，Python 3.11/3.12/3.13）还包含：ruff、覆盖率门禁、真 fr
 | 契约 | `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 表的双向一致性 |
 
 让契约层跑起来（需要真实二进制）：
 
@@ -1226,6 +1287,8 @@ fail）——它们是"插件真的接得住 frp 调用"的唯一证明，因此
 | **`max_proxies` 计数需配 `admin_url`** | 不配时只在插件进程内计数（重启归零、多实例各算各的），`plugin check` 会告警 |
 | **frps 没有热重载** | 改配置必然重启，因此 `config set` 的设计目标就是"失败了要能退回去" |
 | **systemd 模式下 pid 文件不参与判定** | 所有权委托 systemctl；`install` 换版本后需 `systemctl restart` |
+| **Web 管理台不限制并发连接数** | 单机管理工具的取舍（请求线程随连接创建，监听 backlog 64）；公网暴露请在前置反代上做限流 |
+| **`--trusted-proxy` 只信 X-Forwarded-For 的最后一跳** | 前提是前面确实有一层会重写该头的可信代理；直连部署不要开启 |
 
 ---
 

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

@@ -388,6 +388,21 @@ alice.alice-ssh              alice      tcp     6000   online   0      0 B / 0 B
 $ frpsctl proxies --type http      # 只看某类型
 ```
 
+近 7 天的流量历史（日粒度；数据源与 Web 趋势图相同）：
+
+```console
+$ frpsctl traffic                  # 全部代理逐日汇总
+date                  in         out
+2026-09-16       1.2 MiB     3.4 MiB
+2026-09-17       0.4 MiB     1.1 MiB
+合计             1.6 MiB     4.5 MiB
+
+$ frpsctl traffic alice.alice-ssh  # 单个代理的明细
+```
+
+离线或已删除的代理在数据源上返回 404 = 无数据（不是错误）；单个代理查询失败
+也不拖垮整体。
+
 `prune` 清理离线代理记录；在线代理无法从服务端强制下线（frp 没有该 API，
 见"清理离线记录"一节）。
 
@@ -427,6 +442,10 @@ $ frpsctl config set maxPortsPerClient 30
 
 ```bash
 frpsctl config set bindPort 8000 --no-restart   # 只写不重启（输出会提示"尚未生效"）
+frpsctl config set bindPort 8000 --dry-run      # 只校验并展示 diff，不写入、不重启
+frpsctl config set webServer.password --prompt  # 敏感值隐藏输入（不进 argv / shell 历史）
+frpsctl config set webServer.password --stdin   # 或从管道读：echo -n "$PW" | frpsctl ...
+frpsctl config unset maxPortsPerClient          # 删键回落 frp 默认值（同一事务闭环）
 frpsctl config list                             # 列出全部键（值自动打码）
 frpsctl config list --prefix webServer          # 只看某张表
 frpsctl config list --tree                      # 按表分组缩进展示
@@ -439,6 +458,10 @@ frpsctl config rollback                         # 回滚到上一份
 frpsctl config rollback 3                       # 回滚到 3 份之前
 ```
 
+> `--dry-run` 与 `--no-restart` 的区别：前者**什么都不写**（只校验+预览），
+> 后者已经落盘、只是没有重启；`config unset` 删除不存在的键会报配置错误(3)
+> ——拼错键名的"成功删除"会让人以为清掉了某个设置。
+
 **机密保护**：`config get` 默认打码（`SU***56` 形式，保留首尾便于核对是不是同一个
 值），`--json` 与所有 diff 输出同样打码。要看明文必须 `--reveal`。
 
@@ -583,6 +606,20 @@ frpsctl plugin check     # 离线校验 + 试算典型裁决
 frpsctl plugin serve     # 启动（只允许绑回环）
 ```
 
+策略里的用户可以用命令维护——不必手写 JSON（写入前用与 `plugin check` 相同的
+判据复验，0600 原子写，`_comment` 等自定义字段原样保留）：
+
+```bash
+frpsctl plugin user list                               # 用户与权限摘要（不显示策略级凭据）
+frpsctl plugin user set alice --ports 6000-6010 --max-proxies 5
+frpsctl plugin user set alice --no-random-port         # 只改这一个字段，其余保持
+frpsctl plugin user set bob --names ""                 # 空串 = 删除该字段（不限名称）
+frpsctl plugin user remove alice
+```
+
+> 插件服务在启动时载入策略：改完记得重启它才生效
+> （`systemctl restart frpsctl-plugin@<实例>`）。
+
 `plugin check` 让你在部署前就看到"策略会怎么判"：
 
 ```console
@@ -732,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 更严——它正是本项目安全决策的来源）：
 
@@ -759,6 +799,23 @@ sudo frpsctl web service uninstall
 > `web service install` 同样需要 `frpsctl` 位于系统路径（不能被 `ProtectHome`
 > 挡住）——与插件服务的部署要求一致。
 
+配置页里还有**历史与回滚**：列出最近 10 份快照（时间 / 动作 / 步数），每行可
+先"查看差异"再决定是否回滚到那一份（差异接口 `GET /api/config/history/{steps}/diff`
+与 `config diff --steps` 共用同一实现，同样打码；列表接口只读快照元数据，
+**不下发配置原文**——快照是含 token 与口令的完整副本）。
+
+生成的口令随时可以取回（权限过宽时会告警）：
+
+```bash
+frpsctl web password show
+```
+
+**在反向代理后运行**（`--allow-non-loopback` + Nginx 等）时加 `--trusted-proxy`：
+登录失败限速按 `X-Forwarded-For` 的**最后一跳**区分来源。默认关闭时该头完全
+不被读取；开启的前提是"前面确实有一层会重写该头的可信代理"——否则攻击者的
+失败会与管理员同源，5 次失败就能把管理员锁在冷却之外。
+`web service install --trusted-proxy` 会把该标志写进 unit。
+
 ## 用 systemd 托管
 
 ```bash
@@ -1146,16 +1203,19 @@ FRPSCTL_TRACEBACK=1 frpsctl status
 
 ```bash
 uv venv && uv pip install -e ".[dev]"
-.venv/bin/pytest                       # 全部 435 条（契约层缺二进制时自动 skip）
-.venv/bin/pytest -m "not contract"     # 快速回归（405 条）
-.venv/bin/pytest --cov=frpsctl         # 覆盖率（CI 门禁 80%，当前 83%）
+.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）还包含：ruff、覆盖率门禁、真 frp 0.71.0 契约层、
-**真 frp 0.70.0 下界契约矩阵**、无二进制降级路径、端到端冒烟。
+CI（Linux，Python 3.11/3.12/3.13/3.14）还包含：ruff、覆盖率门禁、真 frp 0.71.0
+契约层、**真 frp 0.70.0 下界契约矩阵**、无二进制降级路径、端到端冒烟与
+Web 管理台冒烟（含配置差异接口）、**前端静态守卫**（逐 `<script>` 块
+`node --check` + 禁 innerHTML/外部资源）、**文档一致性守卫**（README/设计文档/
+API 表 vs 代码的交叉核对）。
 
-### 测试分六层
+### 测试分七层
 
 | 层 | 文件 | 目标 |
 |----|------|------|
@@ -1165,6 +1225,7 @@ CI（Linux，Python 3.11/3.12/3.13）还包含：ruff、覆盖率门禁、真 fr
 | 契约 | `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 表的双向一致性 |
 
 让契约层跑起来（需要真实二进制）：
 
@@ -1203,6 +1264,8 @@ fail）——它们是"插件真的接得住 frp 调用"的唯一证明，因此
 | **`max_proxies` 计数需配 `admin_url`** | 不配时只在插件进程内计数（重启归零、多实例各算各的），`plugin check` 会告警 |
 | **frps 没有热重载** | 改配置必然重启，因此 `config set` 的设计目标就是"失败了要能退回去" |
 | **systemd 模式下 pid 文件不参与判定** | 所有权委托 systemctl；`install` 换版本后需 `systemctl restart` |
+| **Web 管理台不限制并发连接数** | 单机管理工具的取舍（请求线程随连接创建，监听 backlog 64）；公网暴露请在前置反代上做限流 |
+| **`--trusted-proxy` 只信 X-Forwarded-For 的最后一跳** | 前提是前面确实有一层会重写该头的可信代理；直连部署不要开启 |
 
 ---