TIP

**推荐做法：**使用 Lovrabet 官方服务时，在 createClient() 中配置 region；企业独立部署时配置 runtimeDomain。显式 runtimeDomain 的优先级高于 region。

本文面向使用 @lovrabet/sdk 的前端和 Node.js 开发人员，说明如何选择中国大陆或印度尼西亚 Runtime 节点，以及如何接入企业独立部署的 Runtime。

SDK 与 CLI 的配置方式不同

产品	配置入口
Rabetbase / Lovrabet CLI	通过 config init Prompt 或本地 JSON 配置。
Lovrabet Node SDK	没有 config init，也不会主动读取 .rabetbase.json 或 .lovrabet.json；在应用代码的 createClient() 中传入配置。

通过 Rabetbase 项目模板生成项目时，模板可以把 Rabetbase 中非默认的 region 和 runtimeDomain 写入 SDK 初始化代码；真正运行时，SDK 仍只消费传给 createClient() 的值。

使用官方中国大陆节点

cn 是默认国家/地区。可以显式写出：

import { createClient } from "@lovrabet/sdk";

const client = createClient({
  appCode: "app-xxx",
  region: "cn",
  models: [],
});

也可以省略 region，默认就是中国大陆官方节点：

const client = createClient({
  appCode: "app-xxx",
  models: [],
});

使用官方印度尼西亚节点

const client = createClient({
  appCode: "app-xxx",
  region: "id",
  models: [],
});

SDK 会把 region 解析为对应的官方 Runtime 地址。当前只支持 cn 和 id；使用其他值会抛出 INVALID_REGION，不会静默访问其他国家/地区。

region 的官方 Runtime 地址

国家/地区	region	官方 Runtime 地址
中国大陆	cn	https://runtime.lovrabet.com
印度尼西亚	id	https://runtime.lovrabet.id

用户只需要选择国家/地区。其他地址需求统一通过显式 runtimeDomain 处理，不对外暴露内部路由维度。

企业独立部署：配置 runtimeDomain

企业 Runtime 使用自定义地址时，直接在 createClient() 中传入：

const client = createClient({
  appCode: "app-xxx",
  runtimeDomain: "https://runtime.customer.example.com",
  models: [],
});

一旦配置 runtimeDomain，它会覆盖 region 选择的官方地址：

const client = createClient({
  appCode: "app-xxx",
  region: "id",
  
  runtimeDomain: "https://runtime.customer.example.com",
  models: [],
});

// 实际基地址仍是 https://runtime.customer.example.com

地址格式要求

• 必须是绝对 HTTP(S) 地址。
• 不能包含账号密码、query 或 fragment。
• 首尾空白和末尾斜杠会被规范化。
• HTTP 仅为本地开发和少量兼容场景保留；正式服务与企业部署应使用 HTTPS。

浏览器页面注入配置

Lovrabet 生成的业务页面可以在加载时注入 Runtime 地址：

window.__GLOBAL__ = {
  deploymentConfig: {
    RUNTIME_API_DOMAIN: "https://runtime.customer.example.com"
  }
};

应用代码无需重复传入 runtimeDomain：

const client = createClient({
  appCode: "app-xxx",
  models: [],
});

如果代码同时传入 runtimeDomain，代码参数优先于页面注入值。这让同一个前端构建产物可以由不同部署实例动态注入 Runtime 地址，同时仍允许应用显式覆盖。

完整解析优先级

1. createClient({ runtimeDomain })：正式的企业部署配置，优先级最高。
2. serverUrl：旧字段，仅为向后兼容保留；新代码不要再使用。
3. window.__GLOBAL__.deploymentConfig.RUNTIME_API_DOMAIN：浏览器页面注入。
4. region：官方国家/地区节点映射。
5. 未传时：默认使用 cn。

所有 SDK 服务共用一个 Runtime Domain

当前 SDK 只支持 runtimeDomain，没有 ocrDomain、fileDomain 或通用 serviceDomains。以下能力都使用同一个 Runtime 基地址：

• 数据模型 CRUD 与过滤查询
• SQL 与 BFF
• OCR
• 文件上传与取用
• 其他 Runtime 服务

如果企业只部署部分 Runtime 服务，SDK 不会把未部署的某项能力自动回退到 Lovrabet 官方服务；请求仍发往企业 runtimeDomain，由服务端明确返回“暂未部署”或相应错误。需要多套地址时，由业务应用创建不同 Client 或自行编排。

认证模式不会改变 Domain

authMode 决定请求路径和认证头，不决定基础地址：

authMode	典型凭据	Domain
cookie	浏览器 Cookie 或显式 Cookie	仍使用同一个 runtimeDomain / 官方 Runtime
client-ak	accessKey	仍使用同一个 runtimeDomain / 官方 Runtime
openapi	accessKey，或 token + timestamp	仍使用同一个 runtimeDomain / 官方 Runtime

未设置 authMode 时默认是 cookie；SDK 不会因为配置了 accessKey 就自动切换认证模式。

常见配置示例

Node.js 使用企业 Runtime 与 Client AK

const client = createClient({
  appCode: "app-xxx",
  authMode: "client-ak",
  accessKey: secureAccessKey,
  runtimeDomain: "https://runtime.customer.example.com",
  models: [],
});

浏览器使用印度尼西亚节点与 Cookie

const client = createClient({
  appCode: "app-xxx",
  authMode: "cookie",
  region: "id",
  
  models: [],
});

验证配置

初始化后可读取最终基地址：

console.log(client.getBaseUrl());

预期结果示例：

• region: "id" → https://runtime.lovrabet.id
• region: "cn" → https://runtime.lovrabet.com
• 显式 runtimeDomain → 返回规范化后的企业地址

常见问题

SDK 会读取 Rabetbase CLI 的配置文件吗？
不会。需要由项目模板或应用代码把 region、runtimeDomain 传给 createClient()。

可以同时配置 region 和 runtimeDomain 吗？
可以，但 runtimeDomain 优先，region 不参与当前 Client 的地址选择。

不同部署实例有不同企业 Runtime 怎么办？
应用可以从自己的部署配置读取 runtimeDomain，再传入 createClient()。SDK 不额外引入新的公开路由维度。

还能继续使用 serverUrl 吗？
暂时可以，但它已废弃且优先级低于 runtimeDomain。新代码统一使用 runtimeDomain。

---

适用版本：按 2026-08-23 Lovrabet Node SDK main 分支（包版本 1.5.1-beta.0）核对。