Ghost Tinybird Build & Deploy 目标定位指南：tb build 与 tb deploy 如何决定作用环境
【免费下载链接】GhostIndependent technology for modern publishing, memberships, subscriptions and newsletters.项目地址: https://gitcode.com/GitHub_Trending/gh/Ghost
本文基于 Ghost 仓库内的 Agent 技能规则文档.agents/skills/tinybird/rules/build-deploy.md，系统讲解 Tinybird CLI 4.0 中tb build与tb deploy的目标环境（targeting）判定机制：tinybird.config.json如何作为构建目标的事实来源、dev_mode的local/branch两种取值分别指向哪里，以及--cloud、--branch等显式覆盖参数的用法。读完本文，你可以按仓库既定规范完成 Tinybird 数据管道的本地构建、分支验证与云端生产发布，并理解 Ghost 开发栈中tb --local build的真实调用位置。
项目初始化与配置事实来源
按规则文档的要求，新的 Tinybird 项目统一从tb init开始，并以tinybird.config.json作为tb build目标定位的唯一事实来源（source of truth）。仓库给出的标准配置示例如下：
{ "dev_mode": "branch", "include": [ "tinybird" ] }其中：
dev_mode：决定tb build默认作用到哪个开发环境，取值只能是local或branch（见下文"tb build 目标定位"）；include：声明项目内包含 Tinybird 数据文件的目录，示例中为项目根下的tinybird/目录。
CLI 4.0 的工作流设计要点是"配置一次，命令简洁"：只需把dev_mode配好，后续开发就使用不带环境参数的tb build和tb deploy，而--cloud、--local、--branch只作为手动临时覆盖使用。这一点在 Tinybird CLI 技能总览 的 Quick Reference 中被再次强调，并建议用tb info随时检查当前 CLI 上下文。
Build/Deploy 三步流程
规则文档将构建与部署收敛为严格的三步流程：
- 从
tinybird.config.json读取dev_mode； - 按配置的开发目标执行
tb build（即构建到本地容器或云端分支，而非生产）； - 只有当明确要求部署到云端生产时，才执行
tb deploy。
这条流程的核心约束是第三条：tb build绝不能被视为生产部署。tb build只验证并构建项目资源到开发目标环境；生产环境的变更必须显式走tb deploy路径。该约束与 Tinybird 最佳实践总览 中 "Build target comes fromtinybird.config.jsondev_mode(localorbranch)；tb deploytargets Tinybird Cloud production" 的速查结论完全一致。
tb build 目标定位：local 与 branch
dev_mode的两个取值对应两条截然不同的开发路径：
dev_mode: "local"——tb build针对Tinybird Local执行，即由 CLI 管理的本地 Docker 容器，适合快速迭代、离线开发和 fixture 数据测试；dev_mode: "branch"——tb build针对一个Tinybird Cloud 分支执行，分支环境由云端工作区支撑，可选地从生产数据复制分区，适合团队协作与接近生产的测试。
配套的开发工作流细节可参见 development-workflows.md 与 local-development.md：本地路径推荐tb local start启动容器后用tb dev（等价于tb build --watch）监听文件并自动重建；分支路径推荐tb dev按 git 分支名自动创建云端分支并热重建，再用tb endpoint data <pipe_name>以消费者视角验证端点输出（注意使用tb endpoint data而不是已废弃语义的tb pipe data）。
tb deploy 目标定位：云端生产与显式确认
部署命令的行为边界在规则中逐条写明：
tb --cloud deploy部署到Tinybird Cloud 生产环境，完整过程是：创建 staging 部署 → 迁移数据 → 提升到 live；- 不带
--cloud的tb deploy与tb --cloud deploy等价——在 CLI 4.0 中，tb deploy固定指向云端生产，与dev_mode无关； - 不得把
tb build当作生产部署； - 用
tb --cloud deploy --check做不落地应用的部署校验，推荐用于 CI； - 需要显式人工确认时，使用两步流程：
tb --cloud deployment create --wait创建并等待 staging 部署完成，再执行tb --cloud deployment promote将其提升到生产。
这套"check → create → promote"的设计让部署既能自动化（一条tb --cloud deploy），也能拆成可审计的两步操作。对应的完整 CI/CD 模式（PR 阶段tb --local build+tb --local test run+tb --cloud deploy --check，合并主干后tb --cloud deploy，含 GitHub Actions 与 GitLab CI 示例）记录在 ci-cd.md 中。
非构建命令的目标定位：tb sql 与 tb logs
与 build/deploy 不同，tb sql、tb logs等非构建命令默认作用于本地（local），不受dev_mode影响。要指向其他环境必须使用显式覆盖参数：
--cloud：指向云端生产；--branch=<branch-name>：指向指定云端分支。
规则文档给出的完整示例：
tb sql "SELECT 1" tb sql --cloud "SELECT 1" tb sql --branch=feature_metrics "SELECT 1" tb logs tb logs --cloud tb logs --branch=feature_metrics从 cli-commands.md 的 Global Overrides 一节可以看到，这类覆盖参数是全局位置参数（tb --cloud <command>、tb --local <command>、tb --branch <name> <command>），此外还有tb --debug <command>用于输出调试信息；同文档也要求"绝不凭空捏造命令或参数，不确定时先运行tb <command> --help验证"。
仓库实证：Ghost 开发栈中的tb --local build
文档所述的local目标在 Ghost 仓库中有真实、可验证的落地。开发环境通过 Docker Compose 编排 Tinybird Local 与一个专用的tb-cli服务：
- docker/tb-cli/entrypoint.sh 的入口脚本第一步就是执行
tb --local build，把仓库中的 Tinybird 数据文件（.datasource、.pipe等）构建部署到 Tinybird Local 容器；随后通过tb --output json info提取 workspace ID 与 workspace token，再从本地 Tinybird API（http://tinybird-local:7181/v0/tokens）中按ADMINscope 查找 admin token、按名称查找trackertoken，最终将TINYBIRD_WORKSPACE_ID、TINYBIRD_ADMIN_TOKEN、TINYBIRD_TRACKER_TOKEN三个值写入共享卷的.env.tinybird文件，供 Ghost 核心与 Analytics 服务自动建立与 Tinybird Local 的连接； - e2e/scripts/sync-tinybird-state.mjs 在 e2e 测试中通过
docker cp从已退出的tb-cli容器直接拷出同一份.env.tinybird，并解析出 workspace ID 与 token 写入e2e/data/state/tinybird.json；脚本注释特别说明用docker cp而非docker compose run是为了避免重新触发 tb-cli entrypoint（一次完整的数据文件部署）以及 compose 依据配置差异重建依赖容器； - e2e/compose.e2e.tinybird-slim.yaml 则使用精简版 tinybird-local 镜像来压缩 e2e 基础设施的拉取与磁盘开销（e2e/README.md 提到 slim 镜像约 0.7GB 拉取、2.4GB 磁盘）。
从源码结构看，Ghost 的本地与 e2e 环境走的是规则中dev_mode: "local"对应的那条路径（显式tb --local build覆盖），而生产数据的部署则由tb deploy路径负责，两条链路在仓库中边界清晰。
要点速查
| 场景 | 命令 / 配置 | 作用目标 |
|---|---|---|
| 初始化项目 | tb init | 生成含tinybird.config.json的项目 |
| 开发构建 | tb build（读dev_mode） | local→ Tinybird Local；branch→ Cloud 分支 |
| 生产部署 | tb deploy（等价tb --cloud deploy） | Cloud 生产：staging → 数据迁移 → 提升 live |
| CI 预检 | tb --cloud deploy --check | 仅校验，不落地 |
| 显式两步部署 | tb --cloud deployment create --wait+tb --cloud deployment promote | 人工确认后提升 |
| 临时查询/日志 | tb sql/tb logs | 默认 local |
| 显式覆盖 | --cloud、--branch=<name> | 指定 Cloud 生产或某分支 |
核心原则可以浓缩为三句：构建目标由tinybird.config.json的dev_mode决定；tb build永远不碰生产；只有显式的tb deploy才进入云端生产，且建议先--check再部署。遵循这套定位规则，可以在 Ghost 这样的单体仓库中让 Tinybird 数据管道与 Web 服务一样，做到本地可构建、分支可验证、生产可审计。
【免费下载链接】GhostIndependent technology for modern publishing, memberships, subscriptions and newsletters.项目地址: https://gitcode.com/GitHub_Trending/gh/Ghost
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
