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	***	控制器与工作节点通信
   集群 gossip 协议通信	TCP	7946	Swarm 节点发现
   overlay 网络数据通信	UDP	4789	跨节点容器网络

初始化 UCP 控制器

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

bash
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. 在目标节点执行加入命令
   示例（工作节点加入）：

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

bash
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：初始化单控制器节点（基础配置）

bash
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 和持久化存储的生产环境部署

bash
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：工作节点加入集群

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

注意事项

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 内存），避免因资源不足导致集群管理中断。