Skip to content

改版说明:从「通知工具」到「Web 控制台」

状态:方向已确认(2026-11-18),自 v1.3 起分期落地;同日修订:console 内置账号体系(见 §5.2)。v1.3(只读控制台 + 账号)、v1.4(控制台拦截、撤销、封后对比、只读快照)、v1.5(Google / GitHub 登录)与 v1.7(实时小时、涨降榜下钻、WAF 入门与规则配方、控制台规则管理)已发布,实现约定见 SPEC 第 19 节。 本文是方向性文档,描述产品定位、功能范围与安全模型的变化;具体实现细节在开发时补入 SPEC 对应章节。

1. 为什么改

v1.x 的实际使用反馈很明确:通知只是把数字念了一遍,人还是不知道「现在到底什么情况」。

  • 报警文本是单向的、一次性的。收到「总量 +47%」之后,真正想问的是:谁在涨?谁在降?有没有新面孔?涨的是不是贵的那部分(回源 / dynamic)?这些都要再开电脑、查 API、拼数据才能回答。
  • 事件处理(以 2026-11-17 的抓取洪水为例)本质上是一个持续数小时的「盯盘 + 决策」过程:每小时看一次构成变化,判断要不要封、封谁、封了有没有效。文本通知撑不起这个过程,来回问答才行——而问答的内容,其实就是一组固定的查询。
  • 拦截目前只有 CLI。事件当下人在手机边上,flarehound block asn … 这条路太远。

结论:通知应该是提醒层,不是产品本体。 产品本体应该是一个随时打开就能看清状况、并且能当场处置的 Web 控制台;通知负责把人叫到控制台前——画龙点睛,而不是龙本身。

2. 为什么 Cloudflare 面板答不了这个问题

这不是 FlareHound 重复造轮子——Cloudflare 官方产品里确实没有这个视图:

  • 面板分析按产品割裂:域名分析、防火墙事件、Workers 分析各在一处,「一个小时里全站发生了什么」要自己跨页拼。
  • 面板只有「当前值」和 Top N,没有基线对比:没有「同小时 28 天中位数」这个参照系,「涨了」要靠人肉记忆判断。
  • 面板没有新面孔的概念:某个 UA / ASN 是不是第一次出现、什么时候进来的,面板不记录、无从查起(这正是本地归档存在的意义)。
  • 面板更没有把「发现 → 判断 → 封禁 → 验证效果」串成一条操作路径。

FlareHound 的数据层(GraphQL + 本地归档 + 基线)本来就为回答这些问题而建,缺的只是一个能看的界面。

3. 新定位

FlareHound = 自托管的 Cloudflare 流量控制台:实时查询 + 基线对比 + 一键拦截,通知是它的提醒层。

不变的底线:

  • 自托管、单二进制、令牌不出本机;
  • 监控(watch)永远只读;
  • 所有写操作有护栏、有确认、有审计、可回滚(沿用 SPEC §13 的全部规则)。

4. Web 控制台功能

4.1 总览(首页)

  • 当前小时 vs 基线(28 天同小时中位数)一屏对比:总量、Worker 调用、CPU P50、dynamic、源站 5xx,每项带涨跌幅与状态色。
  • 多 zone 切换;数据新鲜度(最后一次成功查询时间)明示,过期数据不装实时。

4.2 涨 / 降榜(Movers)

  • 按 UA、ASN、路径三个维度,分别给出本小时相对基线涨幅最大与跌幅最大的条目,按绝对变化量排序(避免小基数百分比噪音),每条带当前量、基线量、变化量、主要路径 / 主要状态码构成。
  • 这是日报与日内报警的「可视化版」:通知里的一行字,在这里是可下钻的榜单。
  • 口径限制:归档每个维度只保存 Top N,某条目若在基线期内从未进入 Top N,其基线记为「未入榜(< 第 N 名的量)」而非 0,页面明示,避免把「没记录」误读为「从零暴涨」。

4.3 新面孔(New faces)

  • 首次出现的 UA / ASN / 路径列表:首次出现时间、当前量、涨速、主要去向。
  • 数据来自本地归档的面孔历史(CF 侧无此数据);已知面孔(known_faces 配置)自动标注,不重复惊动。
  • 注意:v1.2 及以前的归档只记录 UA 与 ASN 两个维度的面孔;路径维度自 v1.3 起开始记录,历史无法补回,页面对路径面孔标注「记录起始于 …」。

4.4 历史与时间线

  • 小时级历史回看(归档保留期内任意时段),与基线带叠加显示;
  • 时间线标记:报警、封禁 / 解封、规则变更、审计结果——处置效果(封了之后量怎么走)直接在图上看。

