云沙箱支持将您在火山引擎之外自建的私有镜像仓库 (如 Harbor、Nexus、通用 Registry V2 等) 中的镜像，直接用作沙箱实例的自定义镜像，无需将镜像迁移即可快速拉起沙箱环境。 ## 使用场景镜像仓库部署在您的本地数据中心或自有机房，出于安全合规要求仅允许内网访问、不对公网暴露，系统侧无法通过公网直接拉取。通过自定义镜像仓库能力，veFaaS 可以经由您预先建好的专线，把这类内网镜像仓库的镜像预热到沙箱节点并完成格式转换，从而在创建实例时直接命中本地缓存，实现秒级启动，减少每次创建实例都远程回源拉取大体积镜像的耗时。本文以通过专线方式拉取 Harbor 镜像仓库中的镜像、并将其预热为沙箱自定义镜像为例，介绍私网仓库从配置到创建沙箱实例的完整流程。 ## 前提条件 * **网络打通（私网访问前置）** * 已打通云上私有网络到本地数据中心的专线，操作详情参见 [本地 IDC 上云](https://docs.volcengine.com/docs/6407/1791170?lang=zh)。 * 自建镜像仓库在您的 VPC 内可以通过一个或多个私网 IPv4 地址访问。 * （可选）需要通过域名访问镜像仓库时，需要提前准备好 VPC 内可解析该域名的 DNS 解析器 IP，操作详情参见 [查看 TrafficRoute 解析记录](https://docs.volcengine.com/docs/6420/192724?lang=zh#VPC)。 * （可选）如果通过子账号进行操作，已提前添加 VeFaaSFullAccess 系统预设策略，操作详情参见 [使用全局范围的预设策略并授权](https://docs.volcengine.com/docs/6662/1355665?lang=zh#.5Zy65pmv5LiA77ya5L2_55So5YWo5bGA6IyD5Zu055qE6aKE6K6-562W55Wl5bm25o6I5p2D)。 * **第三方仓库** 已获取第三方仓库（本示例为 Harbor）的访问凭证。 * BasicAuth 类型：提前获取访问第三方仓库的用户名和密码。 * BearerToken 类型：提前获取访问第三方仓库的令牌。 ## 操作流程通过自定义镜像创建云沙箱应用需依次完成 6 个步骤，从创建镜像仓库到最终创建沙箱实例。下图展示了完整的操作流程，各步骤的详细说明如下。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_315d7c8c03aa95ae733a3df0f4b43daf.png) ## 操作步骤 ### 第一步：创建自定义镜像仓库调用 [CreateCustomImageRegistry](https://docs.volcengine.com/docs/6662/2600006) 创建自定义镜像仓库。 * 请求示例 ```JSON { "Name": "harbor", "Server": "registry-cn-shanghai.harbor.com", "Namespace": "****", "AuthConfig": { "AuthType": "BasicAuth", "Username": "admin", "Password": "****" }, "NetworkConfig": { "AccessType": "PrivateVpc", "VpcId": "vpc-****", "SubnetId": "subnet-****", "ServerIps": ["192.168.***.***"], "UserSecurityGroupIds": ["sg-****"], "DnsServerIps": ["10.0.***.***"] } } ```

说明

详细的网络配置说明参见 CustomImageRegistryNetworkConfig。

|**字段** |**是否必填** |**说明** | |---|---|---| |AuthConfig |否 |自定义镜像仓库的认证类型，用于指定访问该仓库时的认证方式，取值如下。

* BasicAuth：用户名和密码认证。

* BearerToken：令牌认证。

