Smail/docs/安全引导修复验收.md

安全引导与设置提示修复验收

日期：2026-09-05

本次范围

• [✓] 首次登录显示密保问题、外部安全邮箱、安全密钥引导，包含超级管理员。
• [✓] 引导确认状态按账号持久化，确认失败保留弹窗并允许重试。
• [✓] 强制修改密码页面不显示引导，进入邮箱后再提示。
• [✓] 设置标签页按需加载，未启用安全密钥时显示状态说明。
• [✓] 旧版配置模式先读取配置管理状态，不继续请求分区、备份、审计。
• [✓] 退出时销毁会话和 CSRF Cookie，避免下一次登录被残留会话阻断。
• [!] 现有主服务替换及完整 setup 向导重新验收未完成。
• [!] Git 推送因远程认证失败未完成；用户已授权先本地修复。

引导语义

新增数据库迁移 15，为用户增加 security_setup_acknowledged，默认值为零。 新账号与尚未确认过新引导的旧账号均显示一次引导。 只有点击引导中的确认或前往设置按钮，并且服务端成功持久化后，才停止自动提示。 未确认时刷新仍显示，避免页面刚加载或请求失败就丢失引导。 多标签页已经显示的弹窗不会实时同步关闭，确认接口可重复安全调用。

POST /api/v1/security/setup/acknowledge 只处理当前会话用户，不接受目标账号切换。 接口使用正式会话、请求来源、CSRF 与强制改密校验链路。 确认引导不代表已完成任何安全设置，也不会修改密码或安全版本。

普通账号离线恢复码仍可在安全设置内生成，旧恢复码组件文件保留但不再全局自动弹出。 超级管理员不开放网页密码恢复或离线恢复码入口，部署端本机 IPC 安全边界保持不变。

浏览器实测

隔离服务地址：https://localhost:15443/，采用临时自签名证书。 服务使用独立空 SQLite、正式迁移器、真实登录/会话/CSRF/配置控制器，以及最新前端构建。 测试账号由夹具创建，并非完整 setup 向导创建；未使用当前业务库。

1. 超级管理员通过登录表单进入收件箱，出现三项安全引导。
2. 未带 CSRF 的确认请求返回业务错误，不能确认引导。
3. 点击开始设置，确认成功后进入密保问题页，无配置管理请求和错误通知。
4. 点击安全密钥，显示服务器未启用说明，不发送凭据列表请求。
5. 切到配置管理，只请求一次状态，显示旧版配置迁移说明，无重复错误通知。
6. 刷新后用户信息成功返回，showSecuritySetupPrompt=false，保持登录且不再弹窗。
7. 退出重登实测发现原实现保留会话 Cookie；改为销毁后，在干净隔离浏览器上下文重测，登录成功且不再弹窗。

隔离夹具不启动 SMTP/IMAP/POP 或管理员 IPC，不构成完整服务部署验收。 当前旧后端仍需要由具备相应权限的部署人员切换至新版本。 旧版配置迁移及 WebAuthn 服务启用本身不在此次自动操作范围，不能将状态提示当成功能已启用。

验证与产物

• 后端全套 go test ./... 已运行通过；部分外部数据库或管理员权限相关测试按原有条件跳过。
• 新增迁移默认值/幂等、账号隔离、匿名拒绝、HTTP 方法/CSRF、退出 Cookie 销毁回归测试。
• 前端新增引导与配置请求行为测试；执行 npm test 与 npm run build。
• 前端构建仍有大型分包警告，不影响本次构建成功。
• 本地后端产物：backend/.tmp-smail-security-setup.exe。
• 真实业务 SQLite、现有 DKIM 改动未修改或提交；测试数据保留在忽略目录中。

隔离浏览器夹具需显式设置 SMAIL_BROWSER_FIXTURE=1、新的 SMAIL_BROWSER_ROOT、 SMAIL_BROWSER_PASSWORD、SMAIL_BROWSER_DIST，然后仅运行 TestSecuritySetupBrowserFixture。默认跳过，启用后最长运行 30 分钟。 不要给夹具指定真实数据目录，也不要把测试密码写入版本控制。