4.5 WAF 审计页

  • 现有 flarehound audit 的可视化:规则清单与命中量、两级覆盖结论(挑战级 / 拦截级)、未覆盖的敏感路径、IP Access 检查结果,逐项给出与 CLI 版一致的口径说明。

4.6 拦截操作

  • 当前封禁列表:对象、类型(IP / CIDR / ASN / 国家 / UA)、动作(Block / Managed Challenge)、到期时间、累计拦截尝试量;支持解封与续期。
  • 新建封禁:从涨榜 / 新面孔条目一键带入对象,选动作与时长,执行前过一遍 §13 护栏检查并展示结果(永不封名单、占比 < 1% 时提示「封了也没用」、骨干 / eyeball(宽带)ASN 强警告、国家封禁先展示真实用户构成),二次确认后执行,执行后读回验证,结果写入审计日志。
  • 封后效果自动对比:每次封禁生效后自动在时间线打点,并生成封前 / 封后 1 小时的对比(该对象请求量、占比、状态码构成变化),处置有没有效一目了然,不用再人工算。
  • 撤销入口显式化:每条封禁记录旁有「撤销本次操作」,一键回滚到封禁前状态(落实 §13 的回滚要求),撤销同样过确认流并写入审计。
  • 到期处理(原 enforce 的职责)在控制台内可见可查。

4.7 只读快照分享

  • 任一视图(总览 / 涨降榜 / 某小时历史)可导出为只读静态快照(自包含 HTML,与 §6 的无外部资源原则一致),或生成带签名、有有效期的临时链接;
  • 用途是事件复盘与对外沟通:把当时的状况发给站点团队 / 合作方看,不需要给对方开账号;
  • 快照只含导出时刻的数据,不含任何令牌与账号信息;临时链接过期即废,可随时吊销。

5. 安全模型:双进程隔离与账号体系(本次改版的硬约束)

Web 能拦截,意味着「写能力」第一次进入常驻服务——这是整个改版里最不能含糊的一点。现有安全模型是:watch 守护进程永不接触写令牌,写令牌只存在于一次性的 block / unblock / enforce 进程环境中。 改版后这条不放松,落地方式是隔离:

5.1 双进程隔离

  • 两个进程,两个令牌:flarehound(watch)照旧只读、照旧不读写的环境变量;Web 控制台是独立模式 flarehound console,写令牌只注入 console 进程的环境。watch 挂了不影响看盘,console 不开不影响监控。
  • 默认关闭、默认只绑本机:console 默认不启用;启用时默认监听 127.0.0.1。工具不做公网暴露、不做 TLS 终结;远程访问由使用者自己的 Tailscale / 反向代理 / Cloudflare Tunnel 负责——这是自托管工具的信任边界,写进文档明示。
  • 写操作不可绕过确认流:不存在「点一下直接封」的路径;护栏检查结果与确认步骤是执行链的一部分,前端后端都要校验,不能只靠界面置灰。
  • 审计先行:任何写操作先落审计日志(含操作者账号、来源 IP、对象、护栏检查结果),再执行,再读回验证;失败也要留痕。
  • doctor 相应扩展:检测 console 是否启用、监听地址是否超出本机、写令牌是否误注入 watch 进程环境(发现即警告)。

5.2 账号与认证(console 内置)

