

本文面向使用「自主构建推送」把自有镜像上传到平台镜像仓库的用户,说明上传前需要准备什么、镜像必须满足哪些规格、完整操作流程以及常见问题的排查方式。
「自主构建推送」允许用户在自己的构建环境里构建镜像,推送到平台指定的镜像仓库;平台在收到仓库回调后把镜像登记到「镜像管理」列表(来源 = 自主构建),之后可以在「新建模板」时选择该镜像作为基础镜像。
需要注意:
项目 | 要求 |
Docker | 已安装且 docker login / tag / push 可用(Docker 20.10+ 建议) |
网络 | 能访问弹窗里「仓库地址」的主机(registry-wanqing.streamlake.com:443;内网环境使用对应的 IDC 域名) |
磁盘 | 预留足够的镜像构建与导出空间 |
架构 | 构建机可以是 x86_64 或 Apple Silicon,但产物必须是 linux/amd64(见 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 以上可用空间 |
明确不支持:
多架构镜像(manifest list)只要包含 amd64 即可。
在弹窗中获取,账号粒度是商业化主体(主账号 / 每个子账户各一个):
身份 | 仓库用户名 |
主账号 | <tenantId> |
子账户 | <tenantId>-<子账户标识> |
进入 镜像管理 → 自主构建推送,弹窗中会显示:
docker login registry-wanqing.streamlake.com -u '<用户名>'
# 按提示输入密码;也可以使用弹窗里的「变量传密码」方式:
# printf '%s' "$HARBOR_PASSWORD" | docker login registry-wanqing.streamlake.com -u '<用户名>' --password-stdin
登录成功只代表认证通过;实际是否有该项目推送权限以 docker push 结果为准。
# 普通 Docker
docker build --platform linux/amd64 -t my-image:v1 .
# 如果使用 buildx(Apple Silicon 推荐)
docker buildx build --platform linux/amd64 -t my-image:v1 --load .
docker tag my-image:v1 \
registry-wanqing.streamlake.com/proj-xfr2sg-1784694202813896643/my-image:v1
标签规则:
docker push registry-wanqing.streamlake.com/proj-xfr2sg-1784694202813896643/my-image:v1
限制:
推送完成后,镜像仓库会回调平台,镜像随即出现在「镜像管理」列表:
通常几秒内完成;如果长时间未出现,见第 5 节排查。
在列表里点「新建模板」,选择该镜像作为基础镜像,构建出模板后即可用于创建沙箱。模板构建期间会执行系统初始化,耗时通常为几分钟。
项目 | 说明 |
并发推送 | 10(排队) |
镜像大小 / 层数 | 不限制 |
tag 规则 | 字母数字开头;仅允许字母、数字、.、_、-;≤128 字符 |
覆盖推送 | 同名同 tag 视为同一镜像;仓库允许覆盖时平台按更新处理,开启 tag 不可变时会拒绝 |
删除镜像 | 若仍有模板引用该镜像,平台会拒绝删除,并提示「仍有 N 个模板引用它」,需要先删除/迁移相关模板 |
仓库侧删除 | 直接在仓库里删除镜像后,平台会同步删除记录;但被模板引用的镜像会保留记录,避免模板引用悬空 |
子账户 | 子账户使用独立账号(<tenantId>-<子账户>),与主账号的镜像归属、凭证均独立 |
凭证泄露 | 密码一旦泄露请立即「重置密码」,旧密码会立即失效 |
镜像不是 linux/amd64。重新用 --platform linux/amd64 构建并 push,再新建模板。
基础镜像不是 Debian/Ubuntu 系,初始化脚本无法执行 apt-get / dpkg-query。改用 ubuntu:22.04 / debian:12 等 Debian 系基础镜像重建。
镜像仍被模板引用。提示会给出引用数量,先在「模板管理」里删除或改用其它镜像,再删除该镜像。
# 必须显式指定 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
不要做的事情: