AgentbaseDocs
文档目录

注册与登录

本章说明 Agentbase 2.10.0 控制台开发者账号(Console Account)的自助注册、受邀加入、多方式登录(邮箱密码 / GitHub / 企业 SSO)、邮箱验证守卫、多因素认证(MFA)二次核验、密码找回以及首次登录引导(Onboarding)的完整流程。

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

功能概述

在 Agentbase 中,存在两套完全独立的身份体系,首次使用的团队成员务必明确区分:

控制台注册与登录模块围绕企业安全合规要求设计,内置了未登录重定向记忆、强制邮箱验证守卫、多因子 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 二次验证操作步骤

2. 新账号自助注册与受邀注册流程

方式一:自助注册(/console/register)

表单字段是否必填校验约束与填写说明
Name(姓名)必填开发者在组织成员列表与操作审计日志中显示的姓名(如 张工 - AI架构师)。
Email(邮箱)必填用于登录、接收系统告警、密码找回与组织邀请的有效邮箱地址。
Password(密码)必填长度至少 8 个字符;建议使用大小写字母、数字与特殊符号的高强度组合。
条款勾选框必选必须勾选同意隐私政策(Privacy Policy)与使用条款(Terms of Use)后方可提交。

方式二:通过团队邮件邀请加入(/console/invite)

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)

常见问题与排障

Q1:输入正确的账号密码点击 Sign in 后,没有任何密码错误提示,却又瞬间跳回了 /console/login?

原因与排查步骤: 这通常是由于浏览器未能成功保存或回传会话 Cookie 所致,请按以下顺序排查:

Q2:为什么同事的控制台登录页有“企业单点登录(SSO / SAML)”或“GitHub 登录”按钮,而我的环境登录页只有邮箱密码框?

原因与排查步骤: 登录页展示的第三方认证按钮完全由当前目标部署实例的环境变量开关动态驱动。GitHub 登录通常在云端公共部署中开启;企业 SAML / SSO 单点登录则需要平台管理员在实例部署配置中填入企业 IdP 元数据并开启对应 SSO 开关后才会在 /console/login 渲染显示。

Q3:收不到邮箱验证邮件、组织邀请邮件或密码找回邮件怎么办?

原因与排查步骤:

相关文档