更新日志

按版本记录流盾 WAF 的功能更新与修复。升级前建议对照本页与 升级与备份 核对变更。

完整源文件见主仓库 CHANGELOG.md。

[1.0.8] - 2026-09-15

新增

• 后台管理面板增加禁止搜索引擎爬取的标签（noindex / nofollow），避免登录页与管理界面被收录
• 优化了后台部分位置的 UI 样式
• 管理面板支持安全入口（环境变量 PANEL_ENTRANCE）：未登录必须访问 /{入口} 才会打开登录页，其它地址返回 404；留空则保持直接进入登录页。已登录会话可直接访问面板；登录页始终需要先走入口

修复

• 修复面板绑定域名并经反向代理访问时，安全入口跳转登录页会错误带上内部端口（如 :9000）的问题

[1.0.7] - 2026-08-19

新增

• 系统设置增加 引擎 页签：可调最大请求体（默认 50 MB）和源站响应超时（默认 60 秒），避免经流盾上传大文件报 413、慢接口报 504。详见 系统设置
• 防护日志可按 请求 ID 筛选；凡经流盾的请求都会带 X-WAF-Request-Id（转给源站的请求头、返回浏览器的响应头）。详见 防护日志
• IP 组与匹配规则支持 IPv6。详见 IP 组
• 一键安装 / 更新在构建成功后会清理未使用的 Docker 构建缓存与悬空镜像，减轻多次升级后的磁盘占用

修复

• 站点列表批量删除或批量修改后会立刻刷新
• AI 防护「仅生成建议」时，在面板或邮件里点应用会真正写入规则。详见 AI 防护
• 导入「系统设置」后会重载引擎，使上传上限和源站超时一并生效。详见 系统设置
• 引擎配置写入 Nginx 失败时不再显示保存成功；缺少 snippet 文件时启动脚本会补上默认上传上限与超时

变更

• 重新设计系统设置页面，按六个分组组织（账户、引擎、访客页面、日志采样、面板与通道、配置备份），提供更人性化的操作体验。详见 系统设置
• 优化引擎自身错误页（413、502 等）的响应展示效果：统一为错误码、简要说明与流盾通用页脚，保留原始 HTTP 状态码；与 WAF 规则拦截页互不影响
• 优化 AI 防护「AI 配置」页面的 UI 显示效果，配置分组与控件类型与系统设置页保持一致。详见 AI 防护
• 大体积请求只把前 64KB 交给 body 规则匹配（内置 SQLi 等仍可看前缀）；整包不再载入 Lua。上传文件名/后缀仅在规则用到时解析。详见 命中条件常用字段
• AI 对话确认创建自定义规则后，可在消息中查看仍存在的规则；名称自动加 [AI规则] 前缀
• AI 防御分析最多轮次由 6 轮调整为 10 轮
• AI 写入自定义规则与人工操作对齐：非观察模式禁止空条件，并校验站点与引用
• AI 防护默认规则应用模式改为「自动分析并处理」：由 AI 在观察、拦截、JS 挑战、滑动验证中选择（原「自动创建拦截」并入该模式）。详见 AI 防护
• AI 智能助手可开关自定义规则，并可创建与管理 Bot 库、IP 组；分析时允许联网搜索公开资料
• 优化程序启动顺序获取和逻辑，避免出现可能因 Nginx 未启动而导致的警告

[1.0.6] - 2026-08-18

新增

• 防护日志记录 直连 IP（TCP 连接地址）。有 CDN 时日志详情与筛选仍可看到边缘节点；规则条件新增「直连 IP」。详见防护日志、命中条件常用字段
• 证书「到期前自动续期」可在续期成功后自动推送到宝塔 / 1Panel 所选站点。配合一键申请免费证书+证书自动续期+自动推送到其他面板功能即可完全实现证书自动化证书管理

变更

• 证书管理列表增加「到期自动续期」列：已开启显示绿色标签并注明证书机构，未开启显示关闭
• 证书管理点击名称可打开更新、删除菜单，交互与防护规则一致
• 站点管理筛选栏右侧可在卡片与表格之间切换
• 优化了前台部分 UI 页面的样式显示效果

修复

• 申请免费证书未提交推送配置时不再清空已保存的面板推送
• 自动续期后保留所选续期域名，避免被证书 PEM 元数据覆盖

[1.0.5] - 2026-08-17

新增

• 证书管理支持一键申请 Let's Encrypt / ZeroSSL 免费证书。详见证书管理
• 证书到期前 10 天可自动续期免费证书
• 编辑已有证书时，可从宝塔 / 1Panel 导入并覆盖当前证书（域名须一致）。详见从其他面板导入

变更

• 「到期前自动续期」与「到期前通知」并列配置：选定证书机构、绑定站点和域名后，即使未点「立即申请」，到期前也会按日尝试续期
• 只开自动续期时，通知通道改为可选；不选则续期结果不发信
• JS 挑战验证中改为极简转圈；失败时才展示带原因的提示页
• 优化 JS 挑战的自动化检测，减少误判
• 站点卡片跳转链接会带上自定义访问端口（优先 HTTP；80 / 443 不显示端口号）
• 管理面板静态资源按类型缓存，升级后浏览器不再容易继续用旧页面

