AgentbaseDocs
文档目录

项目设置

项目设置(Settings)位于项目控制台左侧边栏底部(路由前缀 /console/project-{region}-{project}/settings),集中承载项目级的全局治理与高权限基础设施配置:包括数据库列删除开关(Column deletion)、项目表存储模式转换(共享表 / 独占表 / Shared V2)、客户端服务可达性开关(Services)、Git VCS 连接、项目级全局环境变量(Global variables)、自定义 API 域名(Custom domains)、事件推送钩子(Webhooks)、自定义邮件通道(SMTP)、跨平台数据迁移(Migrations)以及项目跨组织转移与永久销毁。

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

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

功能概述

在企业生产项目(如 企业智能客服与知识中台,ID:enterprise-ai-hub-210)的全生命周期中,项目设置模块为架构师与运维负责人提供六大治理能力:

设置子页签名称控制台路由后缀核心治理对象所需最小权限 / 角色边界
Overview(概览设置)/settings列删除开关、名称与标签、项目表模式、客户端 Services 开关、Git 连接、Global variables、转移组织、删除项目常规项需 projects.write(owner/admin/developer/editor);**Column deletion 仅限组织 owner 与平台管理员**
Custom domains(自定义域名)/settings/domains绑定项目级自定义 API 域名、DNS CNAME 校验与 SSL 证书生成重试projects.write / 域名管理权限
Webhooks(事件钩子)/settings/webhooks创建事件监听器、勾选触发事件、配置 SSL/TLS 校验与签名密钥projects.write / Webhooks 写权限
Migrations(数据迁移)/settings/migrations跨源数据导入与项目数据导出向导projects.write
SMTP(自定义邮件服)/settings/smtp启用并配置企业自有 SMTP 发信服务器(TLS/SSL、端口、账号密码)projects.write(云端部署受付费计划约束)
Usage(设置页用量)/settings/usage云端部署下的项目资源账单用量汇总视图任意项目成员可读

核心概念与架构

项目设置中的各项配置直接作用于数据面网关、底层 OceanBase 存储引擎、云函数/站点运行时沙箱以及异步事件分发器。下图展示了 Settings 各子模块在系统架构中的控制流向:

flowchart TB
    subgraph SettingsOverview["Settings -> Overview 全局治理面"]
        ColDel["Column deletion 列删除开关<br/>(仅组织 Owner / 平台管理员可改)"]
        TblMode["项目表模式转换<br/>共享表 <-> 独占表 / Shared V2<br/>(深度独占表不可转 / 含 relationship 集合时阻断)"]
        Services["Services 客户端可达性开关<br/>开启 AI Gateway / 关闭仅拦截 Client SDK, 不删数据"]
        GlobalVars["Global variables 全局变量 (.env 导入 / Secret 掩码)<br/>自动注入全部 Functions 与 Sites 运行时"]
    end

    subgraph SettingsSubtabs["Settings 专项集成子页签"]
        Domains["Custom domains 自定义域名<br/>DNS 校验 -> 自动签发 SSL 证书"]
        Webhooks["Webhooks 事件分发<br/>事件匹配 + SSL 证书校验 + HMAC 签名密钥"]
        SMTP["Custom SMTP 自定义邮件通道<br/>接管 Auth 验证 / 密码找回 / 邀请邮件"]
        Migrations["Migrations 数据导入导出向导"]
    end

    subgraph RuntimeTargets["受控的目标系统组件"]
        OBEngine["OceanBase 数据库与 Schema 版本引擎"]
        DataPlaneGate["客户端 API 网关与侧栏导航"]
        ComputeSandbox["Functions 云函数 & Sites 站点容器"]
        ExtSystems["企业外部 Webhook 接收端 & 企业邮件网关"]
    end

    ColDel --> OBEngine
    TblMode --> OBEngine
    Services --> DataPlaneGate
    Domains --> DataPlaneGate
    GlobalVars --> ComputeSandbox
    Webhooks --> ExtSystems
    SMTP --> ExtSystems

项目表模式(Table Mode)选型与转换规则矩阵

在 Settings → Overview 的 项目表模式 卡片中,系统明确定义了不同表存储模式的承载特性与转换边界:

表模式类型承载机制说明是否支持在线转换转换前置约束与 AI 能力关联
共享表(Shared Tables)多个集合/表共享底层物理承载结构,适合轻量级原型项目支持转换为独占表或 Shared V2若项目内存在包含 relationship(关联关系)类型的集合,系统会主动阻止转换并明确提示需先处理关联集合。
**独占表 / Shared V2(企业级标准)**高性能表隔离与 OceanBase Shared V2 架构(如 enterprise-ai-hub-210)支持与共享表互转**AI Memory 长期记忆服务强制要求项目运行于 Shared V2 模式**;转换前需选择目标类型与 tag(底层目标集群按创建项目规则自动轮询分配)。
深度独占表(Deep Dedicated)极端高吞吐单表物理深度隔离模式不支持转换(不可转为其他模式,其他模式也不可转入)仅用于创建时即确定无需变更模式的特殊专有负载。

