tilt

用途

Tilt 是一个开发环境编排工具，用于在 Kubernetes 与 Docker Compose 环境中构建、部署和实时更新服务。本技能面向需要检查部署健康状况、调查错误、读取日志或编写 Tiltfile 的场景，提供通过命令行查询 Tilt 资源状态与管理开发流程的实践指引。

主要能力

查询资源健康状态：使用 tilt get uiresources -o json 配合 jq，按 runtimeStatus / updateStatus 筛选错误、进行中与待处理的资源。
定位失败原因：错误信息从 buildHistory[0].error 读取，而不仅是状态字段。
识别 Docker Compose 健康检查问题：compose 资源的 runtimeStatus/updateStatus 不反映容器 HEALTHCHECK，需检查 .status.composeResourceInfo.healthStatus。
读取日志：tilt logs <resource>，支持 --since、--tail 与 --json。
触发与生命周期管理：tilt trigger <resource> 强制更新，tilt up 启动，tilt down 停止并清理。
等待就绪：tilt wait --for=condition=Ready uiresource/<name> --timeout=120s。

使用方式

首先检查错误，并将错误与 pending/in-progress 分开查询，避免真实失败被大量待处理条目掩盖。示例命令：

# 1. 仅错误
tilt get uiresources -o json | jq -r '.items[] | select(.status.runtimeStatus == "error" or .status.updateStatus == "error") | "\(.metadata.name): runtime=\(.status.runtimeStatus) update=\(.status.updateStatus)\n  reason: \((.status.buildHistory[0].error // "(no buildHistory error; check tilt logs)") | gsub("\n"; " ") | .[0:240])"'

# 2. 进行中与待处理
tilt get uiresources -o json | jq -r '.items[] | select(.status.updateStatus == "in_progress" or .status.updateStatus == "pending" or .status.runtimeStatus == "pending") | "\(.metadata.name): runtime=\(.status.runtimeStatus) update=\(.status.updateStatus)"'

# 3. Docker-compose 容器健康
tilt get uiresources -o json | jq -r '.items[] | select(.status.composeResourceInfo.healthStatus == "unhealthy") | "\(.metadata.name): compose healthStatus=unhealthy (HEALTHCHECK failing — service may still be up)"'

# 4. 状态概览
tilt get uiresources -o json | jq '[.items[].status.updateStatus] | group_by(.) | map({status: .[0], count: length})'

若资源处于 in_progress，在宣告健康前应重新轮询，因为它可能直接转为 error 并带有 buildHistory[0].error。updateStatus 只反映当前构建尝试，最后一次错误始终保存在 buildHistory[0].error 中，即使 updateStatus 为 none 或 not_applicable。

Docker Compose 资源存在盲区：其 runtimeStatus/updateStatus 只反映构建/启动状态，不反映容器的 docker HEALTHCHECK。因此探针失败（docker ps 显示 Up (unhealthy)）的容器仍显示 runtimeStatus=ok，会绕过前两项查询，而 Tilt UI 仍标红。权威信号是 .status.composeResourceInfo.healthStatus（healthy / unhealthy / 无 healthcheck 时缺失）。这类资源 k8sResourceInfo: null（spec.type == "docker-compose"）；如需查明探针失败原因，可执行 docker inspect <compose-project>-<svc> --format '{{json .State.Health}}' 读取探针最后退出码与输出。常见原因是 healthcheck 脚本调用了镜像未包含的 CLI（如精简镜像移除了 curl/grpcurl），此时服务本身正常，是探针有问题。

非默认端口需加 --port：

tilt get uiresources --port 37035
tilt logs <resource> --port 37035

状态值：

RuntimeStatus：ok、error、pending、none、not_applicable
UpdateStatus：ok、error、pending、in_progress、none、not_applicable

运行 tilt up 时，遵循 zmx 技能模式：检查已有会话，从 git 根目录派生会话名，使用 zmx run（而非 attach）：

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

关键提醒：代码变更切勿重启。Tilt 会自动 live-reload，以下情况不要建议重启 tilt up：Tiltfile 编辑、源代码变更、Kubernetes manifest 更新。仅在以下情况重启：Tilt 版本升级、端口/主机变更、崩溃、集群上下文切换。

适用场景

使用 Tilt 管理本地或集群开发环境。
排查构建失败、运行时错误、部署不健康。
读取服务日志、检查资源状态、查看 Docker Compose 健康检查。
编写 Tiltfile 与使用 Tilt CLI。

限制

资料未提供 Tilt 的收费、价格、具体平台支持、性能指标等细节，这些内容暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制