修复

• 从 1Panel 添加账号、测试连接或导入站点/证书时失败
• 一键安装写入本机 1Panel 地址时不再带安全入口，只需协议、主机和端口
• 一键申请后保存到期通知或自动续期配置失败时，不再误判整次申请失败
• 备份导入证书时保留自动续期相关字段，并映射所用通知通道
• 从其他面板导入时，跳过或失败的项会显示具体原因
• AI 智能助手会话列表经常不同步，必须刷新整个后台才能看到新对话

[1.0.4] - 2026-08-16

新增

• 站点可自定义访问监听端口（不再固定 80/443）。在 .env 写入 EXTRA_LISTEN_PORTS（如 9088）后由脚本生成 docker-compose.override.yml 映射到 Docker（不要手改该文件），升级会保留 .env，详见站点配置
• 站点域名支持填写 IPv4 / IPv6（IPv6 会规范为带中括号的 Host 形式）
• 默认拦截页、人机验证页脚与挑战页的品牌名称链到官网

变更

• 容器内 FastAPI 改为 Unix socket，不再占用 TCP 8000，该端口可给站点使用；滑动验证经同一 socket 调用后端
• 自定义端口校验按当前面板端口动态判断，不再写死 8000、9000
• 面板组件使用中文语言包；表单开关行、站点卡片分页与悬浮 AI 助手等界面细节调整

修复

• 修复了站点数量超过 20 时无法显示的 bug
• 站点列表在桌面宽度下分页条与卡片列表对齐
• 滑动验证在 FastAPI 改走 Unix socket 后因本机校验把引擎请求判成 403，导致拼图不加载
• 保存站点时检查跨站点 HTTP/HTTPS 同端口冲突（含引擎默认 HTTP 80），避免 Nginx 重载才失败

[1.0.3] - 2026-08-14

新增

• 全新安装首次打开登录页时设置管理员账号密码（不再从环境变量写入默认 admin / admin888）；已有环境因库中已有账号，仍走正常登录

变更

• 默认登录会话有效期改为 3 天（JWT_REFRESH_TTL_DAYS=3），到期后需重新登录
• 一键安装自动探测本机 IP：写入宝塔 API 白名单，完成页展示面板「IP:端口」
• Docker 构建将 apk 系统包层与 pip/npm 等源解耦，日常更新不再因换 pip 源而重装 python/nginx
• 优化前端面板显示，调整其他面板导入的 UI 界面
• 文档同步首次登录设管理员、构建过慢时把国内源写入 .env（勿临时换镜像）

修复

• 宝塔 API 白名单漏加本机 IP，导致同机调用面板接口失败

[1.0.2] - 2026-08-13

新增

• 系统设置可保存多个宝塔 / 1Panel 账号；站点与证书页支持「从其他面板导入」一次性批量导入
• 一键安装在容器健康检查通过后，自动检测本机宝塔 / 1Panel 并写入「同服务器」账号（失败不阻断安装）
• 一键安装脚本新增github拉取自动换加速源的功能，放置在国内的服务器，因连不上 GitHub 而导致拉取失败
• 一键安装脚本支持选择国内加速：确认安装后可按服务器在国内（Y）或海外（N）启用镜像加速

变更

• 「从其他面板导入」改为单个按钮，抽屉内用宝塔 / 1Panel 两个 Tab；未配置时显示「暂未设置」并跳转系统设置
• 优化一些UI细节
• 文档：侧栏将站点配置与证书管理收进「站点管理」；新增 从其他面板导入 教程
• 优化安装部署逻辑，减少出错概率（拆分 Dockerfile 构建步骤、构建进度改为纯文本、国内加速仅当次生效不写入 .env）

修复

• 回源协议选择「跟随协议」时，可能出现 502 错误
• 一键更新不再重复询问清理失效 Docker 镜像加速源；写入国内加速时会一并去掉已下线源
• 非 git 仓库更新时可选择下载最新代码覆盖项目文件（保留 .env 与数据卷）
• 前端 Docker 构建：npm ci 后先移走 node_modules 再 COPY frontend/，避免部分 BuildKit 用空目录覆盖依赖，导致间歇性 vite: not found；package-lock.json 未变时仍复用依赖缓存

[1.0.1] - 2026-08-12

新增

• 一键安装脚本在启动前检测失效的 Docker registry-mirrors（如已下线的中科大源），可自动清理并重启 Docker，避免拉取 redis / clickhouse 时出现 no such host
• 一键安装脚本在官方 Git 源失败或超时时，临时走镜像重试并恢复官方 origin

变更

• .env.example 调整字段顺序，管理员账号与端口等常用项更靠前
• 文档补充：安装前关闭宝塔 Nginx 防火墙 / 雷池等同类型应用；FAQ 增加失效 Docker 镜像加速源排障
• 部署 FAQ 补充：拉取镜像 timeout / i/o timeout 时，按毫秒镜像一键配置国内加速后再构建

修复

