升级须知

功能简介

升级须知回答一个问题：「我刚升完级，这一版到底变了什么？有没有什么是我该去点一下的？」

以往这些内容只写在版本发布的「重要说明」里，升级路径上没有任何一步会把你引到那儿。现在 SamWaf 启动时会自动比对「上次运行的版本」和「当前版本」，把这中间引入的须知事项列出来，并在首页给出提示。

每条须知都会说清三件事：

• 这是什么 —— 变更或建议本身
• 做了 / 不做的区别 —— 开启之后会怎样，不开启的代价是什么
• 怎么撤销 —— 改了之后后悔了怎么退回去

提示

升级须知只提醒、只引导，不会替你修改任何配置。所有开关都需要你自己到对应页面上确认后再动手。

前置条件

• 无需任何配置，升级后自动出现。
• 所有已登录角色都能看到，包括首页提示条与「系统设置 → 升级须知」页面。
• 只在版本发生变化时生成。同版本重启、开发调试版本不会产生任何提示。

你会在哪里看到它

1. 首页提示条

升级后登录管理端，首页顶部会出现一条蓝色提示：

已从 v1.3.23 升级到 v1.3.24，有 3 项升级须知待处理。 去查看

• 点 去查看 直接进入升级须知页面。
• 全部处理完之后，提示条自动消失。
• 右侧 × 可以收起。收起状态只对本次升级有效，下次再升级时会重新出现，不是永久关闭。

2. 重要须知弹窗

如果本次升级里有重要级别的须知（例如涉及口令、认证、回滚兼容性的变更），进入首页时会弹出一次窗口，只列出重要条目。

注意

这个弹窗一辈子只弹一次。无论你点「我知道了」还是「查看全部」，关掉之后都不会再弹 —— 后续靠首页提示条和升级须知页面兜底。所以看到时请先读一遍再关。

3. 升级须知页面

进入「系统设置 → 升级须知」，可以随时回看全部条目。

操作步骤

1. 查看与筛选

页面顶部三个页签：

页签	内容
待处理	还没确认过的条目，带数量
已完成	已点过「我知道了」的条目
全部	含已忽略的条目，带总数

下面还有两个筛选：类型（知悉 / 建议操作 / 场景确认）和版本（该条是哪个版本引入的）。

2. 展开看细节

点击任意一行（或行首的展开箭头），会展开三块内容：

1. 这是什么 —— 这条须知的完整说明。
2. 做了 / 不做 的区别 —— 左侧绿色是"做了之后"，右侧灰色是"不做"。右侧会明确写出代价，例如占用磁盘、影响性能、可能误拦、可能掉线等。
3. 怎么撤销 —— 改完之后如何退回原状。

底部还有 去设置（直达对应配置页面）和 查看文档 两个链接。

提示

建议先读完「做了 / 不做 的区别」再决定，不要看到"建议开启"就直接开 —— 每个开关都有代价，这一栏就是专门写代价的。

3. 处理条目

按钮	作用
去设置	跳转到该条对应的配置页面，由你自己操作
我知道了	标记为已完成，从「待处理」移到「已完成」
忽略	不计入待处理，但仍保留在「全部」里，随时可以翻回来
恢复待处理	把已完成 / 已忽略的条目退回待处理（误点之后的回头路）

「已完成」和「已忽略」的条目会记录处理人与处理时间。

条目类型说明

类型	含义	你需要做什么
知悉	程序行为变了，但不需要你操作	读一遍，点「我知道了」
建议操作	有个默认关闭的能力，建议你开启	看完「做了 / 不做的区别」，自行决定去不去开
场景确认	只有部分部署环境受影响，需要你自己判断	对照说明看自己是不是那种情况，是就去处理

重要标签表示这条会触发登录弹窗，通常涉及安全、认证或回滚兼容性。

特殊情况

全新安装

全新安装的实例没有"上一个版本"可比，此时列出的是上手建议而不是升级须知，通常包括：

• 立即修改初始登录口令
• 管理端前有反向代理时声明可信代理网段
• 为管理端开启两步验证
• 至少配置一个通知渠道

老实例升级不会收到这几条。

降级运行

如果程序版本低于数据库里记录的「曾经运行过的最高版本」（常见于容器部署：应用内升级后容器被重建，程序回退到镜像自带版本，而数据库回不去），首页和升级须知页面顶部会出现一条红色告警：

检测到降级运行：数据库记录曾经运行过的最高版本是 vX，当前程序版本是 vY……

这种状态下不会生成任何升级须知，只有这条告警。处理办法是把镜像更新到不低于告警中提到的版本，然后重建容器。

注意

这条告警不会因为重启而消失。判定依据是「曾经运行过的最高版本」，这个记录只升不降 —— 只要程序版本还低于它， 每次启动都会提示。这是刻意的：容器反复重建的场景下，只提示第一次等于没提示。

如果你是有意长期运行旧版本，点告警条右侧的 × 关闭即可，之后不再打扰。 但如果后来又发生了一次「升上去再退回来」，最高版本变得更高，说明出现了新的不一致，告警会重新出现。

测试版（beta）

测试版和正式版走同一套逻辑，按版本号先后顺序判断，不会因为你在用 beta 而漏掉或重复提示。典型情况：

• 从正式版升到 beta（如 v1.3.23 → v1.3.24-beta.15）：会看到这中间引入的须知。
• 从 beta 升到同版本正式版（如 v1.3.24-beta.15 → v1.3.24）：beta 期间已经看过的不会重复出现，只补上 beta.15 之后新增的。
• 从正式版装回 beta（如 v1.3.24 → v1.3.24-beta.15）：按版本号这是回退，会被判为降级运行并给出红色告警。

常见问题

升级完了，为什么一条须知都没有？

说明这次升级涉及的版本区间里确实没有需要提醒的事项。不是每一版都会有须知 —— 纯 Bug 修复通常不需要你做任何事。

我用的是开发调试版，为什么从来看不到？

调试版的版本号恒为 v1.0.0，永远追不上实际发布的版本号，所以不会产生任何须知。这是有意为之，避免开发时被打扰。

跨了好几个版本升级，会把中间每一版的须知都列出来吗？

会。例如从 v1.3.21 直接升到 v1.3.24，v1.3.22、v1.3.23、v1.3.24 引入的须知都会列出来，不会因为跳版本而漏掉。

同一条须知会重复出现吗？

不会。每条须知有唯一标识，生成过一次就不会再生成，你处理过的状态也不会被后续升级覆盖。

「忽略」之后还能找回来吗？

能。切到「全部」页签就能看到，点 恢复待处理 即可退回。忽略不是删除。

降级告警关掉之后又冒出来了？

说明「曾经运行过的最高版本」变得比你上次确认时更高了 —— 也就是中间又发生过一次「升级到更高版本，然后又退回旧版本」。这是新的不一致证据，所以告警重新出现，不是没关掉。

这个功能会联网吗？

不会。须知内容随程序版本一起编译在安装包里，不产生任何对外请求，内网与离线部署同样可以正常使用。

弹窗关早了没看清怎么办？

去「系统设置 → 升级须知」，内容一条不少。弹窗只是提醒入口，不是唯一入口。

为什么处理完之后首页提示条还在？

提示条按待处理数量显示。确认「待处理」页签的计数是不是已经归零；如果只是「忽略」了部分条目，忽略的条目不再计入待处理，提示条也会相应减少。