Ghost 中的 Tinybird CLI 命令指南：tb 命令全景解析与 Ghost Analytics 实战用法

Ghost 的流量分析（Traffic Analytics）构建在 Tinybird 实时分析平台之上，其数据管道由一组 .datasource、.pipe、.endpoint 文件定义（位于 ghost/core/core/server/data/tinybird）。仓库内置了一份面向 AI 协作与开发者的 tb CLI 命令规范（cli-commands.md），它覆盖了从本地构建、部署、数据操作、分支开发到测试的全部命令，并针对 CLI 4.0 的 dev_mode 工作流做了专门约定。读完本文，你将能够完整掌握 Ghost 仓库中 Tinybird 项目的本地开发、验证与数据运维流程，并理解每个命令在 Ghost 代码库中的真实落点。

核心原则：绝不臆造命令与参数

规范文档开篇即强调了一条铁律：不要凭空发明命令或参数（flag）。当不确定某个命令或参数是否存在时，先运行 tb <command> --help 验证，只使用文档中记载的、或通过 --help 确认过的命令。

这条原则在 Ghost 仓库中有直接的现实依据。docker/tb-cli/Dockerfile 将 CLI 版本固定在 4.6.13，并附带了一段关键注释：4.6.14 版本会把嵌套 JSON 对象按 ClickHouse Tuple 语法写入 String 列，导致对 analytics_events.payload 的 JSONExtractString 返回空字符串（相关说明见 .github/workflows/tinybird.yml）。这正是“版本行为需要验证、不能假设”的典型例子——在 Ghost 这样的数据管道项目中，一次未经确认的 CLI 升级就足以破坏整个解析链路。

CLI 4.0 的构建与部署上下文：dev_mode 优先

Tinybird CLI 4.0 引入了 dev_mode 概念，Ghost 的 SKILL.md 对此给出了工作流约定：

• 推荐流程：只配置一次 dev_mode，之后运行“裸”的 tb build 和 tb deploy；
• tb build 会构建到 tinybird.config.json 中配置的开发环境（branch 或 local）；
• tb deploy 面向 Tinybird Cloud 生产环境；
• --cloud、--local、--branch 仅作为显式的手动覆盖手段使用。

对应的全局覆盖参数如下：

tb --cloud <command>        # 命令指向 Cloud
tb --local <command>        # 命令指向 Local
tb --branch <branch_name> <command>  # 命令指向指定分支
tb --debug <command>        # 输出调试信息

在 Ghost 的 Docker 开发链路中，--local 覆盖参数是被真实使用的：docker/tb-cli/entrypoint.sh 的容器启动脚本第一条有效命令就是 tb --local build，把 Tinybird 数据文件构建部署到 Tinybird Local 容器；随后通过 tb --output json info 获取 JSON 格式的 workspace ID 与 token，并用 jq 解析出 TINYBIRD_WORKSPACE_ID、TINYBIRD_ADMIN_TOKEN、TINYBIRD_TRACKER_TOKEN 写入共享的 .env.tinybird 文件，供 Ghost 主服务与 Analytics 服务自动完成连接配置。这说明 JSON 输出（如 --output json）是脚本化集成的重要能力。

项目与开发命令

开发与构建阶段的核心命令：

命令	作用
tb init	初始化新项目
tb create	tb init 的弃用别名
tb info	显示项目信息与 CLI 上下文（用于确认当前指向 local/branch/cloud）
tb build	校验并构建项目
tb build --watch	构建并监听文件变更
tb dev	构建并监听变更（开发态）
tb dev --ui	将本地项目连接到 Tinybird UI
tb preview	为当前分支创建/更新预览环境
tb open	在浏览器中打开 workspace
tb fmt <file>	格式化 .datasource、.pipe 或 .connection 文件
tb fmt <file> --diff	只展示 diff，不修改文件

Ghost 仓库的 package.json 把 tb dev 封装成了根级脚本：

# package.json 中的脚本定义
"tb": "tb local start && cd ghost/core/core/server/data/tinybird && tb dev",
"tb:install": "curl https://tinybird.co | sh"

也就是说，在仓库根目录执行一次 pnpm tb:install（首次需要安装 CLI），之后运行 pnpm tb 就会自动启动 Tinybird Local 容器并进入 tb dev 的持续监听模式——数据文件一变就自动构建部署。ghost/core/core/server/data/tinybird/README.md 同时提供了“零安装”的 Docker 替代方案：

