# 系统登录与密码类接口加密传输设计文档 ## 1. 背景 当前系统登录、注册、修改密码、重置密码、新增用户等正式接口，在请求体中直接传输明文密码。后端在收到密码后再执行现有的登录校验或 BCrypt 加密入库逻辑。 本次需求是在不改变现有业务语义的前提下，为所有正式密码提交接口增加“密码加密传输”能力，避免密码以明文形式直接出现在接口请求体中。 ## 2. 已确认约束 - 采用对称加密方案 - 前端使用固定密钥加密密码字段 - 后端使用同一固定密钥解密密码字段 - 覆盖所有正式密码提交接口 - 明确不包含 `/login/test` - 不新增兼容性或补丁性方案 - 不允许“解密失败后按明文继续处理” - 保持最短路径实现，不改现有账号、认证、密码存储主逻辑 ## 3. 接口范围 本次加密传输仅覆盖以下正式接口： - `/login` - `/register` - `/system/user/profile/updatePwd` - `/system/user/resetPwd` - `/system/user` 各接口需要处理的密码字段如下： - `/login`：`password` - `/register`：`password` - `/system/user/profile/updatePwd`：`oldPassword`、`newPassword` - `/system/user/resetPwd`：`password` - `/system/user`：`password` 以下接口不在本次范围内： - `/login/test` - 任何不提交密码字段的接口 ## 4. 现状分析 ### 4.1 前端现状 当前前端接口调用中，登录、注册、个人修改密码、管理员重置密码、管理员新增用户都直接提交明文密码字段。仓库中虽然已经存在 `JSEncrypt` 工具，但仅用于“记住密码”场景下 Cookie 的本地存储加密，并没有用于登录或其他正式密码接口。 ### 4.2 后端现状 后端正式接口的密码处理链路如下： - 登录接口直接读取 `LoginBody.password` 并交给认证流程 - 注册接口直接读取 `RegisterBody.password` 并执行 BCrypt 加密入库 - 修改密码接口直接读取 `oldPassword`、`newPassword` 并执行旧密码校验和新密码入库 - 管理员重置密码和新增用户接口直接读取 `SysUser.password` 并执行 BCrypt 加密 现有后端没有统一的密码传输解密层，因此如果直接在前端加密而后端不解密，现有校验链路会全部失效。 ## 5. 方案对比 ### 方案一：保留现有字段名，前端加密后提交，后端统一解密 做法： - 保持现有请求结构不变 - 前端在 API 提交前仅加密密码字段 - 后端在控制器进入业务逻辑前，对密码字段统一解密 优点： - 改动路径最短 - 页面、DTO、控制器入参结构基本不变 - 现有业务校验和 BCrypt 逻辑可直接复用 缺点： - 需要明确每个接口的密码字段清单 - 前后端都要维护一份受控字段映射 ### 方案二：新增专用密文字段 做法： - 每个接口新增 `encryptedPassword`、`encryptedOldPassword` 等字段 - 后端只处理密文字段 优点： - 语义清楚 - 明文和密文边界直观 缺点： - 改动面大 - 前后端 DTO、表单、测试样例都要整体调整 - 不符合本次最短路径实现原则 ### 方案三：全局请求拦截器加密 + 全局参数层解密 做法： - 前端在 axios 拦截器中按 URL 自动加密密码字段 - 后端在过滤器或参数解析层统一自动解密 优点： - 页面层改动最少 缺点： - 隐式逻辑过重 - 对不同入参类型的接口可读性差 - 不利于后续定位问题 ## 6. 设计结论 采用方案一。 本次仅在接口边界增加密码加密传输能力，业务层继续只处理解密后的明文密码。传输链路如下： 1. 前端表单收集用户输入的密码明文 2. API 提交前，使用固定对称密钥加密密码字段 3. 后端控制器收到请求后，先对约定密码字段解密 4. 解密成功后继续走现有业务逻辑 5. 解密失败时直接返回错误，不进入后续业务处理 `/login/test` 保持现状，不加入加密与解密逻辑。 ## 7. 前端设计 ### 7.1 设计目标 前端只负责“在请求发出前对密码字段加密”，不在页面组件中分散实现逻辑，也不修改表单字段命名。 ### 7.2 收口位置 加密逻辑收口在 API 调用层，不放在页面组件层。 原因： - 登录页、注册页、个人中心、用户管理都存在密码提交场景 - 若每个页面独立处理，加密逻辑容易分散和重复 - API 层更容易统一维护接口与字段映射 ### 7.3 前端改动点 - 新增统一的对称加密工具 - 新增“密码字段加密”辅助方法 - 在以下接口调用前对对应字段加密： - 登录 - 注册 - 个人修改密码 - 管理员重置密码 - 管理员新增用户 - 保持请求字段名不变 ### 7.4 配置方式 前端固定密钥通过环境配置读取，不直接散落在业务代码中。 ## 8. 后端设计 ### 8.1 设计目标 后端只负责“在进入现有业务逻辑前将密码字段解密为明文”，不改动现有认证和密码存储主流程。 ### 8.2 收口位置 解密逻辑收口在控制器入口之后、业务逻辑之前，由统一的密码解密工具完成。 原因： - 当前接口入参类型不统一，包含 `LoginBody`、`RegisterBody`、`SysUser` 和 `Map` - 如果直接放到全局过滤器或参数解析层，会增加隐式复杂度 - 控制器显式调用统一解密工具，路径更短、更直观 ### 8.3 后端改动点 - 新增统一的对称解密工具 - 新增面向不同入参类型的密码字段解密方法 - 在以下正式接口进入业务逻辑前显式解密： - `SysLoginController.login` - `SysRegisterController.register` - `SysProfileController.updatePwd` - `SysUserController.resetPwd` - `SysUserController.add` - 不改动 `SysLoginController.loginWithoutCaptcha` ### 8.4 业务链路保持不变 解密成功后继续沿用现有逻辑： - 登录继续走认证管理器与 `SysPasswordService` - 注册继续走 BCrypt 加密入库 - 个人修改密码继续先校验旧密码，再加密新密码入库 - 管理员重置密码和新增用户继续走 BCrypt 加密入库 ## 9. 配置设计 前后端分别维护固定对称密钥配置： - 前端从环境变量读取固定密钥 - 后端从 `application.yml` 读取固定密钥 本次设计默认前后端使用同一把固定密钥，不涉及动态下发、轮换或多套密钥管理。 ## 10. 错误处理 本次只采用单一路径，不做兼容分支： - 受控正式接口收到密码字段后，后端默认按密文处理 - 任一密码字段解密失败，接口直接返回错误 - 不允许“尝试解密失败后继续按明文处理” - 不允许只加密部分密码字段后继续流转 修改密码接口中，`oldPassword` 与 `newPassword` 必须同时成功解密后才能进入现有校验流程。 ## 11. 非目标 本次不包含以下内容： - 不修改 `/login/test` - 不改造密码存储方式 - 不改造现有 BCrypt 校验逻辑 - 不引入非对称加密 - 不增加密钥动态下发能力 - 不增加明密文双通道兼容逻辑 - 不修改与密码无关的请求字段 ## 12. 风险与控制 主要风险如下： 1. 前后端固定密钥不一致，会导致所有正式密码接口失败 2. 某些密码字段漏加密或漏解密，会导致登录失败或入库异常 3. 个人修改密码接口包含多个密码字段，若字段映射错误，会导致旧密码校验失败 控制方式： - 前后端统一约定固定密钥配置名称与用途 - 将密码字段清单明确写入实现计划 - 将正式接口逐一纳入测试验证 - 保持 `/login/test` 完全不接入，避免影响现有测试用途 ## 13. 验证方案 实施后至少验证以下场景： 1. `/login` 提交加密后的 `password` 可以正常登录 2. `/register` 提交加密后的 `password` 可以正常注册 3. `/system/user/profile/updatePwd` 提交加密后的 `oldPassword`、`newPassword` 可以正常修改密码 4. `/system/user/resetPwd` 提交加密后的 `password` 可以正常重置密码 5. `/system/user` 提交加密后的 `password` 可以正常新增用户 6. 受控正式接口在密文非法时直接失败 7. `/login/test` 仍按现有方式运行，不受本次改动影响 ## 14. 实施范围 - 前端：登录、注册、个人中心、用户管理相关 API 和密码加密工具 - 后端：登录、注册、个人中心、用户管理相关控制器和密码解密工具 - 配置：前端环境配置、后端应用配置 - 数据库：无表结构改动 本次属于接口边界增强，不涉及数据库结构和核心认证机制重构。