快速开始：从 0 到 1 跑起一个 Cube 项目
这一篇不追求覆盖所有配置，而是给你一条最短上手路径。
1. 先理解最小目标
一个最小可运行的 Cube 项目，至少需要：
- 一个可 SQL 查询的数据源；
- 一个 Cube 运行实例；
- 一份语义模型；
- 一次成功查询。
2. 官方推荐的本地启动方式
Cube GitHub README 提供了最小 Docker 启动方式：
bash
docker run -p 4000:4000 -p 15432:15432 -v ${PWD}:/cube/conf -e CUBEJS_DEV_MODE=true cubejs/cube含义大致如下：
4000：HTTP / REST / GraphQL 等 API 入口；15432：Postgres-compatible SQL API 端口；${PWD}挂载到/cube/conf：让当前目录作为 Cube 配置与模型目录；CUBEJS_DEV_MODE=true：开发模式。
3. 最小目录建议
你可以从下面这个最小结构开始：
text
cube-project/
cube.js
model/
orders.yml如果采用新版 YAML 风格建模，这个结构已经足够练手。
4. 一个最小模型示例
下面是一个最小 orders.yml 示例：
yaml
cubes:
- name: orders
sql_table: public.orders
measures:
- name: count
type: count
- name: total_amount
sql: amount
type: sum
dimensions:
- name: id
sql: id
type: number
primary_key: true
- name: status
sql: status
type: string
- name: created_at
sql: created_at
type: time这个模型已经定义了：
- 一个 cube：
orders - 两个指标：订单数、销售额
- 三个维度：主键、状态、创建时间
5. 第一次查询：REST API
Cube REST API 的基础查询端点通常是：
text
/cubejs-api/v1/load一个最小查询可以是：
bash
curl -H "Authorization: TOKEN" -G --data-urlencode 'query={"measures":["orders.count"]}' http://localhost:4000/cubejs-api/v1/load在开发环境里，文档说明授权 token 可以不强制开启，但在生产环境中应正常配置认证。
6. 第一次查询：SQL API
如果你想把 Cube 当成“语义数据库”来试，可以走 SQL API：
bash
PGPASSWORD=password psql -h localhost -p 15432 -U user cube然后执行类似：
sql
SELECT
orders.status,
MEASURE(orders.count)
FROM orders
GROUP BY 1
LIMIT 10;这对 BI 工具和 Notebook 特别友好。
7. 第一次查询：GraphQL API
GraphQL 也是可以直接上手的：
graphql
{
cube {
orders {
count
status
created_at {
month
}
}
}
}如果你的前端本身已经是 GraphQL 生态，这种方式很自然。
8. 第一次成功后你应该立即验证什么
验证 1：模型是否可见
你可以通过 REST API 的 /v1/meta 端点查看当前暴露的语义模型。
验证 2：成员命名是否合理
确保不是把原始表字段名直接搬上来，而是已经具备业务表达能力。
验证 3：时间维度是否真的能按粒度切分
很多后续预聚合、趋势分析、增量刷新都依赖时间维度定义正确。
9. 建议你在第二步就做的三件事
1）把模型文件纳入 Git
语义层是代码资产，不是临时配置。
2）尽早区分底层 cube 与面向用户的 view
不要一开始就把所有成员全裸暴露给消费端。
3）选择一个具体业务域做示例
推荐使用：
- 订单 / 销售分析；
- 用户增长分析；
- 订阅收入分析。
这样后续扩展 pre-aggregations、权限、多租户都会更顺手。
10. 下一步该看什么
完成最小启动后，建议继续阅读：
一句话总结
Cube 的最小上手路径非常清晰：启动服务、连接 SQL 数据源、定义一个 cube、然后通过 REST / SQL / GraphQL 成功查到第一条语义化结果。