logologo
快手万擎(Vanchin)
沙箱服务
文档中心
沙箱服务自定义镜像自主构建推送使用指南

自定义镜像自主构建推送使用指南


本文面向使用「自主构建推送」把自有镜像上传到平台镜像仓库的用户,说明上传前需要准备什么、镜像必须满足哪些规格、完整操作流程以及常见问题的排查方式。

1. 功能说明

「自主构建推送」允许用户在自己的构建环境里构建镜像,推送到平台指定的镜像仓库;平台在收到仓库回调后把镜像登记到「镜像管理」列表(来源 = 自主构建),之后可以在「新建模板」时选择该镜像作为基础镜像。

需要注意:

  • 镜像不能直接用来启动沙箱,必须先通过「新建模板」用它构建出模板,模板才能创建沙箱。
  • 平台只负责记录和拉取镜像,不参与你本地的构建过程;镜像内容、依赖、应用都由你自行维护。
  • 同名、同 tag 视为同一个镜像;建议每次使用新的 tag(仓库若开启 tag 不可变策略,覆盖推送会被拒绝)。


2. 前置准备

2.1 本地环境

项目

要求

Docker

已安装且 docker login / tag / push 可用(Docker 20.10+ 建议)

网络

能访问弹窗里「仓库地址」的主机(registry-wanqing.streamlake.com:443;内网环境使用对应的 IDC 域名)

磁盘

预留足够的镜像构建与导出空间

架构

构建机可以是 x86_64 或 Apple Silicon,但产物必须是 linux/amd64(见 2.2)


2.2 镜像规格(必须满足)

平台构建模板时,会把镜像作为一台 Linux 虚拟机的根文件系统直接引导,并在其中执行初始化脚本。因此镜像不是"能跑的容器"就行,必须满足下面的条件:

要求

说明

linux/amd64

只支持 64 位 x86 架构。在 Apple Silicon / ARM 机器上必须显式构建 amd64 镜像(docker build --platform linux/amd64 或 docker buildx build --platform linux/amd64),只把 arm64 镜像 docker tag 成目标名字是无效的,模板构建会报 image is not amd64

Debian / Ubuntu 系

初始化脚本依赖 dpkg / apt 安装 systemd 等系统组件。Alpine、distroless、scratch、CentOS/RHEL 等非 Debian 系镜像不支持,会在模板构建阶段失败(典型错误:error provisioning sandbox: ... exit status: 1)

完整 rootfs

需要标准 Linux 目录结构(/bin、/etc、/lib、/usr 等),不能是单个静态二进制或 distroless 镜像

可安装 systemd

基础镜像可以是 ubuntu:22.04 这类精简镜像,初始化脚本会安装/配置 systemd、systemd-sysv、openssh-server、sudo、chrony、curl、nfs-common、fuse 等组件

/bin/sh 与 /bin/bash

初始化脚本和登录环境依赖它们,Debian/Ubuntu 默认满足

磁盘余量

初始化会创建 128 MiB swap 并安装系统包,建议镜像内保留数百 MB 以上可用空间

明确不支持:

  • alpine / busybox / distroless / scratch;
  • 仅 arm64 或仅其它架构的镜像;
  • Windows 容器镜像;
  • 依赖宿主内核特殊模块、要求特权设备才能启动的镜像。
多架构镜像(manifest list)只要包含 amd64 即可。


2.3 推送账号

在弹窗中获取,账号粒度是商业化主体(主账号 / 每个子账户各一个):

身份

仓库用户名

主账号

<tenantId>

子账户

<tenantId>-<子账户标识>

  • 密码默认只显示掩码,点「查看 / 复制」获取明文;「重置密码」后旧密码立即失效,需要重新登录。
  • 一个账号可以加入该租户下多个项目;每个项目对应一个仓库路径 <仓库地址>/<projectId>。
  • 推送凭证由平台在镜像仓库中创建并授权,不需要也无法自行注册仓库账号。


3. 操作流程

步骤 1:打开弹窗,复制凭证

进入 镜像管理 → 自主构建推送,弹窗中会显示:

  • 仓库地址:registry-wanqing.streamlake.com/<projectId>
  • 用户名 / 密码
  • 可直接复制的 docker login / tag / push 命令

步骤 2:登录镜像仓库

docker login registry-wanqing.streamlake.com -u '<用户名>'
# 按提示输入密码;也可以使用弹窗里的「变量传密码」方式:
# printf '%s' "$HARBOR_PASSWORD" | docker login registry-wanqing.streamlake.com -u '<用户名>' --password-stdin
登录成功只代表认证通过;实际是否有该项目推送权限以 docker push 结果为准。

步骤 3:构建 amd64 镜像

# 普通 Docker
docker build --platform linux/amd64 -t my-image:v1 .

# 如果使用 buildx(Apple Silicon 推荐)
docker buildx build --platform linux/amd64 -t my-image:v1 --load .

步骤 4:打标签

docker tag my-image:v1 \
registry-wanqing.streamlake.com/proj-xfr2sg-1784694202813896643/my-image:v1

