AgentbaseDocs
文档目录

运行环境(endpoint 与 region)

SDK 接入前必须先确定两个环境事实:API endpoint(SDK 调用的绝对基址)与 region(项目部署区域,2.6.0 只有 default)。本页同时说明托管环境与自托管实例的差异,以及 Sites 访问地址的推导规则。

Endpoint 规范

环境API endpoint(SDK setEndpoint)Console origin
托管测试(SIT)https://appbuild-sit.oceanbase.com/v1https://appbuild-sit.oceanbase.com
托管正式https://appbuild.oceanbase.com/v1https://appbuild.oceanbase.com
自托管https://<你的实例域名或IP>:<port>/v1同实例去掉 /v1 的 origin

不确定当前环境时:登录对应 Console,在浏览器开发者工具 → Network 中找任意 /v1/... 请求,复制它的 origin + /v1。Agentbase 不使用 Appwrite Cloud 的区域端点(*.cloud.appwrite.io),也禁止静默回退到另一个环境。

Region

托管环境差异

自托管差异

多语言 SDK 环境初始化与证书/超时配置

在托管测试(SIT https://appbuild-sit.oceanbase.com/v1)、托管正式(https://appbuild.oceanbase.com/v1)与自托管实例之间切换时,各语言 SDK 均通过统一的 setEndpoint(或 WithEndpoint)与 setProject(或 WithProject)装载环境参数。以下给出各语言在服务端与客户端的标准环境装载模板:

import { Client, Health, AgentbaseException } from 'agentbase-node-sdk';

// 优先从环境变量读取,禁止在业务代码中硬编码跨环境回退逻辑
const endpoint = process.env.APPBASE_ENDPOINT ?? 'https://appbuild-sit.oceanbase.com/v1';
const projectId = process.env.APPBASE_PROJECT_ID ?? 'enterprise-ai-hub-210';
const apiKey = process.env.APPBASE_API_KEY!;

const client = new Client()
    .setEndpoint(endpoint)
    .setProject(projectId)
    .setKey(apiKey)
    .setLocale('zh-CN');

// 仅自托管开发/测试环境使用自签名 TLS 证书时开启,生产环境严禁开启
if (process.env.APPBASE_SELF_SIGNED === 'true') {
    client.setSelfSigned(true);
}

const health = new Health(client);
const status = await health.get();
console.log(`环境连通成功: endpoint=${endpoint}, status=${status.status}`);

数据库表模式(Shared V2 vs JsonTable)与环境池标签(poolTag)

维度Shared V2 模式(企业推荐)JsonTable / 独立表模式
适用能力**Memory(长期记忆、画像、经验与技能蒸馏)强制要求 Shared V2**;同时全面支持 TablesDB、知识库、词库(Lexicon)与 AI 网关支持基础 TablesDB、Storage、Functions,无法启用 Memory 服务
创建时选择在 Console 新建项目弹窗或 projects.create 中指定归属 Shared V2 的数据库池 poolTag(或使用默认 Shared V2 池)指定对应模式的 poolTag
环境迁移支持在平台管理面(Admin)按标准流程执行项目表模式转换与读写栅栏排空可经平台管理面在线转换至 Shared V2

常见环境配置错误与排障

现象 / 错误响应根因分析解决方式
404 Project with the requested ID could not be foundAPPBASE_ENDPOINT 指向了正式环境(appbuild.oceanbase.com),但传入的是 SIT 环境(appbuild-sit.oceanbase.com)创建的 projectId(或反之)核对 endpoint 与 projectId 是否属于同一套环境;SIT 与正式环境数据完全隔离
Invalid 'region' param: Value must be one of (default)调用 projects.create 时传入了 fra、sgp、cn-hangzhou 等非标准区域值固定传 region: 'default'(Java 传 Region.DEFAULT)
浏览器报错 CORS Access-Control-Allow-Origin当前前端运行域名(如 localhost:5173 或线上业务域名)未在目标环境的目标项目下注册为 Web Platform进入对应环境的 Console → 项目 Overview → Platforms(或调用 Console SDK projects.createPlatform)注册主机名
DEPTH_ZERO_SELF_SIGNED_CERT / PKIX path building failed连接自托管测试实例时使用了自签名 TLS 证书仅在受控测试环境调用 .setSelfSigned(true) 或将内部根 CA 导入运行时信任库

环境上下文文件(可选约定)

需要把环境元数据交给自动化(Agent / 部署脚本)时,可保存非敏感上下文(endpoint、region、来源),禁止写入邮箱、密码、Session、API Key、Project ID 等凭据:

{
  "schemaVersion": 1,
  "apiEndpoint": "https://appbuild.oceanbase.com/v1",
  "consoleOrigin": "https://appbuild.oceanbase.com",
  "region": "default",
  "source": "console-skill-card"
}

存放位置:用户级 ${XDG_CONFIG_HOME:-$HOME/.config}/ob-agentbase/environment.json;项目级 <projectRoot>/.agentbase/environment.json 覆盖用户级。解析顺序:请求显式给定 → 项目级 → 项目 .env 的 APPBASE_ENDPOINT(兼容 APPWRITE_ENDPOINT)→ 用户级 → 询问用户。

事实源