* Anonymous：匿名访问，无需认证。 | |VpcId |是 |自定义镜像仓库所在的私有网络的 ID。 | |SubnetId |是 |自定义镜像仓库所在的子网 ID。 | |ServerIps |是 |自定义镜像仓库在 VPC 内的私网 IPv4 地址列表。 | |UserSecurityGroupIds |是 |私网链路使用的安全组 ID 列表。 | |DnsServerIps |否 |私有网络内可解析该域名的 DNS 解析器 IP，仅当通过自定义镜像仓库域名访问时填写。 | * 返回示例调用成功后，返回自定义镜像仓库的 ID (RegistryId, 本示例为 `regcfg-8xkq****`), 且 PrivateAccess.Status 为 `pending`, 即表示调用成功。 ```JSON { "ResponseMetadata": { "RequestId": "20260709190000****", "Action": "CreateCustomImageRegistry", "Version": "2024-01-01", "Service": "vefaas", "Region": "cn-shanghai" }, "Result": { "RegistryId": "regcfg-8xkq****", "Name": "harbor", "Server": "registry-cn-shanghai.harbor.com", "Namespace": "****", "AuthStatus": { "AuthType": "BasicAuth", "Configured": true }, "NetworkConfig": { "AccessType": "PrivateVpc", "VpcId": "vpc-****", "SubnetId": "subnet-****", "ServerIps": ["192.168.***.***"], "UserSecurityGroupIds": ["sg-****"], "DnsServerIps": ["10.0.***.***"] }, "PrivateAccess": { "Status": "pending", "Message": "", "EndpointIp": "", "LastCheckTime": "" } } } ``` ### 第二步：轮询私网访问状态通过 [第一步](https://docs.volcengine.com/docs/6662/2599221?lang=zh#xYVRWS8Q) 返回的镜像仓库 ID（本示例为 `regcfg-8xkq****`）调用 [GetCustomImageRegistry](https://docs.volcengine.com/docs/6662/2600007?lang=zh) 直到私网访问状态 PrivateAccess.Status 变为 `ready`。 * 请求示例 ```JSON { "RegistryId": "regcfg-8xkq****" } ``` * 返回示例 ```JSON { "ResponseMetadata": { "RequestId": "20250829114726002227007142CD44EA", "Action": "GetCustomImageRegistry", "Version": "2024-06-06", "Service": "vefaas", "Region": "cn-shanghai" }, "Result": { "Id": "regcfg-****", "Name": "harbor", "Server": "registry-cn-shanghai.harbor.com", "Namespace": "****", "AuthConfig": { "AuthType": "BasicAuth", "Configured": true }, "NetworkConfig": { "AccessType": "PrivateVpc", "VpcId": "vpc-****", "SubnetId": "subnet-****", "ServerIps": ["172.16.***.***"], "UserSecurityGroupIds": ["sg-****"], "DnsServerIps": ["192.168.***.***"] }, "PrivateAccess": { "Status": "ready", "Message": "Private network access is ready", "EndpointIp": "192.168.***.***", "LastCheckTime": "2025-04-25 11:11:29.376 +0000 UTC" } } } ```

说明

若长时间停留在 enabling 或 failed状态，请先核对以下配置，修正后通过 UpdateCustomImageRegistry 重新触发编排。

VpcId、SubnetId 与安全组是否属于同一 VPC。

子网是否有空闲 IP。