标签规则:

  • 镜像名(repository)建议只使用小写字母、数字、-、_、.;
  • tag 以字母或数字开头,只能包含字母、数字、.、_、-,长度不超过 128;建议统一使用小写;
  • 必须使用 tag 推送,只推 digest 不会在平台登记。

步骤 5:推送

docker push registry-wanqing.streamlake.com/proj-xfr2sg-1784694202813896643/my-image:v1

限制:

  • 单租户并发推送上限 10,超出会排队等待;
  • 镜像体积、层数不做限制;
  • 同一 tag 再次推送:仓库允许覆盖时,平台按同一镜像处理(展示为更新);仓库开启 tag 不可变策略时会拒绝,需换 tag 或先删除旧镜像。建议每次使用新 tag。

步骤 6:等待平台同步

推送完成后,镜像仓库会回调平台,镜像随即出现在「镜像管理」列表:

  • 来源:自主构建
  • 类型:自定义
  • 状态:成功
  • 大小 / 创建人:按实际推送结果展示

通常几秒内完成;如果长时间未出现,见第 5 节排查。

步骤 7:用镜像创建模板

在列表里点「新建模板」,选择该镜像作为基础镜像,构建出模板后即可用于创建沙箱。模板构建期间会执行系统初始化,耗时通常为几分钟。


4. 限制与注意事项

项目

说明

并发推送

10(排队)

镜像大小 / 层数

不限制

tag 规则

字母数字开头;仅允许字母、数字、.、_、-;≤128 字符

覆盖推送

同名同 tag 视为同一镜像;仓库允许覆盖时平台按更新处理,开启 tag 不可变时会拒绝

删除镜像

若仍有模板引用该镜像,平台会拒绝删除,并提示「仍有 N 个模板引用它」,需要先删除/迁移相关模板

仓库侧删除

直接在仓库里删除镜像后,平台会同步删除记录;但被模板引用的镜像会保留记录,避免模板引用悬空

子账户

子账户使用独立账号(<tenantId>-<子账户>),与主账号的镜像归属、凭证均独立

凭证泄露

密码一旦泄露请立即「重置密码」,旧密码会立即失效


5. 常见问题

5.1 docker login 返回 401 Unauthorized

  • 密码已被重置或不是弹窗里当前的密码 → 重新打开弹窗获取,必要时点「重置密码」;
  • 网络把仓库域名解析到了错误的实例(例如本地 /etc/hosts 手工映射过旧地址)→ 检查 getent hosts registry-wanqing.streamlake.com,与平台提供的地址核对;
  • 注意:部分 Harbor 配置下即使密码错误,docker login 也可能"成功"但拿不到权限,最终在 push 时 401,务必以 push 结果为准。

5.2 docker push 返回 401 / 403 denied

  • 推送的路径与弹窗里的「仓库地址」不一致(projectId 写错)→ 使用弹窗中复制的完整地址;
  • 账号未被授权到该项目 → 重新打开弹窗触发平台重新开通(会自动补项目成员关系);
  • 子账户误用了主账号凭证 → 检查弹窗用户名是否为 <tenantId>-<子账户>。

5.3 推送成功,但「镜像管理」里看不到

  • 等待几秒后刷新;回调偶发延迟;
  • tag 不合法(包含空格、/ 等特殊字符,或超长);
  • 推送时只给了 digest、没有 tag;
  • 推送到了其它项目(不在当前 projectId 下);
  • 使用了平台分配之外的仓库账号(例如仓库管理员代推)——这类推送不会被登记为你的镜像;
  • 若仍不出现,联系平台排查同步服务。

5.4 模板构建失败:image is not amd64

镜像不是 linux/amd64。重新用 --platform linux/amd64 构建并 push,再新建模板。

5.5 模板构建失败:error provisioning sandbox: ... exit status: 1

基础镜像不是 Debian/Ubuntu 系,初始化脚本无法执行 apt-get / dpkg-query。改用 ubuntu:22.04 / debian:12 等 Debian 系基础镜像重建。

5.6 删除镜像返回 409

镜像仍被模板引用。提示会给出引用数量,先在「模板管理」里删除或改用其它镜像,再删除该镜像。


6. 合格镜像示例

# 必须显式指定 amd64;Debian/Ubuntu 系;保留标准 rootfs
FROM --platform=linux/amd64 ubuntu:22.04

RUN apt-get update \
&& apt-get install -y --no-install-recommends ca-certificates curl tzdata \
&& rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY app /app

# 应用不会在模板构建阶段被启动;这里只是把程序放进镜像
CMD ["/app/server"]

构建与推送:

docker build --platform linux/amd64 -t my-app:v1 .
docker tag my-app:v1 registry-wanqing.streamlake.com/<projectId>/my-app:v1
docker push registry-wanqing.streamlake.com/<projectId>/my-app:v1

不要做的事情:

  • 不要基于 alpine / distroless / scratch 构建;
  • 不要在镜像里删除 systemd、bash、apt;
  • 不要依赖镜像的 ENTRYPOINT 在构建阶段启动应用(模板构建只做系统初始化,启动命令在模板/沙箱侧配置)。


上一篇:沙箱服务 API 调用指南下一篇:GPU算力服务
该篇文档内容是否对您有帮助?
有帮助没帮助