Docs
文档目录

项目设置

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

项目设置页(测试项目)

界面参考:测试项目的设置页局部;项目 ID 和 API 地址已遮罩。

功能概述

在项目的全生命周期中,项目设置模块为架构师与运维负责人提供六大治理能力:

  1. 存储底座与表结构保护:控制是否允许通过版本化 Schema 物理删除表列(Column deletion),并支持在共享表、独占表与 OceanBase Shared V2 模式之间执行在线表模式转换(深度独占表除外)。

  2. 客户端 API 暴露面精细裁剪(Services):支持按服务维度独立开启或关闭面向客户端 SDK 的可达性,并解锁默认关闭的 统一 AI 网关(AI Gateway) 侧栏入口,且关闭服务绝不损毁底层已有数据。

  3. 全局环境变量与构建集成(Global Variables & Git):集中维护注入到该项目下全部云函数(Functions)与站点(Sites)中的环境变量与加密 Secret(支持 .env 批量导入),并管理 GitHub App 等 VCS 仓库安装。

  4. 自定义域名与 HTTPS 证书自动化(Custom Domains):为项目 API 绑定企业自有域名(如 api.support.enterprise.example.com),自动签发并续期 SSL/TLS 证书。

  5. 事件驱动 Webhooks 与自有 SMTP 通道:将数据库行变更、用户注册、文件上传、函数执行等内部事件实时推送至外部业务系统(带 HMAC 签名,可配置 SSL 证书校验);通过配置企业自有 SMTP 服务器接管平台验证与通知邮件。

  6. 数据导入导出与项目归属治理:通过向导完成数据迁移,或将项目平滑转移至其他组织、执行不可逆的项目销毁。

设置子页签名称控制台路由后缀核心治理对象所需最小权限 / 角色边界
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 存储引擎、云函数/站点运行时沙箱以及异步事件分发器。具体设置和适用边界见下文。

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

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

表模式类型承载机制说明是否支持在线转换转换前置约束与 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 存储结构中高风险(重负载操作):转换进行中卡片显示实时进度,期间严禁叠加执行其他表结构变更;历史记录在 账号 → 表模式转换 查看。
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 客户端服务开关全量清单

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

功能详解与操作指南

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

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

  1. 进入项目 设置 → 概览,向下滚动至 全局变量 卡片。

  2. 三种添加与维护方式:

    • 逐条创建(Create variable):点击添加按钮,输入变量键名(Key,最长 255 字符,推荐大写字母加下划线如 ENTERPRISE_ERP_BASE_URL)与变量值(Value)。

    • 批量导入(Import .env):点击导入按钮,上传或粘贴标准 .env 格式的键值对文本,一键批量创建或更新多条全局变量。

    • 在线编辑器模式:在编辑器视图中集中检视和调整变量。

  3. 启用 Secret 加密掩码:

    • 若变量值为敏感凭据(如内部系统签名密钥),在创建或编辑时勾选 密钥 复选框。

    • 勾选并保存后,该变量值在 Console 界面与 API 响应中将永久以掩码(••••••)展示,不支持再次明文查看,仅在云函数和站点容器启动时由平台安全注入到运行环境变量中。

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

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

  1. 进入项目 Settings → Custom domains 页签(路径 /settings/domains),点击 添加域名。

  2. 输入拟绑定的完整自定义子域名,点击下一步查看系统给出的 DNS CNAME 指向目标。

  3. 前往企业 DNS 服务商控制台,添加对应的 CNAME 记录指向目标地址。

  4. 回到 Agentbase 域名列表查看状态流转:

    • 证书自动签发期间状态显示为 Generating certificate。

    • 若因 DNS 解析尚未生效导致显示 Certificate generation failed,可在确认 DNS 生效后点击行内的 Retry(重试),或点击 查看日志 查看详细的 ACME 证书校验日志。

    • 证书签发成功后,即可将该自定义域名作为 SDK 的 Endpoint 投入生产使用。

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

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

  1. 进入项目 设置 → Webhook 页签(路径 /settings/webhooks),点击 创建 Webhook。

  2. 按向导填写核心配置项:

配置项名称必填要求详细说明与生产安全建议
Name(名称)必填标识该 Webhook 的业务用途(如 工单落库同步至企业微信群机器人)。
POST URL(回调地址)必填填写 Agentbase 实例可访问的 HTTP/HTTPS 回调 URL;创建接口会校验 URL 格式和域名。域名解析及出站网络的安全边界应由部署环境确认。
Events(触发事件)必选选择触发推送的事件表达式(如 databases.*.tables.*.rows.*.create、users.*.create 等)。
Certificate verification (SSL/TLS)强烈建议开启控制台创建表单预选启用证书校验;API 创建或更新时省略 security 的默认值为 false。调用 API 时应明确设置 security: true。
HTTP Basic Auth(可选)选填可选配置回调请求携带的 HTTP Basic 认证用户名与密码。
  1. 创建后通过受控渠道保存 Signature Key。接收端使用 HMAC-SHA1 校验 X-Agentbase-Webhook-Signature;签名输入为配置 URL 经 rawurldecode 后的字节与原始请求体字节,详见 SDK 文档中的事件回调章节。不要在日志中输出密钥。

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

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

  1. 进入项目 设置 → SMTP 页签(路径 /settings/smtp),打开 自定义 SMTP 服务器 开关。

  2. 填写发件与服务器连接参数:

    • Sender name(发件人名称):例如 企业智能客服中心。

    • Sender email(发件人邮箱) 与 Reply to(回复邮箱):例如 no-reply@enterprise.example.com。

    • Server host(SMTP 主机) 与 Server port(端口):例如 smtp.enterprise.example.com,端口 465(SSL)或 587(TLS)。

    • Username / Password:SMTP 认证账号与密码(密码加密保存不回显)。

    • Secure protocol(加密协议):选择 TLS、SSL 或 None(生产环境强烈建议使用 TLS 或 SSL)。

  3. 点击 Update 保存后,前往项目 认证 → 模板 页签(见邮件与短信模板)可进一步定制各类系统邮件的标题与正文模板。

常见问题与排障

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

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

  1. 底层 OceanBase 数据库、对象存储桶、知识库索引与长期记忆数据完好无损。

  2. 后端微服务携带服务端 X-Appwrite-Key(Server API Key)发起的一切读写请求依然正常执行。 只需重新在 服务 卡片中点击 全部启用 或按需打开对应开关,前端客户端访问即可立即恢复。

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

原因与排查步骤:

  1. URL 被拒绝:检查 URL 是否符合 HTTP/HTTPS 格式和域名校验要求。字面回环和私网 IP 在当前校验中会被拒绝;域名解析和实际出站访问仍需结合部署网络策略核对。

  2. 投递超时或 TLS 握手失败:在 Webhook 详情页检查目标 HTTPS 域名证书是否过期或缺少中间证书链;若测试环境确需使用自签名证书,需在 Webhook 的 安全 设置中显式关闭 Certificate verification (SSL/TLS)(生产环境切勿关闭)。

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

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

  1. 检查是否存在 relationship 关联集合:当项目数据库内存在包含 relationship 类型属性的集合时,系统转换前置检查会主动阻断转换并弹出明确提示。需先移除 relationship 属性或相关集合后再发起转换。

  2. 检查当前是否为“深度独占表”:共享表与独占表支持互相转换,但深度独占表(Deep Dedicated)在架构上不支持转换为其他任何表模式。转换任务的历史状态与详细报错可在顶部导航 账号 → 表模式转换 页签中核查。

相关文档