为通用性,console 内置账号体系。设计原则:本地账号是身份锚点,第三方登录是挂在锚点上的外部身份——先有锚点,加 Google / GitHub 等快捷登录就是增量绑定,不需要迁移用户数据。

  • 账号与角色:用户表(用户名 / 邮箱、口令哈希、角色、状态);角色只做两级:admin(可执行封禁等写操作)与 viewer(只读浏览)。不做更细的 RBAC。
  • 不开放自助注册:首个 admin 在初始化时创建(CLI flarehound console init-admin 或首次启动向导);其余账号由 admin 创建,或经 admin 发出的邀请链接加入。自托管场景没有陌生人注册的需求,开放注册只会白送攻击面。
  • 口令与会话:口令以 argon2id 哈希存储,绝不存明文;会话为服务端可吊销的 session,配 HttpOnly / SameSite cookie,经 HTTPS 访问(直连 TLS 或可信代理标明 X-Forwarded-Proto: https)时加 Secure;纯 HTTP 且来源非本机时 console 页面与 doctor 均给出警告;登录失败限速与临时锁定;改密、吊销全部会话、禁用账号是 admin 的基本操作;所有写接口带 CSRF 防护。
  • 二次验证:每个账号可启用 TOTP 二次验证(标准 authenticator 应用);admin 可全局要求开启。已开启 TOTP 的账号执行封禁等敏感操作时,要求 step-up(再次输入验证码)才放行。
  • 口令找回:走 admin 重置,或邮件重置链接(复用已有的 SMTP 通知配置);不做短信找回。
  • 第三方登录(扩展路径,见 §7 v1.5):外部身份表(provider + provider 侧唯一 ID ↔ 本地用户 ID)与用户表分离,从 v1.3 起就预留。Google、GitHub 等 OAuth / OIDC 登录作为附加登录方式绑定到已有本地账号,不替代本地账号;新增一种登录方式 = 新增一个 provider 适配,用户数据零迁移。
  • 与外部认证方案并行不互斥:部署在 Cloudflare Access / 反代认证之后时,可开启「信任代理头」模式,从代理注入的身份头读取操作者身份写入审计日志,此模式下可关闭 console 内置登录。此模式必须配置可信代理来源地址白名单(trusted_proxies),只有来自白名单地址的请求才读取身份头,否则任何能连到端口的人都可伪造身份;未配白名单时拒绝启用该模式。用户按部署环境二选一或叠加,产品不强迫。
  • 审计以账号为操作者主体(账号体系的正确性收益):WAF 写操作(封禁 / 解封等)的审计记录以登录账号为操作者,不以来源 IP 代替身份——谁、何时、对什么对象、护栏检查结论、执行结果,一条链可追责;人员变动时禁用单个账号即切断其操作能力,无需全员更换共享口令。共享口令模式下审计只能记到 IP,追责与分权都无从谈起,这正是 WAF 操作必须有账号记录的原因。

6. 技术路线

  • 仍是 Go 单二进制,控制台是同一二进制的子命令 / 模式,不引入第二个运行时。
  • 服务端渲染 + 内嵌 SVG 图表(v1.2 的 internal/chart 输出 PNG、位图字体无 CJK,控制台另写轻量 SVG 渲染,复用其刻度算法与配色),无前端构建链、无 CDN、无外部静态资源——离线可用、供应链面为零,与「令牌不出本机」的气质一致。
  • 数据来源:本地 SQLite 归档(历史、基线、面孔)+ 按需实时 GraphQL 查询(当前小时);查询口径与报警完全一致(同一套校准参数),杜绝「面板一个数、通知一个数」。
  • 页面自动刷新(可配间隔),但所有数字标注窗口与落定状态,未落定的小时明示「数据未落定」。
  • 移动端优先:通知到达的是手机,console 的第一屏(总览 + 涨 / 降榜)以手机竖屏为第一设计目标——关键数字一眼看完,封禁等关键操作在手机上能完整走通;桌面宽屏是增强,不是默认假设。

7. 分期

v1.3 — 只读控制台 + 账号体系

  • 总览、涨 / 降榜、新面孔、历史时间线、WAF 审计页、封禁列表(只读);
  • console 账号体系一同落地(本地账号、admin / viewer 两级、TOTP 二次验证,见 §5.2)——只要 console 能被本机以外访问,登录就是必需品,不能等 v1.4;
  • 通知消息支持附控制台深链(配置了 console 基地址才附);
  • 此阶段 console 进程不持有写令牌,与 watch 一样纯只读。

v1.4 — 控制台拦截

  • 双进程隔离落地,写令牌只进 console 进程;
  • 封禁 / 解封 / 续期全套操作与护栏确认流(TOTP 账号带 step-up);
  • 封后效果自动对比、撤销入口(§4.6);只读快照与签名临时链接(§4.7);
  • CLI 的 block / unblock / blocks / enforce 保留不删:无头环境与脚本化仍需要,且 CLI 是 console 故障时的兜底处置路径。

v1.5 — 第三方登录

  • Google、GitHub OAuth 登录(外部身份绑定本地账号,见 §5.2);
  • 视反馈再评估其他 OIDC 提供商。

8. 不做的事

  • 不做托管 SaaS;不做开放自助注册与细粒度 RBAC(账号由 admin 创建 / 邀请,角色只分 admin / viewer 两级,见 §5.2);
  • 不做工具自带的公网暴露、域名与证书管理;
  • 不试图复刻 Cloudflare 面板的全部功能——只做「看清状况 + 当场处置」这一条线;
  • AI 解读(SPEC §17)维持原定位:可选、默认关、只读证据包,不因有了 Web 而进入决策链。

9. 对现有文档的影响

  • SPEC 新增一章「Web 控制台」(定位、页面、隔离模型、鉴权与确认流);
  • SPEC §13 补 console 入口与「写令牌只进 console 进程」的隔离要求;
  • 通知章节补深链约定;
  • README 的一句话定位由「watchdog」更新为「console + watchdog」口径,快速开始补 console 启用方式。