docker/ucp-controller Docker Image

Docker UCP 镜像文档

1. 镜像概述和主要用途

Docker UCP（Universal Control Plane）是 Docker 企业级容器平台的核心组件，提供对 Docker 集群的集中式管理能力。该镜像（docker/ucp）用于部署和运行 UCP 服务，主要用途包括：

• 统一管理多节点 Docker 集群（包括控制器节点和工作节点）
• 提供图形化界面和 REST API，实现容器、镜像、网络、存储等资源的全生命周期管理
• 集成身份认证、角色授权和安全策略，满足企业级多租户和合规需求
• 监控集群健康状态、资源使用率及容器运行指标

2. 核心功能和特性

2.1 集群管理

• 支持多节点集群部署，自动发现和管理节点，支持横向扩展
• 提供节点标签、污点/容忍机制，实现工作负载调度控制

2.2 多租户与权限控制

• 基于角色的访问控制（RBAC），支持细粒度权限配置（如管理员、开发者、查看者等角色）
• 组织和团队层级管理，隔离不同业务单元资源

2.3 安全与合规

• 集成 Docker Trusted Registry（DTR），支持镜像签名验证和供应链安全
• 内置 TLS 加密（节点间通信、API 访问），支持外部 CA 证书导入
• 审计日志记录所有操作，满足合规审计需求

2.4 监控与可观测性

• 实时监控集群资源（CPU、内存、网络、存储）及容器运行状态
• 集成 Prometheus 和 Grafana，支持自定义监控指标和告警
• 日志聚合功能，对接外部日志系统（如 ELK Stack）

2.5 集成与扩展

• 兼容 Docker Compose 和 Kubernetes 编排模式
• 提供 REST API 和 CLI 工具（ucpctl），支持自动化运维集成
• 支持外部负载均衡器对接，实现高可用部署

3. 使用场景和适用范围

3.1 适用场景

• 企业级容器集群管理：需统一管控多节点、多区域 Docker 部署的场景
• 多团队协作：需要隔离不同团队资源、数据和权限的企业环境
• 安全敏感场景：对镜像来源、容器运行权限、数据传输加密有严格要求的***、政务等领域
• 大规模容器部署：需监控集群资源瓶颈、优化调度策略的高并发场景

3.2 环境要求

• Docker Engine 版本：需兼容 UCP 版本（如 UCP 3.9 要求 Docker Engine 20.10+）
• 节点资源：控制器节点至少 4 CPU 核心、8GB 内存、100GB 磁盘；工作节点根据负载调整
• 网络：节点间需开放端口（443、2376、、、*** 等，详见「注意事项」）

4. 详细使用方法和配置说明

4.1 前提条件

• 所有节点已安装兼容版本的 Docker Engine（推荐使用 Docker Enterprise Engine）
• 节点间网络互通，且可访问互联网（用于拉取 docker/ucp 镜像及依赖）
• 控制器节点需保留持久化存储（建议使用 SSD），用于存储集群状态和数据

4.2 安装步骤

4.2.1 部署 UCP 控制器节点

UCP 控制器节点是集群管理的核心，需通过 docker run 命令初始化（首次部署需指定主控制器节点）：

bash
# 示例：部署 UCP 控制器节点（替换版本号和 IP 地址）
docker run --rm -it \
  --name ucp \
  -v /var/run/docker.sock:/var/run/docker.sock \
  docker.xuanyuan.run/docker/ucp:3.9.0 install \
  --host-address 192.168.1.100 \  # 控制器节点的 IP 地址（需替换为实际地址）
  --interactive \                  # 交互式配置（手动输入管理员密码等）
  --admin-username admin \         # 管理员用户名（默认 admin）
  --license /path/to/license.lic   # 企业版许可证文件（可选，试用版可省略）

参数说明：

• --host-address：必填，控制器节点的公网/内网 IP（用于节点间通信）
• --interactive：启用交互式安装，支持手动设置管理员密码、接受许可协议等
• --admin-username/--admin-password：直接指定管理员账户（非交互式场景使用）
• --license：指定 Docker 企业版许可证文件路径（试用版默认提供 30 天有效期）

4.2.2 加入工作节点

控制器部署完成后，其他节点需通过 UCP 生成的「加入命令」加入集群：

