项目设置
项目设置(Settings)位于项目控制台左侧边栏底部(路由前缀 /console/project-{region}-{project}/settings),集中承载项目级的全局治理与高权限基础设施配置:包括数据库列删除开关(Column deletion)、项目表存储模式转换(共享表 / 独占表 / Shared V2)、客户端服务可达性开关(Services)、Git VCS 连接、项目级全局环境变量(Global variables)、自定义 API 域名(Custom domains)、事件推送钩子(Webhooks)、自定义邮件通道(SMTP)、跨平台数据迁移(Migrations)以及项目跨组织转移与永久销毁。
界面参考:测试项目的设置页局部;项目 ID 和 API 地址已遮罩。
功能概述
在项目的全生命周期中,项目设置模块为架构师与运维负责人提供六大治理能力:
存储底座与表结构保护:控制是否允许通过版本化 Schema 物理删除表列(
Column deletion),并支持在共享表、独占表与 OceanBaseShared V2模式之间执行在线表模式转换(深度独占表除外)。客户端 API 暴露面精细裁剪(Services):支持按服务维度独立开启或关闭面向客户端 SDK 的可达性,并解锁默认关闭的 统一 AI 网关(AI Gateway) 侧栏入口,且关闭服务绝不损毁底层已有数据。
全局环境变量与构建集成(Global Variables & Git):集中维护注入到该项目下全部云函数(Functions)与站点(Sites)中的环境变量与加密 Secret(支持
.env批量导入),并管理 GitHub App 等 VCS 仓库安装。自定义域名与 HTTPS 证书自动化(Custom Domains):为项目 API 绑定企业自有域名(如
api.support.enterprise.example.com),自动签发并续期 SSL/TLS 证书。事件驱动 Webhooks 与自有 SMTP 通道:将数据库行变更、用户注册、文件上传、函数执行等内部事件实时推送至外部业务系统(带 HMAC 签名,可配置 SSL 证书校验);通过配置企业自有 SMTP 服务器接管平台验证与通知邮件。
数据导入导出与项目归属治理:通过向导完成数据迁移,或将项目平滑转移至其他组织、执行不可逆的项目销毁。
| 设置子页签名称 | 控制台路由后缀 | 核心治理对象 | 所需最小权限 / 角色边界 |
|---|---|---|---|
| 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.write | Console 展示与项目分类筛选 | 低风险:更新项目显示名称;项目标签(Labels)仅允许使用字母与数字字符(Alphanumeric)。 |
| 项目表模式(Table mode) | projects.write | 项目底层 OceanBase 存储结构 | 中高风险(重负载操作):转换进行中卡片显示实时进度,期间严禁叠加执行其他表结构变更;历史记录在 账号 → 表模式转换 查看。 |
| Services(客户端服务开关) | projects.write | 客户端 SDK(Web / 移动端)API 可达性与侧栏入口 | 中风险:关闭服务仅拦截客户端直接访问,服务端 API Key 访问不受影响,且绝不删除已有数据。支持 Enable all / Disable all(需二次确认)。 |
| Git(代码仓库安装) | projects.write | Functions 与 Sites 的 Git 构建源 | 低风险:连接或更新 GitHub App 安装授权;安装或更新连接本身不会自动触发线上重部署。 |
| Global variables(全局变量) | projects.write | 自动注入项目内全部 Functions 与 Sites | 中风险:支持标记为 Secret(保存后单向掩码不回显);若与函数级同名变量冲突,在函数变量页会明确标出。 |
| Change organization(更换组织) | 组织 Owner | 项目所属的顶层组织容器 | 中风险:将当前项目整体迁移到当前账号名下拥有的另一个组织中。 |
| Delete project(删除项目) | 组织 Owner / 高权限写角色 | 整个项目及其下属全部资源 | 极高风险(不可逆):永久销毁项目元数据、数据库、存储桶、知识库、记忆与统计数据,必须手动输入完整项目名称确认。 |
2. Services 客户端服务开关全量清单
在 服务 卡片中,可逐项控制以下服务面向客户端的开关状态:
基础与后端服务:
Account、Avatars、Databases、TablesDB、Health、Functions、Locale、Messaging、Storage、Sites、Teams、Users、GraphQL。AI 原生与知识服务:
Memory(长期记忆)、Knowledge Bases(知识库)、AI Gateway(模型网关llmGateway)、统一 AI Gateway(aiGateway,默认关闭,开启后左侧边栏才显示“AI 网关”入口)。
功能详解与操作指南
1. 管理项目级全局环境变量(Global Variables)
当项目内有多个云函数(Functions)或多个前端站点(Sites)需要共享同一套第三方服务地址、公共配置或密钥(例如企业内部 ERP 接口地址或共享验证公钥)时,可在 全局变量 卡片中统一维护:
进入项目 设置 → 概览,向下滚动至 全局变量 卡片。
三种添加与维护方式:
逐条创建(Create variable):点击添加按钮,输入变量键名(
Key,最长 255 字符,推荐大写字母加下划线如ENTERPRISE_ERP_BASE_URL)与变量值(Value)。批量导入(Import .env):点击导入按钮,上传或粘贴标准
.env格式的键值对文本,一键批量创建或更新多条全局变量。在线编辑器模式:在编辑器视图中集中检视和调整变量。
启用 Secret 加密掩码:
若变量值为敏感凭据(如内部系统签名密钥),在创建或编辑时勾选 密钥 复选框。
勾选并保存后,该变量值在 Console 界面与 API 响应中将永久以掩码(
••••••)展示,不支持再次明文查看,仅在云函数和站点容器启动时由平台安全注入到运行环境变量中。
2. 绑定自定义 API 域名(Custom Domains)
若企业安全合规要求前端应用不能直接请求平台默认域名,而是通过企业自有品牌域名(如 https://api-aihub.enterprise.example.com/v1)访问 Agentbase:
进入项目 Settings → Custom domains 页签(路径
/settings/domains),点击 添加域名。输入拟绑定的完整自定义子域名,点击下一步查看系统给出的 DNS CNAME 指向目标。
前往企业 DNS 服务商控制台,添加对应的 CNAME 记录指向目标地址。
回到 Agentbase 域名列表查看状态流转:
证书自动签发期间状态显示为
Generating certificate。若因 DNS 解析尚未生效导致显示
Certificate generation failed,可在确认 DNS 生效后点击行内的 Retry(重试),或点击 查看日志 查看详细的 ACME 证书校验日志。证书签发成功后,即可将该自定义域名作为 SDK 的
Endpoint投入生产使用。
3. 创建与配置事件推送钩子(Webhooks)
Webhooks 允许在项目内部发生特定资源变更(如新工单写入 customer_tickets、新用户完成注册、知识库文档摄取完成)时,由 Agentbase 主动向企业外部业务系统发送 HTTP POST 回调:
进入项目 设置 → Webhook 页签(路径
/settings/webhooks),点击 创建 Webhook。按向导填写核心配置项:
| 配置项名称 | 必填要求 | 详细说明与生产安全建议 |
|---|---|---|
| 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 认证用户名与密码。 |
创建后通过受控渠道保存 Signature Key。接收端使用 HMAC-SHA1 校验
X-Agentbase-Webhook-Signature;签名输入为配置 URL 经rawurldecode后的字节与原始请求体字节,详见 SDK 文档中的事件回调章节。不要在日志中输出密钥。
4. 配置企业自定义邮件服务器(Custom SMTP)
项目默认使用平台级邮件通道发送终端用户(Auth)的注册验证、Magic URL 登录与密码找回邮件。如需使用企业自有品牌邮箱发信:
进入项目 设置 → SMTP 页签(路径
/settings/smtp),打开 自定义 SMTP 服务器 开关。填写发件与服务器连接参数:
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)。
点击 Update 保存后,前往项目 认证 → 模板 页签(见邮件与短信模板)可进一步定制各类系统邮件的标题与正文模板。
常见问题与排障
Q1:在 Settings → Services 中不小心点击了 Disable all 关闭了所有服务,我的数据库工单和知识库文档会丢失吗?
原因与排查步骤: 数据完全不会丢失,且后端服务不受影响。Services 卡片中的所有开关仅控制客户端访问面(即浏览器 Web SDK、iOS/Android 客户端直接发起的请求)是否被网关放行。即使关闭了全部客户端服务开关:
底层 OceanBase 数据库、对象存储桶、知识库索引与长期记忆数据完好无损。
后端微服务携带服务端
X-Appwrite-Key(Server API Key)发起的一切读写请求依然正常执行。 只需重新在 服务 卡片中点击 全部启用 或按需打开对应开关,前端客户端访问即可立即恢复。
Q2:为什么 Webhook 配置保存后一直投递失败,或者在填写 URL 时直接被拒绝?
原因与排查步骤:
URL 被拒绝:检查 URL 是否符合 HTTP/HTTPS 格式和域名校验要求。字面回环和私网 IP 在当前校验中会被拒绝;域名解析和实际出站访问仍需结合部署网络策略核对。
投递超时或 TLS 握手失败:在 Webhook 详情页检查目标 HTTPS 域名证书是否过期或缺少中间证书链;若测试环境确需使用自签名证书,需在 Webhook 的 安全 设置中显式关闭 Certificate verification (SSL/TLS)(生产环境切勿关闭)。
Q3:为什么尝试将项目表模式从“共享表”转换为“独占表”时提示失败并被阻止?
原因与排查步骤: 请检查以下两项硬性约束:
检查是否存在
relationship关联集合:当项目数据库内存在包含relationship类型属性的集合时,系统转换前置检查会主动阻断转换并弹出明确提示。需先移除relationship属性或相关集合后再发起转换。检查当前是否为“深度独占表”:共享表与独占表支持互相转换,但深度独占表(Deep Dedicated)在架构上不支持转换为其他任何表模式。转换任务的历史状态与详细报错可在顶部导航 账号 → 表模式转换 页签中核查。