• 一键更新改为 git fetch + reset --hard，强制对齐远程 main，避免本地改动（如 Dockerfile）导致 pull 失败
• 回源不再对普通请求固定发送 Connection: upgrade（仅 WebSocket 升级时使用）；避免部分源站 Nginx（如宝塔）提前断开连接，导致 502「无法连接到源站」
• 引擎补齐 Connection map，与上述回源头逻辑一致
• 移除不安全默认密钥启动拦截，示例环境可直接启动（生产仍应尽快改密）
• 同步移动端侧栏菜单间距；版本号前缀改为大写 V

[1.0.0] - 2026-08-11

新增

• 正式公开发布的第一版
• 统一一键安装/更新脚本 install.sh（官网静态资源 + GitHub 双链接）
• 脚本支持 Linux / 宝塔 / macOS（Docker Desktop），自动处理依赖、80/443 与 Nginx listen、最少交互生成 .env
• 侧栏底部增加版本号（链到更新日志）与教程文档入口
• 官网页脚增加 ICP 备案号；导航增加「讨论反馈」外链

变更

• 诸多 UI 细节优化
• 文档将原分步部署改为「手动安装」；快速开始改为推荐一键命令
• AI 悬浮助手仅在 AI 总开关与「显示悬浮 AI 助手」同时开启时显示
• 侧栏去掉折叠交互，结构与移动端抽屉统一
• 官网首页 Hero 卖点调整为「开源免费 / 超高性能 / AI 驱动」

[0.3.13] - 2026-08-09

新增

• 首次安装预制数据升级：内置 IP 组、黑白名单、防护例外、限速、自定义规则与更完整的 Bot 库/分类（builtin_seed.json）
• 引擎重载失败提示附带具体原因（证书异常 / nginx 原始错误）；未捕获异常也会把错误信息返回给面板
• 日志观察采样率支持按百分比设置（后台仍存 0～1，兼容百分比入参）

变更

• IP 组编辑改为「手动编辑 / 导入文件」，保存时整表覆盖，可增删条目
• 证书到期通知支持绑定多个通知通道
• Nginx 重载失败区分证书问题与引擎问题；站点保存/配置导入提示更明确
• 规则等资源「生效站点」下拉仅显示站点名称（不再附带域名）
• 备注字段统一为自适应高度文本框
• 限速维度至少保留一项；仅剩一项时禁用删除
• 管理面板 viewport 锁定缩放，减轻移动端点击输入框自动放大
• 条件编辑器、拦截页配置、速率防护、Bot 库等表单交互与文案打磨
• 宝塔部署文档补充首次部署与端口检查说明

修复

• 站点保存后引擎重载失败时不再只显示笼统提示，便于定位证书或配置问题

[0.3.12] - 2026-08-07

新增

• 证书「到期前通知」：开启后选择通知通道，按系统时区每日本地 10:00 检测，到期前 7 天内每日提醒一次
• 源站不可达时自定义错误页（502 / 503 / 504）：展示对应状态码与文案，页脚复用「全局验证页页脚」配置
• 站点域名支持通配符（如 *.example.com）；引擎按父域回退匹配
• 站点编辑页可内联导入 SSL 证书；证书表单抽离为共用抽屉组件
• 配置导出/导入能力；总览增加依赖健康检查
• 规则备注字段；站点 Tag 操作；日志补充客户端识别相关字段

变更

• 站点监听端口与强制 HTTPS、证书选择等表单交互优化
• 条件等于/不等于/正则改用自适应高度文本框
• 观察采样空闲默认值调整为 1.0
• 站点增删改后刷新站点选项缓存，避免日志等页面站点列表滞后
• 列表/表格与防护日志相关界面体验打磨（列宽、分页、筛选等）

修复

• ClickHouse 查询客户端正确关闭连接
• 证书创建校验失败返回 400；公钥比对对 Ed25519 更稳健
• 引擎 GeoIP 启动失败相关修复

[0.3.11] - 2026-08-06

新增

• 品牌资源支持日/夜间横版与方形 logo；新增透明 icon.png 用于侧栏收起与 AI 入口
• 登录页能力卖点文案更新：覆盖反向代理、热同步、多防护模式、CC 限速、日志预警与 AI 规则辅助

变更

• Ant Design 主题改为读取 --fs-* 设计令牌，与日夜间 CSS 变量统一
• 应用根层增加氛围背景；布局卡片与表格等表面样式适配半透明令牌
• 侧栏展开显示横版 logo、收起与 AI 相关入口统一使用透明图标（不区分日夜）
• 统一全站表格分页：默认每页 20 条，数据总数大于 20 时显示每页条数选择（20/50/100）
• 下拉菜单箭头、AI 会话侧栏动效、全局滚动条与若干交互样式打磨

[0.3.10] - 2026-08-03

新增

• 总览新增「近 24 小时请求趋势」折线图：同图展示请求量与回源请求量，支持 1/5/10/30/60 分钟颗粒度与站点筛选
• 新增 GET /api/v1/traffic/timeline：从 Redis 分钟环读取近 24 小时时间序列
• 总览「近 24 小时安全态势」统一站点筛选：实时请求量、请求/命中趋势、防护分布与来源、拦截国家、命中规则、攻击 IP、最新动态等板块共用同一站点
• 总览「24H 命中趋势」支持时间颗粒度选择，与请求趋势共用颗粒度设置