1. 登录 UCP 图形界面（默认地址：https://<控制器IP>:443），进入「节点」→「添加节点」
2. 选择节点类型（工作节点/控制器节点），复制生成的 docker run 命令（包含临时证书和集群地址）
3. 在目标节点执行命令，示例：

bash
# 示例：加入工作节点（命令由 UCP 界面生成，包含证书和控制器地址）
docker run --rm -it \
  --name ucp-join \
  -v /var/run/docker.sock:/var/run/docker.sock \
  docker.xuanyuan.run/docker/ucp:3.9.0 join \
  --token "xxxxxx" \  # UCP 生成的临时令牌（有效期 24 小时）
  --server 192.168.1.100:443  # 控制器节点地址:端口

4.3 配置参数说明

4.3.1 核心安装参数

4.3.2 环境变量

通过 -e 参数传递环境变量，覆盖默认配置：

4.4 Docker 部署方案示例

4.4.1 单控制器节点部署（测试环境）

bash
docker run --rm -it \
  --name ucp \
  -v /var/run/docker.sock:/var/run/docker.sock \
  docker.xuanyuan.run/docker/ucp:3.9.0 install \
  --host-address 192.168.1.100 \
  --admin-username admin \
  --admin-password "SecurePass123!" \  # 生产环境需使用强密码
  --disable-usage-metrics

4.4.2 多控制器高可用部署（生产环境）

需配合外部负载均衡器（如 NGINX、HAProxy），部署 3 个控制器节点（避免单点故障）：

bash
# 第 1 个控制器节点（主节点）
docker run --rm -it \
  --name ucp \
  -v /var/run/docker.sock:/var/run/docker.sock \
  docker.xuanyuan.run/docker/ucp:3.9.0 install \
  --host-address 192.168.1.100 \
  --external-service-lb 192.168.1.200  # 外部负载均衡器 IP

# 第 2、3 个控制器节点（通过负载均衡器加入）
docker run --rm -it \
  --name ucp-join \
  -v /var/run/docker.sock:/var/run/docker.sock \
  docker.xuanyuan.run/docker/ucp:3.9.0 join \
  --token "xxxxxx" \  # 从主控制器获取的令牌
  --server 192.168.1.200:443  # 负载均衡器地址:端口

4.4.3 docker-compose 配置示例（简单测试场景）

yaml
version: '3.8'
services:
  ucp:
    image: docker.xuanyuan.run/docker/ucp:3.9.0
    command: install --host-address 192.168.1.100 --admin-username admin --admin-password "TestPass123"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - "443:443"  # UCP 管理界面端口
      - "2376:2376" # Docker API 端口（用于客户端连接）
    restart: unless-stopped

5. 访问和管理 UCP

5.1 图形界面访问

部署完成后，通过浏览器访问 https://<控制器IP或负载均衡器IP>:443，使用配置的管理员账户登录。界面功能包括：

• 集群概览：显示节点数量、容器运行状态、资源使用率
• 资源管理：创建/管理容器、服务、网络、存储卷
• 节点管理：添加/移除节点、配置节点标签和调度规则
• 组织与权限：创建团队、分配角色和资源访问权限

5.2 CLI 工具管理

通过 ucpctl 命令行工具管理 UCP（需先在本地安装 Docker 客户端并配置 UCP 证书）：

bash
# 下载 UCP 客户端证书（从 UCP 界面「用户设置」→「客户端证书」获取）
# 配置 Docker 客户端连接 UCP
export DOCKER_HOST=tcp://<ucp-ip>:2376
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH=/path/to/certificates

# 示例：查看集群节点状态
ucpctl node ls

6. 注意事项

• 端口开放：控制器节点需开放端口 443（UI/API）、2376（Docker API）、（内部通信）、-（etcd 集群）；工作节点需开放 2376、 端口。
• 证书管理：默认使用自签名证书，生产环境建议通过「UCP 设置 → 证书」替换为 CA 签名证书。
• 数据备份：定期备份 UCP 数据（通过 ucpctl backup 命令），避免集群配置丢失。
• 版本兼容性：升级 UCP 前需确认与 Docker Engine、DTR 版本的兼容性（参考 Docker 官方兼容性矩阵）。

如需更多细节，可参考 Docker 官方文档：https://docs.docker.com/ee/ucp/。