Lybic Docs
沙箱

自定义镜像管理

你可以根据你的需求，根据现有运行中的沙箱自定义你的沙箱系统镜像，以定制预装所需的软件和配置，从而简化业务所需沙箱的创建和使用过程。本文将介绍如何创建、管理和使用自定义镜像。

提示：

  1. 仅 Windows 沙箱支持自定义镜像功能；
  2. 当自定义镜像超过 30天 未被使用时，系统会自动删除该镜像，请注意及时使用；
  3. 基本套餐中，每个组织最多可创建 3个 自定义镜像，如需更多自定义镜像，请联系我们的 商务团队。

通过控制台管理自定义镜像

创建

进入沙箱详情页面，点击 “创建镜像” 按钮，填写镜像名称和描述后，点击“创建镜像”按钮，请等待一会，系统会基于当前沙箱的 文件状态 生成一个新的自定义镜像，同时删除当前的沙箱。

Sandbox Detail

在“镜像”管理页面，你可以查看和通过右侧的小图标管理你创建的自定义镜像。

Sandbox Detail

删除

在“镜像”管理页面，找到你想删除的自定义镜像，点击右侧的删除图标，确认删除即可。

通过 API 管理自定义镜像

你可以通过以下 API 接口管理自定义镜像。所有请求都需要在 Header 中携带 API Key 进行身份验证。

1. 创建镜像

从现有沙箱创建自定义镜像。创建镜像后，原沙箱将被删除。

端点： POST /api/orgs/{orgId}/machine-images

请求参数：

  • sandboxId (string, 必填): 要创建镜像的沙箱 ID
  • name (string, 必填): 镜像名称，长度 1-100 字符
  • description (string, 可选): 镜像描述，最长 500 字符

请求示例：

curl -X POST "https://api.lybic.cn/api/orgs/{orgId}/machine-images" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "sandboxId": "sandbox_123",
    "name": "My Custom Image",
    "description": "Ubuntu with Node.js and Python pre-installed"
  }'
import asyncio
from lybic import LybicClient, LybicAuth

async def main():
    async with LybicClient(
        LybicAuth(
            org_id="ORG-xxxx",
            api_key="lysk-xxxxxxxxxxx",
            endpoint="https://api.lybic.cn/"
        )
    ) as client:
        image = await client.sandbox.create_machine_image(
            sandboxId="sandbox_123",
            name="My Custom Image",
            description="Ubuntu with Node.js and Python pre-installed"
        )
        print(f"已创建镜像: {image.id}, 状态: {image.status}")

if __name__ == "__main__":
    asyncio.run(main())
import { LybicClient } from '@lybic/core'

const lybic = new LybicClient({
  baseUrl: 'https://api.lybic.cn',
  orgId: 'ORG-xxxx',
  apiKey: 'lysk-your-api-key-here',
})

const result = await lybic.client.POST('/api/orgs/{orgId}/machine-images', {
  params: {
    path: {
      orgId: lybic.orgId,
    },
  },
  body: {
    sandboxId: 'sandbox_123',
    name: 'My Custom Image',
    description: 'Ubuntu with Node.js and Python pre-installed',
  },
})

console.log(`已创建镜像: ${result.data?.id}, 状态: ${result.data?.status}`)
package main

import (
    "context"
    "fmt"
    "github.com/lybic/lybic-sdk-go"
)

func main() {
    ctx := context.Background()
    client, _ := lybic.NewClient(nil)

    description := "Ubuntu with Node.js and Python pre-installed"
    imageDto := lybic.CreateMachineImageDto{
        SandboxId:   "sandbox_123",
        Name:        "My Custom Image",
        Description: &description,
    }

    image, err := client.CreateMachineImage(ctx, imageDto)
    if err != nil {
        fmt.Println("创建机器镜像时出错:", err)
        return
    }
    fmt.Printf("已创建镜像: %s, 状态: %s\n", image.Id, image.Status)
}

响应示例：

