Ubuntu上用Docker快速搭建Hyperf集群的核心是单服务容器化、多节点编排与依赖分离；需先装Docker 24.x和docker-compose v2.20+，构建含Swoole等扩展的定制镜像，再通过docker-compose启动多实例验证，最后用Swarm实现跨节点高可用部署。
在 Ubuntu 上用 Docker 快速搭建 Hyperf 集群，核心是“单服务容器化 + 多节点编排 + 依赖分离”，不依赖复杂中间件即可跑通基础集群能力（如多实例负载、配置统一、日志可查）。关键不在堆组件，而在结构清晰、启动可控。
一、确保基础环境就绪
集群前提是每个节点都能独立运行 Hyperf 容器：
- Ubuntu 20.04+ 系统，已安装 Docker 24.x 和 docker-compose v2.20+（推荐用
apt install docker.io docker-compose或官方二进制） - 所有节点时间同步（
sudo timedatectl set-ntp true），避免 Swarm 节点握手失败 - 关闭或放行防火墙端口：2377（Swarm 管理）、7946（节点通信）、4789（overlay 网络）
- 非 root 用户加入
docker组：sudo usermod -aG docker $USER，然后重新登录终端
二、准备可复用的 Hyperf 服务镜像
别直接拉官方 hyperf/hyperf 镜像——它不含生产所需扩展，也不适配集群启动逻辑。推荐基于 Alpine 构建轻量定制镜像：
- 新建
Dockerfile，以php:8.2-cli-alpine为基础 - 安装必要扩展：
swoole（≥5.1）、redis、pdo_mysql、yaml（Hyperf 配置必需） - 禁用
opcache.enable_cli=0，但生产模式下通过环境变量启用（OPCACHE_ENABLE=1） -
关键操作：把项目代码 COPY 进镜像前，先在宿主机执行
composer install --no-dev -o，再 COPYvendor/和bin/hyperf.php，避免镜像层污染
三、用 docker-compose 启动本地多实例（开发验证用）
无需 Swarm，先用 docker-compose.yml 快速起 2 个 Hyperf 实例 + 1 个 Redis + 1 个 MySQL，验证服务互通性：
- 定义
hyperf-app服务，使用上面构建的镜像，设置restart: unless-stopped - 用
scale: 2启动两个副本，并通过ports: ["9501-9502:9501"]映射不同宿主机端口 - 挂载配置目录：
./config:/app/config:ro，让所有实例读同一份配置（如redis.host指向redis服务名） - MySQL 和 Redis 使用默认镜像，用
networks统一桥接，Hyperf 容器内直接用服务名访问
执行 docker-compose up -d 后，用 curl http://localhost:9501/health 和 curl http://localhost:9502/health 分别验证两个实例是否正常响应。
四、升级为 Docker Swarm 集群（生产就绪）
当需要跨机器、高可用、滚动更新时，启用 Swarm：
- 在任一节点执行
docker swarm init --advertise-addr初始化管理节点，记录join token - 其他节点执行
docker swarm join --token <token><manager-ip>:2377</manager-ip></token>加入集群 - 将
docker-compose.yml改写为docker-compose.prod.yml，添加 Swarm 特有字段：deploy:
replicas: 3
placement:
constraints: [node.role == worker]
update_config:
parallelism: 1
delay: 10s - 部署：
docker stack deploy -c docker-compose.prod.yml hyperf-cluster - 查看状态：
docker service ls和docker service logs hyperf-cluster_hyperf-app
此时 3 个 Hyperf 实例自动分布在不同节点，共享 Redis 和 MySQL 服务（需部署为 global 或 replicated service），请求可通过任意节点 IP:9501 访问，由 Swarm 内置路由网状分发。