变更

• Redis / SQLite 流量分钟环保留由 24 小时延长至 25 小时（为 24 小时图表预留冗余）
• 移除未使用的 ClickHouse 遗留能力：内置流量突增告警（traffic_alerts）、/traffic/intel/alerts 与 /traffic/intel/series 接口
• 仪表盘 /overview、/summary、/feed 支持 site_id 与 trend_granularity 参数
• 移动端左侧导航抽屉宽度由 280px 调整为 200px
• 防护资源列表（黑名单、速率防护、规则等）移动端「更多」菜单补全命中日志/统计等快捷操作，并将按钮右对齐
• 总览图表布局：请求/命中趋势各占一整行；移除「日志类型」卡片；防护方式分布、防护来源、拦截来源国家 Top 三等分一行
• 总览安全态势站点筛选改为纯下拉选择，不可输入搜索
• 总览「24H 请求趋势」与「24H 命中趋势」支持 tooltip 联动，并补全无数据时间桶为 0、统一 24 小时时间轴刻度
• 修复总览命中趋势 UTC 时间解析错误导致 JS 挑战等防护方式不显示；TOP 命中规则排除观察模式
• 防护日志统计「命中时间趋势」颗粒度按钮适配夜间模式
• 防护日志筛选：移动端改用底部抽屉编辑，修复弹层内操作误关闭；清空/移除 Tag 时同步关闭并重置草稿
• 防护日志筛选移动端条件行布局优化（字段+运算符、值+删除横排，条件间分割线）
• 防护日志统计：移动端统计维度改为整卡点击选择；图表与表格 loading 分离，避免 skeleton 导致高度跳动
• 防护日志/明细表格操作菜单顶部展示完整字段名；下拉菜单背景适配设计令牌
• 所有 ECharts 图表 tooltip 适配日夜间模式（背景、边框、文字色）
• 移动端表格卡片与详情 KV 标签列宽优化；防护日志明细「请求 URI」列加宽

[0.3.9] - 2026-07-31

新增

• 预警通知与 AI 防护策略的「生效站点」支持「任意站点」：任一站点满足阈值即触发（区别于「全部站点合计」与「指定站点」）
• 总览「实时请求量」各时间窗口展示回源请求量与回源 QPS
• 回源请求量：WAF 放行后按与请求量相同的时间窗口（10s–24h）记录全站/分站点回源计数，同步至 Redis 快照
• 防护规则条件新增 traffic.origin_global / traffic.origin_site（回源请求量、回源 QPS）
• 预警通知与 AI 防护策略新增「回源请求量」「回源 QPS」触发条件
• AI 防护「事件记录」「防护策略」移动端改为卡片列表；FsDataTable 支持移动端卡片模式
• AI 分析记录 PC 端「分析摘要」列限制宽度并省略过长文本

部署

• App 容器启动：entrypoint 集中等待 Redis（默认 120s，可用 WAIT_REDIS_MAX_SEC 覆盖）；panel 在 backend 就绪后再监听 :9000，避免重启时 /health 反代刷屏 Connection refused
• App 容器启动：增加分步流程日志与就绪后品牌展示（[startup] 前缀，5 步进度 + 流盾 WAF 标语）
• 还原构建默认行为：不再强制国内 Alpine/npm 镜像；ALPINE_MIRROR 改为可选 build-arg
• 前端构建恢复分层 npm ci + .dockerignore 排除 node_modules，避免上下文空目录覆盖依赖
• docker-compose.yml 注释说明：Linux 宿主机构建容器出网失败时可启用 build.network: host

[0.3.8] - 2026-07-23

修复

• 日志采集：Redis 客户端对非 UTF-8 字段使用 encoding_errors=replace，避免 Stream 脏数据触发 UnicodeDecodeError 打挂整个 worker（此前会导致防护日志断流且 CPU 指标消失）
• Worker 各后台循环改为独立监督重启；采集循环内异常只退避重试，不再拖垮同进程的流量/指标任务
• 反代上游改为传递 WAF 解析后的真实客户端 IP（X-Real-IP / X-Forwarded-For ← $waf_geoip_client），修复 XFF 模式下源站拿到边缘节点 IP 的问题

总览与防护日志

• 「命中趋势」按实际出现的防护方式动态分系列（含滑动验证等）；全程为 0 的方式不展示；后续新增防护方式无需改前端硬编码

流量基线