角色、入口与关联关系

1.Overview 页签八大治理卡片权限与风险等级对照

进入 /console/project-default-enterprise-ai-hub-210/settings(如图 1 所示),页面自上而下排列八张核心治理卡片。不同卡片的权限门槛与操作影响如下:

卡片名称操作权限要求生效范围风险等级与不可逆边界说明
Column deletion(列删除)**仅限项目所属组织 Owner 与平台管理员**数据库 Schema 版本管理高风险:开启后允许通过 Schema 版本删除数据表物理列,删除列将永久抹除该列全部历史数据。
Name / Labels(名称与标签)projects.writeConsole 展示与项目分类筛选低风险:更新项目显示名称;项目标签(Labels)仅允许使用字母与数字字符(Alphanumeric)。
项目表模式(Table mode)projects.write项目底层 OceanBase 存储结构中高风险(重负载操作):转换进行中卡片显示实时进度,期间严禁叠加执行其他表结构变更;历史记录在 Account → Table mode conversions 查看。
Services(客户端服务开关)projects.write客户端 SDK(Web / 移动端)API 可达性与侧栏入口中风险:关闭服务仅拦截客户端直接访问,服务端 API Key 访问不受影响,且绝不删除已有数据。支持 Enable all / Disable all(需二次确认)。
Git(代码仓库安装)projects.writeFunctions 与 Sites 的 Git 构建源低风险:连接或更新 GitHub App 安装授权;安装或更新连接本身不会自动触发线上重部署。
Global variables(全局变量)projects.write自动注入项目内全部 Functions 与 Sites中风险:支持标记为 Secret(保存后单向掩码不回显);若与函数级同名变量冲突,在函数变量页会明确标出。
Change organization(更换组织)组织 Owner项目所属的顶层组织容器中风险:将当前项目整体迁移到当前账号名下拥有的另一个组织中。
Delete project(删除项目)组织 Owner / 高权限写角色整个项目及其下属全部资源极高风险(不可逆):永久销毁项目元数据、数据库、存储桶、知识库、记忆与统计数据,必须手动输入完整项目名称确认。

2. Services 客户端服务开关全量清单

在 Services 卡片中,可逐项控制以下服务面向客户端的开关状态:

功能详解与操作指南

1. 管理项目级全局环境变量(Global Variables)

当项目内有多个云函数(Functions)或多个前端站点(Sites)需要共享同一套第三方服务地址、公共配置或密钥(例如企业内部 ERP 接口地址或共享验证公钥)时,可在 Global variables 卡片中统一维护:

2. 绑定自定义 API 域名(Custom Domains)

若企业安全合规要求前端应用不能直接请求平台默认域名,而是通过企业自有品牌域名(如 https://api-aihub.enterprise.example.com/v1)访问 Agentbase:

3. 创建与配置事件推送钩子(Webhooks)

Webhooks 允许在项目内部发生特定资源变更(如新工单写入 customer_tickets、新用户完成注册、知识库文档摄取完成)时,由 Agentbase 主动向企业外部业务系统发送 HTTP POST 回调:

配置项名称必填要求详细说明与生产安全建议
Name(名称)必填标识该 Webhook 的业务用途(如 工单落库同步至企业微信群机器人)。
POST URL(回调地址)必填接收事件推送的外部服务端 URL。必须可从 Agentbase 实例公网/专线出站可达,且受平台 SSRF 防护约束(禁止填写 127.0.0.1、私网 IP 或云元数据地址)。
Events(触发事件)必选选择触发推送的事件表达式(如 databases.*.tables.*.rows.create、users.*.create 等)。
Certificate verification (SSL/TLS)强烈建议开启在 Security 区域默认开启 SSL/TLS 证书校验;若因测试环境使用自签名证书而关闭该开关,界面会弹出明确的安全风险警示。
HTTP Basic Auth(可选)选填可选配置回调请求携带的 HTTP Basic 认证用户名与密码。

4. 配置企业自定义邮件服务器(Custom SMTP)

项目默认使用平台级邮件通道发送终端用户(Auth)的注册验证、Magic URL 登录与密码找回邮件。如需使用企业自有品牌邮箱发信:

常见问题与排障

Q1:在 Settings → Services 中不小心点击了 Disable all 关闭了所有服务,我的数据库工单和知识库文档会丢失吗?

原因与排查步骤: 数据完全不会丢失,且后端服务不受影响。Services 卡片中的所有开关仅控制客户端访问面(即浏览器 Web SDK、iOS/Android 客户端直接发起的请求)是否被网关放行。即使关闭了全部客户端服务开关:

Q2:为什么 Webhook 配置保存后一直投递失败,或者在填写 URL 时直接被拒绝?

原因与排查步骤:

Q3:为什么尝试将项目表模式从“共享表”转换为“独占表”时提示失败并被阻止?

原因与排查步骤: 请检查以下两项硬性约束:

相关文档