运行环境(endpoint 与 region)
SDK 接入前必须先确定两个环境事实:API endpoint(SDK 调用的绝对基址)与 region(项目部署区域,2.6.0 只有 default)。本页同时说明托管环境与自托管实例的差异,以及 Sites 访问地址的推导规则。
Endpoint 规范
- 必须是绝对
http://或https://URL,可使用域名、IPv4、IPv6 和显式端口。 - API 路径只允许空、
/或/v1;SDK 使用时统一规范为单个/v1(setEndpoint('https://<host>/v1'))。 - 拒绝 userinfo、query、fragment 和其他业务路径。
consoleOrigin是规范 endpoint 去掉/v1后的 origin,必须保留协议和端口(Console 页面、Webhook 回报都用它)。
| 环境 | API endpoint(SDK setEndpoint) | Console origin |
|---|---|---|
| 托管测试(SIT) | https://appbuild-sit.oceanbase.com/v1 | https://appbuild-sit.oceanbase.com |
| 托管正式 | https://appbuild.oceanbase.com/v1 | https://appbuild.oceanbase.com |
| 自托管 | https://<你的实例域名或IP>:<port>/v1 | 同实例去掉 /v1 的 origin |
不确定当前环境时:登录对应 Console,在浏览器开发者工具 → Network 中找任意 /v1/... 请求,复制它的 origin + /v1。Agentbase 不使用 Appwrite Cloud 的区域端点(*.cloud.appwrite.io),也禁止静默回退到另一个环境。
Region
- 2.6.0 实例配置(
app/config/regions.php)只注册了一个区域:default(默认启用)。 - 创建项目时
region传default即可;传其他区域值会得到Invalid 'region' param: Value must be one of (default)。 - 不要使用 Appwrite Cloud 的
Region.Fra/Region.Sgp等区域枚举;项目创建后的 API 基址与环境一致,不按 region 生成项目专属域名。 - 创建项目时可另传可选
poolTag指定数据库池标签(不传时匹配空 tag 的 fallback 池),见 overview.md。
托管环境差异
- 测试与正式是两套独立环境:账号、项目、Platform 注册、API Key 都不共享;多环境各自建项目、各自注册 Platform。
- Console 管理面的「Console 项目」常见 ID 为
console;Console SDK 初始化先setProject('console')(或环境实际的 Console project ID),创建应用项目后再切换setProject(应用项目 ID)。 - Sites 与 API 同 origin:Site 访问地址 = endpoint 去掉
/v1(例:https://appbuild-sit.oceanbase.com/v1对应https://appbuild-sit.oceanbase.com);Sites 子域和 Proxy rule domain 均从该 origin 推导,不额外生成「子域 + IP」地址。
自托管差异
- endpoint 使用自己的实例地址;行为基线与托管实例一致,但能力开关由实例环境变量决定(例如 Sites 白名单、Function 沙箱后端、模块门控),升级节奏以实例运维为准。
- 2.6.0 安全默认值在自托管同样生效:外部 URL(迁移 source、Custom OAuth2 endpoint、远程预览等)拒绝本机 / 私网 / 云元数据地址;远程 Avatar/Favicon/Screenshot 默认不可用;Function/Site 受限身份运行。不要建议长期关闭 SSRF 防护恢复旧行为。
- 自托管排障涉及后台 worker(如列状态停在
processing、队列积压),见 troubleshooting.md。
多语言 SDK 环境初始化与证书/超时配置
在托管测试(SIT https://appbuild-sit.oceanbase.com/v1)、托管正式(https://appbuild.oceanbase.com/v1)与自托管实例之间切换时,各语言 SDK 均通过统一的 setEndpoint(或 WithEndpoint)与 setProject(或 WithProject)装载环境参数。以下给出各语言在服务端与客户端的标准环境装载模板:
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
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}`);import { Client, Account } from 'agentbase-web-sdk';
// 浏览器端仅配置 Endpoint 与 Project ID,严禁注入任何 API Key
const client = new Client()
.setEndpoint(import.meta.env.VITE_APPBASE_ENDPOINT || 'https://appbuild-sit.oceanbase.com/v1')
.setProject(import.meta.env.VITE_APPBASE_PROJECT_ID || 'enterprise-ai-hub-210')
.setLocale('zh-CN');
const account = new Account(client);
// 浏览器跨域请求前,需确保当前前端域名已在 Console -> Overview -> Platforms 注册为 Web 平台import io.agentbase.Client;
import io.agentbase.services.Health;
String endpoint = System.getenv().getOrDefault("APPBASE_ENDPOINT", "https://appbuild-sit.oceanbase.com/v1");
String projectId = System.getenv().getOrDefault("APPBASE_PROJECT_ID", "enterprise-ai-hub-210");
String apiKey = System.getenv("APPBASE_API_KEY");
Client client = new Client()
.setEndpoint(endpoint)
.setProject(projectId)
.setKey(apiKey)
.setSelfSigned("true".equalsIgnoreCase(System.getenv("APPBASE_SELF_SIGNED")));
Health health = new Health(client);
System.out.println("Gateway status: " + health.get().getStatus());import os
from agentbase.client import Client
from agentbase.services.health import Health
endpoint = os.environ.get('APPBASE_ENDPOINT', 'https://appbuild-sit.oceanbase.com/v1')
project_id = os.environ.get('APPBASE_PROJECT_ID', 'enterprise-ai-hub-210')
api_key = os.environ['APPBASE_API_KEY']
client = (
Client()
.set_endpoint(endpoint)
.set_project(project_id)
.set_key(api_key)
.set_self_signed(os.environ.get('APPBASE_SELF_SIGNED', '').lower() == 'true')
)
health = Health(client)
print('Gateway status:', health.get().status)package main
import (
"fmt"
"os"
"time"
"agentbase-go-sdk/agentbase"
)
func main() {
endpoint := os.Getenv("APPBASE_ENDPOINT")
if endpoint == "" {
endpoint = "https://appbuild-sit.oceanbase.com/v1"
}
cl := agentbase.NewClient(
agentbase.WithEndpoint(endpoint),
agentbase.WithProject(os.Getenv("APPBASE_PROJECT_ID")),
agentbase.WithKey(os.Getenv("APPBASE_API_KEY")),
agentbase.WithTimeout(30*time.Second),
)
health := agentbase.NewHealth(cl)
st, err := health.Get()
fmt.Println(st, err)
}# 验证当前环境 Endpoint、Project ID 与 API Key 三元组是否匹配
export APPBASE_ENDPOINT="https://appbuild-sit.oceanbase.com/v1"
export APPBASE_PROJECT_ID="enterprise-ai-hub-210"
curl -sS "$APPBASE_ENDPOINT/health" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY"数据库表模式(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 found | APPBASE_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)→ 用户级 → 询问用户。
事实源
skills/ob-agentbase/references/environment-context.mdskills/ob-agentbase/references/console-sdk.md(endpoint 与 region 口径)- appbase v2.7.0(tag v2.7.0)(
app/config/regions.php仅注册default区域) - agentbase-sdks v2.7.0 specs