{
  "id": "img_abc123",
  "name": "My Custom Image",
  "description": "Ubuntu with Node.js and Python pre-installed",
  "createdAt": "2026-01-16T06:30:00.000Z",
  "shapeName": "linux-small",
  "status": "CREATING"
}

状态说明：

  • CREATING: 镜像正在创建中
  • READY: 镜像已就绪，可以使用
  • ERROR: 镜像创建失败

2. 列出所有镜像

获取组织下的所有自定义镜像列表。

端点： GET /api/orgs/{orgId}/machine-images

请求示例：

curl -X GET "https://api.lybic.cn/api/orgs/{orgId}/machine-images" \
  -H "Authorization: Bearer YOUR_API_KEY"
import asyncio
from lybic import LybicClient, LybicAuth

async def main():
    async with LybicClient(
        LybicAuth(
            org_id="ORG-xxxx",
            api_key="lysk-xxxxxxxxxxx",
            endpoint="https://api.lybic.cn/"
        )
    ) as client:
        images = await client.sandbox.list_machine_images()
        for image in images.images:
            print(f"镜像 ID: {image.id}, 名称: {image.name}, 状态: {image.status}")

if __name__ == "__main__":
    asyncio.run(main())
import { LybicClient } from '@lybic/core'

const lybic = new LybicClient({
  baseUrl: 'https://api.lybic.cn',
  orgId: 'ORG-xxxx',
  apiKey: 'lysk-your-api-key-here',
})

const result = await lybic.client.GET('/api/orgs/{orgId}/machine-images', {
  params: {
    path: {
      orgId: lybic.orgId,
    },
  },
})

result.data?.images?.forEach((image) => {
  console.log(`镜像 ID: ${image.id}, 名称: ${image.name}, 状态: ${image.status}`)
})
package main

import (
    "context"
    "fmt"
    "github.com/lybic/lybic-sdk-go"
)

func main() {
    ctx := context.Background()
    client, _ := lybic.NewClient(nil)

    images, err := client.ListMachineImages(ctx)
    if err != nil {
        fmt.Println("列出机器镜像时出错:", err)
        return
    }

    for _, image := range images {
        fmt.Printf("镜像 ID: %s, 名称: %s, 状态: %s\n", image.Id, image.Name, image.Status)
    }
}

响应示例：

{
  "images": [
    {
      "id": "img_abc123",
      "name": "My Custom Image",
      "description": "Ubuntu with Node.js and Python pre-installed",
      "createdAt": "2026-01-16T06:30:00.000Z",
      "shapeName": "linux-small",
      "status": "READY"
    },
    {
      "id": "img_def456",
      "name": "Windows Dev Environment",
      "description": "Windows with Visual Studio",
      "createdAt": "2026-01-15T10:20:00.000Z",
      "shapeName": "windows-medium",
      "status": "READY"
    }
  ]
}

3. 从镜像创建沙箱

使用自定义镜像创建新的沙箱实例。

端点： POST /api/orgs/{orgId}/sandboxes/from-image

请求参数：

  • imageId (string, 必填): 镜像 ID
  • name (string, 必填): 沙箱名称，长度 1-100 字符
  • maxLifeSeconds (integer, 必填): 沙箱最大生命周期（秒），最小 300 秒，最大 604800 秒（7天）
  • projectId (string, 可选): 项目 ID，不提供则使用默认项目

请求示例：

curl -X POST "https://api.lybic.cn/api/orgs/{orgId}/sandboxes/from-image" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "imageId": "img_abc123",
    "name": "Development Sandbox",
    "maxLifeSeconds": 7200
  }'
import asyncio
from lybic import LybicClient, LybicAuth

async def main():
    async with LybicClient(
        LybicAuth(
            org_id="ORG-xxxx",
            api_key="lysk-xxxxxxxxxxx",
            endpoint="https://api.lybic.cn/"
        )
    ) as client:
        sandbox = await client.sandbox.create_from_image(
            imageId="img_abc123",
            name="Development Sandbox",
            maxLifeSeconds=7200
        )
        print(f"已创建沙箱: {sandbox.id}, 状态: {sandbox.status}")