# 一次性命令：不安装 tb，直接借用 compose 中的 tb-cli 服务
docker compose run --rm -it tb-cli tb <command>

# 例如列出所有 token
docker compose run --rm -it tb-cli tb token ls

# 持久化监听会话：持续监听数据文件变更并自动部署
docker compose run --rm -it tb-cli tb dev

这个 tb-cli compose 服务定义在 compose.dev.analytics.yaml 中（dockerfile: docker/tb-cli/Dockerfile，容器名 ghost-dev-tb-cli），通过挂载共享配置卷，Ghost 与 Analytics 服务才能读取 tb-cli 部署后生成的 token。

部署命令：从校验到生产

tb deploy                                   # 部署项目
tb deploy --check                           # 只校验，不实际创建部署
tb deploy --wait                            # 等待部署完成
tb deploy --allow-destructive-operations    # 允许破坏性变更（需要显式确认）
tb deployment ls                            # 列出所有部署
tb deployment create                        # 创建 staging 部署并先校验再晋升
tb deployment promote                       # 将 staging 部署晋升到生产
tb deployment discard                       # 丢弃一个待处理部署

--check 与 --allow-destructive-operations 两个参数体现了 Tinybird 部署的安全设计：前者让 CI 可以先“干跑”一遍验证，后者把破坏性 schema 变更（如删列、改分区键）从普通部署中隔离出来，要求显式授权。

日志命令

tb logs                                  # 查看常用服务 datasource 的最近日志
tb logs --start -30m --source '*'       # 自定义时间范围查询全部 source
tb logs --output json                    # 以 JSON 输出日志，便于脚本处理

在 Ghost 的分析体系中，api_monitoring_ingestion 这一组端点（见 api_monitoring_ingestion.pipe）正是围绕数据摄取链路做的监控，tb logs 是排查事件写入异常的第一入口。

数据源操作：append / replace / delete / truncate / sync / export

这是规范中篇幅最大、也最实战的部分。Ghost 的 analytics_events 数据源（analytics_events.datasource）使用 MergeTree 引擎、按 toYYYYMM(timestamp) 分区、按 site_uuid, timestamp 排序，并声明了 TOKEN "tracker" APPEND 与 TOKEN "analytics-service" APPEND 两个写入口——所有下面的数据操作命令最终都作用于这类声明了引擎、分区与 token 权限的数据源。

命令	说明
tb datasource ls	列出所有数据源
tb datasource append <name> --file <path>	从本地文件追加数据
tb datasource append <name> --url <url>	从 URL 追加数据
tb datasource append <name> --events '<json>'	追加 JSON 事件
tb datasource replace <name> <file_or_url>	整体替换数据源
tb datasource replace <name> <file_or_url> --sql-condition "<condition>"	按条件选择性替换
tb datasource delete <name> --sql-condition "<condition>"	删除匹配行
tb datasource delete <name> --sql-condition "<condition>" --wait	删除并等待完成
tb datasource truncate <name> --yes	清空全部行
tb datasource truncate <name> --cascade --yes	连同依赖的物化视图一起清空
tb datasource sync <name> --yes	从 S3/GCS 连接同步
tb datasource export <name> --format csv	导出数据到文件

Ghost 仓库对 append 命令有完整的落地场景：fixtures/ 目录下的 analytics_events.ndjson 存着本地测试事件（site_uuid=mock_site_uuid、2100 年日期的合成数据），Tinybird 的 README 明确说明“在 Tinybird Local 运行时，可以从 fixture 文件向数据源追加数据或删除数据，文件被修改后数据源会自动更新”。同时它提醒了一个重要细节：更新 fixture 会重建数据，但物化视图（如 mv_hits、mv_session_data）是追加式的，旧数据不会被清除——保证测试数据一致性的做法是先 truncate 所有数据源，再注入测试数据。

另外，ghost/core/core/server/data/tinybird/scripts/README.md 提供了 Docker 环境下的数据生成/清空脚本（pnpm data:analytics:generate / pnpm data:analytics:clear），配合 tb datasource append 构成 Ghost 本地数据运维的完整闭环。

Pipes 与 Endpoints：用 endpoint data 测试端点