• 取消内置基线突增自动告警（不再写 traffic_alerts、打 TRAFFIC_ALERT 日志）；改由预警/AI 策略的「流量高于/低于基线」条件自行配置
• 移除 AI 防护触发类型 traffic_intel.anomaly；总览卡片改称「流量与基线」，不再标红异常状态
• 实时请求量：秒桶/分钟环同步 Redis，面板与告警判断只读 Redis；SQLite 仅存稀疏分钟环轻量备份（约 30s，不含 10s）；全站/分站点含 24 小时窗口
• 实时计数与基线改为仅按站点存储；仪表盘/规则「全局」为各站点动态求和，未匹配站点的请求不计入
• 基线改从窗口快照学习（与面板滑动窗口同口径）；读/发布在 15 分钟刻切换时回退最近可用值，避免整段暂用基线
• 基线对齐改为轻量「按天内钟点」：不再区分星期，短窗口用小时+15 分刻，长窗口只用小时；同钟点跨天样本可叠加，学得更快
• 流量历史 ClickHouse TTL 由 90 天改为 35 天（学习回看 28 天 + 约 7 天缓冲）；MergeTree 到期自动淘汰，pipeline 启动时同步已有表 TTL
• 全部站点实时 QPS：对各站请求量求和后再 ÷ 窗口（即整体每秒请求量）；10s/30s 进度条满分按视图缩放（单站 10 QPS，全部站点为 10×站点数）

部署

• Docker 命名卷收敛为 3 个：app_data（SQLite + 引擎 conf/certs）、redis_data、clickhouse_data
• Compose 中 Redis 默认走 TCP；镜像不再声明 engine 子路径 VOLUME，避免匿名卷盖住 app_data

[0.3.7] - 2026-07-20

站点卡片

• 站点列表改为卡片指标布局：第一行展示 24 小时总请求、拦截数、独立 IP，并附带「较昨日」对比；点击跳转对应防护日志统计页
• 第二行展示 5 / 30 / 60 分钟实时流量（请求数 + QPS）及基线偏差，样式对齐总览流量异常检测；实时流量卡片不可点击
• 底部操作改为「查看 / 编辑 / 日志 / 统计 / 更多」（更多靠右）；日志与统计默认近 24 小时；「更多」中移除重复的日志入口
• 源站、证书、客户端 IP 等元信息单行显示，超出省略

总览大屏

• 「安全总览」标题区改为透明背景：左侧圆角图标 + 同行副标题，下方展示 MySQL / Redis / ClickHouse 服务状态
• 右侧两行：更新时间精确到时分秒；「自动刷新」改为文案 + 开关（自顶栏移入）
• 「最新动态」改为时间线展示，并补充站点 / 规则元信息

AI 防护

• 防御分析支持多轮工具调用：首轮仅提供近 30 分钟、最多 200 条放行日志，AI 可继续查询日志后再提交结论
• 分析结束需调用 submit_analysis；可选择不创建规则（事件状态 analyzed）
• 防护策略支持自定义提示词，触发分析时一并传给 AI
• AI 配置新增「显示悬浮 AI 助手」开关，可按需隐藏悬浮入口

地理字段

• 移除无数据的 geo.ip_type / geo_ip_type（引擎、字段目录、ClickHouse、规则 DSL、前端统计维度）

界面与其他

• 总览大屏流量异常检测与站点卡片基线展示对齐
• 日志筛选条件字段选择器优化；地理标签展示增强
• 表格分页在移动端改为小号无边框样式

[0.3.6] - 2026-07-20

地理字段语义化

• 日志统计与详情：城市、省/州、ASN 常见值展示中文语义（如 北京 (Beijing)、广东 (GD)、亚马逊 AWS (16509)）
• 补充中国省市、美国州、常见城市与主流 ASN 映射；未知值仍显示原文

规则条件编辑器

• geo.region / geo.city / geo.asn 提供常见可视化选项
• 国家/地理等带选项字段支持「下拉选择 + 手动输入代码」
• 多选操作改为可搜索 tags，可点选也可回车添加自定义值

界面微调

• 条件编辑器与侧栏选中态样式微调

[0.3.5] - 2026-07-20

Bot 库

• 修复 Bot 库页 Tab 切换后内容空白（对齐 fs-tabs-animated 外置内容渲染）
• 取消内置/自定义类型限制：Bot 与分类均可编辑、删除；仅预留分类 other 不可删除
• 移除 Bot 启用/关闭开关，库内条目一律参与识别
• 本地 Bot 表格增加 UA 匹配模式列（Tag 展示）
• Bot 支持多分类：同一 Bot 可同时属于多个分类，规则按任一分类即可命中

地理与条件字段

• geo.country 升级为枚举字段，条件编辑器提供国家选项
• geo.isp 等地理字段补充选项提示与中文标签映射

AI 防护

• 增强 AI 助手上下文、工具与提示词，改进待确认动作卡片与对话面板交互

[0.3.4] - 2026-07-20

修复

• 修复日志国家/地区/运营商为空：OpenResty 镜像缺少 GeoIP2 动态模块导致 entrypoint 静默跳过 .mmdb 配置
• 构建阶段编译并安装 ngx_http_geoip2_module.so，启动时启用 GeoLite2 Country/City/ASN
• 修复 GeoIP2 构建：正确解析 openresty/x.y.z 版本（此前误用 nginx/ 导致下载失败）；模块源码改为 vendored，避免依赖 GitHub clone
• GeoIP 查询源改为站点解析后的真实客户端 IP（waf_geoip_client），避免 CDN 场景下误查边缘节点
• 若检测到 .mmdb 但模块缺失，启动日志输出明确 WARN，不再静默失败

[0.3.3] - 2026-07-20

界面与交互

