tiltup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tilt Up

启动Tilt

Principles (Always Active)

核心原则（始终适用）

These apply whenever working with Tiltfiles, Tilt errors, or dev environment bootstrap:

以下原则适用于所有Tiltfile编写、Tilt错误排查或开发环境引导场景：

Fix the Tiltfile, Not the Symptoms

修复Tiltfile本身，而非解决表面问题

Fix the source config directly - Tiltfile, Dockerfile, k8s manifest, or helm values
Never add shell workarounds - no wrapper scripts, no
```
|| true
```
, no
```
try/except pass
```
Never hard-code ports, paths, hostnames, image tags, or container names that should be dynamic
Never add fallbacks that mask the real error - if a resource fails, the failure must be visible
Never add sleep/retry loops for flaky dependencies - fix dependency ordering via
```
resource_deps()
```
or
```
k8s_resource(deps=)
```
Never add polling for readiness that Tilt already handles - use
```
k8s_resource(readiness_probe=)
```
or probe configs

直接修复源配置 - Tiltfile、Dockerfile、k8s 清单或 helm 配置值
绝不添加Shell脚本临时方案 - 不使用包装脚本、不写
```
|| true
```
、不使用
```
try/except pass
```
绝不硬编码 动态的端口、路径、主机名、镜像标签或容器名称
绝不添加掩盖真实错误的回退机制 - 若资源启动失败，必须让失败状态可见
绝不添加针对不稳定依赖的睡眠/重试循环 - 通过
```
resource_deps()
```
或
```
k8s_resource(deps=)
```
修复依赖顺序
绝不添加Tilt已处理的就绪状态轮询 - 使用
```
k8s_resource(readiness_probe=)
```
或探针配置

Express Dependencies Declaratively

声明式定义依赖关系

Port conflicts: fix the port allocation source, don't pick a different port
Resource ordering: use
```
resource_deps()
```
, not sequential startup scripts
Env vars: use
```
silo.toml
```
or gen-env output, not inline defaults
Image availability: use
```
image_deps
```
or
```
deps
```
, not sleep-until-ready

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

Tilt Live-Reloads

Tilt 热重载

After editing a Tiltfile, Tilt picks up changes automatically. Never restart
tilt up
for:

Tiltfile edits
Source code changes
Kubernetes manifest updates

Restart only for: Tilt version upgrades, port/host config changes, crashes, cluster context switches.

编辑Tiltfile后，Tilt会自动检测变更。以下情况绝不重启
tilt up
：

Tiltfile 编辑
源代码变更
Kubernetes 清单更新

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

Workflow (When Explicitly Starting Tilt)

操作流程（当明确需要启动Tilt时）

Step 1: Assess Current State

步骤1：评估当前状态

Check if tilt is already running:

bash

SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)
tmux list-windows -t "$SESSION" -F '#{window_name}' 2>/dev/null | grep -q "^tilt$"

If running, check health via

tilt get uiresources -o json

and skip to Step 3.

Check for required env files (
```
.localnet.env
```
,
```
.env.local
```
,
```
silo.toml
```
):
- If
```
silo.toml
```
  exists, use
```
silo up
```
  path
- If gen-env script exists, run it first
- If neither, check project README for bootstrap instructions
Check for k3d cluster or Docker prerequisites.

检查Tilt是否已在运行：

bash

SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)
tmux list-windows -t "$SESSION" -F '#{window_name}' 2>/dev/null | grep -q "^tilt$"

若已运行，通过

tilt get uiresources -o json

检查健康状态，直接跳至步骤3。

检查所需的环境文件（
```
.localnet.env
```
、
```
.env.local
```
、
```
silo.toml
```
）：
- 若存在
```
silo.toml
```
  ，使用
```
silo up
```
  流程
- 若存在gen-env脚本，先执行该脚本
- 若都不存在，查看项目README中的引导说明
检查k3d集群或Docker的前置条件。

Step 2: Start Tilt in tmux

步骤2：在tmux中启动Tilt

Follow the

tmux

skill patterns:

bash

SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)

if ! tmux has-session -t "$SESSION" 2>/dev/null; then
  tmux new-session -d -s "$SESSION" -n tilt
  tmux send-keys -t "$SESSION:tilt" 'tilt up' Enter
elif ! tmux list-windows -t "$SESSION" -F '#{window_name}' | grep -q "^tilt$"; then
  tmux new-window -t "$SESSION" -n tilt
  tmux send-keys -t "$SESSION:tilt" 'tilt up' Enter
else
  echo "Tilt window already exists in session: $SESSION"
fi

For silo projects:

silo up

instead of

tilt up

遵循

tmux

使用模式：

bash

SESSION=$(basename $(git rev-parse --show-toplevel 2>/dev/null) || basename $PWD)

if ! tmux has-session -t "$SESSION" 2>/dev/null; then
  tmux new-session -d -s "$SESSION" -n tilt
  tmux send-keys -t "$SESSION:tilt" 'tilt up' Enter
elif ! tmux list-windows -t "$SESSION" -F '#{window_name}' | grep -q "^tilt$"; then
  tmux new-window -t "$SESSION" -n tilt
  tmux send-keys -t "$SESSION:tilt" 'tilt up' Enter
else
  echo "Tilt window already exists in session: $SESSION"
fi

对于silo项目：使用

silo up

替代

tilt up

。

Step 3: Monitor Bootstrap

步骤3：监控引导过程

Poll for convergence:

Wait 10s for initial resource registration

Poll every 15s, up to 20 iterations:

bash

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

Track resources:
```
pending
```
->
```
in_progress
```
->
```
ok
```
Success: all resources reach
```
runtime=ok, update=ok
```
(or
```
not_applicable
```
)
If resources stabilize in
```
error
```
, proceed to Step 4

轮询收敛状态：

等待10秒，让初始资源完成注册

每15秒轮询一次，最多20次：

bash

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

追踪资源状态：
```
pending
```
->
```
in_progress
```
->
```
ok
```
成功状态：所有资源达到
```
runtime=ok, update=ok
```
（或
```
not_applicable
```
）
若资源稳定在
```
error
```
状态，进入步骤4

Step 4: Diagnose and Fix Errors

步骤4：诊断并修复错误

For each resource in error state:

Read logs:
```
tilt logs <resource> --since 2m
```
Read the Tiltfile and relevant k8s manifests
Identify root cause in the config (not the running process)
Apply fix following the Principles above
Tilt live-reloads - re-poll status to verify

After 3 fix iterations on the same resource without progress:

Report the error with full logs
Identify whether it's a Tiltfile bug, upstream dependency, or infrastructure problem
Do not silently skip or disable the resource

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

查看日志：
```
tilt logs <resource> --since 2m
```
阅读Tiltfile及相关k8s清单
从配置中定位根本原因（而非运行中的进程）
遵循上述核心原则应用修复方案
Tilt会热重载变更 - 重新轮询状态以验证修复效果

若同一资源经过3次修复尝试仍无进展：

附上完整日志上报错误
判断问题属于Tiltfile漏洞、上游依赖问题还是基础设施问题
不得静默跳过或禁用该资源

Step 5: Report

步骤5：状态报告

undefined

undefined

Tilt Status: <healthy|degraded|errored>

Tilt 状态：<健康|降级|错误>

Resources: X/Y ok Session: tmux $SESSION:tilt

资源状态：X/Y 正常会话：tmux $SESSION:tilt

Errors (if any)

错误信息（如有）

<resource>: <root cause> — <what was fixed or what remains>

undefined

<资源名称>：<根本原因> — <已修复内容或剩余问题>

undefined