tinybird-deploy

Tinybird 部署技能

将可观测性管道和数据源部署到 Tinybird Cloud。

要求

• 部署前检查： which -a tb && tb --version。如果找不到 tb，或解析到的是 pyenv/pip shim，而不是 ~/.local/bin/tb，则 PATH 配置有误，或尚未安装 Forward CLI——请修正 PATH，或引导用户查看安装文档；不要通过 curl 管道运行安装程序。
• 使用 Tinybird Forward CLI，并将其命令记作 tb。在此计算机上，它应解析到 ~/.local/bin/tb，并支持 tb --cloud deployment create --check。
• 不要使用 pip install tinybird-cli 安装或更新此工作流；这可能会导致 Classic CLI 在 PATH 中优先。
• 如果缺少 tb --cloud，或者 Tinybird 表示这是一个 Forward 工作区，但 CLI 是 Classic，请修正 PATH，使 ~/.local/bin 优先。Classic CLI 仅以 tb-classic 的名称保留。
• 从 enter.pollinations.ai/observability 运行命令。
• 显式将 TB_TOKEN 设置为对目标工作区具有 WORKSPACE:DEPLOY 权限的令牌，并在每条部署命令中传入 --host。不要依赖 .tinyb 或 tb workspace use 选择工作区。
• SELECT 1 执行成功并不意味着令牌可以读取数据源（PIPES:READ 与 DATASOURCES:READ、WORKSPACE:DEPLOY 权限不同）。在为新路径使用令牌之前，先对已知数据源执行 SELECT 查询进行探测。

工作区

有两个工作区，使用同一区域（gcp-europe-west2）。两个工作区中的管道和数据源必须保持同步。

工作区	接收流量的来源	UI
pollinations_enter	仅生产 worker	https://cloud.tinybird.co/gcp/europe-west2/pollinations_enter
pollinations_enter_staging	staging worker、dev worker 和本地 npm run dev	https://cloud.tinybird.co/gcp/europe-west2/pollinations_enter_staging

工作区路由由令牌决定：同一个区域主机服务于两个工作区，令牌负责选择工作区。

本地 .tinyb 已加入 gitignore，不能依赖它来选择生产或 staging 环境。请从 macOS Keychain 设置 TB_TOKEN，不要使用 Enter 运行时 SOPS 文件（这些文件只存放 Worker 的读取/摄取令牌）。staging 环境使用 staging 工作区的部署令牌，生产环境使用生产工作区的部署令牌。不要将令牌写入日志。

运维部署令牌存储在 macOS Keychain 中（与 SOPS age 密钥的存储方式相同）：

# staging (pollinations_enter_staging)
TB_TOKEN="$(security find-generic-password -a "$USER" -s tinybird-staging-deploy -w)"
# prod (pollinations_enter)
TB_TOKEN="$(security find-generic-password -a "$USER" -s tinybird-prod-deploy -w)"

部署前务必确认令牌对应的工作区：tb --cloud --host "$TB_HOST" info 会输出 workspace_name。

目录结构

enter.pollinations.ai/observability/
├── datasources/       # Data source definitions (.datasource)
│   ├── generation_event_v2.datasource
│   ├── polar_event.datasource
│   ├── stripe_event.datasource
│   └── ...
└── endpoints/         # Pipe definitions (.pipe)
    ├── weekly_usage_stats.pipe
    ├── weekly_active_users.pipe
    ├── daily_stripe_revenue.pipe
    └── ...

---

命令

每个 shell 会话中设置一次区域，并从 Keychain 获取 staging 部署令牌：

TB_HOST="https://api.europe-west2.gcp.tinybird.co"
TB_TOKEN="$(security find-generic-password -a "$USER" -s tinybird-staging-deploy -w)"
export TB_HOST TB_TOKEN

步骤 1：验证（试运行）

部署前务必先验证。对 staging 运行此命令是安全的。

tb --cloud --host "$TB_HOST" deployment create --check --no-allow-destructive-operations

输出示例：

| status   | name                  | type     | path                                 |
|----------|-----------------------|----------|--------------------------------------|
| modified | weekly_usage_stats    | endpoint | endpoints/weekly_usage_stats.pipe    |

步骤 2：部署

如果验证通过，先部署到 staging。deployment create --wait 会创建 staging 部署并等待其就绪。除非传入 --auto，否则不会提升部署。

tb --cloud --host "$TB_HOST" deployment create --wait --no-allow-destructive-operations

