# 启动和就绪命令
<subtitle>为沙箱定义运行中的进程</subtitle>

## 启动命令

启动命令指定在**模板构建结束时**运行的进程——而不是在创建沙箱时运行。在构建期间，UCloud Sandbox 执行启动命令，等待 [就绪命令](#就绪命令) 确认进程已启动，然后对整个沙箱（包括正在运行的进程）进行 [快照](/docs/agent-sandbox/template/how-it-works.md)。

当您稍后从该模板创建沙箱时，快照进程**已经在运行**——没有启动等待时间。这就是如何让服务器、已播种的数据库或任何长期运行的进程在使用 SDK 生成沙箱时立即可用。

> **启动命令不在沙箱创建时运行**
> 
> 启动命令在**模板构建期间运行一次**并被捕获到快照中。每次创建沙箱时不会重新执行。如果您需要在每次创建沙箱时运行命令，请在创建沙箱后使用 `sandbox.commands.run()`。
> 
> 这也意味着 [传递给 `Sandbox.create()` 的环境变量](/docs/agent-sandbox/sandbox/environment-variables.md#1-全局环境变量) **不可用于**启动命令进程——它已在构建期间运行。如果您的启动命令需要环境变量，请使用 `set_envs()` 在模板定义中设置它们。

您可以在 [这里](/docs/agent-sandbox/template/how-it-works.md) 查看完整的构建流程。

## 就绪命令

就绪命令确定在创建 [快照](/docs/agent-sandbox/template/how-it-works.md) 之前沙箱何时就绪。它在无限循环中执行，直到返回成功的**退出码 0**。这让您可以控制构建等待 [启动命令](#启动命令) 或任何其他系统状态就绪的时间。

## `set_start_cmd`

当您想在模板构建期间运行进程**并**等待它就绪时，使用 `set_start_cmd`。此方法接受**两个参数**：启动命令和就绪命令。

```python
from ucloud_sandbox import Template, wait_for_port, wait_for_url, wait_for_timeout

# 启动 Python HTTP 服务器并等待它监听 8000 端口
template = (
    Template()
    .from_ubuntu_image("22.04")
    .apt_install(["curl", "python3"])
    .set_start_cmd("python3 -m http.server 8000", wait_for_port(8000))
)
```

您也可以传递自定义 shell 命令作为就绪命令，而不是使用辅助函数：

```python
# 带有自定义就绪命令的启动命令
template.set_start_cmd("npm start", "curl -s http://localhost:3000/health")
```

更多示例：

```python
from ucloud_sandbox import Template, wait_for_url, wait_for_port

# Next.js 应用——等待开发服务器 URL
template.set_start_cmd("npx next --turbo", wait_for_url("http://localhost:3000"))

# Python HTTP 服务器——等待 8000 端口
template.set_start_cmd("python -m http.server 8000", wait_for_port(8000))

# VNC 桌面——等待 VNC 端口
template.set_start_cmd("/start_command.sh", wait_for_port(6080))
```

## `set_ready_cmd`

当您**不需要启动命令**但仍想控制何时拍摄沙箱快照时，使用 `set_ready_cmd`。此方法只接受**一个参数**：就绪命令。

当您的模板的构建步骤（例如，`run_cmd`）已经启动了后台进程，或者您只需要额外的时间让系统在快照之前稳定下来时，这很有用。

```python
from ucloud_sandbox import Template, wait_for_timeout, wait_for_port, wait_for_file

# 在拍摄快照之前等待 nginx 开始监听
template = (
    Template()
    .from_ubuntu_image("22.04")
    .run_cmd("apt-get install -y nginx && service nginx start")
    .set_ready_cmd(wait_for_port(80))
)
```

更多示例：

```python
# 等待后台进程创建文件
template.set_ready_cmd(wait_for_file("/tmp/ready"))

# 等待固定时间让系统稳定
template.set_ready_cmd(wait_for_timeout(10_000))

# 自定义就绪检查
template.set_ready_cmd("curl -s http://localhost:8080/health")
```

## 就绪命令辅助函数

SDK 提供了常见就绪命令模式的辅助函数。这些可以与 `set_start_cmd` 和 `set_ready_cmd` 一起使用。

```python
from ucloud_sandbox import wait_for_port, wait_for_url, wait_for_process, wait_for_file, wait_for_timeout

# 等待端口可用
wait_for_port(3000)

# 等待 URL 返回特定状态码（默认为 200）
wait_for_url("http://localhost:3000/health")
wait_for_url("http://localhost:3000/health", 200)

# 等待进程运行
wait_for_process("node")

# 等待文件存在
wait_for_file("/tmp/ready")

# 等待指定的时间
wait_for_timeout(10_000)  # 10 秒
```