界面与路由速查
本章提供 Agentbase 2.10.0 控制台(Console SPA)的全量浏览器路由字典、左侧边栏菜单结构、多级子页签 URL 映射以及侧栏可见性判定规则。无论是日常研发运维快速直达深层配置页、访问默认隐藏模块(如消息 Messaging 与智能体运维报表 Reports),还是在企业内部知识库与告警通知中嵌入精确的控制台跳转链接,均可以本章作为权威参考。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
功能概述
Agentbase 控制台前端单页应用(SPA)统一挂载在 /console 基路径之下,通过结构化的 URL 路径参数(如 {organization}、{region}、{project}、{database}、{kb})精确映射三级资源树与各级子页面。
在实际使用中,研发与运维人员常遇到两类导航需求:
快速直达深层子页面:例如收到线上告警后,直接拼接项目 ID 与 Trace ID 跳转到
/console/project-default-enterprise-ai-hub-210/observability/traces或函数执行路径查询页,省去层层点击。访问侧栏默认隐藏或受开关控制的入口:例如当前版本侧栏默认隐藏的 消息(Messaging) 模块(
/messaging)与 智能体运维报表(Observability Reports)(/observability/reports/overview),只能通过直达 URL 或快捷键命令中心进入。
| 路由空间层级 | URL 路径前缀 | 典型示例(生产样板实景) | 核心承载模块 |
|---|---|---|---|
| 公共与认证入口 | /console/*(无租户前缀) | /console/login · /console/mfa · /console/verify-email | 登录、注册、找回密码、邀请接受、MFA 二次核验、首次登录引导(Onboarding) |
| 开发者账号中心 | /console/account/* | /console/account/sessions · /console/account/project-cleanup | 个人资料、MFA 与恢复码、会话列表、账号 30 日用量、待删项目恢复、表模式转换记录 |
| 组织治理空间 | /console/organization-{organization}/* | /console/organization-69c6d1aa00062e6bb60/members | 组织项目列表、成员邀请与角色管理、30 日组织聚合用量、不活跃项目清理、组织级工作台 |
| 项目工作台(概览与设置) | /console/project-{region}-{project}/overview/* · .../settings/* | /console/project-default-enterprise-ai-hub-210/overview/api-keys | 平台登记(Platforms)、API Keys、Dev Keys、入门引导、30 日项目用量、项目设置 |
| 项目工作台(Build 应用后端) | /console/project-{region}-{project}/{service}/* | /console/project-default-enterprise-ai-hub-210/databases/database-enterprise_biz_db | Auth 认证、Databases 数据库、Storage 存储、Functions 函数、Sites 站点、Messaging 消息、Moderation 审核 |
| 项目工作台(AI 与 AgentOps) | /console/project-{region}-{project}/{ai-module}/* | /console/project-default-enterprise-ai-hub-210/knowledge-base/kb-kb_enterprise_support | 智能体工作台、上下文、记忆、知识库、词库、模型(LLM Gateway)、AI 网关、智能体运维(Observability) |
核心概念与架构
Agentbase 控制台路由采用“守卫拦截(Auth Guard) → 组织上下文注入 → 项目区域与服务能力判定 → 二级/三级页签渲染”的层次化路由架构。
流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。
路由路径变量与参数替换规范表
| 路径变量 | 含义与来源 | 生产样板替换示例 | 格式约束与注意事项 |
|---|---|---|---|
{organization} | 组织唯一 ID($id) | 69c6d1aa00062e6bb60 | 位于 /console/organization-{organization},切换顶部组织下拉框时自动更新。 |
{region} | 项目所属物理区域标识 | default(或具体可用区代号) | 创建项目时选定后不可更改,与 {project} 共同组成 /console/project-{region}-{project}。 |
{project} | 项目唯一 ID($id) | enterprise-ai-hub-210 | 数据面请求头 X-Appwrite-Project 所填写的值即为此处的 {project}。 |
{database} / {table} | 数据库 ID / 数据表 ID | enterprise_biz_db / customer_tickets | 嵌套于 /databases/database-{database}/table-{table}。 |
{bucket} / {file} | 存储桶 ID / 文件对象 ID | kb_enterprise_docs / file_arch_whitepaper | 嵌套于 /storage/bucket-{bucket}/file-{file}。 |
{kb} / {document} | 知识库 ID / 知识文档 ID | kb_enterprise_support / doc_sop_manual | 嵌套于 /knowledge-base/kb-{kb}/doc-{document}。 |
角色、入口与关联关系
1. 左侧边栏入口可见性判定规则
在项目控制台中,并非所有路由都会无条件显示在左侧边栏。一个导航项是否可见、进入页面后按钮是否可点,受以下四层规则共同约束:
| 控制维度 | 影响的具体导航入口 | 生效逻辑与解锁方式 |
|---|---|---|
| 1. 实例部署级开关(Capability) | Sites(站点)、记忆(Memory)、智能体工作台、智能体运维(Observability)、上下文(PowerContext) | 由平台基础设施环境变量(如 _APP_SITES_ENABLED)决定。若实例未部署某组件,侧栏隐藏或接口返回 412。 |
| 2. 项目级服务开关(Project Services) | AI 网关(/ai-gateway) 等项目可选能力 | AI 网关默认处于关闭状态;需具备 projects.write 权限的成员在项目 Settings → Overview → Services 中手动开启后,侧栏才显示入口。 |
| 3. 构建内置默认隐藏(支持 URL 直达) | Messaging(/messaging)、Observability Reports(/observability/reports/*) | 路由与功能本身保留,但侧边栏不展示图标。用户可通过浏览器地址栏直接输入完整路由或通过命令中心跳转。 |
| 4. 组织成员角色(RBAC) | 全部页面内的写操作按钮(Create / Update / Delete) | owner、admin、developer、editor 具备写权限;billing 与 analyst 角色虽能打开路由查看数据,但写操作按钮禁用或被服务端拦截。 |
2. 控制面路由与数据面 API 端点的区别
控制面浏览器路由(
/console/*):仅供人类开发者在浏览器中通过会话 Cookie 访问,返回 HTML/JS 界面视图。数据面与管理面 API 端点(
/v1/*):供应用程序 SDK、脚本或curl调用,返回结构化 JSON 或 SSE 事件流。其中公开探活端点GET /v1/health/version无需任何鉴权即可返回当前服务稳定版本(如{"version":"2.10.0"})。
功能详解与操作指南
以下按公共页与账号中心、组织治理级路由、项目 Build 应用后端路由与项目 AI 及 AgentOps 路由四个部分,提供完整的路径速查表。
1. 公共认证页与账号中心路由(/console/* & /console/account/*)
| 分类 | 精确浏览器路径 | 页面名称与核心功能说明 | 关联章节 |
|---|---|---|---|
| 公共认证与守卫 | / | 公开站点主机返回产品落地页;其他主机自动重定向至 /console | 注册与登录 |
/console/login · /console/register · /console/recover | 开发者登录(邮箱密码 / GitHub / 企业 SSO)、新账号注册、忘记密码邮件找回 | 注册与登录 | |
/console/invite · /console/register/invite/{slug} | 已注册账号接受组织邀请、新用户通过邀请专属链接注册并加入组织 | 注册与登录 | |
/console/mfa · /console/verify-email | 登录多因素认证质询页(验证器/邮箱/短信/恢复码)、强制邮箱验证拦截页 | 注册与登录 | |
/console/onboarding/create-organization · /console/onboarding/create-project | 首次注册登录后的组织创建向导与首个项目创建引导 | 快速开始 | |
/console/auth/magic-url · /console/auth/oauth2/success · /console/auth/oauth2/failure | 项目 Auth 终端用户 Magic URL 与 OAuth2 授权登录回调确认页 | 认证概览 | |
| 开发者账号中心 | /console/account | Overview:修改姓名、邮箱、密码、关联外部身份(Identities)、配置 MFA 与一次性恢复码、永久注销账号 | 组织与账号中心 |
/console/account/sessions · /console/account/activity | Sessions:查看当前登录设备/IP 并支持登出全部会话;Activity:账号级操作审计时间线 | 组织与账号中心 | |
/console/account/organizations | Organizations:查看所属组织列表、创建新组织(/console/create-organization)、管理自托管成员配额 | 组织与账号中心 | |
/console/account/rate-limits · /console/account/quota-limits | Rate / Quota limits:只读查看当前账号适用的平台请求速率限制与资源配额上限 | 限额与配额 | |
/console/account/usage · /console/account/metering | Usage / Metering:账号级最近 30 个 UTC 日四项核心计量聚合趋势与覆盖状态 | 限额与配额 | |
/console/account/project-cleanup | Project cleanup:查看待物理清理项目列表(Pending / Purging / Purge failed),支持在物理清理开始前点击 Restore 恢复误删项目 | 组织与账号中心 | |
/console/account/table-mode-conversions | Table mode conversions:追踪跨项目发起的共享表/独占表/Shared V2 表模式转换任务历史与状态 | 项目设置 |
2. 组织治理级路由(前缀 /console/organization-{organization})
| 组织页签名称 | 路径后缀 | 核心操作与治理说明 |
|---|---|---|
| Projects(项目列表) | /console/organization-{organization} | 展示组织下全部项目卡片(含区域标签),提供 Create project 入口 |
| Members(成员管理) | /members | 邀请新成员、查看 2FA 状态、按 ID/邮箱搜索、修改组织角色(Owner/Admin/Developer/Editor/Billing/Analyst)、移除成员 |
| Usage / Metering(组织用量) | /usage · /metering | 组织级最近 30 个 UTC 日聚合用量(自动过滤已处于删除态的项目,确保计量准确) |
| Project cleanup(不活跃项目清理) | /project-cleanup | 仅组织 Owner 可操作:按不活跃天数与新项目豁免天数检索(达标满 24 小时后列出),支持单次最多勾选 50 个项目提交清理 |
| Agent Workbench(组织级工作台) | /agent-runtime | 组织维度的智能体运行工作台入口 |
| Domains / Billing / Invoices | /domains · /billing · /invoices · /change-plan | 组织级自定义域名、云端账单、发票与套餐变更管理 |
| Settings(组织设置) | /settings | 修改组织名称、查看成员配额、执行不可逆的 Delete organization |
3. 项目控制台:概览、治理与 Build 应用后端路由(前缀 /console/project-{region}-{project})
| 侧边栏分组 | 模块名 | 路径后缀与子路由层次 | 功能覆盖说明 |
|---|---|---|---|
| 顶层概览 | Overview | /overview/platforms · /overview/api-keys · /overview/api-keys/{keyId} · /overview/dev-keys | 查看项目实时请求/存储吞吐;登记 15 类客户端 Platform;创建与轮换生产 API Key(12 类 Scope 折叠选择器)及开发 Dev Key |
| 旧入门引导路径 | /get-started | 重定向至 /overview/platforms,不再是独立引导页面 | |
| Build 应用后端 | Auth(认证) | /auth(Users 列表)· /auth/user-{user}(概览/memberships/sessions/targets/activity/identities)· /auth/teams · /auth/templates · /auth/usage · /auth/settings · /auth/security · /auth/test | 终端用户生命周期、通知目标(Targets)、团队与成员角色、邮件/短信模板、密码历史与个人数据校验安全策略、OAuth2 隔离测试页 |
| Databases(数据库) | /databases · /databases/usage · /databases/database-{database}(Tables / usage / settings / sql / schema-versions / backups)· .../table-{table}(rows / columns / indexes / activity / export / moderation / settings / usage) | 多数据库管理、表/列/行/索引 CRUD、在线 SQL 编辑器与 SQL Proxy、版本化 Schema 快照回滚、云端备份恢复、单表写路径文本审核 | |
| Storage(存储) | /storage · /storage/usage · /storage/bucket-{bucket}(Files / usage / settings / moderation / create / file-{file}) | 存储桶权限(Bucket 级 vs File Security)、文件分片上传、File Token 临时访问令牌、图片 fail-closed 内容审核 | |
| Functions(函数) | /functions · /functions/usage · /functions/create-function · /functions/templates · /functions/function-{function}(Deployments / executions / usage / domains / settings / deployment-{deployment}) | Git/模板/手动源码(.tar.gz)与 Java 17 预构建 JAR(artifactMode=java-jar) 部署、去重执行路径查询(支持 path/pathMatch/method 过滤)、ACS 容器组资源监控 | |
| Messaging(消息) | /messaging · /messaging/topics · /messaging/providers · /messaging/message-{message} · /messaging/create-{type} | 侧栏默认隐藏,通过直达 URL 访问:管理 FCM/APNS/SMTP/Twilio 等发送提供商、订阅主题(Topics)与立即/定时/草稿消息投递 | |
| Moderation(内容审核) | /moderation · /moderation/logs · /moderation/logs/{log} | 项目级与平台级阿里云 Green 内容安全凭据配置、30 日审核调用分项统计、支持按表/桶/结果过滤的审核日志详情 | |
| Sites(站点) | /sites · /sites/create-site · /sites/site-{site}(Overview / deployments / logs / domains / usage / settings) | 受 _APP_SITES_ENABLED 与邮箱白名单控制:托管 Next.js / SvelteKit 等站点、一键回滚(Instant rollback)与自定义域名 | |
| 底部治理 | Trace logs | /logs | 项目级底层链路与系统追踪日志检索 |
| Metering | /usage/aggregates · /usage | 项目级最近 30 个 UTC 日四项计量聚合趋势与数据完整性状态 | |
| Settings | /settings · /settings/domains · /settings/webhooks · /settings/migrations · /settings/smtp · /settings/usage | 列删除开关、项目表模式转换、客户端 Services 开关、Global variables 全局变量、自定义域名、Webhooks、自定义 SMTP 与数据迁移 |
4. 项目控制台:AI 原生能力与 AgentOps 路由(前缀 /console/project-{region}-{project})
| 侧栏可见名称 | 路径后缀与子路由层次 | 核心功能与 2.10.0 关键路由亮点 | 关联章节 |
|---|---|---|---|
| 智能体工作台(Agent Workbench) | /agent-runtime | 在线装配主对话模型(如 qwen-plus)、系统提示词、企业知识库、长期记忆/PowerContext、干预词库、AI Gateway 工具与 Skill 技能包,支持多轮 ReAct 流式对话调试与项目级配置持久化(/v1/agent-runtime/project/*) | 智能体工作台概览、模型与词库配置、会话与运行、知识库与记忆协同、工具网关与技能包 |
| 上下文(PowerContext) | /powercontext | 托管上下文初始化校验与可视化管理(服务端支持 /v1/projects/{projectId}/powercontext/compaction 显式预览/提交上下文压缩) | 记忆概览与启用 |
| 记忆(Memory) | /memory(涵盖概览、记忆列表与检索、用户画像 Profiles、经验与技能 Evolution、模型路由 Models、上下文 Contexts、Pipeline 配置 Configuration、审计 Audit、轨迹 Traces) | 基于 Shared V2 的长期记忆全生命周期管理:四类 Pipeline 草稿验证与发布、经验与技能候选版本 Diff 审批回滚、图片/PDF 异步记忆解析 | 记忆概览与启用、召回调优与 Pipeline 配置 |
| 知识库 | /knowledge-base · /knowledge-base/kb-{kb}(documents / search / wiki / graph / indexes / versions / datasources / settings / doc-{document}) | 富文档摄取、标签树与 documentTag/subProductId 过滤、混合检索测试、GraphRAG / RAPTOR / LLM Wiki 索引构建(带进度与中断控制)、版本封存发布与回滚 | 知识库概览与词库管理、Wiki、GraphRAG、RAPTOR 与索引治理 |
| 词库(Lexicons) | /knowledge-base/lexicons | 独立维护同义词词典(如 lex_enterprise_synonyms)与停用词词典(如 lex_support_stopwords),支持绑定至知识库与工作台 | 知识库概览与词库管理 |
| 模型(Models) | /llm-gateway · /llm-gateway/provider-{provider} · /llm-gateway/keys · /llm-gateway/keys/{key}/usage · /llm-gateway/usage | 管理 DashScope 等模型供应商预设、导入 Chat/Embedding/Rerank/Vision 模型目录、签发带月度预算与限流的 Gateway Key | LLM Gateway 模型管理 |
| AI 网关(AI Gateway) | /ai-gateway · /ai-gateway/gateways · /ai-gateway/models-routes · /ai-gateway/policies-credentials · /ai-gateway/tools-agents · /ai-gateway/traffic-quality | 统一 AI 网关治理面(需在项目 Settings → Services 中开启):管理网关实例、逻辑模型主备路由、安全护栏、语义缓存、MCP 工具注册与流量质量监控 | 统一 AI 网关 |
| 智能体运维(Observability / AgentOps) | /observability · /observability/traces · /observability/observations · /observability/sessions · /observability/users · /observability/scores · /observability/score-settings · /observability/prompts · /observability/metrics · /observability/evals · /observability/evaluation-skills · /observability/datasets · /observability/annotations · /observability/reports/overview · /observability/reports/agents · /observability/reports/quality | 侧栏分区名为 AgentOps:全链路 Trace/Observation 追踪、通用/Memory/解析/知识索引质量(GraphRAG/RAPTOR/Wiki)四类评估任务、内置评估模板目录、指标分析,以及侧栏隐藏但可直达访问的 Reports 三大看板 | 可观测性概览、评估、评分与索引质量评测 |
常见问题与排障
Q1:直接拼接 URL 访问某个项目子页面时返回 404 或自动跳回组织首页是什么原因?
原因与排查步骤:
检查
{region}与{project}参数:项目控制台路由严格要求格式为/console/project-{region}-{project}/...(例如/console/project-default-enterprise-ai-hub-210/overview)。若遗漏了project-default-前缀或项目 ID 拼写有误,路由守卫无法解析项目上下文。检查当前账号所属组织权限:若当前登录的开发者账号尚未被邀请加入该项目所属的组织(如
69c6d1aa00062e6bb60),服务端会拒绝加载项目元数据并重定向回账号默认组织页。
Q2:如何进入侧边栏默认不显示的“消息(Messaging)”与“智能体运维报表(Observability Reports)”页面?
原因与排查步骤: 这两项功能在当前版本中采取“保留完整前端路由与后端能力、仅隐藏侧栏导航项”的策略。只需在浏览器地址栏将项目路径后缀直接替换为:
消息模块:
/console/project-{region}-{project}/messaging(包含Messages、Topics、Providers三个页签)。智能体运维报表:
/console/project-{region}-{project}/observability/reports/overview(含Overview、Agents、Quality三个页签)。
Q3:为什么在侧栏能点进某个模块(如 Memory 或知识库高阶索引),但页面内操作返回 412?
原因与排查步骤: Console 浏览器路由存在仅代表前端 UI 组件已加载;当点击按钮发起后端 API 调用时,服务端会实时校验实例部署级 Capability 与项目前置条件。若项目表模式非 Shared V2(针对 Memory)或底层实例未启用可选索引 Worker(针对知识库高阶索引),后端即返回稳定的 HTTP 412。请对照常见问题中的 Capability 排障矩阵逐项核查。