• 顶栏控件统一为图标按钮：自动刷新、主题切换、用户菜单视觉风格一致
• 主题切换改为太阳/月亮图标，匹配日间/夜间模式认知
• 侧栏折叠触发器改为底部图标按钮，且侧栏固定在视口高度，长页面下始终可见
• Bot 库页面布局优化：远程库与本地库信息层级更清晰

邮件通知

• 统一引入流盾品牌化 HTML 邮件模板（含标题区、内容区、页脚）
• AI 防护触发、分析中、分析结果邮件全部支持 HTML 展示
• 预警策略通知与通知通道测试邮件改为纯文本 + HTML 双格式发送
• SMTP 发送逻辑升级为标准 multipart/alternative，提升主流邮箱客户端渲染兼容性

[0.3.2] - 2026-07-20

地理维度（GeoIP）

• 新增引擎模块 geo_lookup.lua：规则提取与日志写入共用同一套 Geo 字段解析
• 日志懒补全：凡写入日志的请求均补全 geo_country / geo_region / geo_city / geo_asn / geo_isp；规则已 trace 的字段直接复用，未 trace 的仅在日志路径批量读取 ngx.var（不影响未写日志的请求与未引用 geo.* 的规则匹配）
• 内网 IP 跳过 Geo：规则匹配与日志补全前均判断 util.is_private_ip（10/8、172.16/12、192.168/16、127/8），内网地址不进行任何地理查询
• 部署支持自动启用 GeoIP2：将 MaxMind .mmdb 放入 deploy/geoip/ 后容器启动自动生成 geoip2 配置；未配置时国家可回退 CF-IPCountry
• 仓库已附带 GeoLite2-Country / City / ASN 三库（deploy/geoip/），开箱即用；需更新时自行下载覆盖同名文件后重启 app
• 大屏「来源国家」统计改为仅统计已拦截请求（blocked = 1）

站点与 CDN

• 站点新增 客户端 IP 获取方式：支持直连 IP、X-Forwarded-For（首/末跳）、X-Real-IP、CF-Connecting-IP、True-Client-IP、X-Client-IP；影响规则 ip.src、限速、挑战、日志与 GeoIP
• 单值 CDN 头模式自动生成 Nginx real_ip 配置，使 GeoIP2 与真实客户端 IP 对齐

Bot 识别

• CrawlerDetect 改为 vendored 规则：从上游 JayBizzle/Crawler-Detect 拉取 JSON，本地编译后下发引擎；移除运行时 crawlerdetect Python 依赖
• Bot 管理页展示 vendored 版本信息，支持「立即更新 vendored」；系统每 30 天自动同步上游
• 引擎日志入库时直接写入 bot_name / bot_category / ua_family；识别顺序仍为 自建 Bot 库 → vendored 爬虫规则 → UA 启发式
• Python 日志 enrich 优先信任引擎已写入的 bot 维度，减少重复判断
• 修复引擎 sync.lua 未加载 bots / crawler_detect 导致规则与日志侧 Bot 识别失效的问题
• 引擎 bot.lua 合并 resolve_dimensions 并缓存 vendored 正则匹配结果，避免日志 enrich 重复跑大正则
• bot.name / bot.category 规则求值前先确认 ua.family 为 bot，浏览器流量直接短路，避免重复 Bot 名称/分类判断

URL 维度对齐

• 新增引擎共享模块 uri_parse.lua，规则提取与日志写入共用同一套路径/后缀/深度/查询串解析逻辑
• 修复日志 uri_depth 与规则 http.uri.depth 算法不一致的问题（统一为路径段数量）
• 统一 uri_ext 与 http.uri.ext 的后缀正则（支持字母、数字与连字符）
• 日志列 uri 重命名为 request_uri（对应 http.request_uri）；新增 uri_query（http.uri.query）、referer（http.referer）
• 引擎入库时直接写入 query_count，与 http.query.count 对齐
• 日志统计/筛选 UI 标注与规则字段的对应关系（如 http.uri.path、http.host）

字段目录 UI 对齐

• 规则条件字段选择器与日志统计/筛选维度采用统一分类（网络与地理 / URL 与路径 / HTTP 请求 / 客户端识别 / 时间与流量；日志另含 防护命中）
• 日志统计/筛选支持 request_uri（原始请求行）、uri_query（原始查询串）维度，与规则字段 http.request_uri / http.uri.query 对齐

[0.3.1] - 2026-07-20

清理

• 移除 MySQL → SQLite 一次性迁移脚本与相关依赖（migrate-to-sqlite.sh、migrate_mysql_to_sqlite.py、aiomysql / pymysql）
• 移除 .env 中 MySQL 迁移专用变量与健康检查 mysql 兼容字段
• 总览跳转防护日志时默认时间范围改为近 24 小时（与总览数据一致）

[0.3.0] - 2026-07-20

重大架构升级：自本版本起，Docker Compose 由四容器（含 MySQL）精简为三容器；业务配置迁入嵌入式 SQLite，流水类数据统一写入 ClickHouse。从 0.2.x（MySQL 版）升级请务必阅读下方「迁移指引」。

存储架构（核心）

