Uncloud 镜像管理指南使用 uc image 在集群中查看与分发 Docker 镜像【免费下载链接】uncloudA lightweight tool for deploying and managing containerised applications across a network of Docker hosts. Bridging the gap between Docker and Kubernetes ✨项目地址: https://gitcode.com/GitHub_Trending/unc/uncloud导读uc image是 Uncloud CLI 提供的镜像管理命令组用于在一组 Docker 主机组成的集群中统一查看、筛选和分发容器镜像。通过ls子命令可以跨机器汇总列出镜像及其平台、大小、占用状态等元信息通过push子命令可以把本地 Docker 镜像直接分发到集群中的一台或多台机器且只传输缺失的镜像层。读完本文你将掌握这两个命令的完整用法、参数含义以及 Uncloud 内部通过内置镜像仓库unregistry实现按层增量推送的底层原理。命令总览image 子命令组uc image是管理机器上镜像的根命令在 cmd/uc/image/root.go 中注册其Short描述为Manage images on machines in the cluster.管理集群机器上的镜像包含两个子命令uc image ls列出集群机器上的镜像可别名listuc image push将本地 Docker 镜像上传到集群。根命令本身没有业务参数只有通用的-h, --help-h, --help help for image完整的子命令结构参见 uc image、uc image ls、uc image push 三份 CLI 参考文档。全局父命令继承选项以下选项对所有uc image子命令同样生效用于指定集群连接方式--connect string Connect to a remote cluster machine without using the Uncloud configuration file. [$UNCLOUD_CONNECT] Format: [ssh://]userhost[:port], sshgo://userhost[:port], tcp://host:port, or unix:///path/to/uncloud.sock -c, --context string Name of the cluster context to use (default is the current context). [$UNCLOUD_CONTEXT] --uncloud-config string Path to the Uncloud configuration file. [$UNCLOUD_CONFIG] (default ~/.config/uncloud/config.yaml)选项环境变量默认值说明--connectUNCLOUD_CONNECT无绕过 Uncloud 配置文件直接连接远程集群机器支持ssh://、sshgo://、tcp://、unix://四种格式-c, --contextUNCLOUD_CONTEXT当前上下文指定要使用的集群上下文名称--uncloud-configUNCLOUD_CONFIG~/.config/uncloud/config.yamlUncloud 配置文件路径uc image ls跨机器汇总查看镜像语法与功能uc image ls [REPO:[TAG]] [flags]ls命令默认列出集群中所有机器上的镜像也可以按镜像名或机器进行过滤。其实现位于 cmd/uc/image/ls.goUse定义为ls [REPO:[TAG]]别名list。官方示例# List all images on all machines. uc image ls # List images on specific machine. uc image ls -m machine1 # List images on multiple machines. uc image ls -m machine1,machine2 # List images filtered by name (with any tag) on all machines. uc image ls myapp # List images filtered by name pattern on specific machine. uc image ls myapp:1.* -m machine1参数说明参数/选项说明[REPO:[TAG]]位置参数按镜像名过滤可带标签例如myapp或myapp:1.2支持通配符模式例如myapp:1.*-m, --machine strings按机器名称或 ID 过滤可多次指定或用逗号分隔如-m machine1,machine2默认包含所有机器-h, --help查看帮助从源码看cmd/uc/image/ls.go位置参数最多接受 1 个cobra.MaximumNArgs(1)-m通过StringSliceVarP绑定后会在 internal/cli/completion/machine.go 中注册机器名的自动补全。列表请求会构造api.ImageFilter{Machines, Name}见 pkg/api/image.go其中的 Name 过滤最终转换为 Docker 的reference过滤参数见 pkg/client/image.go因此可以匹配任意标签或使用通配符。输出表格字段ls会汇总各机器返回的镜像按名称、机器名排序后以表格形式输出见 cmd/uc/image/ls.go列含义IMAGE ID镜像 ID去掉sha256:前缀后取前 12 位与 Docker 的显示习惯一致NAME镜像名称取第一个 RepoTag无标签时显示nonePLATFORMS镜像支持的平台列表如linux/amd64多平台镜像会列出全部可用平台CREATED镜像创建时间以人性化时长显示如2 weeks agoSIZE镜像大小使用三位有效数字的人性化格式IN USE是否被容器占用●表示有容器正在使用○表示未被使用信息不可用时显示-STORE镜像存储后端docker或containerdMACHINE镜像所在的机器名称两个细节值得注意源码行为非文档原文IN USE列自适应隐藏IN USE信息依赖 Docker API 1.51 的Containers字段如果所有镜像该字段均不可用值为 -1该列会被自动隐藏STORE列自适应隐藏如果所有机器都使用 containerd 镜像存储STORE列会被隐藏避免冗余。当没有匹配结果时命令会输出No images found.无名称过滤时或No images matching filter found.有名称过滤时。此外如果某台机器列表失败ls不会中断而是打印警告并继续显示其他机器的结果见 cmd/uc/image/ls.go。uc image push把本地镜像按层分发到集群语法与功能uc image push IMAGE [flags]push将本地 Docker 镜像上传到集群机器且只传输缺失的镜像层transferring only the missing layers。默认推送到集群中所有机器也可以用-m指定一台或多台。实现位于 cmd/uc/image/push.go参数IMAGE必填cobra.ExactArgs(1)。官方示例# Push image to all machines in the cluster. uc image push myapp:latest # Push image to specific machine. uc image push myapp:latest -m machine1 # Push image to multiple machines. uc image push myapp:latest -m machine1,machine2,machine3 # Push a specific platform of a multi-platform image. uc image push myapp:latest --platform linux/amd64参数说明参数/选项说明IMAGE位置参数本地镜像引用例如myapp:latest-m, --machine strings要推送到的机器名称或 ID可多次指定或用逗号分隔默认推送到所有机器也支持特殊关键字all显式表示所有机器--platform string对多平台镜像推送指定平台如linux/amd64、linux/arm64前提是本地 Docker 已配置使用 containerd 镜像存储-h, --help查看帮助从 cmd/uc/image/push.go 的源码看--platform会经过platforms.Parse校验非法平台字符串会直接报错推送过程会以进度条形式展示标题为Pushing image IMAGE to cluster。前提目标机器必须启用 containerd 镜像存储这是push最重要的前置条件。在 pkg/client/image.go 的pushImageToMachine实现中推送前会先探测目标机器的镜像存储类型如果目标机器的 Docker未启用 containerd image storeContainerdStore为 false推送会被拒绝并提示错误docker on machine ... is not using containerd image store, which is required for pushing images原因在源码注释中说明得很清楚为了避免把镜像推入 containerd 后在 Docker 中却无法使用的混乱局面to avoid the confusion of pushing images to containerd and then not being able to use them in Docker。因此要使用uc image push需要先按 Docker 官方指南在目标机器上启用 containerd 镜像存储并重启 uncloud 守护进程systemctl restart uncloud。--platform选项同理要求本地Docker 也使用 containerd 镜像存储以支持多平台镜像。底层原理unregistry 内置仓库 本地端口转发push之所以能做到只传输缺失层是因为 Uncloud 在每台机器上内置了一个轻量级镜像仓库unregistryunregistry 监听在机器内网 IP 的51500端口常量定义见 internal/machine/constants/constants.go推送时客户端通过代理拨号器Dialer在本地与目标机器的 unregistry 之间建立端口转发local port forwarding将本机 Docker 当作客户端向该仓库执行docker pushDocker 推送协议天然按层去重因此目标机器上已存在的层不会被重复传输多台机器的推送通过 goroutine 并发执行任何一台失败都会通过errors.Join汇总返回见 pkg/client/image.go。推送链路整体为本地docker push→ 本地端口转发 → 目标机器 unregistry51500 端口→ 写入目标机器的 containerd 镜像存储随后这些镜像即可被uc service run/uc deploy等命令直接使用。常见用法组合结合上面的命令日常镜像管理可以这样串联# 1. 查看本地镜像在某台机器的现状 uc image ls -m machine1 # 2. 构建镜像后分发到所有机器 uc image push myapp:latest # 3. 验证分发结果含平台、大小、是否被容器占用 uc image ls myapp如果你只希望把镜像投递到指定机器例如仅部署机器则uc image push myapp:latest -m machine1,machine2小结uc image把Docker 主机集群中的镜像抽象成了统一可管理的资源ls提供跨机器的镜像清单与过滤能力名称、机器、平台、占用状态push借助每台机器内置的 unregistry 与本地端口转发实现按层增量分发。需要特别留意的是push要求目标机器启用 containerd 镜像存储这是官方文档与源码共同强调的硬性前提。更多相关命令可参考 uc 总览文档或通过uc image ls --help/uc image push --help随时查看帮助。【免费下载链接】uncloudA lightweight tool for deploying and managing containerised applications across a network of Docker hosts. Bridging the gap between Docker and Kubernetes ✨项目地址: https://gitcode.com/GitHub_Trending/unc/uncloud创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考