Ghost 中的 Tinybird 开发工作流：dev_mode、tb dev 与三种开发模式实战指南

Ghost 仓库的 .agents/skills/tinybird-cli-guidelines/rules/development-workflows.md 定义了使用 Tinybird CLI（tb）构建数据分析管道时的三种开发工作流：Local、Branch 和 Cloud Direct。本文基于该文档展开，并结合仓库中的技能规则文件（branch-development.md、local-development.md、ci-cd.md）和 docker/tb-cli/Dockerfile 等实现证据，讲解如何为 Ghost 这类依赖 Tinybird 分析服务的项目选择合适的开发模式、配置 tinybird.config.json、完成本地迭代并走向 CI/CD 部署。读完后你应能独立完成：配置 dev_mode、运行 tb dev 监听构建、用分支隔离环境测试生产数据、以及用 tb endpoint data 验证端点输出。

一、三种开发工作流总览

Tinybird 支持三种开发工作流，选择依据是团队规模、基础设施条件和迭代速度需求：

工作流	适用场景	前置要求	数据来源
Local（dev_mode=local）	独立开发、快速迭代、离线工作	Docker	Fixtures 或手动追加的数据
Branch（dev_mode=branch）	团队协作、生产级测试	Tinybird Cloud workspace	可选地从生产复制数据
Cloud Direct	简单项目、快速原型	Tinybird Cloud workspace	生产数据

三种模式的核心差异在于构建目标的隔离级别：Local 完全运行在本地 Docker 容器内，无网络依赖；Branch 由 Tinybird Cloud 提供隔离环境，每个 git 分支对应一个云端分支环境；Cloud Direct 则直接对 Cloud 工作区操作。

前置条件：CLI 版本与 dev_mode 机制

从 SKILL.md 的 Quick Reference 可以确认，Tinybird CLI 4.0 引入了 dev_mode 配置机制：

• 在 tinybird.config.json 中一次性配置 dev_mode，之后使用无修饰的 tb build 和 tb deploy 即可；
• tb build 会构建到你配置的发育环境（branch 或 local），而 tb deploy 始终指向 Tinybird Cloud 生产环境；
• --cloud / --local / --branch 仅作为显式的手动覆盖（override）保留；
• 使用 tb info 检查当前 CLI 上下文；
• 测试端点统一使用 tb endpoint data <pipe>，而不是 tb pipe data；
• 规则强调"Never invent commands or flags; run tb <command> --help to verify"——不要凭空捏造命令或参数，先用 --help 验证。

在 Ghost 仓库中，这一机制有真实的版本落地：docker/tb-cli/Dockerfile 将 Tinybird CLI 固定为 4.6.13（ARG TINYBIRD_VERSION=4.6.13），基础镜像为 Python 3.13（Tinybird CLI 要求 Python >= 3.10, < 3.14）。Dockerfile 中还记录了一个重要的版本回退原因：4.6.14 会把嵌套 JSON 对象以 ClickHouse Tuple 语法摄入 String 列，导致 JSONExtractString 对 analytics_events.payload 返回空字符串，因此 Ghost 在 4.6.13 上固定版本——这是 analytics_events 这类 payload 型数据源在实际生产管道中遇到的典型兼容性问题，也说明了 Ghost 分析管道确实重度依赖 Tinybird。

二、推荐工作流：Branch 模式（dev_mode=branch）

文档明确建议：对大多数项目使用 dev_mode=branch。它提供由 Tinybird Cloud 支撑的隔离环境，并可选地访问生产数据。配置方式是在 tinybird.config.json 中写入：

{
  "dev_mode": "branch"
}

完整工作流五步

1. 为你的功能创建 git 分支；
2. 运行 tb dev —— Tinybird 会根据 git 分支名自动创建同名 Cloud 分支，随后监听文件变化并自动重建资源；
3. 开发与测试：tb endpoint data <pipe_name>；
4. 推送并创建 PR —— CI 中运行 tb --cloud deploy --check 做部署前校验；
5. 合并 —— CD 中运行 tb --cloud deploy 部署到生产。

分支的创建方式与命名约束

结合 branch-development.md 的细节：

• 自动创建（推荐）：检出 git 分支后运行 tb dev 或 tb build，Tinybird 会自动创建（或复用）与 git 分支同名的 Cloud 分支；
• 手动创建：tb branch create my_feature；
• 命名约束：分支名必须使用下划线而非连字符（例如 my_feature，而不是 my-feature）。

--last-partition：把生产数据带入分支

tb branch create my_feature --last-partition

该标志会把生产的最新分区数据复制到分支中。当你需要真实数据形状来测试查询、验证端点行为或调试依赖生产数据的问题时非常有用；不加该标志，分支从空数据开始。

