注册与登录
本章说明 Agentbase 2.10.0 控制台开发者账号(Console Account)的自助注册、受邀加入、多方式登录(邮箱密码 / GitHub / 企业 SSO)、邮箱验证守卫、多因素认证(MFA)二次核验、密码找回以及首次登录引导(Onboarding)的完整流程。
截图未公开:原图可能包含账号或资源标识。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
功能概述
在 Agentbase 中,存在两套完全独立的身份体系,首次使用的团队成员务必明确区分:
- 控制台开发者账号(Console Account,本章所述对象):面向企业的架构师、研发工程师、知识运营与运维管理员,通过
/console/login登录,用于创建与管理组织(Organization)、项目(Project)、API Key、数据库、知识库与智能体工作台。 - 项目终端用户账号(Project Auth User):面向企业业务应用(如“企业智能客服与知识中台”门户)的最终客户或坐席人员,归属于具体项目的 Auth 模块(见认证概览),通过客户端 SDK 登录业务前端,无法登录
/console/。
控制台注册与登录模块围绕企业安全合规要求设计,内置了未登录重定向记忆、强制邮箱验证守卫、多因子 MFA 质询(支持验证器 App、邮箱、短信与一次性恢复码)、防枚举密码找回以及受邀注册闭环。
| 核心功能流程 | 控制台路由入口 | 适用人群与触发场景 | 安全与状态保障机制 |
|---|---|---|---|
| 账号登录(Sign in) | /console/login | 已注册的研发、运营与运维人员日常进入 Console | 支持邮箱密码、GitHub OAuth、企业 SAML/SSO;登录成功后自动跳回原始请求的深层受保护 URL |
| 自助注册(Sign up) | /console/register | 新团队負責人或独立开发者首次开通账号 | 强制密码最少 8 位字符、必选隐私与服务条款确认,支持实例注册白名单策略管控 |
| 受邀注册与接受邀请 | /console/invite · /console/register/invite/{slug} | 收到组织 Owner/Admin 邮件邀请的团队协作成员 | 绑定邀请令牌与目标组织角色,完成后直接加入目标组织(如 Agentbase 企业智能中台) |
| MFA 二次身份核验 | /console/mfa | 已开启多因素认证的高权限账号完成主密码验证后 | 支持 Authenticator TOTP、邮箱验证码、短信验证码与一次性恢复码四种因子动态切换 |
| 强制邮箱验证守卫 | /console/verify-email | 实例开启强制邮箱验证且当前账号邮箱尚未验证时 | 拦截一切 Console 页面访问,直至完成邮件验证链接确认 |
| 密码恢复(Recover) | /console/recover | 忘记登录密码的开发者自助重置密码 | 两步邮件链接重置流;对任意输入邮箱返回完全一致的提示文案,防止账号枚举攻击 |
核心概念与架构
当开发者在浏览器中访问 Agentbase 控制台任意路径时,前端路由守卫与后端 /v1/account/* 会话服务协同执行一套严密的多阶段认证与引导状态机。
flowchart TB
Start["浏览器访问受保护页面<br/>例如 /console/project-default-enterprise-ai-hub-210/overview"] --> CheckSession{"是否存在有效<br/>Console Session?"}
CheckSession -- "否 (未登录或已过期)" --> RedirectLogin["跳转 /console/login<br/>携带原始目标地址 redirect 参数"]
RedirectLogin --> AuthMethod["选择认证方式:<br/>1. 邮箱 + 密码<br/>2. GitHub 登录 (云端)<br/>3. 企业 SSO / SAML"]
AuthMethod --> CheckMFA{"账号是否启用了 MFA?"}
CheckMFA -- "是" --> MFAPage["进入 /console/mfa 二次核验<br/>(验证器 App / 邮箱验证码 / 短信验证码 / 恢复码)"]
MFAPage -- "验证通过" --> CheckEmail
MFAPage -- "点击 Back" --> DestroySession["销毁当前临时会话并退回 /console/login"]
CheckMFA -- "否" --> CheckEmail
CheckSession -- "是" --> CheckEmail{"实例要求邮箱验证<br/>且当前账号未验证?"}
CheckEmail -- "是 (未验证)" --> VerifyPage["拦截并进入 /console/verify-email<br/>发送验证邮件并完成确认"]
VerifyPage --> CheckTarget
CheckEmail -- "否 (已验证或未强制)" --> CheckTarget{"是否存在原始<br/>redirect 目标地址?"}
CheckTarget -- "是" --> GoTarget["精准跳转回原始目标页面"]
CheckTarget -- "否" --> CheckOrg{"当前账号组织状态?"}
CheckOrg -- "无任何组织 (全新注册)" --> OnboardProj["/console/onboarding/create-project<br/>引导创建组织与首个项目 (默认 Agentbase Project)"]
CheckOrg -- "已完成引导但无可用组织" --> OnboardOrg["/console/onboarding/create-organization<br/>创建新组织 (默认 Personal Projects)"]
CheckOrg -- "已有组织 (如 69c6d1aa00062e6bb60)" --> GoOrg["进入偏好组织首页或 /console/account/organizations"]登录方式与部署环境对照表
| 登录认证方式 | 界面入口标识 | 部署生效条件 | 适用场景与凭据管理说明 |
|---|---|---|---|
| 邮箱 + 密码(Email & Password) | 登录表单主区域(Email / Password 输入框 + Sign in 按钮) | 全环境默认启用 | 基础认证方式;密码修改与找回在 /console/account 或 /console/recover 完成。 |
| GitHub 账号登录 | Sign in with GitHub / Sign up with GitHub | 云端部署或配置了 GitHub OAuth 的实例显示 | 授权后自动关联外部身份(可在 Account → Overview → Identities 中查看或解绑)。 |
| 企业单点登录(SSO / SAML) | 企业单点登录 / SAML 登录按钮 | 实例级环境变量启用企业 SSO 开关时自动展示 | 对接企业内部 IdP(身份提供商),实现员工工号一键免密登录与离职自动收回访问权。 |
| 界面多语言切换 | 登录页右上角语言选择器 | 全环境内置 | 支持在登录前即时切换控制台界面展示语言(如简体中文 / English)。 |
角色、入口与关联关系
1. 注册、受邀与组织角色的衔接关系
新开发者进入 Agentbase 主要有两条路径,不同路径决定了其初始所在的组织与权限范围:
| 进入路径 | 触发入口 | 初始组织归属 | 初始组织角色 | 后续可执行操作 |
|---|---|---|---|---|
| 路径 A:自助注册 | /console/register | 系统引导自动创建个人默认组织(如 Personal Projects) | Owner(组织所有者) | 拥有该组织的最高权限,可创建任意项目(如 enterprise-ai-hub-210)、邀请其他成员并配置全部服务。 |
| 路径 B:受邀加入现有企业组织 | 邮件中的邀请链接(/console/invite 或 /console/register/invite/{slug}) | 直接加入邀请方所在的企业组织(如 Agentbase 企业智能中台 69c6d1aa00062e6bb60) | 由邀请人指定的角色(Admin / Developer / Editor / Billing / Analyst) | 立即按被授予的角色访问该组织下的现有项目;成员邀请状态由 Pending 变为已激活。 |
2. 与项目 Auth OAuth2 测试会话的隔离边界
在项目内开发终端用户登录功能时(见认证概览的 /auth/test 页面),开发者经常需要测试项目的 OAuth2 登录流程。Agentbase 对项目 OAuth 测试会话与开发者自身的 Console 登录会话做了严格的物理隔离:在测试页面登录或退出项目测试用户,绝不会覆盖或登出你当前的 Console 开发者账号。
功能详解与操作指南
1. 开发者账号登录与 MFA 二次验证操作步骤
- 打开登录页:
- 在浏览器访问
https://appbuild.oceanbase.com/console/login(如图 1 所示)。若需要切换界面语言,可先点击页面右上角的语言下拉菜单。
- 在浏览器访问
- 提交主认证凭据:
- 邮箱密码登录:在
Email字段输入已注册的企业邮箱,在Password字段输入密码,点击 Sign in。 - 企业 SSO / GitHub 登录:若当前部署已启用企业单点登录或 GitHub 登录,直接点击下方对应的 SSO 按钮并按企业 IdP 指引完成授权跳转。
- 邮箱密码登录:在
- 完成 MFA 二次身份核验(针对已开启 MFA 的账号):
- 主密码验证通过后,页面自动跳转至
/console/mfa质询页。 - 系统默认优先展示已绑定的主认证因子(如 Authenticator app),请打开手机验证器 App(如 Google Authenticator、Microsoft Authenticator 或 1Password),输入当前 6 位动态数字验证码并提交。
- 切换备用验证因子:若手机不在身边,可点击质询页的切换选项,改用 Email 邮箱一次性验证码、SMS 短信验证码 或 Recovery code(一次性恢复码) 完成验证。
- 注意:在
/console/mfa页面若点击 Back(返回),系统出于安全保护会立即销毁当前半认证态会话并退回/console/login。
- 主密码验证通过后,页面自动跳转至
- 登录后路由分发:
- 若登录前是从某个具体项目链接(如
/console/project-default-enterprise-ai-hub-210/knowledge-base)被拦截跳转而来,验证通过后将直接回到该知识库页面。 - 若直接访问
/console/login登录,则自动进入上次访问的偏好组织页面;若无偏好记录,则进入组织与账号中心的组织列表页。
- 若登录前是从某个具体项目链接(如
2. 新账号自助注册与受邀注册流程
方式一:自助注册(/console/register)
- 在登录页底部点击 Sign up(或直接访问
/console/register)。 - 按表单要求填写:
| 表单字段 | 是否必填 | 校验约束与填写说明 |
|---|---|---|
| Name(姓名) | 必填 | 开发者在组织成员列表与操作审计日志中显示的姓名(如 张工 - AI架构师)。 |
| Email(邮箱) | 必填 | 用于登录、接收系统告警、密码找回与组织邀请的有效邮箱地址。 |
| Password(密码) | 必填 | 长度至少 8 个字符;建议使用大小写字母、数字与特殊符号的高强度组合。 |
| 条款勾选框 | 必选 | 必须勾选同意隐私政策(Privacy Policy)与使用条款(Terms of Use)后方可提交。 |
- 点击 Sign up 提交。若当前私有化实例配置了注册邮箱域名白名单或关闭了开放注册,非白名单邮箱会收到明确提示,此时请联系组织管理员通过下方的“受邀注册”方式加入。
方式二:通过团队邮件邀请加入(/console/invite)
- 当组织
Owner或Admin在 Organization → Members 页面向你的邮箱发送邀请后,查收邀请邮件并点击邮件内的专属接受链接。 - 已有账号的开发者:进入
/console/invite确认页,核对组织名称与分配的角色后点击接受,即刻加入目标组织。 - 尚无账号的新成员:进入
/console/register/invite/{slug}专属注册页,设置姓名与至少 8 位的登录密码后提交,系统会自动完成账号创建、登录并绑定至目标组织。
3. 首次登录引导(Onboarding)与邮箱验证
新账号完成注册并首次进入 Console 时,系统会根据当前账号的组织归属状态自动触发引导向导:
| 账号当前状态 | 触发的引导路由 | 引导页默认行为与操作说明 |
|---|---|---|
| 状态 A:名下无任何组织(全新自助注册) | /console/onboarding/create-project | 系统在后台自动准备默认组织容器,并在界面引导直接创建第一个项目(默认项目名为 Agentbase Project,可修改为 企业智能客服与知识中台,并选择物理区域 Region);提交后直接进入新项目控制台。 |
| 状态 B:已完成早期引导但当前无可用组织 | /console/onboarding/create-organization | 先进入创建组织向导(默认组织名为 Personal Projects,可自定义名称),创建组织后再引导创建项目。 |
| 状态 C:实例开启强制邮箱验证且账号未验证 | /console/verify-email | 访问任何 Console 页面均会被强制路由至 /console/verify-email;请点击重发验证邮件并点击邮箱中的确认链接,验证通过后自动解锁全部控制台功能。 |
4. 忘记密码与安全找回(/console/recover)
- 在
/console/login登录表单下方点击 Forgot password?,进入/console/recover密码恢复页。 - 输入你的账号注册邮箱并点击提交:
- 防账号枚举保护:无论输入的邮箱是否已在系统中注册,界面均返回完全一致的成功提示文案,攻击者无法通过找回密码接口探测企业邮箱是否存在。
- 打开邮箱查收密码重置邮件(依赖实例已正确配置系统 SMTP 服务),点击邮件中的时效性恢复链接回到
/console/recover重置表单,输入两次新密码(不少于 8 位)完成更新。
常见问题与排障
Q1:输入正确的账号密码点击 Sign in 后,没有任何密码错误提示,却又瞬间跳回了 /console/login?
原因与排查步骤: 这通常是由于浏览器未能成功保存或回传会话 Cookie 所致,请按以下顺序排查:
- 检查访问协议与反向代理配置:在生产或预发环境,会话 Cookie 默认带有
Secure属性,必须通过https://访问;若前置了 Nginx / SLB 反向代理,请确认代理已正确透传X-Forwarded-Proto: https请求头且访问域名与实例配置的_APP_DOMAIN一致。 - 检查浏览器隐私拦截与时钟偏移:确认浏览器未全局禁用 Cookie,且客户端系统时间准确(偏差过大可能导致短期凭据立即判定过期)。
- 检查速率限制(Ratelimit):若同一 IP 短时间内连续多次尝试登录失败,可能触发平台登录防爆破限流(HTTP
429),请等待限流窗口恢复后再试。
Q2:为什么同事的控制台登录页有“企业单点登录(SSO / SAML)”或“GitHub 登录”按钮,而我的环境登录页只有邮箱密码框?
原因与排查步骤: 登录页展示的第三方认证按钮完全由当前目标部署实例的环境变量开关动态驱动。GitHub 登录通常在云端公共部署中开启;企业 SAML / SSO 单点登录则需要平台管理员在实例部署配置中填入企业 IdP 元数据并开启对应 SSO 开关后才会在 /console/login 渲染显示。
Q3:收不到邮箱验证邮件、组织邀请邮件或密码找回邮件怎么办?
原因与排查步骤:
- 首先检查企业邮箱的“垃圾邮件(Spam)”或“隔离区”,将平台发件地址加入白名单。
- 注意区分平台级 SMTP 与项目级自定义 SMTP:Console 开发者账号的注册验证、密码恢复与组织成员邀请使用的是实例平台级 SMTP 配置(而非某个具体项目
Settings → SMTP下供终端 Auth 用户使用的 SMTP)。若全员均收不到平台邮件,请联系平台运维管理员检查实例的_APP_SMTP_*环境变量与邮件网关连通性。