tb pipe ls                     # 列出所有 pipes
tb endpoint ls                 # 列出所有 endpoints
tb endpoint data <pipe_name>   # 获取端点数据（测试端点用这个）
tb endpoint data <pipe_name> --param_name value  # 带参数获取数据
tb endpoint stats <pipe_name>  # 查看最近 7 天端点统计
tb endpoint url <pipe_name>    # 打印端点 URL
tb endpoint token <pipe_name>  # 获取读取端点的 token

规范特别强调：测试端点要用 tb endpoint data，不要用 tb pipe data。原因是 endpoint data 像真实消费者一样调用端点，带参数校验与输出格式化，能真实复现前端（如 Ghost 后台 Analytics 页面）取数行为。

Ghost 仓库里这正是被大规模使用的一类命令对象：endpoints/ 目录包含 api_kpis、api_kpis_v2、api_top_pages_v3、api_active_visitors 等 20 多个分析端点，以及 api_top_pages_router 这类路由端点。tests/ 目录中每个端点对应一个 YAML 期望文件（如 api_kpis_v2.yaml），其中记录的是 endpoint data 带参数（site_uuid=mock_site_uuid&date_from=2100-01-01&date_to=2100-01-07）调用后的精确输出——visits、pageviews、bounce_rate、avg_session_sec 逐日期断言，这正是端点级契约测试。

SQL 查询

tb sql "<query>"                                # 执行 SQL 查询
tb sql "<query>" --stats                       # 执行查询并显示统计信息
tb sql --pipe <path> --node <node_name>        # 从指定 pipe 节点执行 SQL

--pipe --node 的组合用于调试多节点 pipe 中某个具体阶段的 SQL 结果，对排查像 filtered_sessions_v2 → mv_daily_pages 这类管道链中数据在哪一层“断掉”非常有用。

物化与 Copy Pipes

tb materialization ls                 # 列出所有物化
tb copy ls                            # 列出所有 copy pipes
tb copy run <pipe_name>               # 手动执行一个 copy pipe
tb copy run <pipe_name> --param key=value  # 带参数执行

Ghost 的 pipes/ 目录中有 mv_hits、mv_session_data_v2、mv_daily_pages 等物化管道文件，与 fixtures 更新后“物化视图不清旧数据”的告诫相互印证——手动触发 copy/物化重建是维护测试数据一致性的重要手段。

测试命令

tb test run                 # 运行完整测试套件
tb test run <file_or_test>  # 运行特定测试文件或测试
tb test update <file_or_test>  # 更新测试期望值

Tinybird 的 README 指出：tb dev 运行时会自动执行 test run，即开发监听模式下端点测试套件随每次变更自动回归。Ghost 的 tests/ 目录包含 29 个端点 YAML 测试文件，每个都基于 fixtures 的固定合成数据做精确输出断言，使得 tb dev 的自动测试在 Ghost 中具备了真实的防护价值：改动任何一个 .pipe 的 SQL，只要 KPI 输出变了，测试套件就会失败。

Mock 数据的替代方案：fixtures + append

规范中一条重要的版本变更：tb mock 命令已在 CLI 4.0 中移除。替代方式是：

1. 使用 fixtures/ 目录（或 agent skills）生成样例数据；
2. 通过 tb datasource append 注入。

Ghost 恰好采用且只采用这一模式：fixtures/analytics_events.ndjson 提供合成事件，测试端点文件（如 api_kpis_v2.yaml）断言其聚合结果。若你在 Ghost 中查找任何 tb mock 的残留用法，应转向“fixture 文件 + tb datasource append”的替代链路。

Tokens 与 Secrets

tb token ls                 # 列出所有 token
tb secret ls                # 列出所有 secret
tb secret set <name> <value>  # 创建或更新 secret
tb secret rm <name>         # 删除 secret

Token 在 Ghost 链路里贯穿始终：analytics_events.datasource 声明 tracker 与 analytics-service 两个 APPEND token；Docker 的 entrypoint.sh 则通过 Tinybird API 的 /v0/tokens 端点按 ADMIN scope 查找 admin token（比按名字匹配更稳健），再按名字取出 tracker token，最终写入 Ghost 与 Analytics 服务共享的 .env.tinybird。Tinybird README 的提示“需要读写权限就用同时具备两种权限的 token”在使用 tb token ls 挑选 token 时应予遵循。

