tiltup

Tilt Up

原则（始终生效）

使用 Tiltfile、排查 Tilt 错误或启动开发环境时，始终遵循以下原则：

修复 Tiltfile，而不是症状

• 直接修复源配置——Tiltfile、Dockerfile、k8s 清单或 helm values
• 绝不添加 shell 变通方案——不使用包装脚本、|| true 或 try/except pass
• 绝不硬编码应该动态确定的端口、路径、主机名、镜像标签或容器名称
• 绝不添加掩盖真实错误的回退方案——如果资源失败，必须让失败明确可见
• 绝不为不稳定的依赖项添加 sleep/retry 循环——通过 resource_deps() 或 k8s_resource(deps=) 修复依赖顺序
• 绝不为 Tilt 已处理的就绪状态添加轮询——使用 k8s_resource(readiness_probe=) 或探测配置

以声明方式表达依赖关系

• 端口冲突：修复端口分配的源头，不要换用其他端口
• 资源顺序：使用 resource_deps()，不要使用顺序启动脚本
• 环境变量：使用 silo.toml 或 gen-env 输出，不要内联默认值
• 镜像可用性：使用 image_deps 或 deps，不要等待镜像就绪

Tilt 会实时重新加载

编辑 Tiltfile 后，Tilt 会自动获取更改。绝不要为了以下情况重启 tilt up：

• Tiltfile 编辑
• 源代码更改
• Kubernetes 清单更新

仅在以下情况重启：升级 Tilt 版本、更改端口/主机配置、发生崩溃、切换集群上下文。

工作流（明确启动 Tilt 时）

步骤 1：评估当前状态

1. 检查 tilt 是否已在运行：

   PROJECT=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" || basename "$PWD")
   zmx list --short 2>/dev/null | grep -q "^${PROJECT}-tilt$"
   

   如果正在运行，通过 tilt get uiresources -o json 检查健康状态，然后跳到步骤 3。

2. 检查必需的环境文件（.localnet.env、.env.local、silo.toml）：

   • 如果存在 silo.toml，使用 silo up 路径
   • 如果存在 gen-env 脚本，先运行
   • 如果两者都不存在，查看项目 README 中的启动说明

3. 检查 k3d 集群或 Docker 前置条件。

步骤 2：在 zmx 中启动 Tilt

遵循 zmx 技能的模式：

PROJECT=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" || basename "$PWD")
SESSION="${PROJECT}-tilt"

if zmx list --short 2>/dev/null | grep -q "^${SESSION}$"; then
  echo "Tilt session already exists: $SESSION"
else
  zmx run "$SESSION" 'tilt up'
  echo "Started tilt in zmx session: $SESSION"
fi

对于 silo 项目，使用 silo up 代替 tilt up。

步骤 3：监控启动过程

轮询直至收敛：

1. 等待 10s，让资源完成初始注册
2. 每隔 15s 轮询一次，最多 20 次。包括 docker-compose 容器健康状态 （composeResourceInfo.healthStatus）——状态为 Up (unhealthy) 的 compose 容器 会保持 runtimeStatus=ok，且不会在其他地方显示，因此启动过程看起来可能 已“完成”，但 canton/splice/postgres 实际上正悄无声息地未通过 HEALTHCHECK：

   tilt get uiresources -o json | jq -r '.items[] | select(.status.runtimeStatus == "error" or .status.updateStatus == "error" or .status.updateStatus == "pending" or .status.composeResourceInfo.healthStatus == "unhealthy") | "\(.metadata.name): runtime=\(.status.runtimeStatus) update=\(.status.updateStatus) compose=\(.status.composeResourceInfo.healthStatus // "-")"'
   

3. 跟踪资源状态：pending -> in_progress -> ok
4. 成功条件：所有资源均达到 runtime=ok, update=ok（或 not_applicable）， 且没有任何 docker-compose 资源的 composeResourceInfo.healthStatus == "unhealthy"
5. 如果资源稳定处于 error 状态，或者某个 compose 资源持续处于 unhealthy， 则继续执行步骤 4。对于不健康的 compose 探测，通过 docker inspect <compose-project>-<svc> --format '{{json .State.Health}}' 查看真实原因—— 通常是挂载的健康检查脚本调用了镜像中不存在的 CLI（服务本身已启动；应修复探测脚本，而不是禁用检查）

步骤 4：诊断并修复错误

对于每个处于错误状态的资源：

1. 查看日志：tilt logs <resource> --since 2m
2. 阅读 Tiltfile 和相关的 k8s 清单
3. 在配置中（而非运行中的进程）找出根本原因
4. 遵循上述原则应用修复
5. Tilt 会实时重新加载——再次轮询状态以确认

对同一资源尝试修复 3 次仍无进展后：

• 提供完整日志并报告错误
• 判断问题属于 Tiltfile 缺陷、上游依赖项问题还是基础设施问题
• 不要悄悄跳过或禁用该资源

步骤 5：报告

## Tilt Status: <healthy|degraded|errored>

**Resources**: X/Y ok
**Session**: zmx $SESSION

### Errors (if any)
- <resource>: <root cause> — <what was fixed or what remains>