docker/ucp-dsinfodocker/ucp 是 Docker 官方提供的 Universal Control Plane(UCP)镜像,用于部署和管理 Docker Swarm 集群的企业级控制平面。UCP 提供集中式管理界面和工具链,支持 Swarm 集群的全生命周期管理,包括节点编排、资源调度、安全控制、多租户隔离等核心能力,是企业级容器化部署的关键组件。
Swarm 集群全生命周期管理
多租户与权限控制
安全加固
监控与可观测性
镜像与仓库管理
API 与自动化集成
环境要求
网络端口要求
| 端口用途 | 协议 | 端口号 | 说明 |
|---|---|---|---|
| UCP 管理界面/API | TCP | 443 | HTTPS 访问端口 |
| Docker 守护进程通信 | TCP | 2376 | 用于 Swarm 管理通信 |
| UCP 内部节点通信 | TCP | *** | 控制器与工作节点通信 |
| 集群 gossip 协议通信 | TCP | 7946 | Swarm 节点发现 |
| overlay 网络数据通信 | UDP | 4789 | 跨节点容器网络 |
首次部署需初始化 UCP 控制器节点(即 Swarm 集群的管理节点),命令格式如下:
bashdocker run --rm -it \ --name ucp \ -v /var/run/docker.sock:/var/run/docker.sock \ docker/ucp:latest install \ --host-address <控制器节点IP> \ --admin-username <管理员用户名> \ --admin-password <管理员密码> \ [可选配置参数]
关键参数说明:
--host-address:控制器节点的公网/内网 IP(需确保其他节点可访问)--admin-username:UCP 管理员用户名(默认 admin)--admin-password:管理员密码(需满足复杂度要求,如 8 位以上含大小写字母+数字)--external-ca:指定外部 CA 证书(格式:"ca-root=<PEM文件路径>,ca-cert=<证书路径>,ca-key=<密钥路径>")--data-path-addr:指定 overlay 网络数据通信的 IP(多网卡节点需显式指定)已有控制器节点后,其他节点(工作节点或备用控制器节点)可通过以下步骤加入集群:
在控制器节点获取加入命令
通过 UCP 管理界面(https://<控制器IP>:443)登录,进入 Nodes > Add Node,选择节点类型(工作节点/控制器节点),生成加入命令。
在目标节点执行加入命令
示例(工作节点加入):
bashdocker run --rm -it \ --name ucp \ -v /var/run/docker.sock:/var/run/docker.sock \ docker/ucp:latest join \ --token <集群加入令牌> \ --server <控制器节点IP>:443
说明:
--token:从控制器节点获取的临时加入令牌(有效期 24 小时)--controller 参数UCP 控制器节点需持久化存储配置数据(证书、用户信息、集群状态等),默认路径为 /var/lib/ucp。生产环境建议通过挂载外部卷(如 Docker Volume 或持久化存储)实现数据持久化:
bashdocker run --rm -it \ --name ucp \ -v /var/run/docker.sock:/var/run/docker.sock \ -v ucp-data:/var/lib/ucp \ # 挂载命名卷 docker/ucp:latest install \ --host-address <控制器IP> \ --admin-password <密码>
| 环境变量名 | 说明 | 默认值 |
|---|---|---|
UCP_ADMIN_PASSWORD | UCP 管理员密码(初始化时必填) | - |
UCP_NODE_ADDRESS | 节点 IP 地址(同 --host-address) | 自动检测节点 IP |
UCP_EXTERNAL_CA | 外部 CA 配置(格式见上文) | - |
UCP_DISABLE_ANONYMOUS_ACCESS | 禁用***访问 | false |
UCP_LOG_LEVEL | 日志级别(debug/info/warn/error) | info |
| 参数 | 用途 | 示例 |
|---|---|---|
--install | 初始化 UCP 控制器节点 | docker/ucp install |
--join | 加入现有 UCP 集群 | docker/ucp join |
--force-new-deploy | 强制重新部署 UCP 服务栈 | --force-new-deploy |
--dry-run | 模拟执行命令,不实际部署 | --dry-run |
bashdocker run --rm -it \ --name ucp \ -v /var/run/docker.sock:/var/run/docker.sock \ docker/ucp:latest install \ --host-address 192.168.1.100 \ # 控制器节点IP --admin-username admin \ --admin-password "Ucp@Admin123" \ # 管理员密码 --dry-run # 首次执行建议加 --dry-run 验证配置
说明:移除 --dry-run 后实际执行部署,完成后通过 [***] 访问 UCP 管理界面。
bashdocker run --rm -it \ --name ucp \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /root/ucp-certs:/certs \ # 挂载外部CA证书目录 -v ucp-data:/var/lib/ucp \ # 持久化数据卷 docker/ucp:latest install \ --host-address 10.0.0.5 \ --admin-password "Prod@Ucp2024" \ --external-ca "ca-root=/certs/root.pem,ca-cert=/certs/ucp-cert.pem,ca-key=/certs/ucp-key.pem" \ --data-path-addr 10.0.0.5 # 显式指定 overlay 网络通信 IP
bash# 从控制器节点获取令牌后执行(示例令牌为占位符,需替换为实际值) docker run --rm -it \ --name ucp \ -v /var/run/docker.sock:/var/run/docker.sock \ docker/ucp:latest join \ --token "swarm-join-token:abc123def456..." \ --server 10.0.0.5:443
版本兼容性:UCP 版本需与 Docker Engine 版本匹配,例如 UCP 3.10 需 Docker Engine 20.10+,具体参考 Docker UCP 官方文档。
高可用部署:生产环境建议部署 3 个控制器节点(避免单点故障),并通过负载均衡器(如 NGINX、HAProxy)暴露 UCP 管理界面。
证书管理:默认使用自签名证书,生产环境需配置可信 CA 证书(通过 --external-ca 参数),避免浏览器/API 访问警告。
备份与恢复:定期通过 docker/ucp backup 命令备份 UCP 数据(需指定备份路径和密码),恢复时使用 docker/ucp restore 命令。
资源限制:控制器节点需预留足够资源(建议 4 CPU/8GB 内存),避免因资源不足导致集群管理中断。




manifest unknown 错误
TLS 证书验证失败
DNS 解析超时
410 错误:版本过低
402 错误:流量耗尽
身份认证失败错误
429 限流错误
凭证保存错误
来自真实用户的反馈,见证轩辕镜像的优质服务