# 镜像 机器启动所用的镜像，可以是预装 SSH 和常用工具的 Arrakis 镜像，也可以是你自己的镜像（公开或私有均可）。 ## Arrakis 镜像 除非你另选镜像，机器默认启动 Arrakis 镜像。每个 Arrakis 镜像都基于官方基础镜像，并加入了 SSH、登录横幅和日常工具：git、git-lfs、tmux、htop、nvtop、rsync、curl、wget、jq 和一个编辑器。在每个 SSH 会话里，Python 都已在 PATH 中。 | 镜像 | 包含内容 | Docker 镜像 | |---|---|---| | PyTorch 2.14（默认） | PyTorch 2.14.1, CUDA 13.0, Python 3.12, Ubuntu 24.04 | `goodailabs/arrakis:pytorch-2.14.1-cuda13.0` | | 带有 CUDA 工具包的 PyTorch 2.14 | 同上，另加 nvcc、CUDA 头文件和编译器 | `goodailabs/arrakis:pytorch-2.14.1-cuda13.0-devel` | | CUDA 13.0 工具包 | CUDA 13.0.3、cuDNN 9、nvcc、Python 3.12、Ubuntu 24.04 | `goodailabs/arrakis:cuda-13.0.3-devel` | | Ubuntu 26.04 | Python 3.14。GPU 驱动由机器提供 | `goodailabs/arrakis:ubuntu-26.04` | CUDA 13.0 正是 `pip install torch` 安装的版本，因此为 PyTorch 构建的 wheel 可以直接使用。它能在 Arrakis 的每台机器上运行，包括 Blackwell：每台机器的 NVIDIA 驱动都是 580 系列或更新版本。这些镜像在 Docker Hub 上公开，你也可以在自己的电脑上拉取同一个镜像；默认镜像是 `goodailabs/arrakis:latest`。 登录时会显示机器的 GPU、镜像和可用磁盘空间： ```text 6 × NVIDIA RTX A4000, 16 GB each PyTorch 2.14.1, CUDA 13.0, Python 3.12.3, Ubuntu 24.04.5 LTS 32 CPU cores, 125 GB memory, 412 GB free in /workspace ``` 请在 `/workspace` 中工作。机器停止时，其上的所有内容（包括 `/workspace`）都会被删除。 ## 你自己的镜像 任何镜像都可以：vLLM、SGLang、NVIDIA NGC 容器，或你们团队自己的镜像，公开或私有均可。 - 在 **Images** 页面选择 **Add an image**，按 `docker pull` 接受的格式粘贴镜像名，例如 `vllm/vllm-openai:v0.11.0`。如果是公开镜像，也可以在租用时选择 **Your own image**。 - Arrakis 会先向镜像所在的镜像仓库确认：镜像必须存在、可以拉取，并且有 linux/amd64 版本。拼写错误或令牌有误时，会在扣费之前就被拒绝。 - 支持的镜像仓库：Docker Hub、GitHub（`ghcr.io`）、Amazon ECR 和 ECR Public、Google（Artifact Registry 和 `gcr.io`）、Azure（`azurecr.io`）、NVIDIA NGC（`nvcr.io`）、Quay、GitLab 和 Microsoft（`mcr.microsoft.com`），也可以是你自己的：Harbor、Artifactory、Nexus、自托管的 GitLab 或 Quay，以及任何可通过公网 DNS 名称访问的镜像仓库，例如 `registry.example.com:5000/team/app:v1`。 - 启动时会为任何镜像加上 SSH，所以你始终以同样的方式用 root 登录。镜像中需要有 shell。 - 在一台机器上首次启动时会下载镜像。镜像越大，耗时越长：在慢速网络上，12 GB 的镜像可能需要 10 到 20 分钟。 ### 私有镜像 添加镜像时勾选 **It's private: log in to pull it**，并填写 `docker login` 所需的登录凭据。Arrakis 会在保存前用它核验镜像，加密保存，并且只在你租用时用它拉取这个镜像。密码之后不会再显示。 | 镜像仓库 | 用户名 | 密码或令牌 | |---|---|---| | Docker Hub | 你的 Docker Hub 用户名 | 具有只读权限的个人访问令牌 | | GitHub（`ghcr.io`） | 你的 GitHub 用户名 | 只带 `read:packages` 权限的经典令牌（classic） | | Amazon ECR（`.dkr.ecr..amazonaws.com`） | 访问密钥 ID | 对应的秘密访问密钥 | | Google（`-docker.pkg.dev`、`gcr.io`） | `_json_key` | 具有 Artifact Registry Reader 角色的服务账号 JSON 密钥 | | Azure（`.azurecr.io`） | 存储库令牌或服务主体 | 对应的密码，仅有拉取权限 | | NVIDIA NGC（`nvcr.io`） | `$oauthtoken` | 你的 NGC API 密钥 | | GitLab（`registry.gitlab.com`） | 部署令牌的用户名 | 部署令牌，需带 `read_registry` 权限 | | Quay | 机器人账户 | 对应的令牌 | | 你自己的镜像仓库 | 它要求的用户名 | 对应的密码或令牌 | - **Amazon ECR**：使用一个只能拉取镜像的 AWS 用户（`AmazonEC2ContainerRegistryReadOnly` 策略）。每次租用时，Arrakis 都会用密钥换取一个新的、有效期 12 小时的拉取登录凭据（即 `aws ecr get-login-password` 输出的那个），因此机器永远接触不到密钥本身。 - **你自己的镜像仓库**：机器无论位于何处都会直接从它拉取，因此它必须能在公网上通过 HTTPS 访问，并使用公共证书颁发机构（例如 Let's Encrypt）签发的证书。位于 VPN 或 IP 允许列表之后的镜像仓库无法访问；使用自签名证书的会被拒绝。 - 请使用只读令牌。机器会用它拉取镜像，而租用结束后镜像可能仍缓存在那台机器上，所以不要把机密信息放进镜像，而是在运行时再传入。 - 要更换令牌，点击镜像旁边的 **Change login**，或用新令牌重新保存同一个镜像。移除镜像时，Arrakis 会在所有保存过其登录凭据的地方将其删除。 ### 启动时的行为 | 选项 | 运行内容 | 适用场景 | |---|---|---| | Wait for me to log in（默认） | 什么都不运行，机器会等你登录 | 训练、notebook，以及任何你通过 SSH 启动的任务 | | Run the image's command | 镜像自带的 entrypoint 和命令 | vLLM、TGI 或 SGLang 等服务器 | | Run a command | 你提供的一行普通命令，例如 `python -m http.server 8000` | 自动开始的任务 | 如果命令退出，机器就无法再访问。拿不准时，请选择 **Wait for me to log in**。 通过 SSH 访问机器上的服务器： ```sh ssh -L 8000:localhost:8000 root@ -p curl localhost:8000/v1/models ``` ### 环境变量 为镜像添加 `KEY=value` 键值对，每行一个。它们会随镜像一起保存，所以不要在这里放机密信息，而应通过 SSH 设置，例如在会话中执行 `export HF_TOKEN=...`。 ## 通过 CLI、API 和智能体使用 ```sh arrakis images list arrakis images add vllm/vllm-openai:v0.11.0 --start image arrakis instances create --node-id --image vllm/vllm-openai:v0.11.0 --start image --termination-hours 2 ``` 私有镜像需要提供登录凭据，令牌按 `docker login` 的方式从 stdin 传入： ```sh echo "$GITHUB_TOKEN" | arrakis images add ghcr.io/acme/trainer:v3 --username acme-bot --password-stdin arrakis instances create --node-id --template-id --termination-hours 2 ``` ```sh curl -X POST $ARRAKIS_URL/v1/instances -H "Authorization: Bearer $ARRAKIS_TOKEN" -H "Content-Type: application/json" \ -d '{"node_id": "", "name": "vllm", "termination_hours": 2, "ssh_public_key": "ssh-ed25519 AAAA...", "image": "vllm/vllm-openai:v0.11.0", "start": "image"}' ``` - `GET /v1/templates` 列出 Arrakis 镜像和你的镜像；`POST /v1/templates` 保存一个镜像（`image`、`start`、`command`、`environment`，私有镜像还需 `registry_username` 和 `registry_password`）。密码只能写入：响应中显示的是 `private` 和 `registry_username`。用 `PATCH /v1/templates/{id}` 同时提交这两个字段即可替换登录凭据。 - `POST /v1/instances` 启动 `template_id` 指定的镜像，或任意公开 `image`（需带 `start`）。 - 通过 MCP 时，`list_images` 会列出这些镜像并标出私有镜像，`rent_gpu` 接受 `template_id` 或 `image`。 更多：[全部文档](/zh-cn/docs.md) · [OpenAPI](/openapi.json) · [llms.txt](/zh-cn/llms.txt)