docker compose 可单机部署 hyperf 全套服务（hyperf+mysql+redis+nginx），核心是复用官方镜像、自定义网络互通、healthcheck 控制就绪状态、.env 统一管理配置，并通过挂载实现初始化与热更新。
用 Docker Compose 在单机上部署 Hyperf 全套服务（应用 + MySQL + Redis + Nginx）很成熟，关键在于镜像轻量、配置解耦、启动顺序可控、端口与网络互通。不依赖 Kubernetes，纯 Compose 就能跑通开发和中小型生产环境。
核心服务选型与镜像策略
避免从零编译 PHP/Swoole，优先复用官方维护的 Hyperf 基础镜像（如 hyperf/hyperf:8.3-alpine-v3.19-swoole），它已预装 Swoole 5.1+、协程支持及必要扩展。MySQL 和 Redis 直接使用官方镜像（mysql:8.0、redis:7-alpine），省去自建 Dockerfile 的维护成本。Nginx 选用 nginx:alpine，通过挂载配置文件实现反向代理到 Hyperf 的 9501 端口。
- Hyperf 应用镜像：基于官方镜像，只 COPY 代码 + 运行时依赖（
--no-dev） - 数据库镜像：用
init.sql初始化脚本自动建库建表，无需手动导入 - Redis 镜像：默认关闭保护模式（
redis.conf中设protected-mode no），并监听0.0.0.0 - Nginx 镜像：挂载自定义
nginx.conf，将/转发到http://hyperf:9501
docker-compose.yml 关键配置要点
版本必须用 3.8 或更高，以支持健康检查、deploy 资源限制等生产级特性。所有服务需共用一个自定义网络（如 hyperf-net），确保容器名可直接解析为 IP。
-
depends_on仅控制启动顺序，不能保证服务就绪 —— 必须配合healthcheck（如 MySQL 用mysqladmin ping -u root -proot123） - Hyperf 服务要暴露
9501，但对外不直接映射；Nginx 才映射80:80和443:443 - MySQL 挂载
./mysql-data:/var/lib/mysql持久化数据，Redis 挂载./redis-data:/data - 环境变量统一通过
.env文件管理（如DB_HOST=hyperf-mysql、REDIS_HOST=hyperf-redis）
配置外挂与热更新支持
开发阶段建议挂载代码目录（./src:/app/src），但不要挂载 vendor —— 容器内已安装好依赖，挂载会覆盖。日志统一输出到 stdout，便于 docker logs 查看；若需持久化，可挂载 ./logs:/app/runtime/logs。
- Hyperf 的
.env不进镜像，改用 Compose 的environment字段或env_file加载 - Nginx 配置单独放在
./nginx/conf.d/default.conf，通过volumes挂载进容器 - MySQL 初始化 SQL 放在
./mysql/init.sql，Compose 自动执行（需设置mysql的volumes映射） - 启动后验证：访问
http://localhost应返回 Hyperf 默认欢迎页，docker exec -it hyperf-redis redis-cli ping返回PONG
一键启停与常见排障
执行 docker-compose up -d 启动全部服务，docker-compose down 清理。首次启动可能因 MySQL 初始化耗时稍长，观察 docker-compose logs mysql 是否出现 ready for connections。
- 如果 Hyperf 报
Connection refused，先确认mysql容器健康状态：docker-compose ps看 STATUS 是否为healthy - Nginx 502 错误，大概率是
upstream地址写错（应为hyperf:9501，不是localhost:9501） - Redis 连接失败，检查
redis容器是否监听0.0.0.0:6379（docker exec -it hyperf-redis netstat -tlnp | grep 6379） - 修改代码后未生效？确认挂载路径正确，且 Hyperf 未启用
SCAN_CACHEABLE=true导致类缓存未刷新（开发时建议设为false）
