# 基础镜像
<subtitle>如何为模板定义基础镜像</subtitle>

## 创建模板

创建模板时，您可以指定选项：

```python
template = Template(
    file_context_path=".",  # 自定义文件上下文路径
    file_ignore_patterns=[".git", "node_modules"],  # 要忽略的文件模式
)
```

**文件忽略**：SDK 会自动读取 `.dockerignore` 文件，并将它们与您的 `file_ignore_patterns` 组合。匹配这些模式的文件将被排除在上传和哈希计算之外。

## 定义基础镜像

每个模板都以一个基础镜像开始，该镜像为您的沙箱环境提供基础。

> UCloud Sandbox 目前仅支持基于 Debian 的镜像。您的基础镜像必须是 Debian 或 Debian 衍生版本（例如，`debian`、`ubuntu`、`python`、`node`）。不支持 Alpine、基于 RedHat 和其他非 Debian 发行版。

### 预定义基础镜像

使用便捷方法获取常见的 Ubuntu、Debian、Python、Node.js 或 Bun 基础镜像：

```python
template.from_ubuntu_image("22.04")  # ubuntu:22.04
template.from_debian_image("stable-slim")  # debian:stable-slim
template.from_python_image("3.13")  # python:3.13
template.from_node_image("lts")  # node:lts
template.from_bun_image("1.3")  # oven/bun:1.3
```

### 自定义基础镜像

使用来自 Docker Hub 或其他注册表的任何 Docker 镜像：

```python
template.from_image("custom-image:latest")
```

### 默认的 UCloud Sandbox 基础镜像

使用默认的 UCloud Sandbox 基础镜像，该镜像已为沙箱环境预配置：

```python
template.from_base_image()  # 使用默认基础镜像
```

### 从现有模板构建

扩展您团队或组织的现有模板：

```python
template.from_template("my-template")  # 您团队的模板
template.from_template("acme/other-template")  # 完整的命名空间引用
```

> 每个模板只能调用一次基础镜像方法。后续调用将抛出错误。

## 解析现有 Dockerfile

使用 `from_dockerfile()` 将现有 Dockerfile 转换为模板格式：

```python
dockerfile_content = """
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y curl
WORKDIR /app
COPY . .
ENV NODE_ENV=production
ENV PORT=3000
USER appuser
"""

template = (
    Template()
    .from_dockerfile(dockerfile_content)
    .set_start_cmd("npm start", wait_for_timeout(5_000))
)
```

### Dockerfile 指令支持

| 指令                 | 支持情况  | 行为                                                                                          |
| :---                 |    :----:  | :---                                                                                              |
| `FROM`               | ✓         | 设置基础镜像                                                                                   |
| `RUN`                | ✓         | 转换为 `run_cmd()`                                                              |
| `COPY` / `ADD`       | ✓         | 转换为 `copy()`                                                                              |
| `WORKDIR`            | ✓         | 转换为 `set_workdir()`                                                      |
| `USER`               | ✓         | 转换为 `set_user()`                                                            |
| `ENV`                | ✓         | 转换为 `set_envs()`；支持 `ENV key=value` 和 `ENV key value` 两种格式 |
| `CMD` / `ENTRYPOINT` | ✓         | 转换为 `set_start_cmd()`，就绪命令为 20 秒超时          |
| `EXPOSE`             | ✗                | 跳过（不支持）                                                                           |
| `VOLUME`             | ✗                | 跳过（不支持）                                                                           |

> 不支持多阶段 Dockerfile。