登录体验配置

登录体验（Sign-in Experience）是 Code Bird Cloud 中控制用户登录和注册界面的核心配置。通过登录体验配置，管理员可以自定义登录页面的品牌外观、登录方式、注册策略、密码强度要求和法律条款，无需编写任何代码。

概述

整个系统只有一份登录体验配置，所有接入 Code Bird Cloud 的应用共享同一套登录和注册体验。配置的变更会立即反映在登录页面上。

登录体验配置包含以下模块：

• 品牌设置 -- 登录页面的视觉外观
• 登录方式 -- 用户可以使用哪些方式登录
• 注册设置 -- 用户注册流程的策略
• 密码策略 -- 密码强度要求
• 法律条款 -- 服务条款和隐私政策

品牌设置

品牌设置用于自定义登录页面的视觉元素，使其与你的产品品牌保持一致。

字段	说明
Logo URL	浅色模式下登录页面 Logo 图片的 URL（最多 500 字符）
深色模式 Logo URL	深色模式下的 Logo URL，未设置时使用浅色 Logo
Favicon	浏览器标签页图标 URL
主色调	登录页面的主题颜色，十六进制格式（如 #1890ff）
深色模式主色调	深色模式下的主题颜色（如 #177ddc）

主色调会应用于登录按钮、链接文字、输入框聚焦状态等关键 UI 元素。

配置示例

{
  "branding": {
    "logo_url": "https://example.com/logo.png",
    "dark_logo_url": "https://example.com/logo-dark.png",
    "favicon": "https://example.com/favicon.ico",
    "primary_color": "#4F46E5",
    "dark_primary_color": "#6366F1"
  }
}

登录方式

登录方式配置决定了用户在登录页面上可以使用哪些认证方式。支持同时配置多种登录方式。

配置项

每种登录方式包含以下设置：

字段	说明
标识符 (identifier)	用户使用的凭证类型
密码登录 (password)	是否启用密码方式登录
验证码登录 (verification_code)	是否启用验证码方式登录

可选标识符

标识符	值	说明
用户名	username	使用用户名作为登录标识。仅支持密码登录
邮箱	email	使用邮箱地址作为登录标识。支持密码和验证码登录
手机号	phone	使用手机号码作为登录标识。支持密码和验证码登录

常见登录方式组合

组合	标识符	密码	验证码	说明
用户名密码登录	username	是	否	最基础的登录方式
邮箱密码登录	email	是	否	适用于不需要验证码的场景
邮箱验证码登录	email	否	是	免密码登录，需配置邮件连接器
邮箱密码 + 验证码	email	是	是	同时支持两种方式，用户可选择
手机验证码登录	phone	否	是	免密码登录，需配置短信连接器

使用验证码登录需要先在连接器模块中配置并启用对应的邮件或短信连接器。

配置示例

{
  "sign_in": {
    "methods": [
      {
        "identifier": "username",
        "password": true,
        "verification_code": false
      },
      {
        "identifier": "email",
        "password": true,
        "verification_code": true
      },
      {
        "identifier": "phone",
        "password": false,
        "verification_code": true
      }
    ]
  }
}

注册设置

注册设置控制用户注册流程的策略，包括需要提供的信息和验证要求。

字段	说明
注册标识符 (identifiers)	注册时需要提供的标识符（支持多选：username、email、phone）
需要密码 (password)	注册时是否必须设置密码
需要验证 (verify)	注册时是否需要验证邮箱或手机号

注册标识符

注册标识符决定了用户注册时需要提供哪些身份信息，可以同时选择多个：

• 用户名：用户必须设置一个唯一的用户名
• 邮箱：用户必须提供邮箱地址
• 手机号：用户必须提供手机号码

注册验证

当启用 "需要验证" 后，系统会在注册流程中向用户发送验证码（通过邮件或短信），用户需输入正确的验证码才能完成注册。

使用验证功能需要先配置对应的邮件连接器或短信连接器。

配置示例

{
  "sign_up": {
    "identifiers": ["username", "email"],
    "password": true,
    "verify": true
  }
}

密码策略

密码策略配置平台的密码强度要求，应用于用户注册、修改密码和管理员重置密码等场景。

字段	说明	默认值
最小长度 (min_length)	密码的最少字符数（范围 6~32）	8
要求大写字母 (require_uppercase)	密码是否必须包含大写字母	否
要求小写字母 (require_lowercase)	密码是否必须包含小写字母	是
要求数字 (require_numbers)	密码是否必须包含数字	是
要求特殊字符 (require_special_chars)	密码是否必须包含特殊字符	否

密码策略会在以下场景中强制执行：

• 用户注册时设置密码
• 用户修改密码
• 用户通过忘记密码流程重置密码
• 管理员重置用户密码

配置示例

{
  "password_policy": {
    "min_length": 8,
    "require_lowercase": true,
    "require_uppercase": true,
    "require_numbers": true,
    "require_special_chars": false
  }
}

法律条款

配置登录和注册页面底部展示的法律条款链接。

字段	说明
使用条款 URL (terms_of_use_url)	服务条款页面的链接地址
隐私政策 URL (privacy_policy_url)	隐私政策页面的链接地址

配置后，登录和注册页面底部会展示指向这些页面的链接，用户可以点击查看。

配置示例

{
  "terms_of_use_url": "https://example.com/terms",
  "privacy_policy_url": "https://example.com/privacy"
}

API 参考

获取登录体验配置

GET /api/v1/sign-in-experience

返回当前完整的登录体验配置，包括品牌设置、登录方式、注册设置、密码策略和法律条款。

更新登录体验配置

PATCH /api/v1/sign-in-experience

更新登录体验配置。仅需传入要修改的字段，未传入的字段保持不变。

完整请求示例：

{
  "branding": {
    "logo_url": "https://example.com/logo.png",
    "primary_color": "#1890ff"
  },
  "sign_in": {
    "methods": [
      {
        "identifier": "username",
        "password": true,
        "verification_code": false
      },
      {
        "identifier": "email",
        "password": true,
        "verification_code": true
      }
    ]
  },
  "sign_up": {
    "identifiers": ["username", "email"],
    "password": true,
    "verify": true
  },
  "password_policy": {
    "min_length": 8,
    "require_uppercase": true,
    "require_lowercase": true,
    "require_numbers": true,
    "require_special_chars": false
  },
  "terms_of_use_url": "https://example.com/terms",
  "privacy_policy_url": "https://example.com/privacy"
}

更多 API 细节请参阅登录体验 API 参考。

最佳实践

1. 先配置连接器：如果需要验证码登录或注册验证，请先在连接器模块中配置好邮件或短信连接器，再在登录体验中启用对应的方式
2. 密码策略适度：过于严格的密码策略可能影响用户体验，建议根据业务安全需求合理设置。对于面向大众用户的应用，建议要求最小 8 位、包含字母和数字即可
3. 测试登录流程：每次修改登录体验配置后，建议打开登录页面实际测试一次完整的登录和注册流程，确保配置符合预期
4. 品牌一致性：Logo 和主色调应与你的产品品牌保持一致，提供统一的用户体验
5. 法律合规：建议配置服务条款和隐私政策链接，满足法律合规要求

相关文档

• 自定义配置概述 -- 所有自定义配置能力
• 连接器 -- 邮件、短信和社交登录连接器配置
• 终端用户流程 -- 配置对用户登录和注册流程的影响
• 登录体验 API 参考 -- 完整的 API 文档
• 管理后台 - 登录体验 -- 管理后台操作指南