• 业务配置库由 MySQL 改为嵌入式 SQLite（DB_PATH，默认 /data/waf.db），Docker Compose 移除 mysql 服务
• 流水数据迁移至 ClickHouse 三张表：ai_guard_incidents、alert_notification_logs、traffic_alerts
• AI 对话历史（ai_guard_chat_*）仍保存在 SQLite
• 废弃遗留 rule_suggestion 表与 /rule-suggestions API
• 新增 scripts/migrate_mysql_to_sqlite.py 与 scripts/migrate-to-sqlite.sh 一键迁移（可选导入历史流水至 ClickHouse）
• 仪表盘健康检查展示 SQLite 状态（保留 mysql 字段名兼容旧前端）

分析与流水层

• 新增 backend/app/services/analytics/：incident_store、alert_log_store、traffic_alert_store
• AI 防护流水线、预警评估、流量异常、仪表盘动态等改为读写 ClickHouse 流水表
• 修复 ClickHouse 24 下 argMax 嵌套聚合报错（incident 列表查询）
• 修复 LogSampler 对 named_results() 生成器误用 len() 的问题

AI 防护增强

• AI 分析完成后发送 HTML 邮件通知，含建议规则摘要与「应用规则」「忽略」操作链接
• 新增 JWT 鉴权公开接口（10 分钟有效）：/api/v1/ai-guard/incidents/actions/apply|dismiss
• 面板外网地址改为 系统设置 → 显示设置 配置（panel_public_url），首次访问自动从请求推断（含端口）
• 分析记录页状态文案中文化（pending / analyzing / suggested / applied / failed / dismissed）

规则与筛选

• 站点筛选改为仅匹配明确绑定站点的规则（不含全局规则），与列表语义一致
• 迁移遗留 site_ids='null' 文本由 schema patch 自动清理

运维与部署

• docker-compose.yml 调整为 redis + clickhouse + app 三服务
• 面板 Nginx 反代补充 Host $http_host 与 X-Forwarded-Port，修复自动推断面板地址丢端口
• .env.example、docs/architecture.md、docs/upgrade.md、deploy/baota/README.md 同步更新

迁移指引（0.2.x MySQL → 0.3.0）

在已运行旧版四容器的服务器上：

git pull origin main
bash scripts/migrate-to-sqlite.sh    # 备份 MySQL → 迁移 SQLite/ClickHouse → 重建三容器栈

全新部署直接 docker compose up -d --build，无需迁移脚本。完整步骤见 scripts/migrate-to-sqlite.sh 头部注释与 README.md。

[0.2.14] - 2026-07-20

AI 智能助手

• 完整页 /ai-guard 离开再进入时自动恢复最近会话，与悬浮窗共用会话记忆
• 悬浮按钮支持拖动并记忆位置；在 AI 智能助手完整页隐藏悬浮入口
• 小屏下完整页侧栏可折叠收起，主区域全宽显示对话
• 欢迎区快捷提示宽屏横排、间距优化；会话列表去除外框留白，选中项浅底高亮
• 悬浮窗使用 v-show 保持状态，关闭后再次打开不丢失对话进度

[0.2.13] - 2026-07-20

AI 智能助手

• 悬浮窗关闭后重新打开时自动恢复上次会话，不再每次重置为新对话
• 输入框上方快捷提示仅在无消息的新会话中显示
• 修复历史消息加载时 steps 未定义导致助手回复无法渲染的问题

[0.2.12] - 2026-07-19

AI 智能助手

• 新增全局悬浮窗入口，支持侧栏会话列表、新对话与一键清空全部会话
• 聊天改为 SSE 真流式输出，展示思考过程、工具调用与最终回复；支持 Markdown 渲染
• AI 可自主按条件查询 ClickHouse 拦截日志与统计
• 修复历史会话仅显示用户消息、流式超时后页面空白等问题；放宽 Nginx SSE 代理超时并增加保活
• 悬浮窗 compact 模式字号优化

防护资源

• 规则、限速、黑白名单支持自定义拦截页（状态码与 HTML 模板）
• 资源管理支持 JSON 批量导入

运维

• Docker 各服务日志轮转（单文件 50MB、保留 3 份）；补充 ClickHouse 相关环境变量说明
• ClickHouse 默认关闭 query_log，降低磁盘占用

[0.2.11] - 2026-07-19

流量基线

• 基线学习支持冷启动与稳定两档样本门槛：先显示初步基线，样本充足后再参与异常告警
• 历史不足时自动放宽时间槽（同星期同时段 → 同小时 → 仅小时）以加快首次出数
• 基线重算间隔由 1 小时缩短为 15 分钟；修复 ClickHouse 查询时区边界
• 总览异常检测卡片在基线未稳定时显示「学习中」

Bot 识别

• 引擎集成 CrawlerDetect 规则库，与日志 enrich 对齐，识别常见爬虫 UA
• 规则同步下发 crawler_detect 配置；bot_name 优先 Bot 库命中，其次爬虫签名

[0.2.10] - 2026-07-19

规则匹配

• 新增 ua.family（UA 类型）、ua.os（操作系统）条件维度，与日志统计一致
• 「包含字符串 / 排除字符串」支持多值输入（回车添加）
• 字段选择改为自定义弹层：分类小标题 + 三列按钮网格，支持搜索

