Docker UCP 镜像文档

镜像概述

docker/ucp 是 Docker 官方提供的 Universal Control Plane（UCP）镜像，用于部署和管理 Docker Swarm 集群的企业级控制平面。UCP 提供集中式管理界面和工具链，支持 Swarm 集群的全生命周期管理，包括节点编排、资源调度、安全控制、多租户隔离等核心能力，是企业级容器化部署的关键组件。

主要用途

• 部署和管理 Docker Swarm 集群，实现容器编排与资源调度
• 提供图形化管理界面，简化集群配置、监控与运维
• 支持多租户隔离与权限控制，满足企业级多团队协作需求
• 集成身份验证与授权机制，保障集群访问安全

核心功能和特性

1. Swarm 集群全生命周期管理

   • 支持集群初始化、节点加入/移除、角色配置（控制器/工作节点）
   • 可视化编排容器服务、栈（Stack）及资源（CPU/内存/存储）

2. 多租户与权限控制

   • 基于组织（Organization）、团队（Team）的层级权限模型
   • 集成 LDAP、Active Directory（AD）等外部身份提供商，支持 SSO 认证

3. 安全加固

   • 自动生成 TLS 证书，加密节点间通信及用户访问
   • 细粒度策略控制（如镜像拉取白名单、容器运行时限制）

4. 监控与可观测性

   • 实时展示集群健康状态、资源使用率、容器日志
   • 支持导出监控数据至第三方工具（如 Prometheus、Grafana）

5. 镜像与仓库管理

   • 集成 Docker Trusted Registry（DTR），支持私有镜像仓库管理
   • 镜像扫描与漏洞检测（需配合 DTR 企业版）

6. API 与自动化集成

   • 提供 RESTful API，支持与 CI/CD 工具（Jenkins、GitLab CI 等）集成
   • 支持 Terraform 等 Infrastructure as Code（IaC）工具自动化部署

使用场景和适用范围

适用场景

• 企业级容器集群部署：需集中管理数百至数千容器的生产环境
• 多团队协作：通过租户隔离实现开发、测试、运维团队资源独立管理
• 生产环境容器编排：需高可用、可监控、安全合规的容器运行环境
• 混合云/多云管理：统一管理跨物理机、虚拟机、公有云的 Swarm 集群

适用范围

• 需满足工业级稳定性与安全性的企业用户
• 已采用 Docker Swarm 作为容器编排引擎的团队
• 需通过集中式平台简化集群运维的场景

使用方法和配置说明

前提条件

1. 环境要求

   • 所有节点需安装 Docker Engine（版本需与 UCP 兼容，建议 Docker Engine 20.10+）
   • 控制器节点建议配置：4 CPU 核心、8GB 内存、100GB 磁盘（SSD 推荐）
   • 节点间网络互通，开放必要端口（见下文“网络端口要求”）

2. 网络端口要求

   端口用途	协议	端口号	说明
   UCP 管理界面/API	TCP	443	HTTPS 访问端口
   Docker 守护进程通信	TCP	2376	用于 Swarm 管理通信
   UCP 内部节点通信	TCP	12376	控制器与工作节点通信
   集群 gossip 协议通信	TCP	7946	Swarm 节点发现
   overlay 网络数据通信	UDP	4789	跨节点容器网络

初始化 UCP 控制器

首次部署需初始化 UCP 控制器节点（即 Swarm 集群的管理节点），命令格式如下：

docker 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 节点

已有控制器节点后，其他节点（工作节点或备用控制器节点）可通过以下步骤加入集群：

1. 在控制器节点获取加入命令
   通过 UCP 管理界面（https://<控制器IP>:443）登录，进入 Nodes > Add Node，选择节点类型（工作节点/控制器节点），生成加入命令。

2. 在目标节点执行加入命令
   示例（工作节点加入）：

   docker 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 或持久化存储）实现数据持久化：

docker 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 <密码>

配置参数与环境变量

核心环境变量

常用命令行参数

Docker 部署示例

示例 1：初始化单控制器节点（基础配置）

docker 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 管理界面。

示例 2：带外部 CA 和持久化存储的生产环境部署

docker 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

示例 3：工作节点加入集群

# 从控制器节点获取令牌后执行（示例令牌为占位符，需替换为实际值）
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

注意事项

1. 版本兼容性：UCP 版本需与 Docker Engine 版本匹配，例如 UCP 3.10 需 Docker Engine 20.10+，具体参考 Docker UCP 官方文档。

2. 高可用部署：生产环境建议部署 3 个控制器节点（避免单点故障），并通过负载均衡器（如 NGINX、HAProxy）暴露 UCP 管理界面。

3. 证书管理：默认使用自签名证书，生产环境需配置可信 CA 证书（通过 --external-ca 参数），避免浏览器/API 访问警告。

4. 备份与恢复：定期通过 docker/ucp backup 命令备份 UCP 数据（需指定备份路径和密码），恢复时使用 docker/ucp restore 命令。

5. 资源限制：控制器节点需预留足够资源（建议 4 CPU/8GB 内存），避免因资源不足导致集群管理中断。