### 第三步：连通自定义镜像仓库和函数服务 [提交工单](https://console.volcengine.com/workorder/create?step=1)，填写镜像仓库的私网 IP（ [第一步](https://docs.volcengine.com/docs/6662/2599221?lang=zh#xYVRWS8Q) 中填写的 ServerIps），允许函数服务访问自定义镜像仓库。 ### 第四步：提交镜像预热调用 [PrecacheSandboxImages](https://docs.volcengine.com/docs/6662/1824712?lang=zh) 提交镜像预热任务。 * 请求示例 ```JSON { "ImageUrls": [ "registry-cn-shanghai.harbor.com/****/native-****:v1" ], "RegistryId": "regcfg-8xkq****" } ``` |**字段** |**是否必填** |**说明** | |---|---|---| |ImageUrls |是 |填写待预热镜像的完整地址，通过目标镜像仓库的域名、命名空间、镜像名称和版本拼接而成，格式为`{仓库域名}/{命名空间}/{镜像名}:{版本}`。本示例为 `registry-cn-shanghai.harbor.com/****/native-****:v1`。 | |RegistryId |否 |填写 [第一步](https://docs.volcengine.com/docs/6662/2599221?lang=zh#xYVRWS8Q) 返回的镜像仓库 ID, 本示例为 `regcfg-8xkq****`。 | * 返回示例预热为异步任务，接口会返回一个查询凭据（TicketId），即预热任务提交提交成功。 ```JSON { "ResponseMetadata": { "RequestId": "20230604110420****100232280022D31", "Action": "PrecacheSandboxImages", "Version": "2024-06-06", "Service": "vefaas", "Region": "cn-shanghai" }, "Result": { "TicketId": "948410ee80954******" } } ``` ### 第五步：查询预热结果预热任务提交完成后轮询 [ListSandboxImages](https://docs.volcengine.com/docs/6662/1824714?lang=zh)，当 PrecacheStatus 返回 `success` ** ** 即预热完成。 * 请求示例 ```JSON { "ImageType": "private", "Filters": [ { "Key": "source_image_url", "Values": [ "registry-cn-shanghai.harbor.com/****/native-****:v1" ] } ], "PageNumber": 1, "PageSize": 10 } ``` |**字段** |**是否必填** |**说明** | |---|---|---| |Filters.Key |否 |过滤条件 Key，本示例填写 `source_image_url` ** ** 即通过镜像地址筛选。 | |Filters.Values |否 |填写 [第四步](https://docs.volcengine.com/docs/6662/2599221?lang=zh#LTWvGatW) 中的 ImageUrls，即待预热镜像的完整地址，本示例为 `registry-cn-shanghai.harbor.com/****/native-****:v1`。 | * 返回示例 PrecacheStatus 返回 `success` ** ** 即预热成功，并获取预热后的镜像 ID ImageId，本示例为 `9px3r6****`。 ```JSON { "ResponseMetadata": { "RequestId": "20230604110420****100232280022D31", "Action": "ListSandboxImages", "Version": "2024-06-06", "Service": "vefaas", "Region": "cn-shanghai" }, "Result": { "Images": [ { "ImageId": "9px3r6****", "ImageUrl": "registry-cn-shanghai.harbor.com/****/native-****:v1", "ImageGroup": "Code", "UpdateTime": "2025-04-25 11:11:29.376 +0000 UTC", "PrecacheStatus": "success", "PrecacheStatusReason": "", "RelatedSandboxApplications": [ "wxd2****" ] } ], "TotalCount": 1 } } ``` ### 第六步：创建沙箱实例调用 [CreateSandbox](https://docs.volcengine.com/docs/6662/1824706?lang=zh) 创建沙箱实例，返回 SandboxId 即创建成功。 * 请求示例 ```JSON { "FunctionId": "wrws****", "Timeout": 60, "Metadata": { "app": "test" }, "InstanceTosMountConfig": { "Enable": true, "TosMountPoints": [ { "BucketPath": "/sandbox", "LocalMountPath": "/mnt/tos" } ] }, "Envs": [ { "Key": "business_type", "Value": "free" } ], "InstanceImageInfo": { "Id": "9px3r6****", "Port": 8080, "Image": "registry-cn-shanghai.harbor.com/****/native-****:v1", "Command": "bash /root/sandbox/scripts/run.sh" }, "CpuMilli": 500, "MemoryMB": 1024, "MaxConcurrency": 20, "RequestTimeout": 30 } ``` |**字段** |**是否必填** |**说明** | |---|---|---| |InstanceImageInfo.Id |否 |填写沙箱镜像的 ID，即上一步 [ListSandboxImages](https://docs.volcengine.com/docs/6662/1824714?lang=zh) 返回的 ImageId，本示例为 `9px3r6****`。 | |InstanceImageInfo.Image |否 |填写已预热镜像的完整地址，即上一步 [ListSandboxImages](https://docs.volcengine.com/docs/6662/1824714?lang=zh) 返回的 ImageUrl，本示例为 `registry-cn-shanghai.harbor.com/****/native-****:v1`。 | * 返回示例 ```JSON { "ResponseMetadata": { "RequestId": "20230604110420****100232280022D31", "Action": "CreateSandbox", "Version": "2024-06-06", "Service": "vefaas", "Region": "cn-shanghai" }, "Result": { "SandboxId": "vefaas-e8m6xarn-p2zamuv2fr-******" } } ``` ##