目录
简介
uni-id导入和配置
用户表与文章表关联foreignKey
字段级权限控制
指定数据集权限控制
权限规则的变量和运算符
简介
- 注册、登录、发送短信验证码、密码加密保存、修改密码、忘记密码、头像管理、token管理、rbac权限角色体系、页面访问权限路由控制、用户邀请裂变、用户签到、日志记录、账户防刷
关于登录方式，目前已实现
- 账户密码登录
- 手机号+短信验证码登录 （内置uniCloud短信能力）
- App手机号一键认证，免验证码（内置uni-app App一键登录能力）
- 三方登录：App中的微信登录、Apple ID、QQ登录；微信小程序中的微信登录；支付宝小程序中的支付宝账户登录；QQ小程序中的QQ登录
由于三方登录很多，DCloud没有精力全部实现，在uni-id-co中留下了空实现，欢迎开发者自行补充、提交pr或发布扩展插件，共同完善
后续计划：DCloud未来将内置 微信扫码登录和公众号登录、邮箱验证集成、facebook等海外主流社交账户登录、活体检测。
其他方面，各种常见开源项目如discuz、wordPress、ecshop的用户导入插件，不属于
| 模块 | 说明 |
|---|---|
| 前端uni-app框架的相关API | uniIdRouter页面路由、token管理客户端API |
| 前端页面uni-id-pages | 登录、注册、修改密码、忘记密码、个人中心、修改头像等前端页面 |
| 网络传输自动管理用户token | 自动保存、续期token、网络自动传输token |
| 云端云对象uni-id-co | 与uni-id-pages搭配的云对象，相关业务的云端部分 |
| 云端配置uni-config-center | 在uni-config-center下提供各种配置 |
| 云端公共模块uni-id-common | 用于云函数或云对象集成该模块验证token身份 |
| 云数据库的用户相关数据表 | uni-id-users等各种opendb数据表 |
| uni-admin | Admin管理后台，包括用户角色权限管理、注册用户统计 |
uni-id导入和配置
- uni-id-pages（适用于uni-app的uni-id客户端）详情查看
- uni-id-pages-x（适用于uni-app x的uni-id客户端）详情查看
- uni-id-co（uni-id 的云对象）详情查看
- HBuilderX 3.1.0+
- 插件市场导入uni-id公用模块uni_modules版本，HBuilderX会自动导入依赖的uni-config-center，插件市场 uni-id
- 在uni-config-center公用模块下创建uni-id目录，在创建的uni-id目录下再创建config.json文件配置uni-id所需参数（请参考下面config.json的说明）
uni-id的云端配置文件在
注意：
- config.json是一个标准json文件，不支持注释
配置项：
passwordSecret 为用于加密密码入库的密钥tokenSecret 为生成token需要的密钥tokenExpiresIn token有效期，以秒为单位passwordErrorLimit 密码错误重试次数，分ip记录密码错误次数，达到重试次数之后等待passwordErrorRetryTime 时间之后才可以重试passwordErrorRetryTime 单位为秒- 如果使用
sendSmsCode 接口发送短信需要前往uniCloud控制台开通并充值，配置config.json 的service 字段，字段说明见下方示例 - 另外可以按照客户端平台进行不同的配置，参考下面示例
下面的配置文件中所有时间的单位都是秒
！！！重要！！！ passwordSecret与tokenSecret十分重要，切记妥善保存（不要直接使用下面示例中的passwordSecret与tokenSecret）。修改passwordSecret会导致老用户使用密码无法登录，修改tokenSecret会导致所有已经下发的token失效。如果重新导入uni-id切勿直接覆盖config.json相关配置
// 如果拷贝此内容切记去除注释
{
"passwordSecret": [
{
"type": "hmac-sha256",
"version": 1
}
], // 数据库中password字段是加密存储的，这里的passwordSecret即为加密密码所用的加密算法，详见[密码安全]
"passwordStrength": "medium", // 密码强度，新增于 uni-id-pages 1.0.8版本，见下方说明
"tokenSecret": "", // 生成token所用的密钥，注意修改为自己的，使用一个较长的字符串即可
"requestAuthSecret": "", // URL化请求鉴权签名密钥
"tokenExpiresIn": 7200, // 全平台token过期时间，未指定过期时间的平台会使用此值
"tokenExpiresThreshold": 3600, // 新增于uni-id 1.1.7版本，checkToken时如果token有效期小于此值且在有效期内则自动获取新token，请注意将新token返回给前端保存（云对象会自动保存符合uniCloud响应体规范的响应内的新token），如果不配置此参数则不开启自动获取新token功能
"maxTokenLength": 10, // 数据库用户记录token数组的最大长度，默认为10。新增于uni-id-common 1.0.16
"passwordErrorLimit": 6, // 密码错误最大重试次数
"passwordErrorRetryTime": 3600, // 密码错误重试次数超限之后的冻结时间
"autoSetInviteCode": false, // 是否在用户注册时自动设置邀请码，默认不自动设置
"forceInviteCode": false, // 是否强制用户注册时必填邀请码，默认为false
"idCardCertifyLimit": 1, // 实名认证相关; 限制每个身份证可以绑定几个账号
"realNameCertifyLimit": 5, // 实名认证相关; 限制用户每日认证次数，防止接口被刷
"sensitiveInfoEncryptSecret": "", // 敏感信息加密密钥(长度为32位的字符串)，如使用实名认证功能需配置此密钥
"frvNeedAlivePhoto": false, // 实名认证相关；是否获取认证照片
"userRegisterDefaultRole": [], // 用户注册时的默认角色
"app": { // 如果你使用旧版本uni-id公共模块而不是uni-id-common这里可能配置的是app-plus，务必注意调整为app
"tokenExpiresIn": 2592000,
"tokenExpiresThreshold": 864000,
"oauth": {
// App微信登录所用到的appid、appsecret需要在微信开放平台获取，注意：不是公众平台而是开放平台
"weixin": {
"appid": "",
"appsecret": ""
},
// App QQ登录所用到的appid、appsecret需要在腾讯开放平台获取，注意：不是公众平台而是开放平台
"qq": {
"appid": "",
"appsecret": ""
},
"apple": { // 使用苹果登录时需要
"bundleId": ""
}
}
},
"web": { // 如果你使用旧版本uni-id公共模块而不是uni-id-common这里可能配置的是h5，务必注意调整为web
"tokenExpiresIn": 7200,
"tokenExpiresThreshold": 3600,
"oauth": {
"weixin-h5": { // 微信公众号登录配置
"appid": "",
"appsecret": ""
},
"weixin-web": { // 微信PC页面扫码登录配置
"appid": "",
"appsecret": ""
}
}
},
"mp-weixin": {
"tokenExpiresIn": 259200,
"tokenExpiresThreshold": 86400,
"oauth": {
// 微信小程序登录所用的appid、appsecret需要在对应的小程序管理控制台获取
"weixin": {
"appid": "",
"appsecret": ""
}
}
},
"mp-qq": {
"tokenExpiresIn": 259200,
"tokenExpiresThreshold": 86400,
"oauth": {
// QQ小程序登录所用的appid、appsecret需要在对应的小程序管理控制台获取
"qq": {
"appid": "",
"appsecret": ""
}
}
},
"mp-alipay": {
"tokenExpiresIn": 259200,
"tokenExpiresThreshold": 86400,
"oauth": {
// 支付宝小程序登录用到的appid、privateKey请参考支付宝小程序的文档进行设置或者获取，https://opendocs.alipay.com/open/291/105971#LDsXr
"alipay": {
"appid": "",
"privateKey": "", // 私钥
"keyType": "PKCS8" // 私钥类型，如果私钥类型不是PKCS8，需要填写此字段，否则会出现“error:0D0680A8:asn1 encoding routines:ASN1_CHECK_TLEN:wrong tag”错误
}
}
},
"service": {
"sms": {
"name": "", // 应用名称，对应短信模版的name
"codeExpiresIn": 180, // 验证码过期时间，单位为秒，注意一定要是60的整数倍
"smsKey": "", // uni-id-co 1.1.17及以上版本无需填写，短信密钥key，开通短信服务处可以看到
"smsSecret": "", // uni-id-co 1.1.17及以上版本无需填写，短信密钥secret，开通短信服务处可以看到
"scene": {
"bind-mobile-by-sms": { // 对绑定手机号场景的配置，短信验证码场景值参考：https://uniapp.dcloud.net.cn/uniCloud/uni-id/summary.html#sms-scene
"templateId": "", // 绑定手机号使用的短信验证码模板
"codeExpiresIn": 240 // 绑定手机号验证码过期时间
}
}
},
"univerify": {
"appid": "", // uni-id-co 1.1.17及以上版本无需填写，当前应用的appid，使用云函数URL化，此项必须配置
"apiKey": "", // uni-id-co 1.1.17及以上版本无需填写，apiKey 和 apiSecret 在开发者中心获取，开发者中心：https://dev.dcloud.net.cn/pages/uniLogin/index，文档：https://ask.dcloud.net.cn/article/37965
"apiSecret": ""
}
}
}
添加完配置后 注册登录 数据库会多出两张表 uni-id-log uni-id-users
uni_modules/uni-id-pages/pages/register/register 注册页
uni_modules/uni-id-pages/pages/login/login-withpwd 登录
用户表与文章表关联foreignKey
| 关联关系 | foreignKey | String | 关联字段。表示该字段的原始定义指向另一个表的某个字段，值的格式为 |
一个复杂的业务系统，有很多张数据表。表与表之间，存在的数据关联。foreignKey用于描述数据关联关系。
比如一个文章系统，至少需要用户表、文章分类表、文章表、评论表。opendb已经包含了这4张表，可以点击链接看这些表的结构：
- 用户表：uni-id-users
- 文章分类表：opendb-news-categories
- 文章表：opendb-news-articles
- 评论表：opendb-news-comments
分表
我们先不展开描述上面这几张表，首先讲解为什么分表、怎么分表。
- 熟悉关系型数据库的开发者对分表设计并不陌生 只不过在uniCloud的数据库中，新增了一个传统数据库并没有的schema，其中还有一个foreignKey来表达各个表之间关联关系。 比如上面几个表中的文章表：opendb-news-articles，其中的作者字段
user_id 配置了"foreignKey": "uni-id-users._id" - 而对于初学者，首先需要搞明白的是，为什么需要分表。
因为MongoDB的灵活性，理论上可以在用户表[uni-id-users]中新增一个字段articles，在articles下面通过数组来存放该作者的每一遍文章，然后在该文章中再来一个字段comments，存放该文章的每一条评论。
如下，uni-id-users表的数据内容，假使里面有2个用户，zhangsan和lisi，然后lisi写了1篇文章，这篇文章又被zhangsan评论了1条。
[{
"_id": "60b92a42e22fbe00018c359d",
"username": "zhangsan",
"password": "03caebb36670995fc261a275d212cad65e4bbebd",
"register_date": 1622747714731,
"register_ip": "192.168.0.1",
},
{
"_id": "60b9315801033700011ba9ed",
"username": "lisi",
"password": "03caebb36670995fc261a275d212cad65e4bbebd",
"register_date": 1622747714731,
"register_ip": "192.168.0.2",
"articles":[
{
"title": "文章标题",
"content": "文章内容",
"publish_date": 1617850851000,
"publish_ip": "192.168.0.2",
"comments":[
{
"user_id":"60b92a42e22fbe00018c359d",
"comment_content":"评论内容",
"comment_date":1617850851022,
"comment_ip": "192.168.0.1"
}
]
}
]
}]
可以看出，这个uni-id-users表形成了用户、文章、评论的三层嵌套。
虽然MongoDB可以这么嵌套，但实际业务中不该这样设计。会导致查询性能低下甚至某些查询条件无法实现。
数据库是数字系统的底层，它应该清晰有条理，人、文章、评论以及这3者的关系，都应该清晰且不冗余。
MongoDB的嵌套，更多的适用于不会被单独拎出来查询的、记录条数较少的场景。
比如简历表中的工作经历，就可以嵌套。因为工作经历数量较少、且不会出现单独查工作经历而不查人的情况。
但文章表，是一定需要独立的，因为文章数量会非常多，它会单独搜索；
评论表其实不太有单独搜索的需求，它总是伴随指定文章出现。但因为数量会很多，评论也需要分页查询，嵌套在文章表下不利于分页查询。
所以正确的数据库设计，还是分开这几张表。另外很多文章系统都会有文章分类，比如 社会、教育、娱乐、体育、科技...，所以还需要一个文章分类表。
opendb的这4张表，才是正确的分表设计。
- 用户表：uni-id-users
- 文章分类表：opendb-news-categories
- 文章表：opendb-news-articles
- 评论表：opendb-news-comments
可以看到注册用户都在uni-id-users表中，而文章内容在opendb-news-articles表中。一个用户可能写了很多文章，这些文章不会存入uni-id-users表。
表之间的关系
既然有了分表的概念，就存在表与表之间关系的概念了。
比如在文章表中，如何存放文章的作者信息？如何表示这篇文章是哪个用户写的？是存放作者的用户名吗？
实际上，文章表中的作者字段，也就是
可以看下用户表uni-id-users和文章表opendb-news-articles具体数据，直观感受下：
uni-id-users用户表，还是假使里面有2个作者，zhangsan和lisi
[{
"_id": "60b92a42e22fbe00018c359d",
"username": "zhangsan",
"password": "03caebb36670995fc261a275d212cad65e4bbebd",
"register_date": 1622747714731,
"register_ip": "127.0.0.1",
},
{
"_id": "60b9315801033700011ba9ed",
"username": "lisi",
"password": "03caebb36670995fc261a275d212cad65e4bbebd",
"register_date": 1622747714731,
"register_ip": "127.0.0.1",
}]
opendb-news-articles文章表，里面只有1篇文章，这篇文章是 lisi 写的，所以在字段
{
"_id": "606e721280b8450001e773c6",
"category_id": "606e6feb653b8400017214a3",
"title": "这里是标题",
"content": "这里是正文",
"user_id": "60b9315801033700011ba9ed",
"publish_date": 1617850851000,
"publish_ip": "119.131.174.251"
}
只要
并不需要在文章表opendb-news-articles存放作者的用户名、昵称、头像、注册时间甚至密码，只需要存它的
当然也有的系统设计为了减少联表查询而在文章表里冗余存放作者昵称和头像，是否使用冗余可以视需求而定，但一定需要用
foreignKey的用法
上面显示的是2个表的数据内容，但回到 DB Schema 中，如何在schema中表达这种关联关系？那就是foreignKey，外键。
文章表opendb-news-articles的 DB Schema 中的
"properties": {
"_id": {
"description": "存储文档 ID（用户 ID），系统自动生成"
},
"user_id": {
"bsonType": "string",
"description": "文章作者ID， 参考`uni-id-users` 表",
"foreignKey": "uni-id-users._id",
"defaultValue": {
"$env": "uid"
}
},
"title":{},
"content":{}
}
上面的重点，就在这个foreignKey，它的前半部分是另一张表的表名，中间用
它代表文章表这个
注意不要搞反，并不是在uni-id-users表的schema的
同样，评论表opendb-news-comments的schema里，
- 评论用户id字段
user_id 的foreignKey需指向"uni-id-users._id" - 文章id字段
article_id 的foreignKey需指向"opendb-news-articles._id"
配置foreignKey，除了清晰描述数据关系，它最大的作用是联表查询。
JQL没有像SQL那样提供了join、leftjoin、innerjoin这些语法，只需要配置好数据关系，配好foreignKey，查询时就可以自动联表查询。
联表查询内容较多，详见
字段级权限控制
permission的字段级控制，包括读写两种权限，分别称为：read、write。
也就是对于一个指定的字段，可以控制什么样的角色可以读取该字段内容，什么样的角色可以修改写入字段内容。
以上述的user表为例，假如要限制前端禁止读取age字段，那么按如下配置，在字段age下面再写permission节点，设定read为false。
// user表的schema
{
"bsonType": "object",
"required": [],
"permission": {
"read": true, // 任何用户都可以读
"create": false, // 禁止新增数据记录（admin权限用户不受限）
"update": false, // 禁止更新数据（admin权限用户不受限）
"delete": false // 禁止删除数据（admin权限用户不受限）
},
"properties": {
"_id":{
},
"name":{
},
"age": {
"bsonType": "number",
"title": "年龄",
"permission": {
"read": false, // 禁止读取 age 字段的数据（admin权限用户不受限）
"write": false // 禁止写入 age 字段的数据（admin权限用户不受限）
}
}
}
}
按上述配置，前端查询数据时，如果不包含age字段，仍然可以查询。但如果查询请求包含age字段，该请求会被拒绝，提示无权访问。
子级会继承父级的权限，即需要同时满足父级权限以及本节点权限，方可操作此节点。例如上述schema中如果配置表级read权限为false，在为name设置read权限为true的情况下，name字段仍不可读
如果字段的bsonType配置为password，则clientDB完全不可操作此字段（即使是admin用户也不可以在客户端读写）。
// user表的schema
{
"bsonType": "object",
"required": [],
"permission": {
"read": true, // 任何用户都可以读
"create": false, // 禁止新增数据记录（admin权限用户不受限）
"update": false, // 禁止更新数据（admin权限用户不受限）
"delete": false // 禁止删除数据（admin权限用户不受限）
},
"properties": {
"_id":{
},
"name":{
},
"pwd": {
"bsonType": "password", // 即使不配置权限，此字段也无法在客户端读写
"title": "密码"
}
}
}
指定数据集权限控制
仍然以user表举例，假使该表有个字段叫
然后有个需求，JQL只能查用户状态正常的用户信息，禁用用户信息无法查。那么schema配置如下，表级控制的read节点的值不再是简单的true/false，而是变成一个表达式：
// user表的schema
{
"bsonType": "object",
"required": [],
"permission": {
"read": "doc.status==true", // 任何用户都可以读status字段的值为true的记录，其他记录不可读
"create": false, // 禁止新增数据记录（admin权限用户不受限）
"update": false, // 禁止更新数据（admin权限用户不受限）
"delete": false // 禁止删除数据（admin权限用户不受限）
},
"properties": {
"_id":{
},
"name":{
},
"pwd": {
"bsonType": "string",
"title": "密码",
"permission": {
"read": false, // 禁止读取 pwd 字段的数据（admin权限用户不受限）
"write": false // 禁止写入 pwd 字段的数据（admin权限用户不受限）
}
},
"status": {
"bsonType": "bool",
"title": "用户状态",
"description": "true代表用户正常。false代表用户被禁用"
}
}
}
根据这个配置，如JQL查询user表的所有数据，则会报权限校验失败；如JQL查询里在where条件里声明了只查询status字段为true的数据，则查询会放行。
权限规则的变量和运算符
除了上述例子提到的doc变量，事实上
权限规则内可用的全局变量
| 变量名 | 说明 |
|---|---|
| auth.uid | 用户id |
| auth.role | 用户角色数组，参考uni-id 角色权限，注意 |
| auth.permission | 用户权限数组，参考uni-id 角色权限 |
| doc | 数据库中的目标数据记录，用于匹配记录内容/查询条件 |
| now | 当前服务器时间戳（单位：毫秒），时间戳可以进行额外运算，如doc.publish_date > now - 60000表示publish_date在最近一分钟 |
| action | 已废弃，使用数据库触发器替代action云函数 |
注意
auth 表示正在执行操作的用户对象auth.xxx 均由uni-id提供，依赖于uni-id公共模块doc.xxx 表示将要查询/修改/删除的每条数据（注意并不包括新增数据，新增数据应通过值域校验进行验证），如果将要访问的数据不满足permission规则将会拒绝执行uni-id 的角色和权限，也即auth.role和auth.permission是不一样的概念。注意阅读uni-id 角色权限- doc可以理解为将要访问的数据，因此create权限内不可使用doc变量。create时建议使用forceDefaultValue或自定义校验函数实现插入数据的值域校验。
权限规则内可以使用的运算符
| 运算符 | 说明 | 示例 | 示例解释(集合查询) |
|---|---|---|---|
| == | 等于 | auth.uid == 'abc' | 用户id为abc |
| != | 不等于 | auth.uid != null | 用户要处于登录状态 |
| > | 大于 | doc.age>10 | 目标数据的 age 属性大于 10 |
| >= | 大于等于 | doc.age>=10 | 目标数据的 age 属性大于等于 10 |
| < | 小于 | doc.age<10 | 目标数据的 age 属性小于 10 |
| <= | 小于等于 | doc.age<=10 | 目标数据的 age 属性小于等于 10 |
| in | 存在在数组中 | doc.status in ['a','b'] | 目标数据的 status 是['a','b']中的一个，数组中所有元素类型需一致 |
| ! | 非 | !(doc.status in ['a','b']) | 目标数据的 status 不是['a','b']中的任何一个，数组中所有元素类型需一致 |
| && | 与 | auth.uid == 'abc' && doc.age>10 | 用户id 为 abc 并且目标数据的 age 属性大于 10 |
| || | 或 | auth.uid == 'abc'||doc.age>10 | 用户Id为abc或者目标数据的 age 属性大于 10 |
我们继续使用user表举例，目前需求如下，前端用户如果登录，那么该用户可以修改自己的name字段。此时需要在schema中配置name字段的permission为
// user表的schema
{
"bsonType": "object",
"required": [],
"permission": {
"read": "doc.status==true", // 任何用户都可以读status字段的值为true的记录，其他记录不可读
"create": false, // 禁止新增数据记录（admin权限用户不受限）
"update": "'updateuser' in auth.permission", // 权限标记为updateuser的用户，和admin管理员，可以更新数据，其他人无权更新数据
"delete": false // 禁止删除数据（admin权限用户不受限）
},
"properties": {
"_id":{
},
"name":{
"bsonType": "string",
"title": "名称",
"permission": {
"read": true,
"write": "doc._id == auth.uid" // 允许登录的用户修改自己的name字段
}
},
"pwd": {
"bsonType": "string",
"title": "密码",
"permission": {
"read": false, // 禁止读取 pwd 字段的数据（admin权限用户不受限）
"write": false // 禁止写入 pwd 字段的数据（admin权限用户不受限）
}
},
"status": {
"bsonType": "bool",
"title": "用户状态",
"description": "true代表用户正常。false代表用户被禁用"
}
}
}
根据这个配置，如前端应用已经登录，且登录的用户发起修改自己的name的请求，则允许修改。其他修改数据请求则会被拒绝。
注意
要分清
在权限规则的变量中只有数据库中的数据doc，并没有前端提交的待入库数据data。所以如果要对待入库的数据data做校验，应该在字段值域validator中校验，而不是在权限permission中校验。
如果想获取和判断目标数据记录doc之外的其他数据，则需要使用get方法，见下一章节。
forceDefaultValue属于数据校验的范畴，在数据写入时生效，但是如果配置forceDefaultValue为
例如在news表新增一条记录，权限需求是“未登录用户不能创建新闻”，其实不需要在news表的create权限里写
permission和role的使用注意
在schema中使用uni-id的permission和role，首先需要在uniCloud admin中创建好权限，然后创建角色并给该角色分配权限，最后创建用户并授权角色。
这样用户登录后，uniCloud会自动分析它的permission和role，在schema里编写的关于permission和role的限制也可以一一对应上，进行有效管理。
admin中创建权限、角色和用户授权，另见文档
???????