--with-connections：在分支中启用连接器

tb branch create my_feature --last-partition --with-connections

该标志启用 Kafka、S3、GCS 连接器。注意事项：

• S3/GCS：用 tb --branch=my_feature datasource sample <datasource> --wait 导入样例数据；
• Kafka：连接默认停止，需用 tb --branch=my_feature datasource start <datasource> 显式启动。

分支 Token：让客户端应用切换环境

创建分支后，客户端应用（仪表盘、API 消费者、脚本）可能需要用分支 token 连接到分支环境而非生产。列出分支 token：

tb --branch my_feature token ls

仓库文档给出了一个常见的 .env.local 模式——设置环境变量让应用优先使用分支 token，未设置时回退到生产 token：

# .env.local
TINYBIRD_API_URL=https://api.tinybird.co
TINYBIRD_API_TOKEN=<production-read-token>
TINYBIRD_BRANCH_TOKEN=<branch-token>

应用内优先取分支 token：

token = TINYBIRD_BRANCH_TOKEN || TINYBIRD_API_TOKEN

这样只需设置或取消分支 token 就能在分支数据与生产数据之间切换，无需改代码。

分支命令速查

命令	作用
tb branch ls	列出所有分支
tb branch create <name>	创建空分支
tb branch create <name> --last-partition	带最新生产数据的分支
tb branch create <name> --last-partition --with-connections	带数据和连接器的分支
tb branch rm <name>	删除分支
tb branch clear	清空分支状态
tb dev	启动开发会话（按 git 分支名自动建分支、监听文件）
tb --branch <name> open	在 Tinybird UI 中打开分支

大多数命令都可用 --branch 标志显式指向某个分支：

tb --branch my_feature endpoint data my_endpoint
tb --branch my_feature sql "SELECT count() FROM my_datasource"
tb --branch my_feature token ls

当 dev_mode=branch 时，tb build 会自动指向分支环境，无需再手动加 --branch。

何时使用分支

适合分支场景包括：需要真实生产数据形状测试的功能开发；多人在同一 workspace 协作；在生产前测试 schema 变更或新端点；以及在 PR 上验证变更的 CI/CD 流程。从源码结构看，Ghost 仓库的 e2e 基础设施（e2e/scripts/sync-tinybird-state.mjs、compose.e2e.tinybird-slim.yaml、docker/tb-cli 等）与 Tinybird 本地/云端状态同步深度绑定，可以推断分支工作流正是其分析管道在 PR 阶段做隔离验证的支撑方式。

三、Local 工作流（dev_mode=local）

当需要无网络依赖的快速迭代时使用 dev_mode=local，适合开发 SQL 逻辑并用 fixture 数据测试。配置：

{
  "dev_mode": "local"
}

完整工作流五步

1. 启动 Tinybird Local：tb local start；
2. 新开终端运行 tb dev —— 监听文件变化并自动重建；
3. 追加测试数据：tb datasource append <name> --file fixtures/<name>.ndjson；
4. 测试端点：tb endpoint data <pipe_name>；
5. 准备好后部署：tb --cloud deploy。

Tinybird Local 命令集

结合 local-development.md，Tinybird Local 以 Docker 容器形式运行、由 CLI 管理，完整命令集如下：

• tb local start，可选参数：--use-aws-creds、--volumes-path <path>、--skip-new-version、--user-token、--workspace-token、--daemon；
• tb local stop；
• tb local restart，可选参数：--use-aws-creds、--volumes-path、--skip-new-version、--yes；
• tb local status；
• tb local remove；
• tb local version；
• tb local generate-tokens。

两个关键注意点：

• 如果在没有持久化卷的情况下移除容器，本地数据会丢失。要跨重启保留数据，使用 --volumes-path 指定持久化目录；
• --local、--cloud、--branch 这些手动标志依然可用，作为 dev_mode 之上的显式覆盖。

tb dev：推荐的开发命令

tb dev 是文档推荐的开发命令：它监听项目文件，检测到变化后自动重建 Data Source 和 Endpoint。此外：

• tb dev --ui：以 watch 模式构建，并把本地项目连接到 Tinybird UI，便于可视化查询结果、探索数据源 schema、调试 pipe 逻辑；
• tb open：在浏览器中打开 workspace。

Local 模式排障

• 状态显示 unhealthy：运行 tb local restart 后重新检查；
• 认证未就绪：等待或重启容器；
• 状态中出现内存告警：调大 Docker 内存分配；
• Local 未运行：用 tb local start 启动。

四、Cloud Direct 工作流

