运行环境(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。
环境上下文文件(可选约定)
需要把环境元数据交给自动化(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