用户数据结构
本文档详细说明 Code Bird Cloud 用户模型的每个字段定义、类型约束和使用说明。
字段总览
| 字段 | 类型 | 必填 | 唯一 | 说明 |
|---|---|---|---|---|
| id | string(21) | 是 | 是 | 用户唯一标识 |
| tenant_id | string(21) | 是 | 否 | 所属租户 ID |
| username | string(128) | 否 | 是 | 用户名 |
| primary_email | string(256) | 否 | 是 | 主邮箱 |
| primary_phone | string(32) | 否 | 是 | 主手机号 |
| name | string(256) | 否 | 否 | 显示名称 |
| avatar | string(512) | 否 | 否 | 头像 URL |
| gender | string(16) | 否 | 否 | 性别 |
| custom_data | JSON | 是 | 否 | 自定义元数据 |
| profile | JSON | 是 | 否 | 用户画像数据 |
| is_suspended | boolean | 是 | 否 | 是否已停用 |
| password_encrypted | string(256) | 否 | 否 | 加密后的密码 |
| password_algorithm | string(16) | 否 | 否 | 密码加密算法 |
| last_sign_in_at | datetime | 否 | 否 | 最后登录时间 |
| last_sign_in_ip | string(64) | 否 | 否 | 最后登录 IP |
| sign_in_count | integer | 是 | 否 | 累计登录次数 |
| created_at | datetime | 是 | 否 | 创建时间 |
| updated_at | datetime | 是 | 否 | 更新时间 |
字段详解
id
- 类型：
string，固定 21 位字符 - 生成方式：系统自动生成 nanoid
- 说明：用户的全局唯一标识符。创建后不可修改。nanoid 相比 UUID 更短且 URL 安全，同时保证足够的唯一性。
tenant_id
- 类型：
string，最长 21 位字符 - 默认值：
"default" - 说明：多租户隔离字段。所有用户数据查询都会基于 tenant_id 进行过滤，确保不同租户之间的数据完全隔离。在单租户部署模式下，所有用户共享默认租户。
username
- 类型：
string，最长 128 字符，可为空 - 唯一约束：是（在整个系统范围内唯一）
- 说明：用户的登录用户名。创建用户时可选填，一旦设置则在系统中唯一。可用于用户名 + 密码登录方式。
primary_email
- 类型：
string，最长 256 字符，可为空 - 唯一约束：是
- 说明：用户的主邮箱地址。用于邮箱登录和通知邮件发送。建议在用户注册流程中进行邮箱验证。
primary_phone
- 类型：
string，最长 32 字符，可为空 - 唯一约束：是
- 说明：用户的主手机号。用于短信验证码登录（需配置 SMS 连接器）。建议使用国际格式存储（如
+8613800138000）。
name
- 类型：
string，最长 256 字符，可为空 - 说明：用户的显示名称，用于 UI 展示。不要求唯一，可以是真实姓名或昵称。
avatar
- 类型：
string，最长 512 字符，可为空 - 说明：用户头像的 URL 地址。建议使用 HTTPS 链接，支持外部图片 URL 或平台内部的媒体资源地址。
gender
- 类型：
string，最长 16 字符 - 默认值：
"unknown" - 可选值：
unknown- 未知（默认）male- 男female- 女
- 说明：用户性别信息，遵循 OIDC 标准声明中的性别定义。
custom_data
- 类型：
JSON - 默认值：
{} - 说明：自定义元数据字段，允许存储任意 JSON 结构的业务数据。典型用途包括：
- 用户偏好设置
- 业务扩展属性
- 第三方系统关联 ID
json
{
"preferred_language": "zh-CN",
"timezone": "Asia/Shanghai",
"external_crm_id": "CRM-12345"
}profile
- 类型：
JSON - 默认值：
{} - 说明：用户画像数据，用于存储符合 OIDC 标准的用户详细资料。典型字段包括：
json
{
"given_name": "三",
"family_name": "张",
"nickname": "小张",
"website": "https://example.com",
"birthdate": "1990-01-01",
"address": {
"country": "CN",
"region": "Beijing"
}
}is_suspended
- 类型：
boolean - 默认值：
false - 说明：用户停用状态标识。设为
true后，用户将无法通过任何方式登录系统。用户数据和关联关系（角色、组织成员身份等）保持不变，管理员可随时恢复。
password_encrypted
- 类型：
string，最长 256 字符，可为空 - 说明：使用 bcrypt 算法加密后的密码哈希值。此字段永远不会通过 API 返回（JSON 标签为
"-"），仅在系统内部用于密码验证。
password_algorithm
- 类型：
string，最长 16 字符 - 默认值：
"bcrypt" - 说明：密码加密算法标识。当前默认且推荐使用 bcrypt 算法，具备自适应计算成本，可有效抵御暴力破解和彩虹表攻击。
last_sign_in_at
- 类型：
datetime，可为空 - 说明：用户最后一次成功登录的时间戳。首次创建用户时为空，用户首次登录后自动记录。采用 UTC 时区存储。
last_sign_in_ip
- 类型：
string，最长 64 字符，可为空 - 说明：用户最后一次登录的客户端 IP 地址。支持 IPv4 和 IPv6 格式。可用于安全审计和异常登录检测。
sign_in_count
- 类型：
integer - 默认值：
0 - 说明：用户累计成功登录的次数。每次用户通过认证流程成功登录时自动递增。可用于用户活跃度分析。
created_at
- 类型：
datetime - 说明：用户记录的创建时间，由系统自动填充，不可修改。采用 UTC 时区存储。
updated_at
- 类型：
datetime - 说明：用户记录的最后更新时间，每次修改用户信息时自动更新。采用 UTC 时区存储。
关联关系
角色关联
用户与角色通过 user_role_relations 中间表建立多对多关系：
- 一个用户可以拥有多个角色
- 一个角色可以分配给多个用户
- 通过
PUT /api/v1/users/:id/roles接口管理用户的角色分配
组织关联
用户与组织通过 organization_users 中间表建立多对多关系：
- 一个用户可以加入多个组织
- 用户在不同组织中可以拥有不同的组织角色
- 通过
GET /api/v1/users/:id/organizations查看用户所属的组织列表
API 响应示例
用户列表和详情接口返回的数据格式（注意：密码相关字段不会返回）：
json
{
"id": "abc123def456ghi789012",
"username": "zhangsan",
"primary_email": "zhangsan@example.com",
"primary_phone": "+8613800138000",
"name": "张三",
"avatar": "https://cdn.example.com/avatars/zhangsan.png",
"gender": "male",
"is_suspended": false,
"last_sign_in_at": "2026-02-10T08:30:00Z",
"sign_in_count": 42,
"created_at": "2026-01-01T00:00:00Z"
}