用户个人信息盲索引重建
校对日期:2026-10-06。适用于社区版及全部商业版。 密钥与密码胡椒值的运维说明见等保三级与密评三级合规配置的“密钥管理”一节。
用户的手机号、邮箱等个人信息(PII)以 SM4-GCM 加密后存入 ujcms_ / email_。 系统通过盲索引列 mobile_index_ / email_index_(HMAC-SM3)进行精确匹配,用于登录查重、找回密码、 注册查重和 用户 → 用户管理 列表的手机号、邮箱筛选等场景。盲索引是根据原始信息计算出的检索值,用于在 不直接查询明文的情况下定位用户。因此列表里按手机号、邮箱筛选须填写完整的值(空格、连字符会被忽略,邮箱 不分大小写),不能按片段模糊查找;这两列也不能排序。
正常新增或保存用户时,系统会自动写入密文和盲索引。本指南介绍如何调用接口批量补齐历史数据: 将仍为明文的手机号、邮箱转为密文,并计算或重建盲索引。
一、何时需要
- 更换了
ujcms.:历史密文与盲索引随旧密钥失效,须在新密钥配置下重新运行重建操作(集群各节点密钥必须一致)。data-secret-key - 用 SQL / 导入工具批量写入了明文用户数据(含系统引导脚本写入的初始账号):已有明文记录通常在下次保存时才会 自动加密;提前调用本接口,可一次性处理所有需要迁移的历史记录。
- 把 13.0 之前的数据库导入 13.0 表结构:
mobile_/email_仍是明文且索引列为空。
processed: 0 表示没有需要处理的行,属于正常结果;可用下方校验 SQL 确认是否存在遗漏。
二、接口
- 方法 / 路径:
POST /api/ backend/ core/ user/ rebuild-pii-index - 权限:超级管理员(
hasAnyAuthority('*'),即拥有“所有权限”的账号)。 - 请求体:无。
- 响应:统一为
Responses.Body(status0=成功 / -1=失败,外加result/message/exception)。 成功{"status":; 遇盲索引冲突或密文无法解密则0, "result": {"processed": N}, "message": null, "exception": null} status:-1,message指明中止原因与出错用户 ID,不会忽略错误或丢弃数据。 - 处理方式:按用户 ID 顺序分批处理,每批最多 500 条,逐批提交。修复出错记录后可再次调用, 从已提交的进度继续;已处理的记录会自动跳过。此接口不会在应用启动时自动运行。
三、前置条件
- 数据库表结构已到 13.0:Liquibase 变更集
db.changelog-13.(0-pii-encryption. yaml mobile_/email_为 MEDIUMTEXT,mobile_index_/email_index_为 VARCHAR(64) 并各有 UNIQUE 索引)。正常启动一次应用即可自动 建表 / 改列。 - 以超级管理员登录管理控制台。
- 若已开启三权分立(
ujcms.),任何账号都不再持有“所有权限”,本接口 不可用:请在开启前执行,或临时关闭该开关、执行后再开启(见等保三级与密评三级合规配置的“三权分立”一节)。security. separation-of-duties: true
请注意操作顺序:重建完成前,依赖盲索引的精确查询无法找到尚未迁移的记录。更换密钥或批量导入后应及时处理。
四、调用方式(浏览器 DevTools)
控制台使用 JWT 访问令牌验证身份:访问令牌存于 Cookie jwt-access-token,请求头 Authorization: Bearer <token>(见 ujcms-ui-console/、request.ts)。 因此登录控制台后,可在浏览器开发者工具的 Console(控制台)中,使用当前令牌发起请求,无需另行登录 (登录接口要求在客户端使用 SM2 加密密码,直接复用登录令牌更方便):
fetch('/api/backend/core/user/rebuild-pii-index', {
method: 'POST',
headers: { Authorization: 'Bearer ' + document.cookie.match(/jwt-access-token=([^;]+)/)[1] },
})
.then((r) => r.json())
.then(console.log);- 成功输出形如
{status: 0, result: {processed: 123}, message: null, exception: null}:status: 0即成功;result.为本次写入索引的用户数。processed processed: 0表示没有需要迁移的存量数据(用户均无手机号/邮箱,或新增用户时已自动建立索引), 属于正常结果。可执行下方校验 SQL 确认是否存在遗漏。 - 失败时
status: -1,message指出中止原因;若提示某用户 ID 的手机号/邮箱盲索引冲突, 说明数据库中存在重复信息(历史数据仅由应用层检查,可能留下重复记录)。请先处理重复数据, 再执行上面的脚本,即可从已提交的进度继续。
五、校验(确认无遗漏)
processed: 0 时,可对目标库执行以下查询,区分“没有需要处理的个人信息”与“存在未处理数据”:
SELECT
COUNT(*) AS total,
SUM(CASE WHEN mobile_ IS NOT NULL AND mobile_ <> '' THEN 1 ELSE 0 END) AS has_mobile,
SUM(CASE WHEN mobile_index_ IS NOT NULL THEN 1 ELSE 0 END) AS mobile_indexed,
SUM(CASE WHEN email_ IS NOT NULL AND email_ <> '' THEN 1 ELSE 0 END) AS has_email,
SUM(CASE WHEN email_index_ IS NOT NULL THEN 1 ELSE 0 END) AS email_indexed
FROM ujcms_user;has_且mobile = mobile_ indexed has_(或两者皆为 0):已全部建立索引,或没有需要建立索引的个人信息,结果正常。email = email_ indexed has_或mobile > mobile_ indexed has_:存在尚未建立索引的个人信息,请检查是否已执行迁移,以及连接的数据库是否正确。email > email_ indexed
生产环境若控制台部署在子路径、API 基址为
../api,相对路径/api/...可能 404; 此时把脚本里的路径换成实际 API 基址前缀(如/your-base/)。api/ backend/ core/ user/ rebuild-pii-index
六、curl 备选
调用前需准备访问令牌。可在浏览器开发者工具的 Application → Cookies 中复制 jwt-access-token 的值:
curl -X POST http://localhost:8080/api/backend/core/user/rebuild-pii-index \
-H "Authorization: Bearer <粘贴令牌>"七、注意
- 密钥轮换会同时使历史密文与盲索引失效:更换
ujcms.后需重新调用本接口 (且集群各节点密钥必须一致)。data-secret-key - 重建只处理“手机号/邮箱非空但索引列为 NULL”的行;已迁移的记录会自动跳过,可重复执行。