Connections 与 Sinks

tb connection ls   # 列出所有连接
tb sink ls         # 列出所有 sinks

连接（如 S3/GCS）与数据源的 tb datasource sync 命令配套使用，属于 Ghost 当前以本地 append 为主的开发场景之外的运维能力。

Jobs 管理

tb job ls               # 列出所有 job
tb job cancel <job_id>  # 取消正在运行的 job

--wait 类操作（如 tb datasource delete --wait）背后都是 job，tb job ls/cancel 提供了对这些异步任务的观察与中止手段。

Branches：Tinybird Cloud 分支开发

tb branch ls                                  # 列出所有分支
tb branch create <name>                        # 创建新分支（初始为空）
tb branch create <name> --last-partition       # 带最新生产数据分区创建分支
tb branch rm <name>                           # 删除分支
tb branch clear                               # 清除分支状态
tb --branch <name> token ls                   # 查看指定分支的 token
tb --branch <name> endpoint data <pipe>       # 在指定分支上测试端点

从命令设计看，分支工作流的关键在于“带生产最新分区创建分支”（--last-partition）与全局 --branch 覆盖参数（前文 Build/Deploy Context 一节）：先在分支上 tb dev 迭代、tb endpoint data 验证端点，再走 tb deploy 回到生产。这与 CLI 4.0 “配置一次 dev_mode、日常用裸 tb build/tb deploy” 的原则是一致的——分支只是把开发目标从 local 换成了 Cloud 上的隔离分支。

Tinybird Local 容器管理

tb local start               # 启动 Tinybird Local 容器
tb local stop                 # 停止 Tinybird Local
tb local restart --yes        # 重启
tb local status               # 查看状态
tb local remove               # 完全移除
tb local version              # 查看 Tinybird Local 版本
tb local clear                # 清除本地 workspace 状态

Ghost 根级脚本 pnpm tb 的第一段正是 tb local start：先确保容器存在，再进入 tb dev。当本地数据混乱到无法用 truncate 修复时，tb local clear（清 workspace 状态）是最后的“硬重置”手段。

Workspace 管理

tb workspace ls           # 列出所有 workspace
tb workspace current      # 显示当前 workspace
tb workspace clear --yes  # 清除 workspace 状态

配合 tb info（显示项目信息与 CLI 上下文）使用，可以在多 workspace 场景下确认命令到底指向哪里。Docker 链路中 tb --output json info 输出的 .local.workspace_id 与 .local.token 字段，就是 Ghost 自动配置 Tinybird Local 连接的信息来源。

认证

tb login    # 通过浏览器认证
tb logout   # 移除认证
tb update   # 升级 CLI 到最新版本

关于 tb update，Ghost 的 Docker 镜像给出了反向操作的最佳实践：不跟随最新版，而是用 uv tool install tinybird@4.6.13 锁定版本，并注释了升级风险（见 docker/tb-cli/Dockerfile）。在数据管道仓库中，CLI 版本应该像依赖一样被显式管理。

小结：Ghost 仓库中 tb 命令的完整工作流

结合上述各节，Ghost 仓库中一个典型的本地分析开发流程是：

# 1. 启动环境（Docker 路线，推荐）
docker compose --profile analytics up -d

# 2. 通过 tb-cli 服务执行任意 tb 命令
docker compose run --rm -it tb-cli tb info
docker compose run --rm -it tb-cli tb token ls

# 3. 本地持续开发（本机已装 CLI 时）
pnpm tb:install   # 仅首次
pnpm tb           # tb local start + tb dev（自动跑端点测试）

# 4. 测试数据：truncate 后再从 fixtures 追加，保证物化视图一致
# 5. 端点验证：tb endpoint data <pipe> 带参数测试
# 6. 部署：tb deploy（生产）/ tb deployment create + promote（staging 流程）

这份命令规范的实用价值在于：它把 Tinybird CLI 4.0 的命令面、Ghost 仓库的真实数据文件布局（datasources / pipes / endpoints / fixtures / tests）以及 Docker 自动化链路（compose.dev.analytics.yaml + docker/tb-cli）串联成了一条可复制、可验证的操作路径，同时以“不臆造命令、先 --help 后使用”的纪律约束保证了操作可靠性。