除非用户明确要求提升部署，否则绝不要传入 --auto 或运行 deployment promote。

部署到生产环境时，命令格式相同，但必须先显式将 TB_TOKEN 替换为 Keychain 中的 tinybird-prod-deploy 令牌，并且只能在 staging 验证和确认之后进行。在 #11127 解决之前，部署到两个工作区仍需手动操作。

部署到 staging 和生产环境需要分别获得批准——不要将两者合并成一条命令，因为用户可能想先查看 staging。但如果指令已明确提到两者（“部署到 staging 和生产环境”），则表示两项批准都已获得；中途不要再次询问。

步骤 3：确认

使用同一工作区的读取令牌确认 staging 部署，并测试已部署的端点。

set -o pipefail
tb --staging --cloud --host "$TB_HOST" endpoint ls
tb --cloud --host "$TB_HOST" deployment ls

TINYBIRD_TOKEN="$(SOPS_AGE_KEY=$(security find-generic-password -a "$USER" -s sops-age-key -w 2>/dev/null || true) \
  sops -d ../secrets/staging.vars.json | jq -r '.TINYBIRD_READ_TOKEN')"
curl -fsS "https://api.europe-west2.gcp.tinybird.co/v0/pipes/weekly_usage_stats.json?weeks_back=12" \
  -H "Authorization: Bearer $TINYBIRD_TOKEN" | jq -e '
    if has("error") then error(.error)
    elif (.data | type) != "array" then error("Missing data array")
    else .data | length end'

确认生产环境时，将 staging.vars.json 替换为 prod.vars.json，且不要使用 --staging。

---

安全功能

标志	说明
--check	验证但不进行更改（试运行）
--wait	等待部署完成
--no-allow-destructive-operations	阻止移除数据源（默认）
--allow-destructive-operations	删除数据源时必需
--auto	自动提升已就绪的部署；除非明确要求，否则不要使用

---

常见任务

添加新 Pipe

1. 在 endpoints/ 中创建 .pipe 文件
2. 对照 staging 进行验证
3. 部署到 staging 并验证；仅在收到请求时部署到 prod

修改现有 Pipe

与上述步骤相同：编辑、对照 staging 验证、部署到 staging 并验证；仅在收到请求时部署到 prod。

在 UI 中查看 Pipe

• Prod：https://cloud.tinybird.co/gcp/europe-west2/pollinations_enter/pipes
• Staging：https://cloud.tinybird.co/gcp/europe-west2/pollinations_enter_staging/pipes

---

故障排查

“tb: command not found”

确保 ~/.local/bin 位于 PATH 中，然后打开新的 shell。此工作流不要通过 pip install tinybird-cli 安装 Classic CLI。

“This is a Tinybird Forward workspace” / Classic CLI 错误

which -a tb
tb --version
tb --help | rg "deployment"

tb 应该是 Forward CLI。如果第一个 tb 路径位于 /Library/Frameworks/Python.framework/... 下，则 PATH 配置错误；请使用 ~/.local/bin/tb 或修正 PATH。

验证报告显示数据源或 Pipe 将被删除

调查删除原因。从 staging pull 中的 temp/ 恢复意外缺失的定义。如果任务中需要在 staging 有意执行迁移或重置，请验证工作区，并遵循根目录 AGENTS.md 的可丢弃 staging 规则，使用 --allow-destructive-operations 重新运行。删除生产环境内容需要明确授权。

Pipe 超时问题

如果 Pipe 因 weeks_back 较大而超时：

• 使用 uniq() 代替 uniqExact() 统计用户数（速度约快 10 倍）
• 避免使用 CTE + JOIN 模式，改用单次遍历查询
• 对开销较大的聚合考虑使用物化视图

物化视图验证问题

• Forward 物化视图不能使用 UNION；请将数据源拆分为单独的物化 Pipe，并写入同一个数据源。
• 使用 deployment create --check 进行验证；较早的本地检查并不足够。
• 某些端点 Pipe 中的查询时去重可能无法通过验证。条件允许时，优先在物化过程中去重。

---

重要说明

• 始终使用 --cloud：否则 CLI 会尝试使用 Tinybird Local。
• 不要使用 tb push：它已不再适用于此工作流。
• 避免使用 tb deploy：使用明确的 deployment create 命令，避免意外提升部署。
• 破坏性操作：遵循根目录 AGENTS.md 中有关 staging 和生产环境的规则；上述命令默认执行非破坏性验证和部署。
• 从 observability 目录运行：不要从仓库根目录运行。