总览

• 流量异常检测仅展示基线窗口（1 分钟～60 分钟），实时流量保留 10 秒 / 30 秒计数
• 优化流量与异常检测卡片布局与字号

[0.2.8] - 2026-07-18

性能

• ClickHouse 日志写入：collector 批次默认 2000、支持积压连续 drain；ingest 线程复用连接并默认开启 async_insert；默认 detach 小时聚合物化视图以降低写入 CPU（可通过 CLICKHOUSE_HOURLY_MV_ENABLED=true 恢复）
• Worker enrich：批量共享 bot 目录快照，减少每条日志重复加载
• 引擎日志路径：capture_baseline 单次采集；多条 observe 命中仅保留最后一条日志；全匹配 catch-all observe 规则自动置底；traffic 窗口聚合仅在 worker 0 执行

日志

• 明细列表域名、IP、方法、URL 等列支持与统计页一致的快捷筛选与资源下钻

界面

• 资源管理列表移动端卡片间距优化

[0.2.7] - 2026-07-18

日志

• 修复统计/明细页「查看当前规则」等资源详情因缺少 GET 接口返回 405 的问题

Bot 库

• 顶部分类筛选支持多选，并修复选项加载后下拉为空的问题
• 表格增加备注列，移除 UA 模式与生效站点列；新增/编辑表单不再配置站点
• 分类管理表格增加备注列

[0.2.6] - 2026-07-18

日志

• 统计页与明细页共用统一筛选栏：扩展时间维度，支持多条件组合（等于/包含/不等于/不包含/模糊匹配）
• 统计表格与明细「命中规则」等维度支持点击菜单：添加到筛选、查看资源管理、下钻日志明细
• 修复「已拦截」筛选导致统计接口 500 的 ClickHouse 列名冲突问题
• 修复 URL dimension 参数在统计页未自动选中的问题
• 窄屏下时间维度改为下拉选择；统计卡片移至结果列上方

[0.2.5] - 2026-07-18

仪表盘

• 修复自动刷新时顶部时间范围不同步的问题；时间显示精确到秒
• 自动刷新轮询间隔由 5 秒调整为 8 秒

[0.2.4] - 2026-07-18

仪表盘

• 顶部时间范围与图表轴时间按系统时区正确显示；刷新前先更新时间再发起请求
• 自动刷新默认开启；改为请求完成后延时 5 秒再轮询，避免网络阻塞时并发重复请求
• 实时刷新时图表与安全动态列表静默更新，不再反复出现加载动画

界面

• 侧边栏触发器与 Logo 区域背景样式微调

[0.2.3] - 2026-07-18

流量异常检测

• 基线计算改用系统时区、15 分钟时间槽、28 天回看、中位数 + 95 分位异常值剔除
• 支持全站与各启用站点分别计算基线；引擎快照新增 sites 维度
• 告警规则条件扩展 traffic.global / traffic.site，支持多时间窗口与 QPS、基线百分比比较
• 修复 options_for_field() 未包含 TRAFFIC 类型导致时间窗口下拉选项不全的问题
• 修复 Alpine 容器缺少 tzdata 时流量智能接口 502 的问题

仪表盘

• 实时流量与流量异常检测卡片支持按站点筛选
• 顶栏新增「实时刷新」开关（默认关闭，5 秒轮询，偏好写入 localStorage）
• 实时刷新时图表静默更新数据，避免重复销毁重建与加载动画闪烁

列表与日志

• 资源列表支持站点筛选、名称悬停快捷操作、规则名称解析展示
• 日志详情与统计页增强；列表筛选栏与条件编辑器小幅优化

构建

• Docker 镜像补充 tzdata；宝塔部署文档更新

[0.2.2] - 2026-07-18

修复

• 移除 logging 包 __init__ 中的预加载导入，避免导入 crawler_detect 时触发 enrich 循环依赖

[0.2.1] - 2026-07-18

修复

• 修复 bot_identify ↔ crawler_detect 循环导入导致后端/worker 无法启动、管理面板 API 全部 502 的问题

[0.2.0] - 2026-07-18

Bot 识别库

• Bot 管理改为纯识别库：维护 UA 模式与分类，不再内置拦截动作；拦截请用黑白名单 / 自定义规则 / 限速，配合 bot.name、bot.category、bot.is_known 条件
• 新增可管理 Bot 分类（/api/v1/bot-categories），内置 other 为系统预留兜底分类
• 未命中 Bot 库但判定为爬虫时，日志 bot_category 统一写入 other（含 CrawlerDetect 兜底）

日志与 UA 解析

• 入库时统一解析 ua_os、ua_browser、bot_name、bot_category 等维度
• UA 库升级为 ua-parser + crawlerdetect，替代停更的 user-agents

构建

• Docker 依赖分层安装（requirements-base / requirements-extra），仅增量包触发重装
• 默认使用清华 PyPI 镜像，构建过程输出分步提示

迁移提示

• 原 Bot 条目上的 action 已移除，请改为自定义规则 + bot.* 字段实现放行或拦截