密码加密
校对日期:2026-11-16。适用于社区版及全部商业版。
用户密码有两层保护:浏览器提交时用国密 SM2 加密(传输),写入数据库时用 PBKDF2-HMAC-SM3 加胡椒值计算散列(存储)。 本文面向需要在自己的代码里创建用户、校验或修改密码、写登录页面或客户端,以及从其它系统迁移用户的开发者。 两层保护所用密钥的配置和更换,见集群部署的“统一各节点的密钥”一节和等保三级与密评三级合规配置的“密钥管理”一节。
一、存储
密码保存在用户表 ujcms_user 的 password_ 字段,由 Spring Security 的 PasswordEncoder 计算和校验。 这个 Bean 在 com. 中创建,是一个 DelegatingPasswordEncoder,按存储值开头的 {标识} 选择算法:
| 标识 | 算法 | 说明 |
|---|---|---|
{pbkdf2} | PBKDF2WithHmacSM3(com.) | 默认算法,新密码都用它 |
{bcrypt} | BCrypt(Spring Security 的 BCryptPasswordEncoder) | 只用于校验,供迁移来的用户使用 |
| 没有标识 | 按 {pbkdf2} 校验 |
默认算法的参数:每个密码一个 8 字节的随机盐,迭代 8192 次,输出 256 位;盐与散列值拼在一起做 Base64 编码。 加上标识后,存储值形如 {pbkdf2} 加 56 个字符,共 64 个字符。
胡椒值是配置项 ujcms.。计算时它接在随机盐的后面一起参与运算,但不保存在数据库里,所以只拿到数据库的人无法离线验证密码。 随之而来的限制:
- 同一个存储值只在胡椒值相同的系统上有效。把一个系统的
password_复制到胡椒值不同的另一个系统,密码校验不会通过。 - 更换胡椒值后,已有的
{pbkdf2}密码全部失效。更换的步骤和影响见上面两篇运维手册。 {bcrypt}的校验不使用胡椒值。
其它相关的字段和约定:
password_为空,或者是0(User.,只用第三方登录的账号),表示没有设置本地密码,PASSWORD_ NONE User.据此判断。isHasPassword() - 修改密码时,旧的存储值追加到用户扩展表的
history_(逗号分隔),用于“不得使用最近用过的密码”的检查。password_ - 存储值不对外输出:
User类上的@JsonIgnoreProperties把password排除在 JSON 之外,模板里也读不到user.password。
二、传输
登录、注册、修改密码、重置密码等接口都只接受 SM2 加密后的密码,后端先解密再做后续处理:
String rawPassword = Secures.sm2Decrypt(params.password, props.getClientSm2PrivateKey());(com.,后台登录接口 POST /。)
客户端的步骤:
- 请求
GET /取得 SM2 公钥。这个接口不需要登录,返回的是一个 JSON 字符串(十六进制,两端带引号)。api/ env/ client-public-key - 用公钥加密明文密码,密文排列方式为 C1C3C2。
- 在密文前补上
04,由十六进制转成 Base64,作为password提交。
源码里有两份现成的实现,都基于 sm-crypto:
- 后台管理界面:
ujcms-ui-console/的src/ utils/ sm.ts sm2Encrypt(明文, 公钥),用法见src/。views/ LoginPage. vue - 默认主题:
assets/提供js/ auth.js window.,自己取公钥,返回 Promise。模板里先加载sm2Encrypt(明文) assets/, 再加载它;用法见vendor/ sm-crypto/ dist/ sm2.js templates/(表单提交前把密码框的值换成密文)。mem_ login. html
Java 一侧(测试代码、另一个后端服务)可以直接用 com.,结果已经是要提交的 Base64 字符串。
密钥对由配置项 ujcms.、ujcms. 指定。没有配置时,程序每次启动都生成一对新的, 所以客户端应当在每次提交前取公钥,不要长期缓存,也不要写死在代码里。
三、在代码里校验和设置密码
需要用到密码的类里注入 PasswordEncoder 和 UserService。
校验密码(与登录接口的判断相同):
String stored = user.getPassword();
boolean matched = StringUtils.isNotBlank(stored) && passwordEncoder.matches(rawPassword, stored);登录接口在此之外还做了失败次数累计、账号锁定、IP 限制、验证码和双因子认证。自己写的校验不经过这些环节,不要用它另开一个可以反复试密码的入口。
修改密码用 UserService.,不要自己给 password_ 赋值再更新:
// 用户自己修改,或通过验证码重置
userService.updatePassword(user, user.getExt(), rawPassword);
// 管理员代为重置:第四个参数为 true,要求该用户下次登录先改密码(安全设置中开启了首次登录强制改密时生效)
userService.updatePassword(user, user.getExt(), rawPassword, true);它会计算新的存储值、把旧值记入历史密码、更新密码修改时间、把登录失败次数清零,并设置或清除“下次登录先改密码”的标记。它不检查原密码、历史密码和密码最短使用天数, 这些由调用它的接口负责,写法见 com.。
创建用户分两步,先插入用户,再设置密码。注册接口的写法(com.):
User user = new User();
user.setUsername(username);
user.setGroupId(Group.MEMBER_GROUP_ID);
user.setOrgId(Org.MEMBER_ORG_ID);
user.setType(User.TYPE_MEMBER);
user.setStatus(User.STATUS_ENABLED);
userService.insert(user, user.getExt(), Collections.emptyList());
userService.updatePassword(user, user.getExt(), rawPassword);UserService. 不检查用户名、手机号、邮箱是否重复,调用之前自己用 selectByUsername 等方法检查。 也可以像批量录入那样在插入之前直接写入存储值:user.(UserBatchService)。 不设置密码的用户无法用密码登录。
只需要一个存储值(例如准备初始化数据)时,在当前系统上调用 passwordEncoder.,得到的值带 {pbkdf2} 标识, 只在胡椒值相同的系统上有效。
四、从其它系统迁移用户
迁移时明文密码通常拿不到,能不能沿用原密码取决于原系统的散列算法:
| 原系统的密码 | 做法 |
|---|---|
BCrypt 散列($2a$、$2b$ 开头) | 在原值前加 {bcrypt} 写入 password_,用户可以用原密码登录。之后修改密码时,新值按 {pbkdf2} 保存 |
| 有明文(如统一的初始密码) | 用后台的批量录入、导入用户,或在代码里按“在代码里校验和设置密码”一节创建,见用户批量操作 |
| 其它散列算法(MD5、SHA 加盐等) | 系统没有内置对应的校验器。可以不迁移密码,让用户通过会员登录页的 忘记密码? 重新设置(需要先配置好邮件或短信,并迁移邮箱或手机号);或者在 SecurityConfig#passwordEncoder 的 encoders 中登记一个该算法的 PasswordEncoder,并给迁移来的值加上相同的 {标识} |
password_ 字段长度为 100,带标识的存储值不能超过这个长度。
直接写数据库迁移用户时,一个用户至少涉及用户表 ujcms_user 和主键相同的用户扩展表 ujcms_user_ext,手机号和邮箱还要加密并建立盲索引。 优先调用 UserService,不要自己拼 INSERT;已经直接写库的,按用户个人信息盲索引重建处理手机号和邮箱。
五、常见问题
数据库里的密码值从另一套环境复制过来,登录提示密码错误。 两套环境的 ujcms. 不同。在目标环境上重新设置密码;管理员账号见找回管理员密码。
自己写的登录页提交后总是失败。 检查密码是否按“传输”一节加密:密文前要补 04,要转成 Base64,公钥要在提交前从接口取。程序重启后公钥可能已经变了。
集群里有的请求登录成功,有的失败。 各节点的 SM2 密钥对或胡椒值不一致,见集群部署的“统一各节点的密钥”一节。