if __name__ == "__main__":
    asyncio.run(main())
import { LybicClient } from '@lybic/core'

const lybic = new LybicClient({
  baseUrl: 'https://api.lybic.cn',
  orgId: 'ORG-xxxx',
  apiKey: 'lysk-your-api-key-here',
})

const result = await lybic.client.POST('/api/orgs/{orgId}/sandboxes/from-image', {
  params: {
    path: {
      orgId: lybic.orgId,
    },
  },
  body: {
    imageId: 'img_abc123',
    name: 'Development Sandbox',
    maxLifeSeconds: 7200,
  },
})

console.log(`已创建沙箱: ${result.data?.sandbox?.id}, 状态: ${result.data?.sandbox?.status}`)
package main

import (
    "context"
    "fmt"
    "github.com/lybic/lybic-sdk-go"
)

func main() {
    ctx := context.Background()
    client, _ := lybic.NewClient(nil)

    var maxLife int32 = 7200
    sandboxDto := lybic.CreateSandboxFromImageDto{
        ImageId:        "img_abc123",
        Name:           "Development Sandbox",
        MaxLifeSeconds: maxLife,
    }

    sandbox, err := client.CreateSandboxFromImage(ctx, sandboxDto)
    if err != nil {
        fmt.Println("从镜像创建沙箱时出错:", err)
        return
    }
    fmt.Printf("已创建沙箱: %s, 状态: %s\n", sandbox.Id, sandbox.Status)
}

响应示例：

{
  "sandbox": {
    "id": "sandbox_xyz789",
    "name": "Development Sandbox",
    "status": "CREATING",
    "createdAt": "2026-01-16T06:35:00.000Z",
    "imageId": "img_abc123"
  }
}

4. 删除镜像

删除指定的自定义镜像。删除后该镜像将无法再用于创建沙箱。

端点： DELETE /api/orgs/{orgId}/machine-images/{imageId}

路径参数：

  • imageId (string, 必填): 要删除的镜像 ID

请求示例：

curl -X DELETE "https://api.lybic.cn/api/orgs/{orgId}/machine-images/img_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
import asyncio
from lybic import LybicClient, LybicAuth

async def main():
    async with LybicClient(
        LybicAuth(
            org_id="ORG-xxxx",
            api_key="lysk-xxxxxxxxxxx",
            endpoint="https://api.lybic.cn/"
        )
    ) as client:
        await client.sandbox.delete_machine_image(image_id="img_abc123")
        print("镜像删除成功")

if __name__ == "__main__":
    asyncio.run(main())
import { LybicClient } from '@lybic/core'

const lybic = new LybicClient({
  baseUrl: 'https://api.lybic.cn',
  orgId: 'ORG-xxxx',
  apiKey: 'lysk-your-api-key-here',
})

await lybic.client.DELETE('/api/orgs/{orgId}/machine-images/{imageId}', {
  params: {
    path: {
      orgId: lybic.orgId,
      imageId: 'img_abc123',
    },
  },
})

console.log('镜像删除成功')
package main

import (
    "context"
    "fmt"
    "github.com/lybic/lybic-sdk-go"
)

func main() {
    ctx := context.Background()
    client, _ := lybic.NewClient(nil)

    err := client.DeleteMachineImage(ctx, "img_abc123")
    if err != nil {
        fmt.Println("删除机器镜像时出错:", err)
        return
    }
    fmt.Println("镜像删除成功")
}

响应： HTTP 204 No Content（删除成功）

使用说明

  1. 替换参数： 在实际使用时，请将示例中的 {orgId}、YOUR_API_KEY、sandbox_123 等替换为实际的值
  2. 镜像状态： 创建镜像后需要等待状态变为 READY 才能使用该镜像创建沙箱

文件传输

在本地存储、对象存储和沙箱之间传输文件

沙箱桌面截屏与串流

下一页

本页内容

通过控制台管理自定义镜像创建删除通过 API 管理自定义镜像1. 创建镜像2. 列出所有镜像3. 从镜像创建沙箱4. 删除镜像使用说明