Rabetbase 常见问题（FAQ）
本页汇总 Rabetbase 开发体系（CLI + SDK + Skill + BaaS）的常见问题。如果你的问题不在此列，可以在 Lovrabet 社区提问。
一、基础概念
Q1: Rabetbase 和 Lovrabet 是什么关系？
Lovrabet 面向所有的业务人员和开发人员，是一套完整的AI-Native业务系统的生成平台。
Rabetbase 是 Lovrabet 的开发者基础设施层。它向上层应用提供标准化的数据访问、权限控制和 API 能力；向开发者提供 CLI、SDK、Skill三件套——在终端完成从数据操作到项目部署的全流程，无需自建后端。
Lovrabet 平台
- AI-Native业务系统生成
- DB Agent / Vibe Coding / 需求描述生成系统
- 工作台 / 权限管理
- 应用托管
Rabetbase 开发体系——隶属于Lovrabet平台
- CLI：终端操作工具
- SDK：数据访问接口
- Skill：AI 辅助开发
- BaaS：后端即服务
Q2: 没有后端开发经验，能用 Rabetbase 吗？
可以。Rabetbase 的 BaaS 层已经把后端能力（数据库、API、权限、认证）全部封装好了。你只需要：
- 用 Lovrabet 平台创建应用和数据表
- 用
rabetbase api pull生成 SDK 配置 - 用 SDK 的 filter、create、update、delete 操作数据
整个过程不需要写后端代码、不需要部署服务器。
Q3: Rabetbase CLI 2.0 和旧版 lovrabet CLI 有什么区别？
| 维度 | 旧版（lovrabet） | 新版（rabetbase 2.0） |
|---|---|---|
| 命令前缀 | lovrabet | rabetbase |
| 构建部署 | lovrabet build | rabetbase run build |
| AI 集成 | MCP Server | Skill（社区标准） |
| 命令体系 | 功能分散 | 统一 service + command 两级结构 |
💡 如果你还在用旧版 lovrabet CLI，请升级到 rabetbase 2.0。旧版已停止维护。
二、安装与配置
Q4: 如何安装 Rabetbase CLI？
安装后验证：
rabetbase --version
rabetbase --help
Q5: Skill 如何安装？
Skill 是 AI 辅助开发的规则集，让 Claude Code、Codex、Cursor 等工具能正确使用 Rabetbase CLI。Rabetbase 面向开发人员，建议优先使用 CLI 内置命令安装官方开发 Skill：
rabetbase skill install
如果当前 CLI 版本尚不支持 skill install，可以使用等价命令：
npx skills add lovrabet/rabetbase -g -y
❗ 网络提示：如果安装或刷新 Skill 时提示无法连接 github.com:443、timeout 或 Could not connect to server，说明当前网络无法访问 GitHub；CLI 可能已经安装成功。请参考故障排查 Q28 Rabetbase 常见问题（FAQ）。
安装后，在 Claude Code、Codex、Cursor 等支持 Skill 的 Agent 中，AI 会理解 Rabetbase CLI 的项目初始化、数据库分析、数据集、SQL、BFF、页面菜单和代码生成规则。
开发者排障步骤：
- 先确认 CLI 本身是否安装成功：
rabetbase --version
rabetbase --help
如果这两条命令正常，说明 CLI 已安装；后续错误只代表 Skill 注册链路需要排查。
- 如果出现
PromptScript does not support global skill installation或自然语言日志里的Failed to install 1，通常是skills@1.5.10自动探测到不支持全局 Skill 目录的 PromptScript Agent，不能直接判定 Rabetbase Skill 整体安装失败。参考上游 Issue #1352 和修复 PR #1362；https://github.com/vercel-labs/skills/issues/1362会跳转到同一个 PR。 - 用真实本地
skillsCLI 输出做辅助确认：
npx skills list -g --json
只有确认该命令是在本地 shell 中执行，才把它作为证据；App 私有 SkillHub、自然语言总结或替代命令输出都不能作为全局注册证据。
- 临时规避可以固定上一版安装工具：
npx skills@1.5.9 add lovrabet/rabetbase -g -y
--agent <agent>只适合作为临时排障手段，用来把安装目标收敛到明确支持全局 Skill 的 Agent；不要把它当成 Rabetbase CLI 的主安装命令，也不要在不知道目标 Agent 名称时让 Agent 自行猜测。- 在 Feishu Aily、钉钉悟空等 IM 类 Agent 中遇到 30 秒超时、沙箱路径、写入目录不确定时，应停止自动化重试，改为让用户在本地终端执行安装命令。
Q6: 认证方式有哪些？
Rabetbase 支持两种认证模式：
| 模式 | 认证方式 | 适用场景 |
|---|---|---|
| WebAPI | Cookie（浏览器登录） | 前端应用 |
| OpenAPI | AccessKey + SecretKey | 后端服务、CLI |
前端推荐使用 Cookie 认证（用户在浏览器中登录后自动获取），后端和 CLI 使用 AccessKey 认证。
🎁 AccessKey 不要硬编码在源码中！请按团队认可的密钥管理方式保存。
三、CLI 常用命令
Q7: 如何创建新项目？
rabetbase project create my-app
cd my-app
rabetbase api pull --appcode your-app-code
project create 会生成完整的项目脚手架（含构建配置、路由、API 客户端）。api pull 会根据你的应用数据生成 SDK 类型定义。
Q8: 如何同步菜单到主应用？
rabetbase menu sync
CLI 会自动扫描 src/pages 下的页面，智能提取菜单名称，批量创建菜单。
Q9: 如何构建和部署？
rabetbase run build
构建产物在 dist/ 目录，可以直接部署到 CDN。
Q10: 常用 CLI 命令速查
| 命令 | 说明 |
|---|---|
rabetbase project create | 创建项目 |
rabetbase api pull | 拉取 API 配置 |
rabetbase dataset detail | 查看数据集结构 |
rabetbase sql validate | 校验 SQL 语法 |
rabetbase sql save | 保存自定义 SQL |
rabetbase sql exec | 执行自定义 SQL |
rabetbase bff new | 创建 Backend Function |
rabetbase bff push | 推送 BFF 到平台 |
rabetbase menu sync | 同步菜单 |
rabetbase run build | 构建项目 |
rabetbase auth login | 登录认证 |
rabetbase app list | 查看应用列表 |
四、SDK 数据操作
Q11: SDK 客户端怎么初始化？
推荐使用单例模式，整个应用共享一个客户端实例：
// src/api/client.ts
import { createClient } from "@lovrabet/sdk";
export const client = createClient({
appCode: "your-app-code",
});
不要在每个组件中重复创建客户端。
Q12: filter、getOne、create、update、delete 怎么用？
import { client } from "@/api/client";
// 查询列表（分页）
const { tableData, total } = await client.models.customers.filter({
currentPage: 1,
pageSize: 20,
});
// 查询单条
const customer = await client.models.customers.getOne("123");
// 创建
const newId = await client.models.customers.create({
name: "张三",
phone: "13800138000",
});
// 更新
await client.models.customers.update("123", { name: "李四" });
// 删除（仅 WebAPI 模式）
await client.models.customers.delete("123");
Q13: 删除操作报错怎么办？
delete 操作只在 WebAPI 模式（Cookie 认证）下可用。如果你用的是 OpenAPI 模式，用"软删除"：
await client.models.customers.update(id, {
status: "deleted",
deleted_at: new Date().toISOString(),
});
五、SQL 与 Backend Function
Q14: 什么时候用自定义 SQL？
| 场景 | 推荐 |
|---|---|
| 单表增删改查 | SDK 的 filter/create/update/delete |
| 单表条件查询 | filter + 搜索/筛选参数 |
| 跨表关联查询 | 自定义 SQL |
| 复杂聚合统计 | 自定义 SQL |
| 数据分组求和 | 自定义 SQL |
Q15: 自定义 SQL 怎么写？
创建 .rabetbase/sql/ 目录下的 SQL 文件：
-- @lovrabet sqlName=myQuery description=我的查询
SELECT
category,
COUNT(*) as count,
SUM(amount) as total
FROM dataset_orders
WHERE 1=1
<if test="startDate">
AND create_time >= #{startDate}
</if>
GROUP BY category
关键语法：
#{paramName}— 参数化查询（防 SQL 注入）<if test="paramName">— 动态 SQL 条件<=需写成<=（XML 转义）
Q16: Backend Function 是什么？
Backend Function（BFF）是在 Lovrabet 后端运行的 JavaScript 函数，用于处理复杂业务逻辑。三种类型：
| 类型 | 说明 | 触发方式 |
|---|---|---|
| HOOK | 依附于数据集标准 API | 数据操作时自动触发 |
| ENDPOINT | 独立 HTTP 端点 | 前端主动调用 |
| COMMON | 公共函数 | 其他 BFF 内部调用 |
Q17: 事务怎么用？
const models = context.client.models;
await context.client.db.transaction(async (tx) => {
// 创建主表
const orderId = await models[TABLES.orders].create(orderData);
// 创建明细
for (const item of items) {
await models[TABLES.orderItems].create({ orderId, ...item });
}
});
关键规则：
- 使用
context.client.models而非tx.models - 异常自动回滚
- 不要在事务中执行耗时操作
六、AI 辅助开发
Q18: Skill 能帮我做什么？
Skill 让 AI 工具（Claude Code、Cursor）理解你的业务数据结构，生成的代码一次通过：
- 自动获取数据集结构（表名、字段名、字段类型）
- 正确使用 CLI 命令（不会猜字段名）
- 遵循最佳实践（单例模式、错误处理、分页）
- 自动执行 CLI 命令（创建项目、拉取 API、推送 BFF）
Q19: 如何用 AI 辅助开发一个完整功能？
在 Claude Code 中描述需求即可：
用 rabetbase CLI 帮我创建一个客户管理页面，包含客户列表（支持搜索和分页）、客户详情页（支持编辑）、新建客户表单（有手机号校验）。
AI 会自动完成：
rabetbase project create创建项目rabetbase api pull生成 SDK- 生成所有页面代码
rabetbase run build构建rabetbase menu sync同步菜单
Q20: 为什么 AI 生成的代码不正确？
可能的原因：
- Skill 未安装 — 运行
npx skills add lovrabet/rabetbase --global - API 未拉取 — 运行
rabetbase api pull更新 SDK 配置 - 描述不够具体 — 明确指定数据集名称、字段名、页面结构
七、性能与安全
Q21: 列表查询怎么优化？
- 加分页 — 始终传 currentPage 和 pageSize
- 搜索加防抖 — 300ms debounce
- 只查需要的字段 — SQL 避免 SELECT *
- 加 LIMIT — SQL 查询限制返回行数
Q22: AccessKey 泄露了怎么办？
- 在 Lovrabet 平台重新生成 AccessKey
- 更新密钥配置
- 检查是否有硬编码的旧 Key
❌ 永远不要在前端代码中硬编码 AccessKey。前端使用 Cookie 认证或 Token 认证。
Q23: 敏感数据怎么处理？
前端脱敏：
const maskPhone = (phone: string) => {
return phone.replace(/(\d{3})\d{4}(\d{4})/, "$1****$2");
};
// 138****8000
后端脱敏（推荐）：使用 Backend Function 的后验函数，在数据返回前统一处理。
八、故障排查
Q24: CLI 命令报错 "command not found"？
确认安装路径：
which rabetbase
rabetbase --version
如果找不到，重新安装或检查 PATH 配置。
Q25: API 调用返回 401？
检查认证状态：
rabetbase auth login
如果是 AccessKey 认证，按团队约定确认密钥已经正确配置。
Q26: BFF 推送失败？
常见原因：
- 语法错误 — 先用
rabetbase bff status检查 - 数据集编码不对 — 检查 TABLES 常量中的编码
- 网络问题 — 检查网络连接
Q27: SQL 执行 execSuccess 为 false？
常见原因：
- SQL 语法错误（检查 XML 转义）
- 表或字段名不正确
- 参数类型不匹配
调试方法：
rabetbase sql exec --sqlcode <sqlcode> --params '{}' --format json
Q28: Windows 下 rabetbase skill install / rabetbase update 连接 GitHub 失败怎么办？
**现象：**Windows 上 curl 可以访问 GitHub，但 rabetbase skill install 或 rabetbase update 在 Git 拉取阶段报 Connection was reset、TLS 连接重置、github.com:443、timeout 或 Could not connect to server。
💡 **说明：**CLI 包通过 npm 安装，Skill 通过 GitHub 源刷新。该问题通常发生在 Git 使用 OpenSSL 作为 TLS 后端时，不代表 CLI 升级失败。
步骤 1：确认 CLI 是否已经可用
rabetbase --version
步骤 2：切换 Git 的 Windows 原生 TLS 通道
git config --global http.sslBackend schannel
为什么这个配置可能有效：Git 通过 HTTPS 拉取 GitHub 仓库时，底层 TLS 后端可能是 OpenSSL 或 Windows Schannel。OpenSSL 通常使用 Git 自带或独立的证书与握手路径；Schannel 使用 Windows 系统证书存储、企业根证书和系统 TLS 策略。企业代理、VPN 或安全软件经常只把根证书写入 Windows 证书存储，所以系统里的 curl 能访问 GitHub，但 Git 的 OpenSSL 通道可能在握手阶段被重置。切换到 schannel 后，Git 与系统 curl 的信任链更一致。
步骤 3：重新刷新 Skill 或重新升级
rabetbase skill install
rabetbase update
如果设置后仍失败，再检查代理、VPN、公司网络策略或 GitHub 访问权限。若 rabetbase --version 已显示目标版本，可以先继续使用已升级的 CLI，待网络恢复后再执行 rabetbase skill install。
修复后的效果示意
Q29: 安装后仍然执行旧版本 rabetbase 怎么办？
**现象：**已经执行 npm install -g @lovrabet/rabetbase-cli，但 rabetbase --version 显示的版本不对，或命令行为仍然像旧版本。
💡 **原因：**电脑里可能同时存在多个 rabetbase。终端会按 PATH 顺序执行排在最前面的那个，所以新版本安装成功后，也可能仍然命中旧的 /usr/local/bin/rabetbase。常见于NVM管理的NODE版本可能会出现这个问题。
步骤 1：查看当前执行路径
rabetbase --version
command -v rabetbase
type -a rabetbase
where rabetbase
步骤 2：确认是否存在多个 rabetbase
如果结果里同时出现 /usr/local/bin/rabetbase 和 /Users/<用户名>/.nvm/versions/node/<node-version>/bin/rabetbase，并且 /usr/local/bin/rabetbase 排在前面，说明当前终端优先执行的是旧入口。
步骤 3：删除旧入口并清理 shell 缓存
sudo rm /usr/local/bin/rabetbase
hash -r
rabetbase --version
command -v rabetbase
❗ 只在确认 /usr/local/bin/rabetbase 是旧入口时删除。删除后，command -v rabetbase 应指向当前 Node/npm 安装路径。
💡 更多问题？查看以下资源：集成开发指南、SDK 使用指南、CLI 使用指南，均可通过 open.lovrabet.com 获取。