对于简单项目或快速原型，可以直接对 Cloud 工作区开发。部署有两种写法：

显式两步流程（create + promote，便于人工确认）：

tb --cloud deployment create --wait
tb --cloud deployment promote

或者一步合并命令：

tb --cloud deploy

从 ci-cd.md 的实现细节可以确认：tb --cloud deploy 会创建 staging deployment、迁移数据并 promote 到 live；--wait 让 CI 任务反映真实的部署结果。显式两步流程的价值在于把"创建部署"和"提升上线"拆成可独立确认的两次操作，在需要人工审批的场景下更安全。

五、如何选择工作流

文档给出的决策规则：

• 新项目起步？ 先用 Local 快速搭建骨架，等需要生产数据或团队协作时切换到 Branch；
• 有共享 workspace 的团队项目？ 用 Branch，每位开发者拥有隔离环境；
• 快速原型或演示？ Cloud Direct 即可；
• CI/CD 流水线？ 用 Tinybird Local 做 CI 构建与测试，再用 tb --cloud deploy 发生产。

CI/CD 场景的落地细节

结合 ci-cd.md，CI 推荐模式为：

1. tb --local build —— 对 Tinybird Local 构建项目；
2. tb --local test run —— 对 Tinybird Local 运行测试；
3. tb --cloud deploy --check —— 在 Cloud 侧做 dry-run 校验。

deploy --check 会在问题到达生产前捕获 schema 兼容性、依赖解析和资源命名问题。CD 侧在 main 分支合并时运行 tb --cloud deploy。

文档还给出完整的 GitHub Actions 示例骨架（tinybird-ci.yml / tinybird-cd.yml），核心是：用 tinybirdco/tinybird-local:latest 作为 service 容器并暴露 7181 端口，环境变量注入 TINYBIRD_HOST（https://api.tinybird.co）与 TINYBIRD_TOKEN（取自 CI secret），CI 触发路径限定在 tinybird/** 以避免无关流水线运行。关键原则包括：生产部署必须走 CI/CD 而非手动；admin token 只存 CI secret 不入代码；CD 使用 --wait。

另一个可选能力是预览环境（Preview Environments）：为每个 PR 创建临时 Tinybird 分支，在合并前用生产数据测试。SDK 侧 tinybird preview 命令会创建名为 tmp_ci_<git-branch> 的分支并部署资源；而 tb CLI 没有 preview 子命令，需手动 tb branch create tmp_ci_xxx --last-partition + tb --branch=tmp_ci_xxx build，PR 关闭时再用 tb branch rm 清理。注意带连接器的项目需手动加 --with-connections，因为 tinybird preview 不会在预览分支中摄入连接器数据。

六、端点测试：为什么用 tb endpoint data 而不是 tb pipe data

三种工作流中反复出现的验证命令是 tb endpoint data：

tb endpoint data my_endpoint
tb endpoint data my_endpoint --start_date 2024-01-01 --end_date 2024-01-31

文档明确强调：用 tb endpoint data，不用 tb pipe data。原因是 endpoint data 以 API 消费者的身份调用端点，包含参数校验和输出格式化——它验证的正是线上真实请求路径。而 tb pipe data 只查询 pipe 本身，绕过了端点层的参数定义（如 --start_date/--end_date 这类参数绑定）与输出行为。对 Ghost 这种以 API 形式对外提供分析数据的场景，endpoint data 才是能反映真实消费行为的验证手段。

七、总结：一条完整的开发链路

把文档与仓库证据串联起来，Ghost 分析管道的完整开发生命周期是：

1. 配置：在 tinybird.config.json 中设置 dev_mode（local、branch 或省略走 Cloud Direct）；
2. 迭代：tb dev 监听文件并自动重建，目标环境由 dev_mode 决定（Local 容器或自动创建的 Cloud 分支）；
3. 验证：tb endpoint data <pipe> 按 API 消费者语义测试端点，可带日期参数复现真实查询窗口；
4. 隔离测试：团队场景用 --last-partition 分支拿生产数据形状，必要时 --with-connections 启用 Kafka/S3/GCS 连接器；
5. CI 校验：PR 上 tb --local build + tb --local test run + tb --cloud deploy --check；
6. CD 发布：合并后 tb --cloud deploy（或 deployment create --wait + deployment promote 两步确认）。

理解 dev_mode 与 tb build / tb deploy 的指向关系（前者指向发育环境、后者指向生产）是这套工作流的核心；仓库中固定 CLI 4.6.13 的 Dockerfile 注释 则提醒我们：即使工作流本身稳定，CLI 版本与 ClickHouse 行为之间的兼容性问题仍需要以仓库实际固定版本为准。